Agent Runtime

Start a run

export SANDBOX_GATEWAY_URL="${SANDBOX_GATEWAY_URL:-http://localhost:8780}"

curl -sS -H "X-Api-Key: dev-local-key" \
  -H "x-correlation-id: agent-run-42" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "opencode",
    "instruction": "Propose a plan to fix the failing test",
    "model": "anthropic/claude-sonnet-4-5",
    "workspace": {"files": {"notes.txt": "context"}},
    "harbor_extensions": {
      "opencode_agent": "plan",
      "agent_env": {"POSTMAN": "1"}
    }
  }' \
  "$SANDBOX_GATEWAY_URL/sandbox/agent/v1/runs"

Returns 202 with job_id when queued via Pub/Sub worker. The correlation id propagates through the worker for logs and Langfuse — see Observability.

Use "opencode_agent": "build" for full tools. This sets OpenCode default_agent in opencode.json — not a Harbor --mode flag. Applies only when agent_id is opencode.

To define custom OpenCode agents (e.g. a read-only review subagent), add harbor_extensions.opencode_config. See Custom agents (opencode_config).

Workspace

Optional workspace object supports inline files, archive_url, and Harbor-native mcp_servers for OpenCode/MCP tooling.

Strict catalog

Only Tier 1 catalog agent_id values are accepted. Use GET /sandbox/v1/catalog?kind=agent or GET /sandbox/agent/v1/agents to discover IDs.

API reference: Agent Runtime.