SMsmolmachines
agents

Create an agent.

Changed on

Creates a managed agent and the machine it runs in. Requires the machine:create scope.

post/v1/agents

Request

Request body

allowHostsstring[]

Hosts the agent may reach beyond its model provider and package registry. The command harness has neither, so callers must name hosts or explicitly opt into unrestricted outbound access.

archstring nullable

amd64 or arm64. A session with checkpoints runs on amd64 unless pinned here.

checkpointsboolean nullable

Checkpoint after every turn so the session can be rewound or branched (default true).

cpusinteger nullable

vCPUs (default 2).

credentialstring nullable

A stored credential holding the model API key. The session's machine then never holds the key: the agent sees a placeholder and the node substitutes the key on requests to the provider, so turns need no key in their env. Its variable must be the one the harness reads (e.g. ANTHROPIC_API_KEY) and its hosts must include the provider's.

harnessstring nullable

claude-code (default), codex, opencode, or command.

imagestring nullable

Image for the command harness.

memoryMbinteger nullable

Memory in MiB (default 2048).

modelstring nullable

Model: optional for codex, required as provider/model for opencode.

namestring required

Session name, unique within the account.

openNetworkboolean

Allow all outbound traffic instead of the host allow-list.

programstring[]

Program for the command harness; the prompt is appended.

Response

Session created; its machine and harness are set up in the background (status starting, then ready or failed)

createdAtstring required
errorstring nullable
harnessstring required
machineIdstring nullable

The machine the session currently runs on (it changes on rewind).

modelstring nullable
namestring required
runningTurninteger nullable

The turn in progress, if any.

statusstring required

starting during setup, turning during a turn, cancelling, rewinding, forking, pausing, resuming, ready, deleting, or failed; stale work may read as interrupted.

Changes