Runtimes & Agents API

Runtime daemons are local processes that execute AI agent tasks. They register with the server, poll for tasks, and report results.

Agent Discovery

List Available Agents

Returns all known agents aggregated from registered runtimes.

GET /api/v1/agents/available
Authorization: Bearer <token>

Response 200 OK

[
  {
    "agent_id": "claude",
    "display_name": "Claude Code",
    "available": true,
    "runtime_count": 2,
    "compatibility_level": "full",
    "versions": ["1.0.22"]
  },
  {
    "agent_id": "gemini",
    "display_name": "Gemini CLI",
    "available": true,
    "runtime_count": 1,
    "compatibility_level": "full",
    "versions": ["2.1.0"]
  }
]

Agent Integrations: claude, codex, copilot, gemini, opencode, kimi, mimo, qwen, codebuddy, qoder, trae, zcode, deepseek

Explicit Agent routing

Seven integrations require explicit selection: mimo, qwen, codebuddy, qoder, trae, zcode, and deepseek. RouterAgent automatic routing and default fallback exclude them. See installation version requirements. TraeCode CLI/ZCode retain live gates; ZCode also requires binary fingerprint approval. Harness adds exact-build/Node/platform acceptance and the personal-Runtime-only boundary described below.

Runtime Management (Platform Admin)

deepseek is the seventh explicit integration, a developer preview on Desktop/personal Runtimes only. Availability requires exactly 0.2.0-rc.2 and matching installed-build/Node/platform acceptance; discovery alone is not readiness. Shared Runtime inventories must not make it available for dispatch. Native Windows stays not-ready. Explicit overrides and attempt-chain telemetry preserve the canonical ID, while automatic routing/default fallback exclude it. See Harness installation.

List Runtimes

Requires platform admin.

GET /api/v1/runtimes
Authorization: Bearer <token>

Response 200 OK

[
  {
    "id": "uuid",
    "daemon_id": "mac-studio-01",
    "device_name": "Mac Studio M2",
    "status": "online",
    "available_agents": ["claude", "gemini", "mimo", "qwen"],
    "max_concurrent_tasks": 3,
    "last_heartbeat": "2026-01-01T00:00:00Z"
  }
]

Get Runtime

GET /api/v1/runtimes/{runtime_id}
Authorization: Bearer <token>

Remove Runtime

DELETE /api/v1/runtimes/{runtime_id}
Authorization: Bearer <token>

Cleanup Stale Runtimes

Remove runtimes that haven't sent a heartbeat recently.

POST /api/v1/runtimes/cleanup-stale
Authorization: Bearer <token>

Daemon Protocol

These endpoints are used by daemon processes, not human users.

Register Daemon

POST /api/v1/runtimes/register
Content-Type: application/json

{
  "daemon_id": "mac-studio-01",
  "hardware_id": "HW-ABC123",
  "device_name": "Mac Studio M2 Ultra",
  "available_agents": ["claude", "gemini", "opencode", "mimo", "qwen"],
  "max_concurrent_tasks": 3,
  "capabilities": { "docker": true, "gpu": false }
}

Heartbeat

POST /api/v1/runtimes/{runtime_id}/heartbeat
Content-Type: application/json

{
  "daemon_id": "mac-studio-01",
  "active_tasks": 1,
  "system_metrics": {
    "cpu_percent": 45.2,
    "memory_percent": 62.1
  }
}

Poll for Tasks

GET /api/v1/runtimes/{runtime_id}/tasks/poll

Report Progress

POST /api/v1/runtimes/{runtime_id}/tasks/{task_id}/progress
Content-Type: application/json

{
  "progress_percent": 60,
  "current_step": "Running tests",
  "files_changed": ["src/auth.py", "tests/test_auth.py"],
  "lines_added": 150,
  "lines_removed": 20
}

Complete Task

POST /api/v1/runtimes/{runtime_id}/tasks/{task_id}/complete
Content-Type: application/json

{
  "status": "success",
  "metrics": {
    "token_usage": 15000,
    "cost_usd": 0.45,
    "duration_seconds": 120
  },
  "artifacts": [],
  "git": {
    "branch": "feat/user-registration",
    "commit_sha": "abc123"
  }
}

On success, the server automatically creates a gate review, generates a PR, and updates the budget.