> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox terminal workbench

> Share a Ghostty or Herdr dashboard with JSON CLI agents, inspect workers and tasks, and use the separate local Docker backend.

The workbench pairs a terminal dashboard with JSON commands. From the reviewed Sandbox
checkout, the launcher uses installed workspace dependencies without rebuilding at startup:

```bash theme={null}
./sandboxctl --help
./sandboxctl --profile development tui
```

CLI **3.3.0** provides `stateset`, `stateset-sandbox`, and `sandboxctl`. CLI source requires
Node 20+; SDK/controller workspace builds need supported Node 20.19+ or 22.12+.
Source candidates and installed package publication are separate.

## Hosted and local backends

API mode uses your CLI profile/credentials. Local Docker uses a cached image and no hosted key:

```bash theme={null}
./sandboxctl --backend docker --image node:20-bookworm-slim tui \
  --cpus 1 --memory 1Gi --timeout 600
./sandboxctl tui --read-only --filter paused
```

The image must already be cached. Docker is a developer backend, not the hosted Kubernetes/VM
boundary. Runtime images, hosted billing, registry, and inference-gateway capabilities differ.

## Dashboard controls

| Control | Action |
| - | - |
| `n` | Edit create settings; Enter reviews, then `y` submits |
| `/`, `t`, `o` | Search, sort, or inspect allocation/status summary |
| F2 or `:` | Search actions for the captured target |
| `c` | Connection diagnostics and refresh errors |
| `g`, `w` | Review a worker launch or inspect workers |
| `v` in worker/task views | Read bounded output/result evidence |
| `h` | Saved execution history/receipts |
| `l`, `m`, `a` | Delegate a task, open task board, or inspect session activity |

Late responses cannot update a changed view. Failed reads retain older output as stale;
stale snapshots block changes until refreshed. Worker log/result views validate identity,
base64 and size, retaining bounded decoded tails and distinct truncation/rotation metadata.
Observation never stops or restarts the worker.

## JSON commands

```bash theme={null}
./sandboxctl status
./sandboxctl show SANDBOX_ID
./sandboxctl ps SANDBOX_ID
./sandboxctl result SANDBOX_ID PROCESS_ID
```

Use actual retained IDs. Create/exec/lifecycle/spawn/task/team/kill commands have their own
help and mutation semantics. JSON parsing or an accepted request does not validate the
worker's artifacts or answer. Candidate create defaults to a separate **210-second**
`--startup-timeout` wait, without extending lifetime or ordinary read deadlines.

## Dedicated Ghostty workspace

```bash theme={null}
bash scripts/ghostty-sandbox.sh --check
bash scripts/ghostty-sandbox.sh --status
bash scripts/ghostty-sandbox.sh
```

The launcher creates a dedicated tmux-backed shell/TUI layout and scoped terminal settings,
without modifying global Ghostty config or launching a model/sandbox by itself. Closing
Ghostty can leave tmux and remote work running; reopening reattaches.

After the dashboard exits, `--dashboard` changes its profile/backend and
`--restore-dashboard` restores the previous configuration. Running dashboards/unrelated
commands cannot be replaced. Versioned status describes **local terminal** state, not API
connectivity. Recovery can bind the opaque status `--if-generation` token; stale observations
fail instead of launching. Changes serialize, with contention exiting 75.

Source: `docs/SANDBOX_WORKBENCH.md`, CLI guide, and Ghostty launcher at `67bc2370`, checked
October 20, 2026. Continue with [prepared tasks](/stateset-sandbox/agent-tasks) or
[execution recovery](/stateset-sandbox/execution-and-recovery).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.