name: mission-control description: "Interact with Mission Control — AI agent orchestration dashboard. Use when registering agents, managing tasks, syncing skills, or querying agent/task status via MC APIs."

Mission Control Agent Skill

Mission Control (MC) is an AI agent orchestration dashboard with real-time SSE/WebSocket, a skill registry, framework adapters, and RBAC. This skill teaches agents how to interact with MC APIs programmatically.

Quick Start

Base URL: http://localhost:3000 (default Next.js dev) or your deployed host.

Auth header: x-api-key: <your-api-key>

Register + heartbeat in two calls:

# 1. Register
curl -X POST http://localhost:3000/api/adapters \
  -H "Content-Type: application/json" \
  -H "x-api-key: $MC_API_KEY" \
  -d '{
    "framework": "generic",
    "action": "register",
    "payload": { "agentId": "my-agent-01", "name": "My Agent" }
  }'

# 2. Heartbeat (repeat every 5 minutes)
curl -X POST http://localhost:3000/api/adapters \
  -H "Content-Type: application/json" \
  -H "x-api-key: $MC_API_KEY" \
  -d '{
    "framework": "generic",
    "action": "heartbeat",
    "payload": { "agentId": "my-agent-01", "status": "online" }
  }'

Authentication

MC supports two auth methods:

Roles (hierarchical): viewer < operator < admin

• viewer — Read-only access (GET endpoints)
• operator — Create/update agents, tasks, skills, use adapters
• admin — Full access including user management

API key auth grants admin role by default. The key is set via API_KEY env var or the security.api_key DB setting.

Agents can identify themselves with the optional X-Agent-Name header for attribution in audit logs.

Agent Lifecycle

register → heartbeat (5m interval) → fetch assignments → report task status → disconnect

All lifecycle actions go through the adapter protocol (POST /api/adapters).

1. Register

{
  "framework": "generic",
  "action": "register",
  "payload": {
    "agentId": "my-agent-01",
    "name": "My Agent",
    "metadata": { "version": "1.0", "capabilities": ["code", "review"] }
  }
}

2. Heartbeat

Send every ~5 minutes to stay marked as online.

{
  "framework": "generic",
  "action": "heartbeat",
  "payload": {
    "agentId": "my-agent-01",
    "status": "online",
    "metrics": { "tasks_completed": 5, "uptime_seconds": 3600 }
  }
}

3. Fetch Assignments

Returns up to 5 pending tasks sorted by priority (critical → low), then due date.

{
  "framework": "generic",
  "action": "assignments",
  "payload": { "agentId": "my-agent-01" }
}

Response:

{
  "assignments": [
    { "taskId": "42", "description": "Fix login bug\nUsers cannot log in with SSO", "priority": 1 }
  ],
  "framework": "generic"
}

4. Report Task Progress

{
  "framework": "generic",
  "action": "report",
  "payload": {
    "taskId": "42",
    "agentId": "my-agent-01",
    "progress": 75,
    "status": "in_progress",
    "output": "Fixed SSO handler, running tests..."
  }
}

status values: in_progress, done, failed, blocked

5. Disconnect

{
  "framework": "generic",
  "action": "disconnect",
  "payload": { "agentId": "my-agent-01" }
}

Core API Reference

Agents — /api/agents

GET response shape:

{
  "agents": [{
    "id": 1, "name": "scout", "role": "researcher", "status": "online",
    "config": {}, "taskStats": { "total": 10, "assigned": 2, "in_progress": 1, "completed": 7 }
  }],
  "total": 1, "page": 1, "limit": 50
}

Tasks — /api/tasks

Priority values: critical, high, medium, low

Status values: inbox, assigned, in_progress, review, done, failed, blocked, cancelled

Note: Moving a task to done via PUT requires an Aegis quality review approval.

POST response:

{
  "task": {
    "id": 42, "title": "Fix login bug", "status": "assigned",
    "priority": "high", "assigned_to": "scout", "ticket_ref": "GEN-001",
    "tags": ["bug"], "metadata": {}
  }
}

Skills — /api/skills

Skill sources: user-agents, user-codex, project-agents, project-codex, openclaw

Status — /api/status

Adapters — /api/adapters

Framework Adapter Protocol

All agent lifecycle operations use a single endpoint:

POST /api/adapters
Content-Type: application/json
x-api-key: <key>

{
  "framework": "<adapter-name>",
  "action": "<action>",
  "payload": { ... }
}

Available frameworks: generic, openclaw, crewai, langgraph, autogen, claude-sdk

Available actions: register, heartbeat, report, assignments, disconnect

All adapters implement the same FrameworkAdapter interface — choose the one matching your agent framework, or use generic as a universal fallback.

Payload shapes by action:

Environment Variables

Real-Time Events

MC broadcasts events via SSE (/api/events) and WebSocket. Key event types:

• agent.created, agent.updated, agent.status_changed
• task.created, task.updated, task.status_changed

Subscribe to SSE for live dashboard updates when building integrations.

Mission Control

Self-hosted control plane for operating AI agents.

Dispatch tasks, inspect runs, review failures, track spend, and coordinate agent runtimes from one local dashboard backed by SQLite.

[!WARNING] Mission Control is alpha software. APIs, schemas, and configuration may change between releases. Read the security guidance before exposing it to a network.

Start locally

Node.js 22 or newer and pnpm are required for a source install.

git clone https://github.com/builderz-labs/mission-control.git
cd mission-control
bash install.sh --local

Open http://localhost:3000/setup, create the first admin account, then copy the API key from Settings if an agent or script needs headless access.

The manual path is useful when you already manage Node and pnpm:

nvm use 22
pnpm install
pnpm dev

Windows users can run ./install.ps1 -Mode local in PowerShell.

Start with Docker

docker compose up

Or run the published multi-architecture image:

docker pull ghcr.io/builderz-labs/mission-control:latest
docker run --rm -p 3000:3000 ghcr.io/builderz-labs/mission-control:latest

Use the hardened Compose overlay for a network-accessible deployment:

docker compose -f docker-compose.yml -f docker-compose.hardened.yml up -d

The deployment guide covers persistent data, TLS termination, gateway connectivity, and standalone builds.

What Mission Control governs

The control plane sits above agent runtimes. It does not replace their reasoning or tool loops. It gives operators one place to see and govern the work around those loops.

The runtime is self-hosted and workspace-aware. SQLite stores local control-plane state. Shared workspaces can use deployment-level runtime integrations. Strict workspaces block those integrations until the underlying resources carry workspace ownership. A gateway is optional for task, project, agent, scheduler, webhook, alert, and cost work; live session messaging needs a connected runtime gateway.

Operator field notes

Dashboards compress a sequence into current state. When a run needs review, record the identity, task, tool call, approval, result, and verification evidence before changing it. Keep unresolved items distinct from accepted risk.

Logs show what ran. A completion receipt or inspected artifact shows what finished.

Pick the right fit

Use Mission Control when multiple agents or runtimes make it hard to answer who owns a task, what executed, which result passed review, or where spend and failures accumulated.

It is probably the wrong tool when:

• one agent on one machine already stays understandable from its native CLI;
• you need a managed multi-tenant SaaS rather than a self-hosted control plane;
• you want an agent framework to define planning and tool use;
• your deployment cannot tolerate alpha schema or API changes.

Adapters and observation surfaces cover OpenClaw, Claude Code, Codex, CrewAI, LangGraph, AutoGen, and Claude SDK workflows. Adapter depth varies by runtime; see agent setup and CLI integration before assuming feature parity.

Connect an agent

The shortest gateway-free loop uses the REST API. Export the URL and API key shown in Settings:

export MC_URL=http://localhost:3000
export MC_API_KEY=replace-with-your-api-key

Register an agent and create work:

curl -s -X POST "$MC_URL/api/agents/register" \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"scout","role":"researcher"}'

curl -s -X POST "$MC_URL/api/tasks" \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Review open incidents","assigned_to":"scout","priority":"medium"}'

The agent can then claim its queue:

curl -s "$MC_URL/api/tasks/queue?agent=scout" \
  -H "Authorization: Bearer $MC_API_KEY"

Continue with the first-agent quickstart for heartbeats, task results, queue behavior, CLI equivalents, and MCP setup.

CLI

pnpm mc agents list --json
pnpm mc tasks queue --agent scout --json
pnpm mc events watch --types agent,task

MCP server

claude mcp add mission-control -- \
  env MC_URL=http://127.0.0.1:3000 MC_API_KEY=replace-with-your-api-key \
  node /absolute/path/to/mission-control/scripts/mc-mcp-server.cjs

Use the CLI and MCP reference for the current command and tool surface. The REST contract lives in openapi.json. A running instance serves the interactive reference at /docs and the OpenAPI JSON at /api/docs.

Product surfaces

Tasks and quality review

The task board tracks work through inbox, assignment, execution, review, quality review, and completion. Aegis review requires an approval record before a task reaches done.

Agents and runtimes

Agent views combine registration state, heartbeats, sessions, configuration, local runtime discovery, and workspace files.

Memory and skills

The memory browser and relationship graph inspect filesystem-backed memory and linked session knowledge. The Skills Hub discovers local skill roots and scans registry content before installation.

Schedules and activity

Recurring task templates create dated work on a cron schedule. The activity stream combines agent, task, and system events for operator review.

Documentation

Architecture

Web UI ─┐
CLI ────┼── auth ─ dispatch ─ events ─ policy ─ receipts
MCP ────┤                                      │
REST ───┘                         SQLite + agent runtimes

Runtime data defaults to .data/. Set MISSION_CONTROL_DATA_DIR to an absolute persistent path for standalone deployments. The complete environment contract is in .env.example.

Security boundary

• Keep Mission Control on a trusted network unless a TLS reverse proxy and MC_ALLOWED_HOSTS are configured.
• Replace or securely store generated credentials before broader access.
• Use the hardened Compose overlay for production-like container deployments.
• Treat agent messages, skill packages, webhooks, and MCP content as untrusted input.
• Report vulnerabilities through SECURITY.md, not a public issue.

Access controls and security inspection surfaces are included, but alpha status still applies. Read SECURITY-HARDENING.md before relying on a network-accessible deployment.

Develop

pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm test:e2e

pnpm quality:gate runs the full repository gate. Useful diagnostics:

bash scripts/station-doctor.sh
bash scripts/security-audit.sh
pnpm api:parity

Common local failures: