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-code",
    "display_name": "Claude Code",
    "available": true,
    "runtime_count": 2,
    "compatibility_level": "full",
    "versions": ["1.0.22"]
  },
  {
    "agent_id": "gemini-cli",
    "display_name": "Gemini CLI",
    "available": true,
    "runtime_count": 1,
    "compatibility_level": "full",
    "versions": ["2.1.0"]
  }
]

Supported Agents: claude-code, codex, gemini-cli, opencode, kimi-code

Runtime Management (Platform Admin)

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-code", "gemini-cli"],
    "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-code", "gemini-cli", "opencode"],
  "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.