Coding agents and setup

Run coding agents (Claude Code, Codex, Gemini CLI, OpenCode, ...) inside any sandbox, and set them up on this machine.

sandbox.agents() (or guest.agents()) runs a harness over the Agent Client Protocol: normalized events, follow-ups, interrupts and results. Runs outlive the handle that started them.

Agents in a sandbox#

Methods of Sandbox.

`Sandbox.agents`#

Coding agents inside this sandbox (needs cua-spacesd): run a harness over ACP, stream normalized events, follow up, interrupt, collect results; runs outlive this handle.

async def agents(self) -> Agents

Returns Agents · Async · Raises CuaError

Agents through a spacesd client#

Methods of SpacesdClient.

`SpacesdClient.agents`#

Coding agents in this guest.

async def agents(self) -> Agents

Returns Agents · Async · Raises CuaError

`Agents`#

Agent runs in one sandbox.

Returned by Sandbox.agents, SpacesdClient.agents.

Method	Description
`ensure`	Installs harnesses or apps (`["claude-code", "blender"]`: harness ids or installable ids) now; returns the progress lines.
`get`	A handle for an existing run (started by any client).
`list`	Every run in the sandbox, newest first.
`run`	Starts `harness` on `prompt` and returns at once; the run lives in the sandbox (fire and forget) until it is stopped.

`Agents.ensure`#

Installs harnesses or apps (["claude-code", "blender"]: harness ids or installable ids) now; returns the progress lines.

async def ensure(self, ids: List[str]) -> List[str]

Parameter	Type	Default
`ids`	`Vec<String>`	required

Returns Vec<String> · Async · Raises CuaError

`Agents.get`#

A handle for an existing run (started by any client).

async def get(self, run_id: str) -> AgentRun

Parameter	Type	Default
`run_id`	`String`	required

Returns AgentRun · Async · Raises CuaError

`Agents.list`#

Every run in the sandbox, newest first.

async def list(self) -> List[AgentRunInfo]

Returns Vec<AgentRunInfo> · Async · Raises CuaError

`Agents.run`#

Starts harness on prompt and returns at once; the run lives in the sandbox (fire and forget) until it is stopped.

async def run(self, harness: str, prompt: str, options: Optional[AgentRunOptions]) -> AgentRun

Parameter	Type	Default
`harness`	`String`	required
`prompt`	`String`	required
`options`	`Option<AgentRunOptions>`	required

Returns AgentRun · Async · Raises CuaError

`AgentRun`#

One run.

Returned by Agents.get, Agents.run.

Method	Description
`artifacts`	Files the run created or changed in its working directory.
`events`	Events after `cursor` (0: from the start), at most `max`.
`interrupt`	Cancels the turn in flight; the session stays open.
`remove`	Stops the run and deletes its directory (secrets included).
`result`	The last turn's outcome.
`send`	A follow-up in the same session (queued while a turn runs).
`status`
`stop`	Stops the run and verifies its process is gone.
`wait`	Waits until no turn is running (at most `timeout_ms`), then returns the result.

Accessor	Returns	Description
`harness()`	`String`
`run_id()`	`String`

`AgentRun.artifacts`#

Files the run created or changed in its working directory.

async def artifacts(self) -> List[AgentArtifact]

Returns Vec<AgentArtifact> · Async · Raises CuaError

`AgentRun.events`#

Events after cursor (0: from the start), at most max.

async def events(self, cursor: int, max: Optional[int]) -> AgentEventPage

Parameter	Type	Default
`cursor`	`u64`	required
`max`	`Option<u32>`	required

Returns AgentEventPage · Async · Raises CuaError

`AgentRun.interrupt`#

Cancels the turn in flight; the session stays open.

async def interrupt(self) -> AgentRunInfo

Returns AgentRunInfo · Async · Raises CuaError

`AgentRun.remove`#

Stops the run and deletes its directory (secrets included).

async def remove(self) -> None

Async · Raises CuaError

`AgentRun.result`#

The last turn's outcome.

async def result(self) -> AgentRunResult

Returns AgentRunResult · Async · Raises CuaError

`AgentRun.send`#

A follow-up in the same session (queued while a turn runs).

async def send(self, text: str, files: Optional[List[AgentFile]]) -> AgentRunInfo

Parameter	Type	Default
`text`	`String`	required
`files`	`Option<Vec<AgentFile>>`	required

Returns AgentRunInfo · Async · Raises CuaError

`AgentRun.status`#

async def status(self) -> AgentRunInfo

Returns AgentRunInfo · Async · Raises CuaError

`AgentRun.stop`#

Stops the run and verifies its process is gone.

async def stop(self) -> AgentRunInfo

Returns AgentRunInfo · Async · Raises CuaError

`AgentRun.wait`#

Waits until no turn is running (at most timeout_ms), then returns the result.

async def wait(self, timeout_ms: Optional[int]) -> AgentRunResult

Parameter	Type	Default
`timeout_ms`	`Option<u64>`	required

Returns AgentRunResult · Async · Raises CuaError

`AgentRunOptions` record#

Options for Agents.run. Every field is optional.

Field	Type	Default	Description
`cwd`	`Option<String>`	`None`	Working directory in the sandbox (default: the run's own).
`repo`	`Option<String>`	`None`	Git URL cloned into the working directory first.
`branch`	`Option<String>`	`None`
`env`	`HashMap<String, String>`	`[:]`	Env for the agent only (API keys): written 0600 in the run, redacted from its event log, never in argv.
`env_from_host` / `envFromHost`	`Vec<String>`	`[]`	Provider key variables copied from THIS process's environment (`["ANTHROPIC_API_KEY"]`); only known provider key names.
`model`	`Option<String>`	`None`	Model id.
`base_url` / `baseUrl`	`Option<String>`	`None`	A custom model endpoint (proxy, gateway, compatible server).
`wire`	`Option<String>`	`None`	Its wire format: `anthropic`, `openai-responses`, `openai-chat`, `gemini` (default: the harness's own).
`mcp_servers` / `mcpServers`	`Vec<AgentRunMcpServer>`	`[]`
`sandbox_mcp` / `sandboxMcp`	`Option<bool>`	`None`	Give the agent the sandbox's own MCP (cua-driver). Default true.
`skills`	`Option<bool>`	`None`	Copy the cua skills into the harness. Default true.
`install`	`Option<bool>`	`None`	Install what the harness needs. Default true.
`files`	`Vec<AgentFile>`	`[]`
`exit_when_idle` / `exitWhenIdle`	`bool`	`false`	Stop (resumably) once the queue is empty: fire-and-forget.
`label`	`Option<String>`	`None`

`AgentRunMcpServer` record#

An MCP server a run's agent gets: url (streamable HTTP, as reachable from inside the sandbox) or command (stdio, run in the sandbox).

Field	Type	Default	Description
`name`	`String`		Name the agent sees.
`url`	`Option<String>`	`None`
`headers`	`HashMap<String, String>`	`[:]`	Header values (secrets allowed: they travel like env keys).
`command`	`Option<String>`	`None`
`args`	`Vec<String>`	`[]`
`env`	`HashMap<String, String>`	`[:]`

`AgentFile` record#

A file for the first prompt or a follow-up.

Field	Type	Default	Description
`name`	`String`		File name in the run's `attachments/`.
`bytes`	`Vec<u8>`

`AgentEvent` record#

One normalized event.

Field	Type	Description
`seq`	`u64`
`ts_ms` / `tsMs`	`u64`
`turn`	`u32`
`kind`	`String`	`message`, `thought`, `tool_call`, `tool_update`, `plan`, `usage`, `permission`, `turn_started`, `turn_ended`, `install`, `error`, `exited`, ... (see `harnesses()`).
`text`	`Option<String>`
`tool_id` / `toolId`	`Option<String>`
`tool_title` / `toolTitle`	`Option<String>`
`tool_kind` / `toolKind`	`Option<String>`
`tool_status` / `toolStatus`	`Option<String>`
`stop_reason` / `stopReason`	`Option<String>`
`category`	`String`	How a conversation view shows it: `message` (the agent's words), `user` (the prompt as the agent got it), `activity` (a muted one-line row: install, thinking, tools, plan, turn end, notice, error, exit) or `hidden`. See `AgentTranscript`.
`summary`	`Option<String>`	One short line for an `activity` event.
`line`	`Option<String>`	One human-readable line, when the kind has one.
`json`	`String`	The event as written (ACP payload included), JSON.

`AgentEventPage` record#

A page of events.

Returned by AgentRun.events.

Field	Type	Description
`events`	`Vec<AgentEvent>`
`cursor`	`u64`	Pass back to continue.
`caught_up` / `caughtUp`	`bool`	Nothing more is written yet.

`AgentRunInfo` record#

A run's state.

Returned by AgentRun.interrupt, AgentRun.send, AgentRun.status, AgentRun.stop, Agents.list.

Field	Type	Description
`run_id` / `runId`	`String`
`harness`	`Option<String>`
`status`	`String`	`running`, `idle`, `failed`, `crashed`, `unknown`.
`phase`	`String`	`installing`, `starting`, `working`, `waiting`, `exited`, ...
`reason`	`String`
`turn`	`u32`
`alive`	`Option<bool>`
`accepts_message` / `acceptsMessage`	`bool`	A follow-up sent now starts the next turn (not mid-turn).
`prompt`	`Option<String>`
`label`	`Option<String>`
`created_at` / `createdAt`	`Option<f64>`	Unix seconds.
`json`	`String`

`AgentRunResult` record#

What the last turn produced.

Returned by AgentRun.result, AgentRun.wait.

Field	Type	Description
`run_id` / `runId`	`String`
`status`	`String`
`turn`	`u32`
`text`	`String`	The agent's messages in the last turn.
`stop_reason` / `stopReason`	`Option<String>`
`usage_json` / `usageJson`	`Option<String>`
`error`	`Option<String>`
`tool_calls` / `toolCalls`	`u32`

`AgentArtifact` record#

A file the run created or changed.

Returned by AgentRun.artifacts.

Field	Type	Default	Description
`path`	`String`
`size`	`u64`
`modified_ms` / `modifiedMs`	`u64`

`agent_harnesses`#

The harnesses, their readiness, installs, key variables and limits, as JSON.

def agent_harnesses() -> str

Returns String

`AgentTranscript`#

A run's events folded into conversation items, the same rule in every language: the agent's message chunks join into message items, the prompt is a user item (never repeated as agent text), and consecutive activity of one turn folds into one activity group. Absorbing an event twice changes nothing, so a poll can re-read a page.

Method	Description
`new`	An empty transcript.
`absorb`	Adds events from `AgentRun.events`.
`absorb_json`	Adds the events of an `agent_events` result (`Space.agent_events`, the MCP tool), or a JSON array of events.
`note`	Adds a line the app itself produced (a start note, "queued") as an activity step of `turn`.

Accessor	Returns	Description
`cursor()`	`u64`	The highest `agent_events` cursor absorbed: pass it back to read on.
`items()`	`Vec<AgentTranscriptItem>`	The items so far.
`preview()`	`Option<String>`	The agent's last message on one line (a roster preview), `None` before it has said anything. Activity is never a preview.
`revision()`	`u64`	Changes whenever the items do.

`AgentTranscript.new`#

An empty transcript.

AgentTranscript()

Returns AgentTranscript

`AgentTranscript.absorb`#

Adds events from AgentRun.events.

def absorb(self, events: List[AgentEvent]) -> None

Parameter	Type	Default
`events`	`Vec<AgentEvent>`	required

`AgentTranscript.absorb_json`#

Adds the events of an agent_events result (Space.agent_events, the MCP tool), or a JSON array of events. Returns the page's cursor (also kept, see AgentTranscript.cursor) when it has one.

def absorb_json(self, json: str) -> Optional[int]

Parameter	Type	Default
`json`	`String`	required

Returns Option<u64> · Raises CuaError

`AgentTranscript.note`#

Adds a line the app itself produced (a start note, "queued") as an activity step of turn.

def note(self, turn: int, text: str) -> None

Parameter	Type	Default
`turn`	`u32`	required
`text`	`String`	required

`AgentTranscriptItem` record#

One item of an AgentTranscript.

Returned by AgentTranscript.items.

Field	Type	Description
`kind`	`String`	`message` (a bubble or prose), `user` (the prompt as the agent got it; skip it when the app shows what the user typed) or `activity` (a muted, collapsible group of one-line steps).
`turn`	`u32`	Turn number (0 before the first prompt).
`text`	`String`	The message or prompt; for `activity`, the group summary (`5 steps`).
`steps`	`Vec<String>`	`activity` only: one line per step.

`agent_event_category`#

The category of an event kind: message, user, activity or hidden (the rule AgentEvent.category and AgentTranscript use).

def agent_event_category(kind: str) -> str

Parameter	Type	Default
`kind`	`String`	required

Returns String

Coding agents and setup

Agents in a sandbox#

Sandbox.agents#

Agents through a spacesd client#

SpacesdClient.agents#

Agents#

Agents.ensure#

Agents.get#

Agents.list#

Agents.run#

AgentRun#

AgentRun.artifacts#

AgentRun.events#

AgentRun.interrupt#

AgentRun.remove#

AgentRun.result#

AgentRun.send#

AgentRun.status#

AgentRun.stop#

AgentRun.wait#

AgentRunOptions record#

AgentRunMcpServer record#

AgentFile record#

AgentEvent record#

AgentEventPage record#

AgentRunInfo record#

AgentRunResult record#

AgentArtifact record#

agent_harnesses#

AgentTranscript#

AgentTranscript.new#

AgentTranscript.absorb#

AgentTranscript.absorb_json#

AgentTranscript.note#

AgentTranscriptItem record#

agent_event_category#

`Sandbox.agents`#

`SpacesdClient.agents`#

`Agents`#

`Agents.ensure`#

`Agents.get`#

`Agents.list`#

`Agents.run`#

`AgentRun`#

`AgentRun.artifacts`#

`AgentRun.events`#

`AgentRun.interrupt`#

`AgentRun.remove`#

`AgentRun.result`#

`AgentRun.send`#

`AgentRun.status`#

`AgentRun.stop`#

`AgentRun.wait`#

`AgentRunOptions` record#

`AgentRunMcpServer` record#

`AgentFile` record#

`AgentEvent` record#

`AgentEventPage` record#

`AgentRunInfo` record#

`AgentRunResult` record#

`AgentArtifact` record#

`agent_harnesses`#

`AgentTranscript`#

`AgentTranscript.new`#

`AgentTranscript.absorb`#

`AgentTranscript.absorb_json`#

`AgentTranscript.note`#

`AgentTranscriptItem` record#

`agent_event_category`#