Integrated agents
Every sandbox ships with Claude Code, Codex, OpenCode, Pi, Kimi and Mistral Vibe. Prompt them over the API, stream their work, run many conversations at once, steer or interrupt them.
You can always SSH in and run any agent by hand. Integrated agents save you the plumbing: Sandboxer starts the harness in the right directory with your keys, captures its output as structured events, keeps its session so the next prompt continues the thread, and runs several threads side by side.
Harnesses#
Provider (provider) |
Harness | Notes |
|---|---|---|
claude-code (alias claude) |
Claude Code | Native steering |
codex |
OpenAI Codex CLI | Native steering |
opencode |
OpenCode | Steering by interrupt-and-continue |
pi |
Pi | Native steering |
prime-agent (alias prime) |
Prime Agent | Coming soon: not installed in sandboxes yet |
kimi (alias kimi-code) |
Kimi Code CLI | |
mistral |
Mistral Vibe |
GET /provider-models returns the live catalog: each harness's models, the reasoning-effort levels each model accepts, and which models support fast mode.
Keys and logins#
Add provider credentials on the dashboard's Agents page — an API key per provider (subscription sign-in is coming) — and choose a default harness and model. Sandboxes whose environment passes agent credentials get them automatically. noEnv sandboxes never do; give those their own key with env (for example -e ANTHROPIC_API_KEY=…).
Prompt#
sbx prompt "Fix the failing tests and commit" # current sandbox, default harness
sbx prompt sb_k3v9x2mq --provider codex --model gpt-5.4 --reasoning-effort high "Refactor the auth module"
sbx prompt --attach ./screenshot.png "Why does the header overlap on mobile?"The call returns at once with promptId, conversationId and status: "queued". Poll GET /sandboxes/{id}/prompts/{promptId} until done, or stream events.
| Field | Meaning |
|---|---|
provider |
Which harness to run |
model |
A model id from /provider-models; omit for your dashboard default |
reasoningEffort |
none, low, medium, high, xhigh, max — whichever the model accepts |
fast |
Fast mode on models that support it (billed by the provider at its fast rate) |
new |
Start a new conversation |
conversationId |
Continue a specific conversation |
The agent runs as user in /home/user, with the sandbox's environment.
Events#
sbx events sb_k3v9x2mq --followcurl -sS "https://sandboxer.com/api/v1/sandboxes/sb_k3v9x2mq/events?limit=100" \
-H "Authorization: Bearer $SANDBOXER_API_KEY"Each event has id, type, timestamp, conversationId and data. The common types:
type |
data |
|---|---|
prompt |
prompt, status (queued → running → finished / failed / interrupted) |
response |
content, model, is_streaming for partial text, tools for tool-call batches |
steer |
message, native, mode |
usage_limit, compaction_complete |
provider-specific details |
Branch on type and ignore types you don't know — new ones appear over time. Filter to one thread with ?conversation=<id>.
Conversations in parallel#
A sandbox runs many conversations at once, each with its own harness process and history:
sbx prompt --new "Start the billing refactor" # conversation A
sbx prompt --new "Investigate the flaky e2e test" # conversation B, in parallel
sbx conversations # ids, prompt counts, running flags
sbx prompt --resume <A> "Now add tests"The concurrency limit per sandbox grows with its memory; beyond it, prompts queue. You can switch provider or model within a conversation — the history carries over. Conversations survive stop, resume and fork (and with memory-preserving resume, a turn that was running keeps running).
Steer and interrupt#
| You want to | Use | The running turn |
|---|---|---|
| Queue another task | sbx prompt / POST /prompt |
finishes first |
| Add an instruction mid-turn | sbx steer / POST /steer |
takes it into account and continues |
| Stop | sbx interrupt / POST /interrupt |
is discarded |
sbx steer sb_k3v9x2mq "Skip the integration tests; unit tests are enough"
sbx interrupt sb_k3v9x2mq --convo <conversationId>The steer response says whether the harness accepted it natively (native: true) or Sandboxer interrupted and immediately continued the same session with your message (native: false). The resulting steer event records the final mode: native, native-continued, fallback or late.
Computer use#
Every harness gets computer tools that drive the sandbox's desktop: screenshots, mouse, keyboard. Watch the desktop stream while a prompt does GUI work.
Customize#
Harnesses read their ordinary config files in the home directory — CLAUDE.md / AGENTS.md, MCP server configs, skills, settings. Commit them to your repo or bake them into a named snapshot and every sandbox from it behaves the same way.
Bring your own harness#
Nothing stops you from running your own agent: install it, run it as a systemd service or a detached command, and talk to it over a hosted port or files. The integrated agents are a convenience, not a requirement.