docs: add quickstart, agent setup, orchestration guides + SEO overhaul
Documentation: - Add docs/quickstart.md — 5-minute first agent tutorial (register, create task, poll queue, complete, heartbeat) - Add docs/agent-setup.md — registration methods, SOUL personalities, config, heartbeats, agent sources - Add docs/orchestration.md — 7 patterns: manual assignment, queue dispatch, auto-dispatch with model routing, Aegis quality review, cron recurring tasks, multi-agent handoff, stale task recovery - Add "Getting Started with Agents" section to README with guide table - Add cross-reference links to docs/deployment.md SEO: - Fix app layout title/description for search ranking - Add og:type, og:siteName, upgrade twitter card to summary_large_image - Add public/robots.txt (block /api/, /setup, /login from crawlers) - Add public/llms.txt for AI discoverability
This commit is contained in:
Nyk
parent
14a0eefd65
commit
34cbc351a1
40
README.md
40
README.md
|
|
@ -2,9 +2,9 @@
|
|||
|
||||
# Mission Control
|
||||
|
||||
**The open-source dashboard for AI agent orchestration.**
|
||||
**Open-source dashboard for AI agent orchestration.**
|
||||
|
||||
Manage agent fleets, track tasks, monitor costs, and orchestrate workflows — all from a single pane of glass.
|
||||
Manage AI agent fleets, dispatch tasks, track costs, and coordinate multi-agent workflows — self-hosted, zero external dependencies, powered by SQLite.
|
||||
|
||||
[](LICENSE)
|
||||
[](https://nextjs.org/)
|
||||
|
|
@ -146,6 +146,42 @@ bash scripts/station-doctor.sh
|
|||
bash scripts/security-audit.sh
|
||||
```
|
||||
|
||||
## Getting Started with Agents
|
||||
|
||||
Once Mission Control is running, set up your first agent in under 5 minutes:
|
||||
|
||||
```bash
|
||||
export MC_URL=http://localhost:3000
|
||||
export MC_API_KEY=your-api-key # shown in Settings after first login
|
||||
|
||||
# Register an agent
|
||||
curl -X POST "$MC_URL/api/agents/register" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "scout", "role": "researcher"}'
|
||||
|
||||
# Create a task
|
||||
curl -X POST "$MC_URL/api/tasks" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"title": "Research competitors", "assigned_to": "scout", "priority": "medium"}'
|
||||
|
||||
# Poll the queue as the agent
|
||||
curl "$MC_URL/api/tasks/queue?agent=scout" \
|
||||
-H "Authorization: Bearer $MC_API_KEY"
|
||||
```
|
||||
|
||||
No gateway or OpenClaw needed — this works with pure HTTP.
|
||||
|
||||
For the full walkthrough, see the **[Quickstart Guide](docs/quickstart.md)**.
|
||||
|
||||
| Guide | What you'll learn |
|
||||
|-------|-------------------|
|
||||
| [Quickstart](docs/quickstart.md) | Register an agent, create a task, complete it — 5 minutes |
|
||||
| [Agent Setup](docs/agent-setup.md) | SOUL personalities, config, heartbeats, agent sources |
|
||||
| [Orchestration](docs/orchestration.md) | Multi-agent workflows, auto-dispatch, quality review gates |
|
||||
| [CLI Reference](docs/cli-agent-control.md) | Full CLI command list for headless/scripted usage |
|
||||
|
||||
## Project Status
|
||||
|
||||
### What Works
|
||||
|
|
|
|||
|
|
@ -0,0 +1,342 @@
|
|||
# Agent Setup Guide
|
||||
|
||||
This guide covers everything you need to configure agents in Mission Control: registration methods, SOUL personalities, working files, configuration, and liveness monitoring.
|
||||
|
||||
## Agent Registration
|
||||
|
||||
There are three ways to register agents with Mission Control.
|
||||
|
||||
### Method 1: API Self-Registration (Recommended for Autonomous Agents)
|
||||
|
||||
Agents register themselves at startup. This is the simplest path and requires no manual setup:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/agents/register \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "scout",
|
||||
"role": "researcher",
|
||||
"capabilities": ["web-search", "summarization"],
|
||||
"framework": "claude-sdk"
|
||||
}'
|
||||
```
|
||||
|
||||
**Name rules**: 1-63 characters, alphanumeric plus `.`, `-`, `_`. Must start with a letter or digit.
|
||||
|
||||
**Valid roles**: `coder`, `reviewer`, `tester`, `devops`, `researcher`, `assistant`, `agent`
|
||||
|
||||
The endpoint is idempotent — registering the same name again updates the agent's status to `idle` and refreshes `last_seen`. Rate-limited to 5 registrations per minute per IP.
|
||||
|
||||
### Method 2: Manual Creation (UI or API)
|
||||
|
||||
Create agents through the dashboard UI or the API:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/agents \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "aegis",
|
||||
"role": "reviewer",
|
||||
"status": "offline",
|
||||
"soul_content": "You are Aegis, the quality reviewer...",
|
||||
"config": {
|
||||
"dispatchModel": "9router/cc/claude-opus-4-6",
|
||||
"openclawId": "aegis"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
This requires `operator` role and supports additional fields like `soul_content`, `config`, and `template`.
|
||||
|
||||
### Method 3: Config Sync (OpenClaw or Local Discovery)
|
||||
|
||||
Mission Control can auto-discover agents from:
|
||||
|
||||
**OpenClaw config sync** — Reads agents from your `openclaw.json` file:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/agents/sync \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"source": "config"}'
|
||||
```
|
||||
|
||||
Set `OPENCLAW_CONFIG_PATH` to point to your `openclaw.json`.
|
||||
|
||||
**Local agent discovery** — Scans standard directories for agent definitions:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/agents/sync \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"source": "local"}'
|
||||
```
|
||||
|
||||
Scanned directories:
|
||||
- `~/.agents/` — Top-level agent directories or `.md` files
|
||||
- `~/.codex/agents/` — Codex agent definitions
|
||||
- `~/.claude/agents/` — Claude Code agent definitions
|
||||
- `~/.hermes/skills/` — Hermes skill definitions
|
||||
|
||||
Agent directories are detected by the presence of marker files: `soul.md`, `AGENT.md`, `identity.md`, `config.json`, or `agent.json`.
|
||||
|
||||
**Flat markdown files** (Claude Code format) are also supported:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-agent
|
||||
description: A research assistant
|
||||
model: claude-opus-4
|
||||
tools: ["read", "write", "web-search"]
|
||||
---
|
||||
You are a research assistant specializing in competitive analysis...
|
||||
```
|
||||
|
||||
## SOUL.md — Agent Personality
|
||||
|
||||
SOUL is the personality and capability definition for an agent. It's a markdown file that gets injected into dispatch prompts, shaping how the agent approaches tasks.
|
||||
|
||||
### What Goes in a SOUL
|
||||
|
||||
A SOUL defines:
|
||||
- **Identity** — Who the agent is, its name, role
|
||||
- **Expertise** — What domains it specializes in
|
||||
- **Behavior** — How it approaches problems, communication style
|
||||
- **Constraints** — What it should avoid, limitations
|
||||
|
||||
### Example: Developer Agent
|
||||
|
||||
```markdown
|
||||
# Scout — Developer
|
||||
|
||||
You are Scout, a senior developer agent specializing in full-stack TypeScript development.
|
||||
|
||||
## Expertise
|
||||
- Next.js, React, Node.js
|
||||
- Database design (PostgreSQL, SQLite)
|
||||
- API architecture and testing
|
||||
|
||||
## Approach
|
||||
- Read existing code before proposing changes
|
||||
- Write tests alongside implementation
|
||||
- Keep changes minimal and focused
|
||||
|
||||
## Constraints
|
||||
- Never commit secrets or credentials
|
||||
- Ask for clarification on ambiguous requirements
|
||||
- Flag security concerns immediately
|
||||
```
|
||||
|
||||
### Example: Researcher Agent
|
||||
|
||||
```markdown
|
||||
# Iris — Researcher
|
||||
|
||||
You are Iris, a research agent focused on gathering and synthesizing information.
|
||||
|
||||
## Expertise
|
||||
- Web research and source verification
|
||||
- Competitive analysis
|
||||
- Data synthesis and report writing
|
||||
|
||||
## Approach
|
||||
- Always cite sources with URLs
|
||||
- Present findings in structured format
|
||||
- Distinguish facts from inferences
|
||||
|
||||
## Output Format
|
||||
- Use bullet points for key findings
|
||||
- Include a "Sources" section at the end
|
||||
- Highlight actionable insights
|
||||
```
|
||||
|
||||
### Example: Reviewer Agent
|
||||
|
||||
```markdown
|
||||
# Aegis — Quality Reviewer
|
||||
|
||||
You are Aegis, the quality gate for all agent work in Mission Control.
|
||||
|
||||
## Role
|
||||
Review completed tasks for correctness, completeness, and quality.
|
||||
|
||||
## Review Criteria
|
||||
- Does the output address all parts of the task?
|
||||
- Are there factual errors or hallucinations?
|
||||
- Is the work actionable and well-structured?
|
||||
|
||||
## Verdict Format
|
||||
Respond with EXACTLY one of:
|
||||
|
||||
VERDICT: APPROVED
|
||||
NOTES: <brief summary>
|
||||
|
||||
VERDICT: REJECTED
|
||||
NOTES: <specific issues to fix>
|
||||
```
|
||||
|
||||
### Managing SOUL Content
|
||||
|
||||
**Read** an agent's SOUL:
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:3000/api/agents/1/soul \
|
||||
-H "Authorization: Bearer $MC_API_KEY" | jq
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"soul_content": "# Scout — Developer\n...",
|
||||
"source": "workspace",
|
||||
"available_templates": ["developer", "researcher", "reviewer"],
|
||||
"updated_at": 1711234567
|
||||
}
|
||||
```
|
||||
|
||||
The `source` field tells you where the SOUL was loaded from:
|
||||
- `workspace` — Read from the agent's workspace `soul.md` file on disk
|
||||
- `database` — Read from the MC database (no workspace file found)
|
||||
- `none` — No SOUL content set
|
||||
|
||||
**Update** a SOUL:
|
||||
|
||||
```bash
|
||||
curl -X PUT http://localhost:3000/api/agents/1/soul \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"soul_content": "# Scout — Developer\n\nYou are Scout..."}'
|
||||
```
|
||||
|
||||
**Apply a template**:
|
||||
|
||||
```bash
|
||||
curl -X PUT http://localhost:3000/api/agents/1/soul \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"template_name": "developer"}'
|
||||
```
|
||||
|
||||
Templates support substitution variables: `{{AGENT_NAME}}`, `{{AGENT_ROLE}}`, `{{TIMESTAMP}}`.
|
||||
|
||||
SOUL content syncs bidirectionally — edits in the UI write back to the workspace `soul.md` file, and changes on disk are picked up on the next sync.
|
||||
|
||||
## WORKING.md — Runtime Scratchpad
|
||||
|
||||
`WORKING.md` is an agent's runtime state file. It tracks:
|
||||
- Current task context
|
||||
- Intermediate results
|
||||
- Session notes from the agent's perspective
|
||||
|
||||
**Do not hand-edit WORKING.md** — it's written and managed by the agent during task execution. If you need to give an agent persistent instructions, use SOUL.md instead.
|
||||
|
||||
## Agent Configuration
|
||||
|
||||
Each agent has a JSON `config` object stored in the database. Key fields:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `openclawId` | string | Gateway agent identifier (falls back to agent name) |
|
||||
| `dispatchModel` | string | Model override for auto-dispatch (e.g., `9router/cc/claude-opus-4-6`) |
|
||||
| `capabilities` | string[] | List of agent capabilities |
|
||||
| `framework` | string | Framework that created the agent (e.g., `claude-sdk`, `crewai`) |
|
||||
|
||||
Example config:
|
||||
|
||||
```json
|
||||
{
|
||||
"openclawId": "scout",
|
||||
"dispatchModel": "9router/cc/claude-sonnet-4-6",
|
||||
"capabilities": ["code-review", "testing", "documentation"],
|
||||
"framework": "claude-sdk"
|
||||
}
|
||||
```
|
||||
|
||||
Update via API:
|
||||
|
||||
```bash
|
||||
curl -X PUT http://localhost:3000/api/agents \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"id": 1,
|
||||
"config": {
|
||||
"dispatchModel": "9router/cc/claude-opus-4-6"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## Heartbeat and Liveness
|
||||
|
||||
Mission Control tracks agent health through heartbeats.
|
||||
|
||||
### How It Works
|
||||
|
||||
1. Agent sends `POST /api/agents/{id}/heartbeat` every 30 seconds
|
||||
2. MC updates `status` to `idle` and refreshes `last_seen`
|
||||
3. If no heartbeat for 10 minutes (configurable), agent is marked `offline`
|
||||
4. Stale tasks (in_progress for 10+ min with offline agent) are requeued
|
||||
|
||||
### Heartbeat Request
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/agents/1/heartbeat \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"token_usage": {
|
||||
"model": "claude-sonnet-4-6",
|
||||
"inputTokens": 1500,
|
||||
"outputTokens": 300
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
The heartbeat response includes pending work items (assigned tasks, mentions, notifications), so agents can use it as both a keepalive and a lightweight work check.
|
||||
|
||||
### Agent Status Values
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `offline` | No recent heartbeat, agent is unreachable |
|
||||
| `idle` | Online and ready for work |
|
||||
| `busy` | Currently executing a task |
|
||||
| `sleeping` | Paused by user (wake with `POST /api/agents/{id}/wake`) |
|
||||
| `error` | Agent reported an error state |
|
||||
|
||||
## Agent Sources
|
||||
|
||||
The `source` field on each agent indicates how it was registered:
|
||||
|
||||
| Source | Origin |
|
||||
|--------|--------|
|
||||
| `manual` | Created through UI or direct API call |
|
||||
| `self` | Agent self-registered via `/api/agents/register` |
|
||||
| `local` | Discovered from `~/.agents/`, `~/.claude/agents/`, etc. |
|
||||
| `config` | Synced from `openclaw.json` |
|
||||
| `gateway` | Registered by a gateway connection |
|
||||
|
||||
## Agent Templates
|
||||
|
||||
When creating agents via API, you can specify a `template` name to pre-populate the config:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/agents \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "scout", "role": "coder", "template": "developer"}'
|
||||
```
|
||||
|
||||
Templates define model tier, tool permissions, and default configuration. Available templates include:
|
||||
- `developer` — Full coding toolset (read, write, edit, exec, bash)
|
||||
- `researcher` — Read-only tools plus web and memory access
|
||||
- `reviewer` — Read-only tools for code review and quality checks
|
||||
|
||||
## What's Next
|
||||
|
||||
- **[Quickstart](quickstart.md)** — 5-minute first agent tutorial
|
||||
- **[Orchestration Patterns](orchestration.md)** — Multi-agent workflows, auto-dispatch, quality review
|
||||
- **[CLI Reference](cli-agent-control.md)** — Full CLI command reference
|
||||
|
|
@ -284,3 +284,12 @@ Then point UI to:
|
|||
```bash
|
||||
NEXT_PUBLIC_GATEWAY_URL=wss://your-domain.com/gateway-ws
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
Once deployed, set up your agents and orchestration:
|
||||
|
||||
- **[Quickstart](quickstart.md)** — Register your first agent and complete a task in 5 minutes
|
||||
- **[Agent Setup](agent-setup.md)** — SOUL personalities, heartbeats, config sync, agent sources
|
||||
- **[Orchestration Patterns](orchestration.md)** — Auto-dispatch, quality review, multi-agent workflows
|
||||
- **[CLI Reference](cli-agent-control.md)** — Full CLI command list for headless/scripted usage
|
||||
|
|
|
|||
|
|
@ -0,0 +1,335 @@
|
|||
# Orchestration Patterns
|
||||
|
||||
This guide covers the task orchestration patterns available in Mission Control, from simple manual assignment to fully automated multi-agent workflows.
|
||||
|
||||
## Task Lifecycle
|
||||
|
||||
Every task in Mission Control follows this status flow:
|
||||
|
||||
```
|
||||
inbox ──► assigned ──► in_progress ──► review ──► done
|
||||
│ │ │ │
|
||||
│ │ │ └──► rejected ──► assigned (retry)
|
||||
│ │ │
|
||||
│ │ └──► failed (max retries or timeout)
|
||||
│ │
|
||||
│ └──► cancelled
|
||||
│
|
||||
└──► assigned (triaged by human or auto-dispatch)
|
||||
```
|
||||
|
||||
Key transitions:
|
||||
- **inbox → assigned**: Human triages or auto-dispatch picks it up
|
||||
- **assigned → in_progress**: Agent claims via queue poll or auto-dispatch sends it
|
||||
- **in_progress → review**: Agent completes work, awaits quality check
|
||||
- **review → done**: Aegis approves the work
|
||||
- **review → assigned**: Aegis rejects, task is requeued with feedback
|
||||
|
||||
## Pattern 1: Manual Assignment
|
||||
|
||||
The simplest pattern. A human creates a task and assigns it to a specific agent.
|
||||
|
||||
```bash
|
||||
# Create and assign in one step
|
||||
curl -X POST "$MC_URL/api/tasks" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"title": "Fix login page CSS",
|
||||
"description": "The login button overlaps the form on mobile viewports.",
|
||||
"priority": "high",
|
||||
"assigned_to": "scout"
|
||||
}'
|
||||
```
|
||||
|
||||
The agent picks it up on the next queue poll:
|
||||
|
||||
```bash
|
||||
curl "$MC_URL/api/tasks/queue?agent=scout" \
|
||||
-H "Authorization: Bearer $MC_API_KEY"
|
||||
```
|
||||
|
||||
**When to use**: Small teams, well-known agent capabilities, human-driven task triage.
|
||||
|
||||
## Pattern 2: Queue-Based Dispatch
|
||||
|
||||
Agents poll the queue and MC assigns the highest-priority available task. No human triage needed.
|
||||
|
||||
### Setup
|
||||
|
||||
1. Create tasks in `inbox` status (no `assigned_to`):
|
||||
|
||||
```bash
|
||||
curl -X POST "$MC_URL/api/tasks" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"title": "Update API documentation",
|
||||
"priority": "medium"
|
||||
}'
|
||||
```
|
||||
|
||||
2. Agents poll the queue. MC atomically claims the best task:
|
||||
|
||||
```bash
|
||||
# Agent "scout" asks for work
|
||||
curl "$MC_URL/api/tasks/queue?agent=scout" \
|
||||
-H "Authorization: Bearer $MC_API_KEY"
|
||||
|
||||
# Agent "iris" also asks — gets a different task (no race condition)
|
||||
curl "$MC_URL/api/tasks/queue?agent=iris" \
|
||||
-H "Authorization: Bearer $MC_API_KEY"
|
||||
```
|
||||
|
||||
### Priority Ordering
|
||||
|
||||
Tasks are assigned in this order:
|
||||
1. **Priority**: critical > high > medium > low
|
||||
2. **Due date**: Earliest due date first (null = last)
|
||||
3. **Created at**: Oldest first (FIFO within same priority)
|
||||
|
||||
### Capacity Control
|
||||
|
||||
Each agent can set `max_capacity` to limit concurrent tasks:
|
||||
|
||||
```bash
|
||||
# Agent can handle 3 tasks at once
|
||||
curl "$MC_URL/api/tasks/queue?agent=scout&max_capacity=3" \
|
||||
-H "Authorization: Bearer $MC_API_KEY"
|
||||
```
|
||||
|
||||
If the agent already has `max_capacity` tasks in `in_progress`, the response returns `"reason": "at_capacity"` with no task.
|
||||
|
||||
**When to use**: Multiple agents with overlapping capabilities, want automatic load balancing.
|
||||
|
||||
## Pattern 3: Auto-Dispatch (Gateway Required)
|
||||
|
||||
The scheduler automatically dispatches `assigned` tasks to agents through the OpenClaw gateway. This is the fully hands-off mode.
|
||||
|
||||
### How It Works
|
||||
|
||||
1. Tasks are created with `assigned_to` set
|
||||
2. The scheduler's `dispatchAssignedTasks` job runs periodically
|
||||
3. For each task, MC:
|
||||
- Marks it `in_progress`
|
||||
- Classifies the task complexity to select a model
|
||||
- Sends the task prompt to the agent via the gateway
|
||||
- Parses the response and stores the resolution
|
||||
- Moves the task to `review` status
|
||||
|
||||
### Model Routing
|
||||
|
||||
MC automatically selects a model based on task content:
|
||||
|
||||
| Tier | Model | Signals |
|
||||
|------|-------|---------|
|
||||
| **Complex** | Opus | debug, diagnose, architect, security audit, incident, refactor, migration |
|
||||
| **Routine** | Haiku | status check, format, rename, ping, summarize, translate, simple, minor |
|
||||
| **Default** | Agent's configured model | Everything else |
|
||||
|
||||
Critical priority tasks always get Opus. Low priority with routine signals get Haiku.
|
||||
|
||||
Override per-agent by setting `config.dispatchModel`:
|
||||
|
||||
```bash
|
||||
curl -X PUT "$MC_URL/api/agents" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"id": 1, "config": {"dispatchModel": "9router/cc/claude-opus-4-6"}}'
|
||||
```
|
||||
|
||||
### Retry Handling
|
||||
|
||||
- Failed dispatches increment `dispatch_attempts` and revert to `assigned`
|
||||
- After 5 failed attempts, task moves to `failed`
|
||||
- Each failure is logged as a comment on the task
|
||||
|
||||
**When to use**: Fully autonomous operation with an OpenClaw gateway. Best for production agent fleets.
|
||||
|
||||
## Pattern 4: Quality Review (Aegis)
|
||||
|
||||
Aegis is MC's built-in quality gate. When a task reaches `review` status, the scheduler sends it to the Aegis reviewer agent for sign-off.
|
||||
|
||||
### Flow
|
||||
|
||||
```
|
||||
in_progress ──► review ──► Aegis reviews ──► APPROVED ──► done
|
||||
└─► REJECTED ──► assigned (with feedback)
|
||||
```
|
||||
|
||||
### How Aegis Reviews
|
||||
|
||||
1. Scheduler's `runAegisReviews` job picks up tasks in `review` status
|
||||
2. Builds a review prompt with the task description and agent's resolution
|
||||
3. Sends to the Aegis agent (configurable via `MC_COORDINATOR_AGENT`)
|
||||
4. Parses the verdict:
|
||||
- `VERDICT: APPROVED` → task moves to `done`
|
||||
- `VERDICT: REJECTED` → feedback is attached as a comment, task reverts to `assigned`
|
||||
5. Rejected tasks are re-dispatched with the feedback included in the prompt
|
||||
|
||||
### Retry Limits
|
||||
|
||||
- Up to 3 Aegis review cycles per task
|
||||
- After 3 rejections, task moves to `failed` with accumulated feedback
|
||||
- All review results are stored in the `quality_reviews` table
|
||||
|
||||
### Setting Up Aegis
|
||||
|
||||
Aegis is just a regular agent with a reviewer SOUL. Create it:
|
||||
|
||||
```bash
|
||||
# Register the Aegis agent
|
||||
curl -X POST "$MC_URL/api/agents/register" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "aegis", "role": "reviewer"}'
|
||||
|
||||
# Set its SOUL
|
||||
curl -X PUT "$MC_URL/api/agents/1/soul" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"template_name": "reviewer"}'
|
||||
```
|
||||
|
||||
**When to use**: When you want automated quality checks before tasks are marked complete.
|
||||
|
||||
## Pattern 5: Recurring Tasks (Cron)
|
||||
|
||||
Schedule tasks to be created automatically on a recurring basis using natural language or cron expressions.
|
||||
|
||||
### CLI
|
||||
|
||||
```bash
|
||||
node scripts/mc-cli.cjs cron create --body '{
|
||||
"name": "daily-standup-report",
|
||||
"schedule": "0 9 * * 1-5",
|
||||
"task_template": {
|
||||
"title": "Generate daily standup report",
|
||||
"description": "Summarize all completed tasks from the past 24 hours.",
|
||||
"priority": "medium",
|
||||
"assigned_to": "iris"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### API
|
||||
|
||||
```bash
|
||||
curl -X POST "$MC_URL/api/cron" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "weekly-security-scan",
|
||||
"schedule": "0 2 * * 0",
|
||||
"task_template": {
|
||||
"title": "Weekly security audit",
|
||||
"priority": "high",
|
||||
"assigned_to": "aegis"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
The scheduler spawns dated child tasks from the template on each trigger. Manage cron jobs with `pause`, `resume`, and `remove` actions.
|
||||
|
||||
**When to use**: Reports, health checks, periodic audits, maintenance tasks.
|
||||
|
||||
## Pattern 6: Multi-Agent Handoff
|
||||
|
||||
Agent A completes a task, then creates a follow-up task assigned to Agent B. This chains agents into a pipeline.
|
||||
|
||||
### Example: Research → Implement → Review
|
||||
|
||||
```bash
|
||||
# Step 1: Research task for iris
|
||||
curl -X POST "$MC_URL/api/tasks" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"title": "Research caching strategies for API layer",
|
||||
"priority": "high",
|
||||
"assigned_to": "iris"
|
||||
}'
|
||||
```
|
||||
|
||||
When iris completes the research, create the implementation task:
|
||||
|
||||
```bash
|
||||
# Step 2: Implementation task for scout (after iris finishes)
|
||||
curl -X POST "$MC_URL/api/tasks" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"title": "Implement Redis caching for /api/products",
|
||||
"description": "Based on research in TASK-1: Use cache-aside pattern with 5min TTL...",
|
||||
"priority": "high",
|
||||
"assigned_to": "scout"
|
||||
}'
|
||||
```
|
||||
|
||||
After scout finishes, Aegis reviews automatically (if auto-dispatch is active), or you create a review task:
|
||||
|
||||
```bash
|
||||
# Step 3: Review task for aegis
|
||||
curl -X POST "$MC_URL/api/tasks" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"title": "Review caching implementation in TASK-2",
|
||||
"priority": "high",
|
||||
"assigned_to": "aegis"
|
||||
}'
|
||||
```
|
||||
|
||||
**When to use**: Complex workflows where different agents have different specializations.
|
||||
|
||||
## Pattern 7: Stale Task Recovery
|
||||
|
||||
MC automatically recovers from stuck agents. The `requeueStaleTasks` scheduler job:
|
||||
|
||||
1. Finds tasks stuck in `in_progress` for 10+ minutes with an offline agent
|
||||
2. Reverts them to `assigned` with a comment explaining the stall
|
||||
3. After 5 stale requeues, moves the task to `failed`
|
||||
|
||||
This happens automatically — no configuration needed.
|
||||
|
||||
## Combining Patterns
|
||||
|
||||
In practice, you'll combine these patterns. A typical production setup:
|
||||
|
||||
1. **Cron** creates recurring tasks (Pattern 5)
|
||||
2. **Queue-based dispatch** distributes tasks to available agents (Pattern 2)
|
||||
3. **Model routing** picks the right model per task (Pattern 3)
|
||||
4. **Aegis** reviews all completed work (Pattern 4)
|
||||
5. **Stale recovery** handles agent failures (Pattern 7)
|
||||
|
||||
```
|
||||
Cron ──► inbox ──► Queue assigns ──► Agent works ──► Aegis reviews ──► done
|
||||
│ │
|
||||
└── timeout ───────┘── requeue
|
||||
```
|
||||
|
||||
## Event Streaming
|
||||
|
||||
Monitor orchestration in real time with SSE:
|
||||
|
||||
```bash
|
||||
# Watch all task and agent events
|
||||
node scripts/mc-cli.cjs events watch --types task,agent --json
|
||||
```
|
||||
|
||||
Or via API:
|
||||
|
||||
```bash
|
||||
curl -N "$MC_URL/api/events" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Accept: text/event-stream"
|
||||
```
|
||||
|
||||
Events include: `task.created`, `task.updated`, `task.completed`, `agent.created`, `agent.status_changed`, and more.
|
||||
|
||||
## Reference
|
||||
|
||||
- **[Quickstart](quickstart.md)** — 5-minute first agent tutorial
|
||||
- **[Agent Setup](agent-setup.md)** — Registration, SOUL, configuration
|
||||
- **[CLI Reference](cli-agent-control.md)** — Full CLI command list
|
||||
- **[CLI Integration](cli-integration.md)** — Direct connections without a gateway
|
||||
|
|
@ -0,0 +1,235 @@
|
|||
# Quickstart: Your First Agent in 5 Minutes
|
||||
|
||||
Get from zero to a working agent loop with nothing but Mission Control and `curl`. No gateway, no OpenClaw, no extra dependencies.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Mission Control running (`pnpm dev` or Docker)
|
||||
- An admin account (visit `/setup` on first run)
|
||||
- Your API key (auto-generated on first run, shown in Settings)
|
||||
|
||||
## Step 1: Start Mission Control
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
Open http://localhost:3000 and log in. If this is your first run, visit http://localhost:3000/setup to create your admin account.
|
||||
|
||||
Your API key is displayed in **Settings > API Key**. Export it for the commands below:
|
||||
|
||||
```bash
|
||||
export MC_URL=http://localhost:3000
|
||||
export MC_API_KEY=your-api-key
|
||||
```
|
||||
|
||||
## Step 2: Register an Agent
|
||||
|
||||
Agents can self-register via the API. This is how autonomous agents announce themselves to Mission Control:
|
||||
|
||||
```bash
|
||||
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"}' | jq
|
||||
```
|
||||
|
||||
Expected response:
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"id": 1,
|
||||
"name": "scout",
|
||||
"role": "researcher",
|
||||
"status": "idle",
|
||||
"created_at": 1711234567
|
||||
},
|
||||
"registered": true,
|
||||
"message": "Agent registered successfully"
|
||||
}
|
||||
```
|
||||
|
||||
Note the `id` — you'll need it for heartbeats. The registration is idempotent: calling it again with the same name just updates the agent's status to `idle`.
|
||||
|
||||
**Valid roles**: `coder`, `reviewer`, `tester`, `devops`, `researcher`, `assistant`, `agent`
|
||||
|
||||
## Step 3: Create a Task
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$MC_URL/api/tasks" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"title": "Research competitor pricing",
|
||||
"description": "Find pricing pages for the top 3 competitors and summarize their tiers.",
|
||||
"priority": "medium",
|
||||
"assigned_to": "scout"
|
||||
}' | jq
|
||||
```
|
||||
|
||||
Expected response:
|
||||
|
||||
```json
|
||||
{
|
||||
"task": {
|
||||
"id": 1,
|
||||
"title": "Research competitor pricing",
|
||||
"status": "assigned",
|
||||
"priority": "medium",
|
||||
"assigned_to": "scout",
|
||||
"tags": [],
|
||||
"metadata": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The task starts in `assigned` status because you specified `assigned_to`. If you omit it, the task goes to `inbox` for manual triage.
|
||||
|
||||
## Step 4: Poll the Task Queue
|
||||
|
||||
This is how your agent picks up work. The queue endpoint atomically claims the highest-priority available task:
|
||||
|
||||
```bash
|
||||
curl -s "$MC_URL/api/tasks/queue?agent=scout" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" | jq
|
||||
```
|
||||
|
||||
Expected response:
|
||||
|
||||
```json
|
||||
{
|
||||
"task": {
|
||||
"id": 1,
|
||||
"title": "Research competitor pricing",
|
||||
"status": "in_progress",
|
||||
"assigned_to": "scout"
|
||||
},
|
||||
"reason": "assigned",
|
||||
"agent": "scout",
|
||||
"timestamp": 1711234600
|
||||
}
|
||||
```
|
||||
|
||||
The task status automatically moved from `assigned` to `in_progress`. The `reason` field tells you why this task was returned:
|
||||
|
||||
| Reason | Meaning |
|
||||
|--------|---------|
|
||||
| `assigned` | Claimed a new task from the queue |
|
||||
| `continue_current` | Agent already has a task in progress |
|
||||
| `at_capacity` | Agent is at max concurrent tasks |
|
||||
| `no_tasks_available` | Nothing in the queue for this agent |
|
||||
|
||||
## Step 5: Complete the Task
|
||||
|
||||
When your agent finishes work, update the task status and add a resolution:
|
||||
|
||||
```bash
|
||||
curl -s -X PUT "$MC_URL/api/tasks/1" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"status": "done",
|
||||
"resolution": "Found pricing for Acme ($29/49/99), Widget Corp ($19/39/79), and Gadget Inc ($25/50/100). All use 3-tier SaaS model. Summary doc attached."
|
||||
}' | jq
|
||||
```
|
||||
|
||||
## Step 6: Send a Heartbeat
|
||||
|
||||
Heartbeats tell Mission Control your agent is alive. Without them, agents are marked offline after 10 minutes:
|
||||
|
||||
```bash
|
||||
curl -s -X POST "$MC_URL/api/agents/1/heartbeat" \
|
||||
-H "Authorization: Bearer $MC_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{}' | jq
|
||||
```
|
||||
|
||||
Expected response:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"token_recorded": false,
|
||||
"work_items": [],
|
||||
"timestamp": 1711234700
|
||||
}
|
||||
```
|
||||
|
||||
In a real agent, you'd send heartbeats every 30 seconds in a background loop. The `work_items` array returns any pending tasks, mentions, or notifications.
|
||||
|
||||
## The Agent Loop
|
||||
|
||||
Here's the complete pattern your agent should follow:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ 1. Register with MC │
|
||||
│ POST /api/agents/register │
|
||||
└──────────────┬──────────────────┘
|
||||
│
|
||||
v
|
||||
┌─────────────────────────────────┐
|
||||
│ 2. Poll for work │◄──────┐
|
||||
│ GET /api/tasks/queue │ │
|
||||
└──────────────┬──────────────────┘ │
|
||||
│ │
|
||||
v │
|
||||
┌─────────────────────────────────┐ │
|
||||
│ 3. Do the work │ │
|
||||
│ (your agent logic here) │ │
|
||||
└──────────────┬──────────────────┘ │
|
||||
│ │
|
||||
v │
|
||||
┌─────────────────────────────────┐ │
|
||||
│ 4. Report result │ │
|
||||
│ PUT /api/tasks/{id} │ │
|
||||
└──────────────┬──────────────────┘ │
|
||||
│ │
|
||||
v │
|
||||
┌─────────────────────────────────┐ │
|
||||
│ 5. Heartbeat + repeat │───────┘
|
||||
│ POST /api/agents/{id}/hb │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Using the CLI Instead
|
||||
|
||||
If you prefer the CLI over `curl`, the same flow works with `pnpm mc`:
|
||||
|
||||
```bash
|
||||
# List agents
|
||||
node scripts/mc-cli.cjs agents list --json
|
||||
|
||||
# Create an agent
|
||||
node scripts/mc-cli.cjs agents create --name scout --role researcher --json
|
||||
|
||||
# Create a task
|
||||
node scripts/mc-cli.cjs tasks create --title "Research competitors" --body '{"assigned_to":"scout","priority":"medium"}' --json
|
||||
|
||||
# Poll the queue
|
||||
node scripts/mc-cli.cjs tasks queue --agent scout --json
|
||||
|
||||
# Watch events in real time
|
||||
node scripts/mc-cli.cjs events watch --types task,agent
|
||||
```
|
||||
|
||||
See [CLI Reference](cli-agent-control.md) for the full command list.
|
||||
|
||||
## Using the MCP Server (for Claude Code agents)
|
||||
|
||||
For agents built with Claude Code, the MCP server is the recommended integration:
|
||||
|
||||
```bash
|
||||
claude mcp add mission-control -- node /path/to/mission-control/scripts/mc-mcp-server.cjs
|
||||
```
|
||||
|
||||
Set `MC_URL` and `MC_API_KEY` in your environment. The MCP server exposes 35+ tools for agents, tasks, sessions, memory, and more. See [CLI Integration](cli-integration.md) for details.
|
||||
|
||||
## What's Next?
|
||||
|
||||
- **[Agent Setup Guide](agent-setup.md)** — Configure SOUL personalities, agent sources, and heartbeat settings
|
||||
- **[Orchestration Patterns](orchestration.md)** — Multi-agent workflows, auto-dispatch, quality review gates
|
||||
- **[CLI Reference](cli-agent-control.md)** — Full CLI command reference
|
||||
- **[CLI Integration](cli-integration.md)** — Direct CLI and gateway-free connections
|
||||
- **[Deployment Guide](deployment.md)** — Production deployment options
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
# Mission Control
|
||||
|
||||
> Open-source dashboard for AI agent orchestration.
|
||||
|
||||
Mission Control is a self-hosted dashboard for managing AI agent fleets. It provides task dispatch, cost tracking, quality review gates, recurring task scheduling, and multi-agent coordination — all powered by SQLite with zero external dependencies.
|
||||
|
||||
## Key Features
|
||||
- Agent management with full lifecycle (register, heartbeat, wake, retire)
|
||||
- Kanban task board with priorities, assignments, and comments
|
||||
- Task queue with atomic claiming and priority-based dispatch
|
||||
- Auto-dispatch with model routing (Opus/Sonnet/Haiku by task complexity)
|
||||
- Aegis quality review gates for task sign-off
|
||||
- Real-time monitoring via WebSocket + SSE
|
||||
- Token usage and cost tracking with per-model breakdowns
|
||||
- Natural language recurring tasks with cron scheduling
|
||||
- MCP server with 35+ tools for agent integration
|
||||
- CLI for headless/scripted usage
|
||||
- Role-based access control (viewer, operator, admin)
|
||||
- REST API with OpenAPI spec
|
||||
|
||||
## Stack
|
||||
Next.js 16, React 19, TypeScript 5, SQLite (better-sqlite3), Tailwind CSS
|
||||
|
||||
## Links
|
||||
- Source: https://github.com/builderz-labs/mission-control
|
||||
- Landing page: https://mc.builderz.dev
|
||||
- License: MIT
|
||||
|
||||
## llms-full.txt
|
||||
For the complete API reference and integration guide, see docs/cli-agent-control.md in the repository.
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
# Mission Control — AI Agent Orchestration Dashboard
|
||||
# https://github.com/builderz-labs/mission-control
|
||||
|
||||
User-agent: *
|
||||
Allow: /
|
||||
Disallow: /api/
|
||||
Disallow: /setup
|
||||
Disallow: /login
|
||||
Disallow: /_next/
|
||||
|
|
@ -52,8 +52,8 @@ export const viewport: Viewport = {
|
|||
}
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: 'Mission Control',
|
||||
description: 'OpenClaw Agent Orchestration Dashboard',
|
||||
title: 'Mission Control — AI Agent Orchestration Dashboard',
|
||||
description: 'Open-source dashboard for AI agent orchestration. Manage agent fleets, dispatch tasks, track costs, and coordinate multi-agent workflows. Self-hosted, zero dependencies, SQLite-powered.',
|
||||
metadataBase,
|
||||
icons: {
|
||||
icon: [
|
||||
|
|
@ -64,14 +64,16 @@ export const metadata: Metadata = {
|
|||
shortcut: ['/icon.png'],
|
||||
},
|
||||
openGraph: {
|
||||
title: 'Mission Control',
|
||||
description: 'OpenClaw Agent Orchestration Dashboard',
|
||||
images: [{ url: '/brand/mc-logo-512.png', width: 512, height: 512, alt: 'Mission Control logo' }],
|
||||
title: 'Mission Control — AI Agent Orchestration Dashboard',
|
||||
description: 'Open-source dashboard for AI agent orchestration. Manage agent fleets, dispatch tasks, track costs, and coordinate multi-agent workflows.',
|
||||
images: [{ url: '/brand/mc-logo-512.png', width: 512, height: 512, alt: 'Mission Control — open-source AI agent orchestration dashboard' }],
|
||||
type: 'website',
|
||||
siteName: 'Mission Control',
|
||||
},
|
||||
twitter: {
|
||||
card: 'summary',
|
||||
title: 'Mission Control',
|
||||
description: 'OpenClaw Agent Orchestration Dashboard',
|
||||
card: 'summary_large_image',
|
||||
title: 'Mission Control — AI Agent Orchestration Dashboard',
|
||||
description: 'Open-source dashboard for AI agent orchestration. Manage agent fleets, dispatch tasks, track costs, and coordinate multi-agent workflows.',
|
||||
images: ['/brand/mc-logo-512.png'],
|
||||
},
|
||||
appleWebApp: {
|
||||
|
|
|
|||
Loading…
Reference in New Issue