Development
Plugin
sandboxedsh
Safe runtime for autonomous on-chain AI agents: isolated sandboxes, Library skills, encrypted secrets.
Plugin Signal75/100Solid
maintained100
capable37
documented100
adopted57
Install
$ npx -y skills add Th0rgal/sandboxed.sh --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Stats
480
Stars
49
Forks
Active
Maintenance
Rust
Language
14h ago
Last commit
7mo ago
Created
Repo: Th0rgal/sandboxed.sh
What's inside
Skills
5/hermes-mission-controlHow Hermes monitors and steers long-running sandboxed.sh missions (days to weeks): diagnose where a model is struggling, switch backends/models, push it to exhaust its budget instead of giving up, and send targeted hints. Trigger terms: mission, sandboxed.sh, babysit, monitor,/orchestrator-advisorPersistent read-only advisor mission. Build a mental map of the repository once, then answer the executor's questions concisely across many turns without re-reading everything./orchestrator-bossBoss skill for parallel worker orchestration. Analyze, split, delegate by outcome, judge by acceptance criteria, integrate. Do not implement directly./orchestrator-executorExecutor skill: do the work yourself, and consult a single persistent smart-model advisor via ask_worker when you hit a dead end./orchestrator-workerWorker skill for boss-spawned missions. Stay within scope, verify, and report blockers quickly.
README
1Vision
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 execution half of a two-part system. The other half is a coordinator (we use Hermes, but any MCP-capable assistant works) that decides what to do; sandboxed.sh does the building in isolation. Four concepts tie the system together:
| Concept | What it is | Where it lives |
|---|---|---|
| Project | The durable unit of work (an audit, a paper, a benchmark). First-class object with a mode (active / blocked / paused), an autonomy grant (merge authority, budget, parallelism), tracks, and open decisions. | projects.db on the sandboxed.sh host, served at /api/projects/* |
| Controller | A coordinator cron that wakes on a schedule, reads its control conversation + GitHub + the project state, and dispatches work. It drives exactly one project and reports back with structured status trailers. | Coordinator (e.g. a Hermes cron with the project MCP tools) |
| Conversation (control session) | The durable Hermes chat thread; the one bound to a project is its control conversation — where you (or the controller) talk — where you (or the controller) talk. Continuations roll over, so it's addressed by route, not a frozen ID. | Coordinator, binding stored in projects.db |
| Mission | One unit of autonomous execution: an agent in an isolated workspace/container running a harness (Claude Code, Codex, …) that writes code, runs builds, opens PRs. Tagged with project/track. | sandboxed.sh workspaces |
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/completionswhen 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 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
| 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.
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.4with domainagent.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
File tree
860Th0rgal/sandboxed.shView on GitHub
.claude/
CLAUDE.md
settings.json
.dockerignore
.env.example
.githooks/
pre-push
.github/
workflows/
android-apk.yml
ci-debounced.yml.example
ci.yml
.gitignore
.gitmodules
.opencode/
skill/
library-management/
SKILL.md
tool/
library-agents.ts
library-commands.ts
library-git.ts
library-skills.ts
agents.md
android_dashboard/
.gitignore
app/
build.gradle.kts
proguard-rules.pro
src/
main/
AndroidManifest.xml
java/
sh/
sandboxed/
dashboard/
data/
api/
ApiClient.kt
ApiService.kt
AskClient.kt
ControlWsClient.kt
DesktopStreamSocket.kt
SseClient.kt
TerminalSocket.kt
AppContainer.kt
Ask.kt
ChatMessage.kt
FidoChannel.kt
MissionCache.kt
Models.kt
Settings.kt
MainActivity.kt
SandboxedDashboardApp.kt
ui/
auth/
AuthGate.kt
automations/
AutomationsScreen.kt
components/
Components.kt
ToolUiWidgets.kt
control/
AskSheet.kt
AskViewModel.kt
ControlScreen.kt
ControlViewModel.kt
desktop/
DesktopStreamScreen.kt
fido/
FidoOverlay.kt
FidoRulesScreen.kt
files/
FilesScreen.kt
history/
HistoryScreen.kt
MissionDetailScreen.kt
more/
MoreScreen.kt
nav/
AppRoot.kt
PipHost.kt
runs/
RunsScreen.kt
settings/
SettingsScreen.kt
tasks/
TasksScreen.kt
terminal/
TerminalScreen.kt
TestTags.kt
theme/
Color.kt
Theme.kt
workspaces/
WorkspacesScreen.kt
util/
Ansi.kt
GitHubAuth.kt
Haptics.kt
TokenCrypto.kt
Truncate.kt
res/
mipmap-anydpi/
ic_launcher_round.xml
ic_launcher.xml
values/
values-night/
themes.xml
colors.xml
strings.xml
themes.xml
xml/
backup_rules.xml
data_extraction_rules.xml
file_paths.xml
network_security_config.xml
build.gradle.kts
gradle/
gradle.properties
wrapper/
gradle-wrapper.jar
gradle-wrapper.properties
gradlew
gradlew.bat
metadata/
icon.png
PUBLISHING.md
README.md
settings.gradle.kts
TEST_PLAN.md
test-helpers.sh
zapstore.yaml
ASK_ASSISTANT_DESIGN.md
backend/
PERF_OVERHAUL.md
STREAMING.md
banner-dark.png
banner-light.png
capabilities/
matrix.v1.json
Cargo.lock
Cargo.toml
claude.md
dashboard/
.gitignore
bun.lock
eslint.config.mjs
next.config.ts
package.json
playwright.config.ts
postcss.config.mjs
public/
favicon.svg
file.svg
fonts/
jetbrainsmono-nerd-font/
JetBrainsMonoNerdFontMono-Bold.ttf
JetBrainsMonoNerdFontMono-Regular.ttf
OFL.txt
line_logo.svg
next.svg
vercel.svg
window.svg
README.md
src/
app/
assistant/
chat/
page.tsx
page.tsx
config/
commands/
page.tsx
layout.tsx
settings/
page.tsx
skills/
page.tsx
workspace-templates/
page.tsx
console/
console-client.tsx
console-wrapper.tsx
page.tsx
control/
components/
common.tsx
HermesConversation.tsx
MissionTaskBoard.tsx
MissionWorkbenchPanel.tsx
SharedFiles.tsx
ThinkingPanel.tsx
control-client.item-views.test.ts
control-client.tsx
control-stores.ts
conversation-router.tsx
events-reducer.test.ts
events-reducer.ts
events-worker.ts
hermes-session-adapter.ts
MissionDebugStats.tsx
page.tsx
transport/
connection.ts
types.ts
favicon.ico
files/
page.tsx
globals.css
history/
page.tsx
inspect/
layout.tsx
mcps/
page.tsx
page.tsx
system/
page.tsx
tools/
page.tsx
layout.tsx
model-routing/
page.tsx
overview/
page.tsx
page.tsx
settings/
backends/
page.test.tsx
page.tsx
data/
page.tsx
github/
page.tsx
layout.tsx
llm/
page.tsx
page.tsx
providers/
page.tsx
secrets/
page.tsx
telegram/
page.tsx
workspaces/
page.tsx
components/
active-automations.tsx
app-shell.tsx
ask-panel.tsx
assistant/
assistant-page.tsx
auth-gate.test.tsx
auth-gate.tsx
backend-preconnect.tsx
config-code-editor.tsx
desktop-stream.test.tsx
desktop-stream.tsx
dev-fetch-throttle-installer.tsx
enhanced-input.test.tsx
enhanced-input.tsx
env-vars-editor.tsx
goal-bar.tsx
hermes/
alerts-feed.test.tsx
alerts-feed.tsx
hermes-page.test.tsx
hermes-page.tsx
hermes-session-delivery.test.tsx
hermes-thread.test.tsx
hermes-thread.tsx
mission-chip.tsx
icons/
BrainLogo.tsx
index.ts
last-day-summary.tsx
lazy-code-block.tsx
lazy-json-highlighter.test.tsx
lazy-json-highlighter.tsx
library-unavailable.tsx
markdown-content.standalone-link.test.tsx
markdown-content.test.tsx
markdown-content.tsx
mission-automations-dialog.test.tsx
mission-automations-dialog.tsx
mission-switcher.test.ts
mission-switcher.tsx
model-routing-debug.tsx
new-mission-dialog.test.tsx
new-mission-dialog.tsx
perf-overlay.tsx
projects/
project-health.tsx
projects-board.test.tsx
projects-board.tsx
queue-strip.tsx
rename-dialog.tsx
server-connection-card.test.tsx
server-connection-card.tsx
sidebar.tsx
stall-bar.tsx
stats-card.tsx
streaming-markdown.tsx
subagents-panel.tsx
system-monitor.tsx
toast.tsx
tool-ui/
data-table/
index.tsx
option-list/
_adapter.tsx
error-boundary.tsx
index.tsx
option-list.tsx
schema.ts
shared/
_adapter.tsx
action-buttons.tsx
actions-config.ts
error-boundary.tsx
index.ts
parse.ts
schema.ts
use-action-buttons.tsx
use-copy-to-clipboard.ts
utils.ts
ui/
add-provider-modal.tsx
async-button.tsx
button.tsx
confirm-dialog.tsx
copy-button.tsx
github-integration-card.tsx
loading-ring.tsx
reconnect-provider-modal.test.ts
reconnect-provider-modal.tsx
relative-time.tsx
separator.tsx
shimmer.tsx
status-icons.tsx
usage-overview.tsx
worker-peek-modal.tsx
workers-strip.tsx
workspace-resources.tsx
contexts/
library-context.tsx
mission-switcher-context.tsx
hooks/
use-copy-to-clipboard.ts
use-dialog.test.ts
use-dialog.ts
use-favicon-status.ts
use-local-storage.ts
use-media-query.ts
use-scroll-to-bottom.ts
use-virtual-timeline-anchor.ts
use-visibility-polling.ts
lib/
__tests__/
stream-continuation.test.ts
api/
api.ts
assistant.ts
automations.ts
core.test.ts
core.ts
github.ts
hermes.test.ts
hermes.ts
index.ts
missions.test.ts
missions.ts
model-routing.ts
projects.ts
providers.ts
proxy-keys.ts
secrets.test.ts
telegram.ts
validation.ts
workspaces.ts
assistant-turn-status.test.ts
assistant-turn-status.ts
auth.ts
client-message-id.test.ts
client-message-id.ts
dev-fetch-throttle.ts
event-cache.ts
file-extensions.ts
format.ts
frontmatter-validation.ts
health-budget.ts
hermes-gateway.ts
hermes-outbox.test.ts
hermes-outbox.ts
hermes-state-signature.test.ts
hermes-state-signature.ts
mission-display.ts
mission-role.test.ts
mission-role.ts
... 659 moreFAQ
sandboxedsh is a Claude Code plugin with 5 hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. It includes hermes-mission-control, orchestrator-advisor, orchestrator-boss. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is sandboxedsh?
- Safe runtime for autonomous on-chain AI agents: isolated sandboxes, Library skills, encrypted secrets.
- How do I install sandboxedsh?
- Run these in Claude Code: npx -y skills add Th0rgal/sandboxed.sh --agent claude-code. Then prompt normally.
- Does sandboxedsh auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is sandboxedsh free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.