Dispatcher API¶

Go + Chi HTTP API. Base URL: http://localhost:8080/

Authentication: X-API-Key header for Controller-to-Dispatcher calls. X-Agent-Key header for agent protocol calls.

Tasks¶

Create Task¶

POST /tasks
X-API-Key: {api_key}
Content-Type: application/json

{
  "task_id": "uuid",
  "agent_image": "kohakku-agent-terminal:latest",
  "runtime_target": {
    "type": "local",
    "namespace": ""
  },
  "resources": {
    "cpu": "1",
    "memory": "2Gi"
  },
  "env": {
    "KEY": "value"
  },
  "ports": [
    {
      "container_port": 6080,
      "protocol": "tcp"
    }
  ],
  "brief_key": "briefs/guid/hash.json",
  "callback_url": "http://controller:8000/api/v1/tasks/guid/callback/",
  "callback_token": "token",
  "timeout_seconds": 3600
}

Response:

{
  "ok": true,
  "data": { "...task..." }
}

Ports field

ports is populated from the tier's port deps (resolved by the Controller). Omitted entirely for tiers with no port deps.

Get Task¶

GET /tasks/{id}
X-API-Key: {api_key}

Response:

{
  "ok": true,
  "data": {
    "task_id": "uuid",
    "status": "running",
    "started_at": "2026-01-15T10:30:00Z",
    "...": "..."
  }
}

List Tasks¶

GET /tasks?limit=50&offset=0
X-API-Key: {api_key}

Response:

{
  "ok": true,
  "data": {
    "tasks": ["..."],
    "total": 42
  }
}

Cancel Task¶

POST /tasks/{id}/cancel
X-API-Key: {api_key}

Response:

{
  "ok": true
}

Agent Protocol¶

These endpoints are called by agents running inside containers. Authenticated via X-Agent-Key -- a per-task key injected as an env var at spawn time.

Check-in¶

Called by the agent at boot. Confirms the agent is alive and retrieves its brief.

POST /agent/checkin
X-Agent-Key: {agent_key}
Content-Type: application/json

{
  "task_id": "uuid"
}

Response:

{
  "ok": true,
  "data": {
    "brief_key": "briefs/guid/hash.json",
    "env": {}
  }
}

Check-back¶

Called by the agent on completion or failure.

POST /agent/checkback
X-Agent-Key: {agent_key}
Content-Type: application/json

{
  "task_id": "uuid",
  "status": "completed",
  "result_key": "results/output.json",
  "result_metadata": {},
  "error": ""
}

Response:

{
  "ok": true
}

Progress Report¶

Called by the agent to report progress during execution.

POST /agent/progress
X-Agent-Key: {agent_key}
Content-Type: application/json

{
  "task_id": "uuid",
  "percentage": 60,
  "message": "Processing step 3/5...",
  "data": {}
}

Response:

{
  "ok": true
}

Health¶

Endpoint	Purpose
`GET /health`	Liveness -- service alive
`GET /ready`	Readiness -- database + Redis connectivity

Task State Machine¶

QUEUED
  | (container booting)
PROVISIONING
  | (agent checks in)
RUNNING
  | (exit 0)        | (exit != 0)      | (deadline exceeded)
COMPLETED         FAILED             TIMED_OUT

The Dispatcher owns this state in Redis. The agent moves it from QUEUED to RUNNING (at check-in) and RUNNING to terminal (at check-back).