# 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

```bash title="CLI"
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?"
```

```bash title="curl"
curl -sS -X POST https://sandboxer.com/api/v1/sandboxes/sb_k3v9x2mq/prompt \
  -H "Authorization: Bearer $SANDBOXER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"claude-code","prompt":"Fix the failing tests and commit"}'
```

```typescript title="TypeScript"
const queued = await sbx.prompt({ sandboxId: "sb_k3v9x2mq", provider: "claude-code", prompt: "Fix the failing tests and commit" });
console.log(queued.promptId, queued.conversationId);
```

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

```bash
sbx events sb_k3v9x2mq --follow
```

```bash title="Polling"
curl -sS "https://sandboxer.com/api/v1/sandboxes/sb_k3v9x2mq/events?limit=100" \
  -H "Authorization: Bearer $SANDBOXER_API_KEY"
```

```bash title="Server-sent events"
curl -N -sS https://sandboxer.com/api/v1/sandboxes/sb_k3v9x2mq/events \
  -H "Authorization: Bearer $SANDBOXER_API_KEY" \
  -H "Accept: text/event-stream"
```

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:

```bash
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 |

```bash
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](/docs/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](/docs/snapshots#named-snapshots-templates) 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](/docs/hosting) or files. The integrated agents are a convenience, not a requirement.
