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.

.md

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 --follow
curl -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.