Core concepts
Jobs, scoring, tenancy, substrates (pods and VMs), and correlation ids.
Six ideas cover almost everything you will meet. The ones that catch people out are scoring vs status and which agent you may use.
Synchronous vs asynchronous
| Synchronous | Asynchronous | |
|---|---|---|
| Example | POST /sandbox/harbor/v2/run/datapoint | POST /sandbox/harbor/v2/jobs/execute-tasks |
| Returns | 200 with the complete result | 202 with a job_id |
| Good for | Short runs | Anything real — long tasks, many agents, cancellation |
Both put work on the same queue. Sync is not a way around a busy queue. On
timeout you get 504, the run keeps going, and the job id is in the headers —
poll it; do not resubmit.
A job and its lifecycle
| Status | Meaning |
|---|---|
queued | Accepted, waiting for capacity |
running | A worker is executing it |
succeeded | Finished with at least one real result |
failed | Nothing usable, or the platform gave up |
cancelled | You asked it to stop |
Prefer SSE …/events for live updates; resume with Last-Event-ID.
status is not a verdict
| Field | Answers |
|---|---|
status | Did orchestration finish? |
outcome.valid_for_scoring | Should you believe the numbers? |
Gate scoring on outcome.valid_for_scoring. Agent runs expose completion
instead — they are ungraded. Details: Run a benchmark.
Agents are catalog ids
You do not invent agent names. Pass an id from
GET /sandbox/v1/catalog?kind=agent. Agent runs reject anything else with 400.
| Common id | Role |
|---|---|
opencode | Recommended default coding agent |
claude-code, codex, gemini-cli, … | Other coding CLIs |
terminus-2 | Harbor reference agent with reasoning effort |
oracle | Task validator — needs solution/solve.sh |
Full list and examples: Supported agents.
Substrates: pods, VMs, external
Isolation is not “always a container”:
| Substrate | When |
|---|---|
| Pod | Harbor/Agent trials, CodeEdit, default long-lived, Linux desktop |
| VM | Windows desktop (ec2-vm) |
| External Mac | macOS desktop (aws-ec2-mac provider) |
The catalog profile driver_hint selects the substrate. Callers use the same
Sandboxes API. See Architecture.
Artifacts
List then download — not returned inline.
| Call | Gives you |
|---|---|
GET …/jobs/{job_id}/artifacts | Inventory |
GET …/jobs/{job_id}/artifacts/archive | Time-limited archive URL |
Artifacts expire. Download what you need to keep.
Tenancy: tenant and project
Every request resolves to tenant:project for billing, quota, and isolation.
Jobs are visible only to the same tenancy — otherwise 404 (same as missing).
Correlation id
Send x-correlation-id once per logical run. It appears in logs, traces, and
Langfuse. Observability.