# div agent

> Reference for div agent, the command that sends tasks to the coding agents in a sandbox and prints their conversations.

## Synopsis

```text
div agent <subcommand> [arguments] [flags]
```

Sends tasks to the coding agents in a sandbox, Claude Code and OpenCode, and prints their conversations. It uses the API key that [`div login`](https://docs.divergentlabs.xyz/compute/cli/login.md) saves. `prompt` needs the `sandboxes:write` scope, and `conversations` needs `sandboxes:read`.

`<sandbox>` is a sandbox's name or id, and the sandbox must be running. `<conversation>` is a conversation's id, such as `c-261001095246-c2f8`.

The agent uses your own API key or subscription. See [Give the agent credentials](https://docs.divergentlabs.xyz/sandboxes/agents.md#give-the-agent-credentials).

## Subcommands

| Subcommand | Description |
| --- | --- |
| [`prompt`](#prompt) | Send a task to an agent and print its messages. |
| [`conversations`](#conversations) | List a sandbox's conversations, or print one. |

## prompt

```text
div agent prompt <sandbox> "<task>" [--new | --resume <conversation>] [--harness claude|opencode] [--model <id>] [--detach] [--json]
```

Sends a task to the sandbox's most recent conversation, or starts one, and prints the agent's work until the turn ends. If a turn is running in the conversation, the task waits in a queue and runs next.

| Flag | Description | Default |
| --- | --- | --- |
| `--new` | Start a new conversation. | off |
| `--resume <conversation>` | Continue this conversation. | the most recent conversation |
| `--harness <harness>` | `claude` for Claude Code, or `opencode` for OpenCode. A harness that differs from the most recent conversation's starts a new conversation. With `--resume`, it must match the conversation's. | `claude` |
| `--model <id>` | Claude Code: `sonnet`, `opus`, `haiku`, or a full model name. OpenCode: `provider/model`, for example `anthropic/claude-sonnet-4-5`, or one of OpenCode's own `opencode/…` models, which need no key. The conversation keeps the model for later turns. | the harness's default |
| `--detach` | Print the conversation's id on stdout and return without following the turn. | off |
| `--json` | Print the turn's events as JSON lines on stdout instead of the usual output. | off |

- The prompt can be up to 262,144 characters.
- A sandbox runs up to one conversation at a time per GiB of memory: 2 on `small`, 4 on `standard`, 8 on `large`, 16 on `xl`. A task queued behind a running turn does not count toward the limit.
- Ctrl-C stops following. The turn continues in the sandbox. Print it later with [`conversations`](#conversations).
- A running turn counts as use, so the sandbox is not stopped as idle.

**Output.** The agent's messages on stdout. Each tool call, and a last line with the outcome and the conversation's id, on stderr. Values of the sandbox's secrets are masked.

With `--json`, one event per line on stdout:

| Field | Description |
| --- | --- |
| `seq` | The event's position in the conversation. |
| `at` | When it happened, in ISO 8601. |
| `turn` | The turn's number in the conversation. |
| `type` | `prompt`, `message`, `tool_call`, `tool_result`, `turn_finished` or `error`. |

| Type | Fields |
| --- | --- |
| `prompt` | `text`, `model` |
| `message` | `text`: the agent's words. |
| `tool_call` | `id`, `name`, `input` |
| `tool_result` | `id`, `output` (cut at 65,536 characters), `error` |
| `turn_finished` | `status` (`finished`, `interrupted` or `failed`), `input_tokens`, `output_tokens` |
| `error` | `code`, `message` |

**Exit code.** `0` when the turn finishes, `1` when it fails or the prompt is refused, `130` when the turn is interrupted or you press Ctrl-C.

**Examples**

```bash
div agent prompt $SB "Run the tests and fix the first failure."
div agent prompt $SB --new --harness opencode --model anthropic/claude-sonnet-4-5 "Write a README."
CONV=$(div agent prompt $SB --detach "Upgrade every dependency and fix what breaks.")
div agent prompt $SB --json "List the open TODOs." | jq -r 'select(.type == "message") | .text'
```

## conversations

```text
div agent conversations <sandbox> [<conversation>] [-f] [--json]
```

Without `<conversation>`, lists the sandbox's conversations, most recently active first. With it, prints that conversation's prompts, messages and tool calls.

| Flag | Description | Default |
| --- | --- | --- |
| `-f`, `--follow` | With `<conversation>`: keep printing new events while a turn runs or waits in the queue. Ctrl-C stops following. | off |
| `--json` | List: the full API response. Conversation: events as JSON lines, as in [`prompt`](#prompt). | off |

**Output.** The list has one row per conversation: id, harness, model, status (with the number of queued prompts, if any), number of turns, and the start of the conversation's first prompt. Status is one of `idle`, `running`, `queued`, `failed` or `interrupted`.

A conversation prints as `prompt` does: messages on stdout, tool calls and outcomes on stderr.

**Examples**

```bash
div agent conversations $SB
div agent conversations $SB c-261001095246-c2f8 -f
```

## Errors

The API's message is printed as it is, with what to do next.

| Code | What to do |
| --- | --- |
| `credentials_missing` | The agent has no key or sign-in for this harness or model. Create a sandbox with `--secret ANTHROPIC_API_KEY`, or sign in over [`div sandbox ssh`](https://docs.divergentlabs.xyz/sandboxes/cli/sandbox.md#ssh). See [Give the agent credentials](https://docs.divergentlabs.xyz/sandboxes/agents.md#give-the-agent-credentials). |
| `agent_unavailable` | The sandbox was created before agents were available. Create a new sandbox with `div sandbox create`. |
| `not_running` | The sandbox is stopped. Resume it with `div sandbox resume`. |
| `too_many_turns` | The sandbox runs as many conversations as its size allows. Wait for one to finish, or create a larger sandbox with `div sandbox create --size`. |
| `conversation_not_found` | No conversation has that id in this sandbox. List them with `div agent conversations`. |
| `unknown_harness` | Use `--harness claude` or `--harness opencode`. |
| `harness_mismatch` | The conversation runs a different harness. Leave out `--harness`, or start a new conversation with `--new`. |
| `unknown_model` | OpenCode names a model as `provider/model`. Fix `--model`. |
| `prompt_too_long` | The prompt is longer than 262,144 characters. Shorten it, or copy the details into a file with [`div sandbox cp`](https://docs.divergentlabs.xyz/sandboxes/cli/sandbox.md#cp) and name the file in the prompt. |

## Exit codes

| Code | When |
| --- | --- |
| `0` | The turn finished, or the subcommand succeeded. |
| `1` | The turn failed, or the API refused the request. The message says what to do next. |
| `2` | A subcommand, argument or flag was typed wrong. |
| `130` | The turn was interrupted, or you pressed Ctrl-C. |

These match [every `div` command](https://docs.divergentlabs.xyz/compute/cli/exit-codes.md).