div agent

Synopsis

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

Subcommands

Subcommand	Description
prompt	Send a task to an agent and print its messages.
conversations	List a sandbox’s conversations, or print one.

prompt

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.
• 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

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

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

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. See 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 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.