Sandbox docs — tools

Quickstart

Install or upgrade the three binaries, the cross-agent skill, and detected MCP client entries in one command. Reruns verify the archive and embedded versions, replace existing binaries, preserve existing MCP entries, and never write SANDBOX_TOKEN into agent configuration.

shell · workstation setup

curl -fsSL https://tools.yshubham.com/sandbox/setup.sh | sh

export SANDBOX_URL=https://sandbox.example.com
export SANDBOX_TOKEN='read-from-your-secret-store'
sandbox doctor

Control planecontroller, workers, leases, heartbeats, operations, and TTL cleanup

StatePostgreSQL through Diesel or zero-service in-memory development mode

Eventsoptional NATS lifecycle publishing with an in-memory fallback

Observabilitystructured logs, Prometheus metrics, health, and readiness endpoints

agent entry point

Agents should begin at /docs/sandbox/index.md or discover the complete reference set through /docs/sandbox/llms.txt.

serverDeploy SandboxController, PostgreSQL, dedicated Docker worker, secrets, health, and lifecycle verification. client PCConnect every agentCLI, MCP bridge, cross-agent skill, native clients, templates, and protocol checks. domainsPublish HTTPS safelyWildcard DNS, Advanced certificates, Origin CA, Full (strict), and hidden-origin Cloudflare Tunnel.

Share a local port

Start a frontend or API on the current machine, then publish it through the first-party relay at a temporary https://local-….tunnel.yshubham.com URL. This path does not need a local sandboxd, SANDBOX_URL, a helper binary, or a remote sandbox. HTTP and WebSocket traffic such as Vite HMR are supported. Keep the command attached and press Ctrl-C to revoke the URL.

shell · temporary public preview

sandbox http 4321

public means public

Anyone with the generated URL can reach the local service. Do not expose admin panels, credentials, private data, or production control surfaces.

The relay rewrites the upstream Host and Origin to loopback, so do not weaken Vite's allowedHosts. For a service inside a managed sandbox, bind it to 0.0.0.0 and use sandbox tunnel create SANDBOX_ID --port PORT. See the CLI reference for relay overrides and managed-tunnel commands.

Safe lifecycle

Verify controller health with sandbox doctor or sandbox_health.
Classify repository trust, generated code, secret use, sensitivity, network, resources, and TTL.
Create with isolation: auto. Never weaken a placement decision merely to obtain capacity.
Wait until the create operation succeeds before depending on the workspace.
Execute argv arrays; inspect operation state, exit code, stderr, and output truncation.
Delete disposable sandboxes and wait for teardown unless retention was explicitly requested.

shell · create → execute → destroy

sandbox create --tenant engineering --image ubuntu:24.04 \
  --cpu-millis 2000 --memory-mib 4096 --ttl 1800 \
  --network restricted --untrusted-repo --generated-code

sandbox exec SANDBOX_ID -- cargo test --workspace
sandbox delete SANDBOX_ID --wait

Architecture

sandboxd is one deployable executable that can run as a controller, worker, or both. Production separates controller and worker roles; workers never accept operator traffic directly.

01 / clientshumans, CI, CLI, MCP hosts, and coding agents

02 / controllerauth, validation, policy, AEGIS, desired state, and leases

03 / statePostgreSQL operations with optional NATS lifecycle events

04 / workercapacity, heartbeats, assignment serialization, and bounded output

05 / runtimehardened Docker or external VMM-grade adapter

AEGIS scheduler

Adaptive Execution Guard and Isolation Scheduler combines workload risk with placement. Capacity pressure cannot silently downgrade the minimum required isolation.

Phase	Decision	Invariant
Risk	Sensitivity, network, trust, generated code, secrets, exposure, mounts, privilege, and TTL produce a saturated 0–100 score.	Inputs are explicit and deterministic.
Isolation floor	The risk score and hard signals select the minimum eligible runtime tier.	The caller cannot request a weaker tier.
Hard filter	Reject stale, pressured, incompatible, undersized, or label-mismatched nodes.	No ranking score can revive an ineligible node.
Rank	Compare headroom, fragmentation, pressure, warm images, region, and bin packing.	Stable tie-breaking keeps placement explainable.

fail closed

When no node satisfies policy and the isolation floor, creation returns no_capacity. Do not lower security thresholds as an incident shortcut.

Read the complete scoring and placement algorithm in the AEGIS Markdown reference.

Interfaces

Interface	Best for	Canonical reference
`sandbox`	Operator terminals, scripts, CI, and agents without native MCP support.	cli.md
`sandbox-mcp`	Codex, Claude, OpenCode, Cursor, VS Code, Gemini, Windsurf, Cline, Roo, Goose, and generic MCP hosts.	mcp.md
HTTP API	Custom portals, gateways, controllers, SDKs, and worker coordination.	api.md

MCP surface

The Rust stdio bridge publishes 12 tools, 3 resources, and 2 prompts with closed JSON schemas, structured results, explicit error semantics, and annotations for read-only, destructive, idempotent, and open-world behavior.

shell · major MCP CLIs

codex mcp add sandbox -- sandbox-mcp
claude mcp add --scope user --transport stdio sandbox -- sandbox-mcp
gemini mcp add sandbox sandbox-mcp --scope user
opencode mcp add

Use the complete MCP client matrix for Cursor, VS Code/Copilot, Windsurf, Cline, Roo Code, Claude Desktop, Gemini Code Assist, Goose, and generic configs.

Coding agents

Profiles encode resource, network, sensitivity, risk, image, and executable defaults. They do not embed provider credentials.

CodexClaude CodeOpenCodePiAiderGooseCommandCode

shell · agent sandbox

sandbox agent list
sandbox agent run codex --tenant engineering
sandbox wait OPERATION_ID

Read agents.md for images, profiles, credentials, custom images, and update policy. Install the workflow skill across supported agents:

shell · cross-agent skill

npx skills add bas3line/rool-repo \
  --skill sandbox-platform --agent '*' --global --yes

Deploy

The baseline self-hosted topology is one or more controllers, PostgreSQL, and dedicated workers. NATS is optional. Start with Compose for development, then split roles and move credentials into the deployment secret mechanism.

shell · developer compose

export SANDBOX_API_TOKEN="$(openssl rand -hex 32)"
export SANDBOX_NODE_TOKEN="$(openssl rand -hex 32)"
docker compose -f deploy/compose/compose.yaml up --build

start hereServer setupDurable Compose deployment, secret separation, health, lifecycle checks, and operating baseline. HTTPS ingressCustom public domainsDirect edge, Cloudflare Full (strict), Origin CA, or an outbound connector with no public origin listener. deploymentCompose → systemd → KubernetesTopology, reverse proxy, release verification, upgrades, scaling, and backup expectations. configurationOne typed configuration surfaceServer, state, bus, policy, node, runtime, observability, and environment overrides.

Security boundary

containers are not microVMs

The built-in Docker adapter is for dedicated or trusted worker hosts. Containers share the host kernel. Use an external VMM-grade driver when the deployment requires a stronger boundary.

Prompts, skills, MCP descriptions, and client approval settings are workflow guidance—not authorization.
Enforcement belongs in API authentication, controller policy, AEGIS, worker eligibility, runtime configuration, host networking, and non-bypassable credentials.
Never put secrets in prompts, argv, labels, image names, logs, or committed MCP configuration.
Default network access to deny; request only the resources and lifetime required.
Keep controller and worker credentials separate and rotate both through the deployment secret system.

Read the full security model and private reporting policy before exposing Sandbox beyond a trusted environment.

Operate and recover

Signal	Inspect	Do not do
`no_capacity`	Node freshness, resource headroom, labels, pressure, isolation tiers, and policy score.	Do not lower the isolation floor as a shortcut.
Repeated assignment	Lease expiry, worker reachability, operation idempotency, and assignment completion logs.	Do not create a second sandbox blindly.
Wait timeout	Read the original operation and current sandbox state.	Do not assume the underlying mutation failed.
Truncated output	Exit code, stderr, operation error, and configured output bounds.	Do not report complete output.

The operations runbook covers health, metrics, logs, backups, restoration, upgrades, cleanup, and capacity drills.

Canonical Markdown

These files are served as raw Markdown with no-cache and nosniff headers. Humans can read them directly; agents can fetch only the reference needed for the current task.

Agent indexRouting, install, lifecycle, MCP surface, invariants, and result contract. OverviewProject intent, current capabilities, quickstart, diagrams, and repository map. ArchitectureComponents, trust boundaries, request flow, failure handling, and scaling. AEGISRisk weights, isolation floor, filters, ranking, and determinism. CLIConnection, lifecycle, agent profiles, waiting, JSON, and MCP config. MCPMajor clients, 12 tools, resources, prompts, errors, and testing. Server setupDedicated Linux host, Compose, secrets, health, lifecycle test, and operating checklist. Client PC setupOne-command install, secret-safe connection, MCP clients, and cleanup test. Custom public domainsWildcard DNS, Cloudflare certificates, Full (strict), direct edge, and hidden origin. Public tunnelsPer-sandbox networks, exact-host routes, custom HTTPS domains, and cleanup behavior. HTTP APIOperator and worker routes, auth, idempotency, and execution limits. Coding agentsProfiles, images, credentials, customization, and version policy. ConfigurationTyped TOML keys, environment overrides, policy, state, and runtime. DeploymentCompose, systemd, Kubernetes, edge, releases, scaling, and backup. OperationsHealth, incidents, metrics, logs, upgrades, and capacity drills. Security modelClaims, Docker boundary, external drivers, threats, and secrets. Runtime driverVersioned protocol and hard requirements for external isolation. DevelopmentToolchain, checks, test layers, performance, and quality gates. RoadmapExplicit future production gates—never current feature claims. Security reportingPrivate disclosure process, scope, evidence, and response expectations.

machine discovery

llms.txt is the compact crawler and LLM index. index.md is the operational entry point. Both link only to canonical raw references.