Skip to main content
Agent Runs are the durable agent layer of the compute runtime. A run binds a ready Workspace, ready Sandbox, one harness declared by the Workspace’s pinned Environment, and a durable agent Execution.
Agent Runs are provider-neutral. Requests select an Environment harness ID, not a compute provider or a shell command.

​
Declare a harness

An Environment manifest must explicitly allow every agent harness:
Harnesses are bounded argv vectors. The manifest does not accept shell command templates or environment-variable values. A run’s model, tools, and environment keys must be subsets of these harness declarations; environment keys must also appear in the Environment-level environmentKeys list.
Generic secretReferences are rejected by the current Daytona and Sail providers. Secret-backed Agent Runs remain unavailable until tenant-scoped provider-vault bindings are implemented.

​
Create a run

The 202 response contains the durable Run and Operation. Reusing the same idempotency key with the same request replays that result; using it with a different request returns 409. The Operation resource uses the Run’s public ID and identifies its containing Sandbox through resource.parent. Input bytes are written to private immutable Artifact storage. PostgreSQL and Run events contain only the input digest and safe metadata. The initial, steering, and cancellation harness envelopes carry the selected model, bounded tool names, selected environment-key names, and safe endpoint metadata when a Run uses an authenticated Endpoint. The runtime re-derives these controls from durable state before delivery. Provider processes inherit only the requested environment-key subset, never every secret present in the Sandbox.

​
CLI and MCP

Keep run input out of shell history. The CLI accepts the complete request from a file or stdin and returns the exact API DTO with global --json:
The event command reconnects with Last-Event-ID and exits nonzero when the Run fails, is cancelled or times out. Over MCP, use create_agent_run, get_agent_run, get_agent_run_event_snapshot, steer_agent_run, cancel_agent_run and list_agent_run_artifacts. Snapshot calls return nextAfter; pass it as the next afterSequence.

​
Compute pricing

Sandbox Offers, Quotes, and Sandboxes disclose the compute provider. Requests remain provider-neutral and cannot name or override a provider. The pricing object also discloses billingModel:
  • reserved settles the first reserved increment when the Sandbox becomes ready, then bills subsequent full increments and a final partial increment at the sealed Quote rate.
  • observed releases the initial wallet hold when the Sandbox becomes ready, then bills completed minute-aligned windows from the provider’s reported actual spend after its reporting lag. Provider nano-USD estimates are rounded conservatively up to exact six-decimal USD.
The initial hold is not a final charge for an observed offer. Usage windows are durably reconciled so delayed provider reporting retries instead of silently creating an unbilled interval.

​
Follow and steer

Events are ordered by sequence. Reconnect an SSE client with the last received sequence:
Steering uses that sequence as an optimistic cursor:
A stale afterSequence is rejected. Cancellation is also an idempotent mutation at POST /v1/agent-runs/{id}/cancel.

​
Artifacts and privacy

List metadata with GET /v1/agent-runs/{id}/artifacts. Fetch one Artifact to mint a fresh short-lived download URL:
Metadata listing requires compute read. Minting a download URL requires compute manage; read-only API keys and organization members are refused. Prompts, tool arguments, tool output, logs, checkpoints, and generated files never appear in event payloads. Unrecognized stdout and all stderr are captured as bounded private log Artifacts. Cross-organization identifiers return the same 404 as unknown identifiers. Agent input, steering, output, log, checkpoint, and file bytes are retained for seven days by default, measured from each Artifact’s availableAt time. The Run, its events, and Artifact metadata remain durable after those bytes expire. Expired or deleted Artifacts do not return a download URL. Cleanup deletes the exact immutable object generation recorded for the Artifact. If storage deletion fails, metadata remains available and cleanup retries later; it is marked deleted only after storage confirms deletion.