Cortex — Frontend Developer Reference

Cortex is a Kubernetes-native AI agent orchestrator. It manages Claude Code agents running in Docker containers, coordinates work through NATS JetStream, and exposes real-time updates via WebSocket.

The hierarchy is simple: Projects contain Agents. Each agent runs in its own K8s pod with a git workspace. You interact with agents through a REST API and receive real-time events over WebSocket.

Entities

Project

A project maps to a git repository. Agents are scoped to a project.

{
  "id": "uuid",
  "name": "my-project",
  "description": "...",
  "repository_url": "https://github.com/org/repo.git",
  "repository_branch": "main",
  "default_model": "anthropic/claude-opus-4-6",
  "max_agents": 10,
  "agent_image": "...",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Agent

An agent is a Claude Code instance running in a K8s pod. Each agent works on a git branch.

{
  "id": "uuid",
  "project_id": "uuid",
  "agent_config_id": "uuid | null",
  "spawned_by": "uuid | null",
  "status": "pending | starting | ready | busy | terminating | terminated | failed | timeout",
  "current_branch": "main",
  "pod_name": "agent-xxx",
  "pod_ip": "10.0.0.1",
  "started_at": "timestamp | null",
  "last_seen_at": "timestamp | null",
  "terminated_at": "timestamp | null",
  "created_at": "timestamp",
  "updated_at": "timestamp"
}

Status values:

AgentConfig

A reusable configuration template for agents. Defines the system prompt, model, and tools.

{
  "id": "uuid",
  "name": "code-reviewer",
  "description": "Reviews PRs",
  "prompt": "You are a code reviewer...",
  "model": "anthropic/claude-opus-4-6",
  "tools": [{}],
  "chrome_enabled": false,
  "created_at": "timestamp",
  "updated_at": "timestamp"
}

TaskDefinition

A named, reusable task with a Go text/template prompt and optional JSON result schema.

{
  "id": "uuid",
  "slug": "analyze-pr",
  "name": "Analyze Pull Request",
  "description": "...",
  "prompt_template": "Analyze PR #{{.number}} in {{.repo}}...",
  "result_schema": { "type": "object", "properties": { ... } },
  "created_at": "timestamp",
  "updated_at": "timestamp"
}

TaskResult

The output of executing a task on an agent.

{
  "id": "uuid",
  "task_definition_id": "uuid",
  "project_id": "uuid",
  "agent_id": "uuid",
  "params": { "number": 42, "repo": "org/repo" },
  "data": { "summary": "...", "score": 8 },
  "status": "pending | running | completed | failed",
  "error": "",
  "created_at": "timestamp",
  "completed_at": "timestamp | null"
}

TaskTrigger

Auto-executes a task when a matching event fires. Can be global or project-scoped.

{
  "id": "uuid",
  "scope": "global | project",
  "project_id": "uuid | null",
  "task_definition_id": "uuid",
  "task_definition_slug": "analyze-pr",
  "pattern": "ai.git.push.completed",
  "filter": { "data.branch": "main" },
  "debounce_seconds": 5,
  "enabled": true,
  "created_at": "timestamp"
}

Event (CloudEvent v1.0)

All events use CloudEvents. This is the wire format for WebSocket messages and persisted history.

{
  "specversion": "1.0",
  "type": "ai.opencode.message.updated",
  "source": "/projects/{projectID}/agents/{agentID}",
  "id": "uuid",
  "time": "2026-01-01T00:00:00Z",
  "subject": "",
  "datacontenttype": "application/json",
  "data": { ... }
}

Agent State Machine

                +---------+
  (create) ---->| pending |-----> failed
                +----+----+       |
                     |            |
                     v            |
                +---------+       |
                |starting |-----> failed
                +----+----+
                     |
                     v
                +---------+       +---------+
                |  ready  |<----->|  busy   |
                +----+----+       +----+----+
                     |                 |
          any active state             |
                  |  |                 |
                  v  v                 v
              +------------+
              |terminating |     (heartbeat lost)
              +-----+------+          |
                    |                 v
                    v            +---------+
              +------------+    | timeout |
              | terminated |    +---------+
              +------------+

  Key rules:
  - ready <-> busy is the normal work cycle
  - Any active state can go to: terminating, failed, timeout
  - terminating can ONLY go to terminated (protected)
  - terminated is final, no way back

REST API

Full endpoint documentation with request/response schemas: Swagger UI (raw JSON spec)

WebSocket

Connect

const ws = new WebSocket("ws://HOST/ws?clientId=my-frontend-123");

clientId is required. If a new connection uses the same ID, the old one is closed.

Subscribe to events

ws.send(JSON.stringify({
  specversion: "1.0",
  type: "cortex.subscribe",
  source: "/clients/my-frontend-123",
  id: crypto.randomUUID(),
  data: {
    projects: ["project-uuid-1"],
    filter: {
      agents: ["agent-uuid-1"],           // optional: only these agents
      event_types: ["ai.opencode.*"]      // optional: wildcard supported
    },
    since: "last-known-event-id"          // optional: replay missed events
  }
}));

Server responds with cortex.subscribe.ack, then (if since was set) replays up to 1000 events followed by cortex.replay.complete.

Unsubscribe

ws.send(JSON.stringify({
  specversion: "1.0",
  type: "cortex.unsubscribe",
  source: "/clients/my-frontend-123",
  id: crypto.randomUUID(),
  data: { projects: ["project-uuid-1"] }
}));

Send a command to an agent

Set subject to {projectID}/{agentID}:

ws.send(JSON.stringify({
  specversion: "1.0",
  type: "ai.agent.command.prompt",
  source: "/clients/my-frontend-123",
  id: crypto.randomUUID(),
  subject: "project-uuid/agent-uuid",
  data: {
    prompt: "Fix the failing tests",
    session_id: "optional-session-id"
  }
}));

Server responds with cortex.command.ack. Then you receive agent events as they happen.

Available commands

Event Types

Agent lifecycle

Chat / OpenCode session

Git

Files

Inter-agent

Wakeup schedules

Tasks

Other

WebSocket protocol

Common Workflows

1. Create a project, spawn an agent, send a prompt

// 1. Create project
POST /api/projects
{ "name": "my-app" }

// 2. Create agent
POST /api/projects/{projectID}/agents
{ "agent_config_id": "optional-config-id", "branch": "main" }
// Returns agent with status "pending"

// 3. Connect WebSocket and subscribe
ws = new WebSocket("ws://HOST/ws?clientId=frontend-1")
ws.send({ type: "cortex.subscribe", data: { projects: [projectID] } })

// 4. Wait for ai.agent.ready event

// 5. Send prompt
ws.send({
  type: "ai.agent.command.prompt",
  subject: "{projectID}/{agentID}",
  data: { prompt: "Add input validation to the signup form" }
})

// 6. Watch for events:
//    ai.opencode.message.part.updated  (streaming response)
//    ai.opencode.message.updated       (complete message)
//    ai.opencode.session.idle          (agent done)

2. Execute a task and get structured results

// 1. Create a task definition (once)
POST /api/tasks
{
  "slug": "analyze-pr",
  "name": "Analyze PR",
  "prompt_template": "Review PR #{{.number}} and return a summary.",
  "result_schema": {
    "type": "object",
    "properties": {
      "summary": { "type": "string" },
      "score": { "type": "integer" }
    },
    "required": ["summary", "score"]
  }
}

// 2. Execute on an agent
POST /api/projects/{projectID}/agents/{agentID}/tasks/analyze-pr/execute
{ "params": { "number": 42 } }
// Returns: { "result_id": "uuid" }

// 3. Poll for result (or listen for cortex.task.result.completed via WebSocket)
GET /api/projects/{projectID}/tasks/analyze-pr/results/{resultID}
// When status is "completed", data contains the structured result

3. Reconnect and replay missed events

// Keep track of the last event ID you received
let lastEventId = null;
ws.onmessage = (e) => {
  const event = JSON.parse(e.data);
  lastEventId = event.id;
  // handle event...
};

// On reconnect, pass "since" to replay missed events
ws.send({
  type: "cortex.subscribe",
  data: {
    projects: [projectID],
    since: lastEventId   // replays up to 1000 events
  }
});
// Wait for cortex.replay.complete, then you're caught up

Notes

• Auth: OIDC (Zitadel). Pass a JWT via Authorization: Bearer <token>. See GET /api/me to bootstrap user state.
• CORS: Configured via CORS_ALLOWED_ORIGINS env var (comma-separated origins). Allowed headers: Authorization, Content-Type, X-Org-Id.
• Errors: All REST errors return { "error": "message" } with an appropriate HTTP status code.
• WebSocket limits: 64 KB max message, 256-message send buffer, 60s ping/pong timeout.
• Constraints: One active agent per branch. One Chrome-enabled agent per project. Max agents per project is configurable.