sandboxed.sh

Self-hosted mission-execution backend for autonomous AI agents
Isolated Linux workspaces with Claude Code, OpenCode, Codex, Gemini, and Grok runtimes
Driven over MCP by a coordinator like Hermes — sandboxed.sh runs the missions

Formerly known as Open Agent

Website · Discord · Vision · Architecture · Features · Ecosystem · Screenshots · Getting Started

Ready to deploy? Jump to the installation comparison, or go straight to the Docker guide / native guide.

Vision

What if you could:

Hand off entire dev cycles. Point an agent at a GitHub issue, let it write code, test by launching desktop applications, and open a PR when tests pass. You review the diff, not the process.

Run multi-day operations unattended. Give an agent SSH access to your home GPU through a VPN. It reads Nvidia docs, sets up training, fine-tunes models while you sleep.

Keep sensitive data local. Analyze your sequenced DNA against scientific literature. Local inference, isolated containers, nothing leaves your machines.

Architecture

sandboxed.sh is the mission-execution backend of a two-part system — the half an autonomous agent drives over MCP to actually build things in isolation. The other half is a coordinator that decides what to do and when: we run our own Hermes fork — hermes-agent (the Python gateway + CLI) and its bundled hermes-desktop Electron app (apps/desktop/) — but any MCP-capable assistant works. The agent never runs untrusted code itself; it hands each unit of work to sandboxed.sh, which runs it in a throwaway workspace/container and streams back structured results. Four concepts tie the system together:

             decide / coordinate                      build / execute
  ┌────────────────────────────────┐      ┌────────────────────────────────────┐
  │  Coordinator (Hermes)          │ MCP  │  sandboxed.sh                      │
  │                                ├─────▶│                                    │
  │  controller crons              │      │  missions in isolated workspaces   │
  │  control conversations         │      │  (systemd-nspawn / Docker)         │
  │  project tools + start_mission │◀─────┤  projects.db · event stream        │
  └────────────────────────────────┘ SSE/ └────────────────────────────────────┘
                                  webhooks

Controllers write structured project state through MCP tools (list_projects, update_project_status, set_project_grant, link_mission_to_project, …) instead of free text; a state ingestor also folds controller status trailers from deliveries into the project record, so the roster stays current even for text-only updates.

Rule of thumb: a controller drives a project through its control conversation by dispatching missions. Decide/coordinate → the assistant; build/execute in isolation → a sandboxed mission. In-conversation subagents are for quick reasoning and decomposition; anything needing a real filesystem, git, builds, or a PR gets dispatched as a mission.

The same project roster is rendered by three surfaces: the web dashboard's board (/), the desktop Projects board, and the iOS app's Projects tab.

Features

• Multi-Runtime Support: Run Claude Code, OpenCode, Codex, Gemini, and Grok agents in the same infrastructure
• Projects & Controllers: First-class projects (mode, autonomy grant, tracks, decisions) driven by scheduled controllers over MCP — structured state, not status prose
• Mission Control: Start, stop, and monitor agents remotely with real-time streaming
• Isolated Workspaces: Containerized Linux environments (systemd-nspawn) with per-mission directories
• Git-backed Library: Skills, tools, rules, agents, and MCPs versioned in a single repo
• Assistant Gateway: Manage Telegram gateway compatibility from the top-level Assistant UI while Hermes takes over assistant runtime over MCP
• Automations: Schedule recurring agent runs with cron-like triggers
• Model Routing: Provider fallback chains with health checks and rate-limit handling
• MCP Registry (optional): Extra tool servers (desktop/playwright/etc.) when needed
• OpenAI-compatible Proxy Queue Mode: Optional deferred execution for /v1/chat/completions when all routed providers are temporarily rate-limited
• Native Inference Protocols: Capability-gated Chat Completions, Responses, and Anthropic Messages with provider-specific reasoning continuity; see docs/INFERENCE_PROTOCOLS.md
• Multi-platform: Web dashboard (Next.js) and iOS app (SwiftUI) with Picture-in-Picture

Ecosystem

The coordinator — the agent that decides what to run and drives sandboxed.sh over MCP:

• Hermes (our fork): the coordinator we run in production — a Python gateway + CLI plus the bundled hermes-desktop Electron app (apps/desktop/). It owns the control conversations, controller crons, and the project MCP tools (start_mission, link_mission_to_project, …). Any MCP-capable assistant can take this role; Hermes is the reference implementation. See its FORK.md for how our changes are layered on upstream to stay easy to update.

The runtimes — the coding agents sandboxed.sh executes inside isolated workspaces:

• Claude Code: Anthropic's official coding agent with native skills support (.claude/skills/)
• OpenCode: Open-source coding agent
• Codex, Gemini, and Grok: Native CLI backends for OpenAI, Google, and xAI coding agents

Each runtime executes inside isolated workspaces, so bash commands and file operations are scoped correctly. sandboxed.sh handles orchestration, workspace isolation, and Library-based configuration management.

Screenshots

Real-time monitoring with CPU, memory, network graphs and mission timeline

Git-backed Library with skills, commands, rules, and inline editing

MCP server management with runtime status and Library integration

Getting Started

Choose your installation method

Docker (recommended for most users)

git clone https://github.com/Th0rgal/sandboxed.sh.git
cd sandboxed.sh
cp .env.example .env
# Edit .env with your settings
docker compose up -d

Open http://localhost:3000 — that's it.

For container workspace isolation (recommended), uncomment privileged: true in docker-compose.yml.

→ Full Docker setup guide

Native (bare metal)

For production servers running Ubuntu 24.04 with maximum performance and native systemd-nspawn isolation.

→ Full native installation guide

First-time setup

After installation, follow the Getting Started Guide for:

• Configuring your backend connection
• Setting up your library repository
• Exploring skills and tools
• Creating your first mission

AI-assisted setup

Point your coding agent at the installation guide and let it handle the deployment:

"Deploy Sandboxed.sh on my server at 1.2.3.4 with domain agent.example.com"

Documentation

User Guides

• Getting Started - First-time setup and usage
• Docker Installation - Recommended installation method
• Native Installation - Bare metal Ubuntu setup

Architecture & APIs

• Hermes orchestration - How Hermes and sandboxed.sh run autonomous projects: sessions, missions, controllers, routes
• Harness System - Backend integration architecture
• ChatGPT UI harness - Experimental subscription-backed browser harness
• Workspaces - Isolated execution environments
• Mission API - Mission lifecycle and control
• Workspace API - Workspace management endpoints
• Backend API - Backend configuration

Setup Guides

• Assistant Gateway - Connect Telegram bots and manage the Assistant cutover
• Hermes Assistant Migration - MCP bridge and runtime handoff notes
• Desktop Setup - X11/Xvfb configuration for GUI automation

Reference

• agents.md - Agent configuration and harness details
• Persistent Sessions Design - Claude CLI session management
• Debugging Guide - Troubleshooting and debug workflows
• Docker Analysis - Docker setup deep dive

Development

Setup git hooks

Enable pre-push formatting checks to catch CI failures locally:

git config core.hooksPath .githooks

This runs cargo fmt --check before each push. If formatting issues are found, run cargo fmt --all to fix them.

Status

Work in Progress — This project is under active development. Contributions and feedback welcome.

License

MIT