Run Spinup Agents

Runtime commands use an agent runtime key (sk_agent_...) scoped to one agent ID. Use SPINUP_API_KEY for a one-off command or store the key in CLI config if this machine should use that runtime key by default. Issue or replace runtime keys with spinup agents runtime-key issue <agent>, the SDK, the public control-plane API, or the dashboard; the status and run commands below use the issued runtime key.

spinup agents runtime-key issue support-agent

Check status

SPINUP_API_KEY=sk_agent_... spinup agents status agent_01hxyz...

JSON output:

SPINUP_API_KEY=sk_agent_... spinup agents status agent_01hxyz... --json

Start a run

SPINUP_API_KEY=sk_agent_... spinup agents runs create agent_01hxyz... \
  --input "Run the full repository audit." \
  --model openrouter/anthropic/claude-sonnet-4-5 \
  --max-output-tokens 32000 \
  --timeout-seconds 1800 \
  --idempotency-key repo-audit-2026-06-14

The create command returns quickly after Spinup has accepted and queued the run. --timeout-seconds is the execution deadline for the accepted run, not how long the create request stays open. It controls how long the runtime may spend once the dispatcher starts the run, and async run creation currently accepts values up to 1800 seconds. Reusing the same idempotency key with the same request returns the existing run; reusing it with a different request fails with a conflict.

Supported create flags:

• --input: prompt text to run
• --harness: openclaw or hermes
• --model: model override for this run as <provider>/<model>
• --max-output-tokens: model output cap for --model
• --timeout-seconds: execution deadline for the run, currently up to 1800 seconds
• --idempotency-key: replay-safe caller key for retries
• --session-id: continue a prior harness session
• --workspace: safe relative runtime workspace path
• --cwd: safe relative runtime working directory

List runs

SPINUP_API_KEY=sk_agent_... spinup agents runs list agent_01hxyz...

Use pagination flags when needed:

SPINUP_API_KEY=sk_agent_... spinup agents runs list agent_01hxyz... --limit 20 --cursor "v1:..."

Get one run

SPINUP_API_KEY=sk_agent_... spinup agents runs get agent_01hxyz... run_01hxyz...

Wait for a run

SPINUP_API_KEY=sk_agent_... spinup agents runs wait agent_01hxyz... run_01hxyz... --timeout-seconds 1800

runs wait polls until the run is completed, failed, or timed_out. Its --timeout-seconds flag is only the local wait budget for this CLI process; it does not change the run's execution deadline after the run has already been created. It exits non-zero for terminal non-completed runs.

Run history returns support-safe fields only. It includes lifecycle timestamps, harness selection, request options, final output, generic error state, warnings, usage counts, phase evidence, and bounded evidence counts. It does not return the original prompt input, raw stdout/stderr, raw provider payloads, billing cost details, audit events, actor IDs, internal session IDs, Worker Host IDs, microVM IDs, or secret/env maps.