sandboxed.sh

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

Getting Started

Choose your installation method