Running code (exec)

exec runs work inside a sandbox on the managed API:

• POST /v1/sandboxes/{id}/exec — run in an existing running sandbox. Files and processes persist between execs; execs are serialized (one at a time, FIFO).

One-shot exec

The managed API doesn't expose a single-request one-shot exec. The collimate-rl rollout_once helper gives you the same one-call ergonomics — over the managed API it composes create → exec → delete for you.

The exec request

The body is a superset that supports several ways to express a step. Provide whichever fields you need; files are materialized first, then the command runs.

Field	Type	Description
command	string	A single shell command string. The simplest path.
code	string	Source code, run via the template's interpreter (e.g. python3).
commands	string[][]	A list of argv arrays, run sequentially.
files	FileSpec[]	Files written into the guest before the command runs.
timeout_seconds	integer	Max wall-clock for the exec (guest-side). The sandbox accepts up to 3600.
seed	string	Pin the guest CRNG for this exec — 64 hex chars. Omitted ⇒ fresh entropy. See replay.
egress	object	Per-exec egress policy override (net templates). See per-fork egress.

Tip

command, code, and commands are three ways to express the same step — pick one. Use files to stage a script or fixtures, then command to run them.

FileSpec

Field	Type	Description
path	string	Path inside the guest (relative to the working dir, or absolute).
content	string	File contents (UTF-8).

Text vs binary files

files writes text and appends a trailing newline to content that lacks one. For byte-exact transfers (binary payloads, no-EOF-newline), the Python SDK's Sandbox.upload_bytes / download move bytes exactly over the same exec channel, verified end-to-end with sha256. See Files.

Examples

Stage a file and run it:

curl https://api.collimate.ai/v1/sandboxes/sbx_9f2a1c7b3e40/exec \
  -H "Authorization: Bearer $COLLIMATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "files": [{ "path": "solve.py", "content": "print(6 * 7)" }],
        "command": "python3 solve.py",
        "timeout_seconds": 30
      }'

Run a batch of argv steps in order:

{
  "commands": [
    ["git", "clone", "https://github.com/acme/repo", "/w"],
    ["make", "-C", "/w", "test"]
  ],
  "timeout_seconds": 300
}

The exec response

{
  "id": "sbx_9f2a1c7b3e40",
  "stdout": "42\n",
  "stderr": "",
  "exit_code": 0,
  "fork_time_ms": 0.0,
  "exec_time_ms": 9.7,
  "total_time_ms": 10.2,
  "seed": "3a7f0b…",
  "seed_ack": "verified"
}

Field	Type	Description
id	string	The sandbox this exec ran in.
stdout	string	Captured standard output.
stderr	string	Captured standard error.
exit_code	integer	Process exit code.
fork_time_ms	number	Fork time (0 for a warm session exec).
exec_time_ms	number	Time the command spent running in the guest.
total_time_ms	number	End-to-end server-side time.
seed	string	The 32-byte guest CRNG seed this exec ran with (hex).
seed_ack	string	Seed-ack verdict: verified, no-ack, off, or a mismatch. See replay.

Timeouts and output caps

The API holds the connection open while your command runs, up to timeout_seconds (max 3600). One exec's merged output is capped in the guest (16 MiB) — beyond that the frame is truncated, so stream large artifacts to a file and download them instead of printing them.

Next steps

• Files — byte-exact file IO over the exec channel.
• Deterministic replay — seeds and seed-ack.
• Per-fork egress — control what an exec can reach.