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.

Features

• Multi-Runtime Support: Run Claude Code, OpenCode, Codex, Gemini, and Grok agents in the same infrastructure
• 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
• Telegram Integration: Connect bots to missions for chat-based AI assistants with auto-mission creation per chat
• 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
• Multi-platform: Web dashboard (Next.js) and iOS app (SwiftUI) with Picture-in-Picture

Ecosystem

sandboxed.sh orchestrates multiple AI coding agent runtimes:

• Claude Code: Anthropic's official coding agent with native skills support (.claude/skills/)
• OpenCode: Open-source alternative via oh-my-opencode
• 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

| | Docker (recommended) | Native (bare metal) | | ------------------------ | ---------------------------------------------- | --------------------------------------------------- | | Best for | Getting started, macOS users, quick deployment | Production servers, maximum performance | | Platform | Any OS with Docker | Ubuntu 24.04 LTS | | Setup time | ~5 minutes | ~30 minutes | | Container workspaces | Yes (with privileged: true) | Yes (native systemd-nspawn) | | Desktop automation | Yes (headless Xvfb inside Docker) | Yes (native X11 or Xvfb) | | Performance | Good (slight overhead on macOS) | Best (native Linux) | | Updates | docker compose pull / rebuild | Git pull + cargo build, or one-click from dashboard |

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

• Harness System - Backend integration architecture
• Workspaces - Isolated execution environments
• Mission API - Mission lifecycle and control
• Workspace API - Workspace management endpoints
• Backend API - Backend configuration

Setup Guides

• Telegram Assistant - Connect Telegram bots to missions
• 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