Set up a Sandbox client

A workstation needs only the client pieces. Install sandbox, sandbox-mcp, the Sandbox skill, a controller URL, and an API token. It does not need Docker, PostgreSQL, NATS, worker credentials, or Cloudflare credentials.

1. Install the client and agent integration

The full installer adds binaries, the cross-agent skill, and detected MCP registrations. It registers sandbox-mcp with Codex, Claude Code, and Gemini CLI, and publishes templates for OpenCode, Cursor, VS Code, Goose, Claude Desktop, Windsurf, Cline, Roo Code, and generic MCP clients.

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

Use the binary-only installer when no local agent integration is wanted.

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

2. Configure the controller connection

Obtain the public HTTPS controller URL and operator API token from the server administrator. Keep the token in the operating-system or agent secret store.

1234export SANDBOX_URL=https://sandbox.example.com
read -r -s -p 'Sandbox token: ' SANDBOX_TOKEN
printf '\n'
export SANDBOX_TOKEN

Do not put the token in shell history, a repository .env, MCP JSON, prompts, labels, or sandbox environment maps. The CLI stores only the non-secret controller URL; use SANDBOX_URL or --server for an explicit one-off target.

3. Verify the CLI

Check the deployment before an agent creates any resources.

12sandbox doctor
sandbox agent list

sandbox doctor must report the expected controller version and tunnel configuration. To share a service already running on the workstation, no managed sandbox is needed:

1sandbox http 4321

The hosted default uses the *.tunnel.yshubham.com wildcard. A self-hosted deployment sets SANDBOX_HTTP_RELAY=https://relay.tunnel.example.com. Keep the command attached; Ctrl-C revokes the exact-host route.

4. Register an MCP client

Every native client starts the same local stdio process. When a desktop app does not inherit your shell PATH, use the absolute sandbox-mcp path or a small local wrapper that reads credentials from the operating-system secret store.

1234567891011121314151617# Codex
codex mcp add sandbox -- sandbox-mcp

# Claude Code
claude mcp add --scope user --transport stdio sandbox -- sandbox-mcp

# Gemini CLI
gemini mcp add sandbox sandbox-mcp --scope user

# OpenCode guided setup
opencode mcp add

# VS Code / Copilot agent mode
code --add-mcp '{"name":"sandbox","type":"stdio","command":"sandbox-mcp"}'

# Goose, one session
goose session --with-extension sandbox-mcp

Cursor, Claude Desktop, Windsurf, Cline, Roo Code, and Gemini Code Assist use the shared mcpServers JSON envelope. Pi, Aider, and CommandCode use the CLI with the installed sandbox-platform skill when their host does not provide native MCP.

Use the verified client templates. Merge only the sandbox entry; never overwrite unrelated MCP servers.

5. Verify MCP behavior

Restart the agent after changing its MCP configuration. Ask it to read sandbox://capabilities and call sandbox_health, or perform a protocol-level check with the MCP Inspector:

123SANDBOX_URL=https://sandbox.example.com \
SANDBOX_TOKEN='read-from-your-secret-store' \
npx @modelcontextprotocol/inspector "$(command -v sandbox-mcp)"

The bridge exposes 12 lifecycle tools, three resources, and two workflow prompts. Public tunnel tools return the deployment-configured URL; use that URL exactly instead of rewriting http:// to https:// on the client.

6. Run and clean up a client test

A client smoke test should leave no active environment behind.

1234sandbox create --tenant workstation-smoke --image alpine:3.22 --ttl 300 --network deny
sandbox wait OPERATION_ID --timeout 120
sandbox exec SANDBOX_ID -- printf 'sandbox-client-ok\n'
sandbox delete SANDBOX_ID --wait

Confirm the delete operation succeeds. A stopped audit record can remain in the controller store after runtime containers, routes, and networks are gone. For the complete tool surface, continue with MCP and skills and CLI workflows. This guide follows the upstream client setup document.