Skip to content
Back to search

mission-control

SkillWorks with Claude CodeGitHub

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/builderz-labs/mission-control with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/builderz-labs/mission-control'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/builderz-labs-mission-control/badge.svg)](/listings/builderz-labs-mission-control)

HTML

<a href="/listings/builderz-labs-mission-control"><img src="/api/listings/builderz-labs-mission-control/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 277 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: mission-control
  3. 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."
  4. ---
  5. # Mission Control Agent Skill
  6. 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.
  7. ## Quick Start
  8. **Base URL:** `http://localhost:3000` (default Next.js dev) or your deployed host.
  9. **Auth header:** `x-api-key: <your-api-key>`
  10. **Register + heartbeat in two calls:**
  11. ```bash
  12. # 1. Register
  13. curl -X POST http://localhost:3000/api/adapters \
  14. -H "Content-Type: application/json" \
  15. -H "x-api-key: $MC_API_KEY" \
  16. -d '{
  17. "framework": "generic",
  18. "action": "register",
  19. "payload": { "agentId": "my-agent-01", "name": "My Agent" }
  20. }'
  21. # 2. Heartbeat (repeat every 5 minutes)
  22. curl -X POST http://localhost:3000/api/adapters \
  23. -H "Content-Type: application/json" \
  24. -H "x-api-key: $MC_API_KEY" \
  25. -d '{
  26. "framework": "generic",
  27. "action": "heartbeat",
  28. "payload": { "agentId": "my-agent-01", "status": "online" }
  29. }'
  30. ```
  31. ## Authentication
  32. MC supports two auth methods:
  33. | Method | Header | Use Case |
  34. |--------|--------|----------|
  35. | API Key | `x-api-key: <key>` or `Authorization: Bearer <key>` | Agents, scripts, CI/CD |
  36. | Session cookie | `Cookie: __Host-mc-session=<token>` (HTTPS) or `mc-session=<token>` (HTTP) | Browser UI |
  37. **Roles (hierarchical):** `viewer` < `operator` < `admin`
  38. - **viewer** — Read-only access (GET endpoints)
  39. - **operator** — Create/update agents, tasks, skills, use adapters
  40. - **admin** — Full access including user management
  41. API key auth grants `admin` role by default. The key is set via `API_KEY` env var or the `security.api_key` DB setting.
  42. Agents can identify themselves with the optional `X-Agent-Name` header for attribution in audit logs.
  43. ## Agent Lifecycle
  44. ```
  45. register → heartbeat (5m interval) → fetch assignments → report task status → disconnect
  46. ```
  47. All lifecycle actions go through the adapter protocol (`POST /api/adapters`).
  48. ### 1. Register
  49. ```json
  50. {
  51. "framework": "generic",
  52. "action": "register",
  53. "payload": {
  54. "agentId": "my-agent-01",
  55. "name": "My Agent",
  56. "metadata": { "version": "1.0", "capabilities": ["code", "review"] }
  57. }
  58. }
  59. ```
  60. ### 2. Heartbeat
  61. Send every ~5 minutes to stay marked as online.
  62. ```json
  63. {
  64. "framework": "generic",
  65. "action": "heartbeat",
  66. "payload": {
  67. "agentId": "my-agent-01",
  68. "status": "online",
  69. "metrics": { "tasks_completed": 5, "uptime_seconds": 3600 }
  70. }
  71. }
  72. ```
  73. ### 3. Fetch Assignments
  74. Returns up to 5 pending tasks sorted by priority (critical → low), then due date.
  75. ```json
  76. {
  77. "framework": "generic",
  78. "action": "assignments",
  79. "payload": { "agentId": "my-agent-01" }
  80. }
  81. ```
  82. **Response:**
  83. ```json
  84. {
  85. "assignments": [
  86. { "taskId": "42", "description": "Fix login bug\nUsers cannot log in with SSO", "priority": 1 }
  87. ],
  88. "framework": "generic"
  89. }
  90. ```
  91. ### 4. Report Task Progress
  92. ```json
  93. {
  94. "framework": "generic",
  95. "action": "report",
  96. "payload": {
  97. "taskId": "42",
  98. "agentId": "my-agent-01",
  99. "progress": 75,
  100. "status": "in_progress",
  101. "output": "Fixed SSO handler, running tests..."
  102. }
  103. }
  104. ```
  105. `status` values: `in_progress`, `done`, `failed`, `blocked`
  106. ### 5. Disconnect
  107. ```json
  108. {
  109. "framework": "generic",
  110. "action": "disconnect",
  111. "payload": { "agentId": "my-agent-01" }
  112. }
  113. ```
  114. ## Core API Reference
  115. ### Agents — `/api/agents`
  116. | Method | Min Role | Description |
  117. |--------|----------|-------------|
  118. | GET | viewer | List agents. Query: `?status=online&role=dev&limit=50&offset=0` |
  119. | POST | operator | Create agent. Body: `{ name, role, status?, config?, template?, session_key?, soul_content? }` |
  120. | PUT | operator | Update agent. Body: `{ name, status?, role?, config?, session_key?, soul_content?, last_activity? }` |
  121. **GET response shape:**
  122. ```json
  123. {
  124. "agents": [{
  125. "id": 1, "name": "scout", "role": "researcher", "status": "online",
  126. "config": {}, "taskStats": { "total": 10, "assigned": 2, "in_progress": 1, "completed": 7 }
  127. }],
  128. "total": 1, "page": 1, "limit": 50
  129. }
  130. ```
  131. ### Tasks — `/api/tasks`
  132. | Method | Min Role | Description |
  133. |--------|----------|-------------|
  134. | GET | viewer | List tasks. Query: `?status=in_progress&assigned_to=scout&priority=high&project_id=1&limit=50&offset=0` |
  135. | POST | operator | Create task. Body: `{ title, description?, status?, priority?, assigned_to?, project_id?, tags?, metadata?, due_date?, estimated_hours? }` |
  136. | PUT | operator | Bulk status update. Body: `{ tasks: [{ id, status }] }` |
  137. **Priority values:** `critical`, `high`, `medium`, `low`
  138. **Status values:** `inbox`, `assigned`, `in_progress`, `review`, `done`, `failed`, `blocked`, `cancelled`
  139. Note: Moving a task to `done` via PUT requires an Aegis quality review approval.
  140. **POST response:**
  141. ```json
  142. {
  143. "task": {
  144. "id": 42, "title": "Fix login bug", "status": "assigned",
  145. "priority": "high", "assigned_to": "scout", "ticket_ref": "GEN-001",
  146. "tags": ["bug"], "metadata": {}
  147. }
  148. }
  149. ```
  150. ### Skills — `/api/skills`
  151. | Method | Min Role | Description |
  152. |--------|----------|-------------|
  153. | GET | viewer | List all skills across roots |
  154. | GET `?mode=content&source=...&name=...` | viewer | Read a skill's SKILL.md content |
  155. | GET `?mode=check&source=...&name=...` | viewer | Run security check on a skill |
  156. | POST | operator | Create/upsert skill. Body: `{ source, name, content }` |
  157. | PUT | operator | Update skill content. Body: `{ source, name, content }` |
  158. | DELETE `?source=...&name=...` | operator | Delete a skill |
  159. **Skill sources:** `user-agents`, `user-codex`, `project-agents`, `project-codex`, `openclaw`
  160. ### Status — `/api/status`
  161. | Action | Min Role | Description |
  162. |--------|----------|-------------|
  163. | GET `?action=overview` | viewer | System status (uptime, memory, disk, sessions) |
  164. | GET `?action=dashboard` | viewer | Aggregated dashboard data with DB stats |
  165. | GET `?action=gateway` | viewer | Gateway process status and port check |
  166. | GET `?action=models` | viewer | Available AI models (catalog + local Ollama) |
  167. | GET `?action=health` | viewer | Health checks (gateway, disk, memory) |
  168. | GET `?action=capabilities` | viewer | Feature flags: gateway reachable, Claude home, subscriptions |
  169. ### Adapters — `/api/adapters`
  170. | Method | Min Role | Description |
  171. |--------|----------|-------------|
  172. | GET | viewer | List available framework adapter names |
  173. | POST | operator | Execute adapter action (see Agent Lifecycle above) |
  174. ## Framework Adapter Protocol
  175. All agent lifecycle operations use a single endpoint:
  176. ```
  177. POST /api/adapters
  178. Content-Type: application/json
  179. x-api-key: <key>
  180. {
  181. "framework": "<adapter-name>",
  182. "action": "<action>",
  183. "payload": { ... }
  184. }
  185. ```
  186. **Available frameworks:** `generic`, `openclaw`, `crewai`, `langgraph`, `autogen`, `claude-sdk`
  187. **Available actions:** `register`, `heartbeat`, `report`, `assignments`, `disconnect`
  188. All adapters implement the same `FrameworkAdapter` interface — choose the one matching your agent framework, or use `generic` as a universal fallback.
  189. **Payload shapes by action:**
  190. | Action | Required Fields | Optional Fields |
  191. |--------|----------------|-----------------|
  192. | `register` | `agentId`, `name` | `metadata` |
  193. | `heartbeat` | `agentId` | `status`, `metrics` |
  194. | `report` | `taskId`, `agentId` | `progress`, `status`, `output` |
  195. | `assignments` | `agentId` | — |
  196. | `disconnect` | `agentId` | — |
  197. ## Environment Variables
  198. | Variable | Default | Description |
  199. |----------|---------|-------------|
  200. | `API_KEY` | — | API key for agent/script authentication |
  201. | `OPENCLAW_GATEWAY_HOST` | `127.0.0.1` | Gateway host address |
  202. | `OPENCLAW_GATEWAY_PORT` | `18789` | Gateway port |
  203. | `OPENCLAW_STATE_DIR` | `~/.openclaw` | OpenClaw state directory |
  204. | `OPENCLAW_CONFIG_PATH` | `<state-dir>/openclaw.json` | Gateway config file path |
  205. | `MC_CLAUDE_HOME` | `~/.claude` | Claude home directory |
  206. ## Real-Time Events
  207. MC broadcasts events via SSE (`/api/events`) and WebSocket. Key event types:
  208. - `agent.created`, `agent.updated`, `agent.status_changed`
  209. - `task.created`, `task.updated`, `task.status_changed`
  210. Subscribe to SSE for live dashboard updates when building integrations.
README.md · README · 306 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # Mission Control
  3. Self-hosted control plane for operating AI agents.
  4. Dispatch tasks, inspect runs, review failures, track spend, and coordinate agent runtimes
  5. from one local dashboard backed by SQLite.
  6. An open-source project by [Builderz Labs](https://builderz.dev), created and maintained by [nyk](https://nyk.dev).
  7. It works with OpenClaw, Claude Code, Codex, and other runtimes - it is not part of any one of them.
  8. [![Quality Gate](https://github.com/builderz-labs/mission-control/actions/workflows/quality-gate.yml/badge.svg)](https://github.com/builderz-labs/mission-control/actions/workflows/quality-gate.yml)
  9. [![Release](https://img.shields.io/github/v/release/builderz-labs/mission-control)](https://github.com/builderz-labs/mission-control/releases)
  10. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  11. [![Sponsor](https://img.shields.io/github/sponsors/builderz-labs?label=Sponsor)](https://github.com/sponsors/builderz-labs)
  12. <img src="docs/mission-control-overview.png" alt="Mission Control overview dashboard with active sessions, live activity, fleet status per runtime, and the task pipeline" width="900">
  13. </div>
  14. > [!WARNING]
  15. > Mission Control is alpha software. APIs, schemas, and configuration may change between
  16. > releases. Read the [security guidance](#security-boundary) before exposing it to a network.
  17. ## Start locally
  18. Node.js 22 or newer and pnpm are required for a source install.
  19. ```bash
  20. git clone https://github.com/builderz-labs/mission-control.git
  21. cd mission-control
  22. bash install.sh --local
  23. ```
  24. Open `http://localhost:3000/setup`, create the first admin account, then copy the API key
  25. from Settings if an agent or script needs headless access.
  26. The manual path is useful when you already manage Node and pnpm:
  27. ```bash
  28. nvm use 22
  29. pnpm install
  30. pnpm dev
  31. ```
  32. Windows users can run `./install.ps1 -Mode local` in PowerShell.
  33. ### Start with Docker
  34. ```bash
  35. docker compose up
  36. ```
  37. Or run the published multi-architecture image:
  38. ```bash
  39. docker pull ghcr.io/builderz-labs/mission-control:latest
  40. docker run --rm -p 3000:3000 ghcr.io/builderz-labs/mission-control:latest
  41. ```
  42. Use the hardened Compose overlay for a network-accessible deployment:
  43. ```bash
  44. docker compose -f docker-compose.yml -f docker-compose.hardened.yml up -d
  45. ```
  46. The [deployment guide](docs/deployment.md) covers persistent data, TLS termination,
  47. gateway connectivity, and standalone builds.
  48. ## What Mission Control governs
  49. The control plane sits above agent runtimes. It does not replace their reasoning or tool
  50. loops. It gives operators one place to see and govern the work around those loops.
  51. | Area | Shipped surface |
  52. |---|---|
  53. | Tasks | Inbox, assignment, execution, review, Aegis quality gate, and completion receipts |
  54. | Agents | Registration, presence, sessions, runtime adapters, configuration, and workspace sync |
  55. | Operations | Activity stream, schedules, alerts, webhooks, logs, token use, and cost views |
  56. | Knowledge | Memory browser, relationship graph, skills registry, and local skill synchronization |
  57. | Governance | Roles, API keys, security events, trust signals, approvals, audits, and evals |
  58. | Interfaces | Web UI, CLI, MCP server, OpenAPI-described REST API, WebSocket, and SSE |
  59. The runtime is self-hosted and workspace-aware. SQLite stores local control-plane state.
  60. Shared workspaces can use deployment-level runtime integrations. Strict workspaces block
  61. those integrations until the underlying resources carry workspace ownership. A gateway is
  62. optional for task, project, agent, scheduler, webhook, alert, and cost work; live session
  63. messaging needs a connected runtime gateway.
  64. ## Operator field notes
  65. Dashboards compress a sequence into current state. When a run needs review, record the
  66. identity, task, tool call, approval, result, and verification evidence before changing it.
  67. Keep unresolved items distinct from accepted risk.
  68. ![Mission Control operator field notes](docs/operator-field-notes.webp)
  69. Logs show what ran. A completion receipt or inspected artifact shows what finished.
  70. ## Pick the right fit
  71. Use Mission Control when multiple agents or runtimes make it hard to answer who owns a
  72. task, what executed, which result passed review, or where spend and failures accumulated.
  73. It is probably the wrong tool when:
  74. - one agent on one machine already stays understandable from its native CLI;
  75. - you need a managed multi-tenant SaaS rather than a self-hosted control plane;
  76. - you want an agent framework to define planning and tool use;
  77. - your deployment cannot tolerate alpha schema or API changes.
  78. Adapters and observation surfaces cover OpenClaw, Claude Code, Codex,
  79. CrewAI, LangGraph, AutoGen, and Claude SDK workflows. Adapter depth varies by runtime; see
  80. [agent setup](docs/agent-setup.md) and [CLI integration](docs/cli-integration.md) before
  81. assuming feature parity.
  82. ## Connect an agent
  83. The shortest gateway-free loop uses the REST API. Export the URL and API key shown in
  84. Settings:
  85. ```bash
  86. export MC_URL=http://localhost:3000
  87. export MC_API_KEY=replace-with-your-api-key
  88. ```
  89. Register an agent and create work:
  90. ```bash
  91. curl -s -X POST "$MC_URL/api/agents/register" \
  92. -H "Authorization: Bearer $MC_API_KEY" \
  93. -H "Content-Type: application/json" \
  94. -d '{"name":"scout","role":"researcher"}'
  95. curl -s -X POST "$MC_URL/api/tasks" \
  96. -H "Authorization: Bearer $MC_API_KEY" \
  97. -H "Content-Type: application/json" \
  98. -d '{"title":"Review open incidents","assigned_to":"scout","priority":"medium"}'
  99. ```
  100. The agent can then claim its queue:
  101. ```bash
  102. curl -s "$MC_URL/api/tasks/queue?agent=scout" \
  103. -H "Authorization: Bearer $MC_API_KEY"
  104. ```
  105. Continue with the [first-agent quickstart](docs/quickstart.md) for heartbeats, task results,
  106. queue behavior, CLI equivalents, and MCP setup.
  107. ### CLI
  108. ```bash
  109. pnpm mc agents list --json
  110. pnpm mc tasks queue --agent scout --json
  111. pnpm mc events watch --types agent,task
  112. ```
  113. ### MCP server
  114. ```bash
  115. claude mcp add mission-control -- \
  116. env MC_URL=http://127.0.0.1:3000 MC_API_KEY=replace-with-your-api-key \
  117. node /absolute/path/to/mission-control/scripts/mc-mcp-server.cjs
  118. ```
  119. Use the [CLI and MCP reference](docs/cli-agent-control.md) for the current command and tool
  120. surface. The REST contract lives in [`openapi.json`](openapi.json). A running instance serves
  121. the interactive reference at `/docs` and the OpenAPI JSON at `/api/docs`.
  122. ## Product surfaces
  123. ### Tasks and quality review
  124. The task board tracks work through inbox, assignment, execution, review, quality review,
  125. and completion. Aegis review requires an approval record before a task reaches done.
  126. ![Mission Control task board with assigned, in-progress, and review columns of agent tasks](docs/mission-control-tasks.png)
  127. ### Agents and runtimes
  128. Agent views combine registration state, heartbeats, sessions, configuration, local runtime
  129. discovery, and workspace files.
  130. ![Mission Control agents panel showing a five-agent squad with roles, heartbeats, and workspace conventions](docs/mission-control-agents.png)
  131. ### Memory and skills
  132. The memory browser and relationship graph inspect filesystem-backed memory and linked
  133. session knowledge. The Skills Hub discovers local skill roots and scans registry content
  134. before installation.
  135. ![Mission Control memory browser rendering a markdown agent note with wiki-style links between memory files](docs/mission-control-memory.png)
  136. ### Schedules and activity
  137. Recurring task templates create dated work on a cron schedule. The activity stream combines
  138. agent, task, and system events for operator review.
  139. ![Mission Control cron management calendar with scheduled jobs across the week](docs/mission-control-cron.png)
  140. ![Mission Control activity stream with per-agent status and heartbeat events](docs/mission-control-activity.png)
  141. ## Documentation
  142. | Guide | Use it for |
  143. |---|---|
  144. | [Quickstart](docs/quickstart.md) | Register an agent and run the first task loop |
  145. | [Agent setup](docs/agent-setup.md) | Sources, identities, SOUL files, and heartbeats |
  146. | [Orchestration](docs/orchestration.md) | Dispatch, handoffs, workflows, and review gates |
  147. | [CLI and MCP](docs/cli-agent-control.md) | Headless commands and agent tools |
  148. | [CLI integration](docs/cli-integration.md) | Claude Code, Codex, and gateway-free connections |
  149. | [Deployment](docs/deployment.md) | Local, Docker, standalone, reverse proxy, and VPS setup |
  150. | [Security hardening](docs/SECURITY-HARDENING.md) | Network, container, CSP, and secret controls |
  151. | [Support](SUPPORT.md) | Questions, bugs, feature proposals, and security-report routing |
  152. | [OpenClaw compatibility](docs/openclaw-config-compatibility.md) | Config and state-directory behavior |
  153. | [Release process](RELEASE.md) | Versioning, tags, images, and release checks |
  154. ## Architecture
  155. ```text
  156. Web UI ─┐
  157. CLI ────┼── auth ─ dispatch ─ events ─ policy ─ receipts
  158. MCP ────┤ │
  159. REST ───┘ SQLite + agent runtimes
  160. ```
  161. | Layer | Technology |
  162. |---|---|
  163. | Application | Next.js 16 App Router, React 19, TypeScript 5 |
  164. | Interface | Tailwind CSS 4, Zustand, Recharts, xterm.js |
  165. | State | SQLite through better-sqlite3, with WAL mode |
  166. | Boundaries | REST/OpenAPI, MCP, CLI, WebSocket, and SSE |
  167. | Access | Session cookies, API keys, Google sign-in, and role checks |
  168. | Validation | Zod at input boundaries |
  169. | Verification | Vitest, Playwright, ESLint, TypeScript, build, and API parity checks |
  170. Runtime data defaults to `.data/`. Set `MISSION_CONTROL_DATA_DIR` to an absolute persistent
  171. path for standalone deployments. The complete environment contract is in
  172. [`.env.example`](.env.example).
  173. ## Security boundary
  174. - Keep Mission Control on a trusted network unless a TLS reverse proxy and
  175. `MC_ALLOWED_HOSTS` are configured.
  176. - Replace or securely store generated credentials before broader access.
  177. - Use the hardened Compose overlay for production-like container deployments.
  178. - Treat agent messages, skill packages, webhooks, and MCP content as untrusted input.
  179. - Report vulnerabilities through [SECURITY.md](SECURITY.md), not a public issue.
  180. Access controls and security inspection surfaces are included, but alpha status
  181. still applies. Read [SECURITY-HARDENING.md](docs/SECURITY-HARDENING.md) before relying on a
  182. network-accessible deployment.
  183. ## Develop
  184. ```bash
  185. pnpm install --frozen-lockfile
  186. pnpm lint
  187. pnpm typecheck
  188. pnpm test
  189. pnpm build
  190. pnpm test:e2e
  191. ```
  192. `pnpm quality:gate` runs the full repository gate. Useful diagnostics:
  193. ```bash
  194. bash scripts/station-doctor.sh
  195. bash scripts/security-audit.sh
  196. pnpm api:parity
  197. ```
  198. Common local failures:
  199. | Symptom | Check |
  200. |---|---|
  201. | Login returns an internal error after changing Node versions | Run `pnpm rebuild better-sqlite3` |
  202. | Docker cannot reach the gateway | Set `OPENCLAW_GATEWAY_HOST=host.docker.internal` |
  203. | Browser WebSocket cannot connect | Leave `NEXT_PUBLIC_GATEWAY_HOST` empty or set a browser-reachable host |
  204. | Password text after `#` disappears | Quote `AUTH_PASS` or use `AUTH_PASS_B64` |
  205. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution scope, coding standards, and review
  206. expectations. Community conduct is defined in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
  207. ## Project status and support
  208. Release notes live in [CHANGELOG.md](CHANGELOG.md). Open issues are the current roadmap;
  209. the project does not promise dates for unassigned work.
  210. - Bugs and feature proposals: [GitHub Issues](https://github.com/builderz-labs/mission-control/issues)
  211. - Vulnerabilities: [private reporting instructions](SECURITY.md)
  212. - Builderz Labs: [builderz.dev](https://builderz.dev)
  213. - Maintained by [Nyk](https://nyk.dev). Sponsor [Nyk](https://github.com/sponsors/0xNyk) or [Builderz Labs](https://github.com/sponsors/builderz-labs). Follow [@nykdotdev](https://x.com/nykdotdev).
  214. <p align="center">
  215. <picture>
  216. <source media="(prefers-color-scheme: dark)" srcset="docs/star-history-dark.svg">
  217. <img src="docs/star-history-light.svg" alt="Mission Control star history" width="600">
  218. </picture>
  219. </p>
  220. ## License
  221. [MIT](LICENSE) © 2026 [Builderz Labs](https://github.com/builderz-labs)
install.sh · Bundled script · 470 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # Mission Control — One-Command Installer
  3. # The mothership for your OpenClaw fleet.
  4. #
  5. # Usage:
  6. # curl -fsSL https://raw.githubusercontent.com/builderz-labs/mission-control/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 6 on GitHub
  7. # # or
  8. # bash install.sh [--docker|--local] [--port PORT] [--data-dir DIR]
  9. #
  10. # Installs Mission Control and optionally repairs/configures OpenClaw.
  11. set -euo pipefail
  12. # ── Defaults ──────────────────────────────────────────────────────────────────
  13. MC_PORT="${MC_PORT:-3000}"
  14. MC_DATA_DIR=""
  15. DEPLOY_MODE=""
  16. SKIP_OPENCLAW=false
  17. REPO_URL="https://github.com/builderz-labs/mission-control.git"
  18. INSTALL_DIR="${MC_INSTALL_DIR:-$(pwd)/mission-control}"
  19. # ── Parse arguments ───────────────────────────────────────────────────────────
  20. while [[ $# -gt 0 ]]; do
  21. case "$1" in
  22. --docker) DEPLOY_MODE="docker"; shift ;;
  23. --local) DEPLOY_MODE="local"; shift ;;
  24. --port) MC_PORT="$2"; shift 2 ;;
  25. --data-dir) MC_DATA_DIR="$2"; shift 2 ;;
  26. --skip-openclaw) SKIP_OPENCLAW=true; shift ;;
  27. --dir) INSTALL_DIR="$2"; shift 2 ;;
  28. -h|--help)
  29. echo "Usage: install.sh [--docker|--local] [--port PORT] [--data-dir DIR] [--dir INSTALL_DIR] [--skip-openclaw]"
  30. exit 0 ;;
  31. *) echo "Unknown option: $1"; exit 1 ;;
  32. esac
  33. done
  34. # ── Helpers ───────────────────────────────────────────────────────────────────
  35. info() { echo -e "\033[1;34m[MC]\033[0m $*"; }
  36. ok() { echo -e "\033[1;32m[OK]\033[0m $*"; }
  37. warn() { echo -e "\033[1;33m[!!]\033[0m $*"; }
  38. err() { echo -e "\033[1;31m[ERR]\033[0m $*" >&2; }
  39. die() { err "$*"; exit 1; }
  40. command_exists() { command -v "$1" &>/dev/null; }
  41. # Escape sed replacement metacharacters (|, &, \) in a value.
  42. # Does not handle newlines — callers must ensure single-line input.
  43. sed_escape() { printf '%s' "$1" | sed 's/[|&\\]/\\&/g'; }
  44. # Portable in-place sed (macOS requires -i '', Linux uses -i)
  45. portable_sed() {
  46. local pattern="$1" file="$2"
  47. if [[ "$(uname)" == "Darwin" ]]; then
  48. sed -i '' "$pattern" "$file"
  49. else
  50. sed -i "$pattern" "$file"
  51. fi
  52. }
  53. detect_os() {
  54. local os arch
  55. os="$(uname -s)"
  56. arch="$(uname -m)"
  57. case "$os" in
  58. Linux) OS="linux" ;;
  59. Darwin) OS="darwin" ;;
  60. *) die "Unsupported OS: $os" ;;
  61. esac
  62. case "$arch" in
  63. x86_64|amd64) ARCH="x64" ;;
  64. aarch64|arm64) ARCH="arm64" ;;
  65. *) die "Unsupported architecture: $arch" ;;
  66. esac
  67. ok "Detected $OS/$ARCH"
  68. }
  69. check_prerequisites() {
  70. local has_docker=false has_node=false
  71. if command_exists docker && docker info &>/dev/null 2>&1; then
  72. has_docker=true
  73. ok "Docker available ($(docker --version | head -1))"
  74. fi
  75. if command_exists node; then
  76. local node_major
  77. node_major=$(node -v | sed 's/v//' | cut -d. -f1)
  78. if [[ "$node_major" -ge 20 ]]; then
  79. has_node=true
  80. ok "Node.js $(node -v) available"
  81. else
  82. warn "Node.js $(node -v) found but v20+ required"
  83. fi
  84. fi
  85. if ! $has_docker && ! $has_node; then
  86. die "Either Docker or Node.js 20+ is required. Install one and retry."
  87. fi
  88. # Auto-select deploy mode if not specified
  89. if [[ -z "$DEPLOY_MODE" ]]; then
  90. if $has_docker; then
  91. DEPLOY_MODE="docker"
  92. info "Auto-selected Docker deployment (use --local to override)"
  93. else
  94. DEPLOY_MODE="local"
  95. info "Auto-selected local deployment (Docker not available)"
  96. fi
  97. fi
  98. # Validate chosen mode
  99. if [[ "$DEPLOY_MODE" == "docker" ]] && ! $has_docker; then
  100. die "Docker deployment requested but Docker is not available"
  101. fi
  102. if [[ "$DEPLOY_MODE" == "local" ]] && ! $has_node; then
  103. die "Local deployment requested but Node.js 20+ is not available"
  104. fi
  105. if [[ "$DEPLOY_MODE" == "local" ]] && ! command_exists pnpm; then
  106. info "Installing pnpm via corepack..."
  107. corepack enable && corepack prepare pnpm@latest --activate
  108. ok "pnpm installed"
  109. fi
  110. }
  111. # ── Clone or update repo ─────────────────────────────────────────────────────
  112. fetch_source() {
  113. if [[ -d "$INSTALL_DIR/.git" ]]; then
  114. info "Updating existing installation at $INSTALL_DIR..."
  115. cd "$INSTALL_DIR"
  116. git fetch --tags
  117. local latest_tag
  118. latest_tag=$(git describe --tags --abbrev=0 origin/main 2>/dev/null || echo "")
  119. if [[ -n "$latest_tag" ]]; then
  120. git checkout "$latest_tag"
  121. ok "Checked out $latest_tag"
  122. else
  123. git pull origin main
  124. ok "Updated to latest main"
  125. fi
  126. else
  127. info "Cloning Mission Control..."
  128. if command_exists git; then
  129. git clone --depth 1 "$REPO_URL" "$INSTALL_DIR"
  130. cd "$INSTALL_DIR"
  131. ok "Cloned to $INSTALL_DIR"
  132. else
  133. die "git is required to clone the repository"
  134. fi
  135. fi
  136. }
  137. # ── Generate .env ─────────────────────────────────────────────────────────────
  138. setup_env() {
  139. if [[ -f "$INSTALL_DIR/.env" ]]; then
  140. info "Existing .env found — keeping current configuration"
  141. return
  142. fi
  143. info "Generating secure .env configuration..."
  144. bash "$INSTALL_DIR/scripts/generate-env.sh" "$INSTALL_DIR/.env"
  145. # Set the port if non-default
  146. if [[ "$MC_PORT" != "3000" ]]; then
  147. portable_sed "s|^# PORT=3000|PORT=$(sed_escape "$MC_PORT")|" "$INSTALL_DIR/.env"
  148. fi
  149. # Auto-detect and write OpenClaw home directory into .env
  150. local oc_home="${OPENCLAW_HOME:-$HOME/.openclaw}"
  151. if [[ -d "$oc_home" ]]; then
  152. portable_sed "s|^OPENCLAW_HOME=.*|OPENCLAW_HOME=$(sed_escape "$oc_home")|" "$INSTALL_DIR/.env"
  153. info "Set OPENCLAW_HOME=$oc_home in .env"
  154. fi
  155. # In Docker mode, the gateway runs on the host, not inside the container.
  156. # Set OPENCLAW_GATEWAY_HOST to the Docker host gateway IP so the container
  157. # can reach the gateway. Users may override this with the gateway container
  158. # name if running OpenClaw in a container on the same network.
  159. if [[ "$DEPLOY_MODE" == "docker" ]]; then
  160. local gw_host="${OPENCLAW_GATEWAY_HOST:-}"
  161. if [[ -z "$gw_host" ]]; then
  162. # Detect Docker host IP (host-gateway alias or default bridge)
  163. if getent hosts host-gateway &>/dev/null 2>&1; then
  164. gw_host="host-gateway"
  165. else
  166. # Fallback: use the default Docker bridge gateway (172.17.0.1)
  167. gw_host=$(ip route show default 2>/dev/null | awk '/default/ {print $3; exit}' || echo "172.17.0.1")
  168. fi
  169. fi
  170. if [[ -n "$gw_host" && "$gw_host" != "127.0.0.1" ]]; then
  171. portable_sed "s|^OPENCLAW_GATEWAY_HOST=.*|OPENCLAW_GATEWAY_HOST=$(sed_escape "$gw_host")|" "$INSTALL_DIR/.env"
  172. info "Set OPENCLAW_GATEWAY_HOST=$gw_host in .env (Docker host IP)"
  173. info " If your gateway runs in a Docker container, update OPENCLAW_GATEWAY_HOST"
  174. info " to the container name and add it to the mc-net network."
  175. fi
  176. fi
  177. ok "Secure .env generated"
  178. }
  179. # ── Docker deployment ─────────────────────────────────────────────────────────
  180. deploy_docker() {
  181. info "Starting Docker deployment..."
  182. export MC_PORT
  183. docker compose up -d --build
  184. # Wait for healthy
  185. info "Waiting for Mission Control to become healthy..."
  186. local retries=30
  187. while [[ $retries -gt 0 ]]; do
  188. if docker compose ps --format json 2>/dev/null | grep -q '"Health":"healthy"'; then
  189. break
  190. fi
  191. # Fallback: try HTTP check
  192. if curl -sf "http://localhost:$MC_PORT/login" &>/dev/null; then
  193. break
  194. fi
  195. sleep 2
  196. ((retries--))
  197. done
  198. if [[ $retries -eq 0 ]]; then
  199. warn "Timeout waiting for health check — container may still be starting"
  200. docker compose logs --tail 20
  201. else
  202. ok "Mission Control is running in Docker"
  203. fi
  204. }
  205. # ── Local deployment ──────────────────────────────────────────────────────────
  206. deploy_local() {
  207. info "Starting local deployment..."
  208. cd "$INSTALL_DIR"
  209. pnpm install --frozen-lockfile 2>/dev/null || pnpm install
  210. pnpm rebuild better-sqlite3 2>/dev/null || true
  211. ok "Dependencies installed"
  212. info "Building Mission Control..."
  213. pnpm build
  214. ok "Build complete"
  215. # Create systemd service on Linux if systemctl is available
  216. if [[ "$OS" == "linux" ]] && command_exists systemctl; then
  217. setup_systemd
  218. fi
  219. info "Starting Mission Control..."
  220. PORT="$MC_PORT" nohup pnpm start > "$INSTALL_DIR/.data/mc.log" 2>&1 &
  221. local pid=$!
  222. echo "$pid" > "$INSTALL_DIR/.data/mc.pid"
  223. sleep 3
  224. if kill -0 "$pid" 2>/dev/null; then
  225. ok "Mission Control running (PID $pid)"
  226. else
  227. err "Failed to start. Check logs: $INSTALL_DIR/.data/mc.log"
  228. exit 1
  229. fi
  230. }
  231. # ── Systemd service ──────────────────────────────────────────────────────────
  232. setup_systemd() {
  233. local service_file="/etc/systemd/system/mission-control.service"
  234. if [[ -f "$service_file" ]]; then
  235. info "Systemd service already exists"
  236. return
  237. fi
  238. info "Creating systemd service..."
  239. local user
  240. user="$(whoami)"
  241. local node_path
  242. node_path="$(which node)"
  243. cat > /tmp/mission-control.service <<UNIT
  244. [Unit]
  245. Description=Mission Control - OpenClaw Agent Dashboard
  246. After=network.target
  247. [Service]
  248. Type=simple
  249. User=$user
  250. WorkingDirectory=$INSTALL_DIR
  251. ExecStart=$node_path $INSTALL_DIR/.next/standalone/server.js
  252. Restart=on-failure
  253. RestartSec=5
  254. Environment=NODE_ENV=production
  255. Environment=PORT=$MC_PORT
  256. EnvironmentFile=$INSTALL_DIR/.env
  257. [Install]
  258. WantedBy=multi-user.target
  259. UNIT
  260. if [[ "$(id -u)" -eq 0 ]]; then
  261. mv /tmp/mission-control.service "$service_file"
  262. systemctl daemon-reload
  263. systemctl enable mission-control
  264. ok "Systemd service installed and enabled"
  265. else
  266. info "Run as root to install systemd service:"
  267. info " sudo mv /tmp/mission-control.service $service_file"
  268. info " sudo systemctl daemon-reload && sudo systemctl enable --now mission-control"
  269. fi
  270. }
  271. # ── OpenClaw fleet check ─────────────────────────────────────────────────────
  272. check_openclaw() {
  273. if $SKIP_OPENCLAW; then
  274. info "Skipping OpenClaw checks (--skip-openclaw)"
  275. return
  276. fi
  277. echo ""
  278. info "=== OpenClaw Fleet Check ==="
  279. # Check if openclaw binary exists
  280. if command_exists openclaw; then
  281. local oc_version
  282. oc_version="$(openclaw --version 2>/dev/null || echo 'unknown')"
  283. ok "OpenClaw binary found: $oc_version"
  284. elif command_exists clawdbot; then
  285. local cb_version
  286. cb_version="$(clawdbot --version 2>/dev/null || echo 'unknown')"
  287. ok "ClawdBot binary found: $cb_version (legacy)"
  288. warn "Consider upgrading to openclaw CLI"
  289. else
  290. info "OpenClaw CLI not found — install it to enable agent orchestration"
  291. info " See: https://github.com/builderz-labs/openclaw"
  292. return
  293. fi
  294. # Check OpenClaw home directory
  295. local oc_home="${OPENCLAW_HOME:-$HOME/.openclaw}"
  296. if [[ -d "$oc_home" ]]; then
  297. ok "OpenClaw home: $oc_home"
  298. # Check config
  299. local oc_config="$oc_home/openclaw.json"
  300. if [[ -f "$oc_config" ]]; then
  301. ok "Config found: $oc_config"
  302. else
  303. warn "No openclaw.json found at $oc_config"
  304. info "Mission Control will create a default config on first gateway connection"
  305. fi
  306. # Check for stale PID files
  307. local stale_count=0
  308. for pidfile in "$oc_home"/*.pid "$oc_home"/pids/*.pid; do
  309. [[ -f "$pidfile" ]] || continue
  310. local pid
  311. pid="$(cat "$pidfile" 2>/dev/null)" || continue
  312. if ! kill -0 "$pid" 2>/dev/null; then
  313. rm -f "$pidfile"
  314. ((stale_count++))
  315. fi
  316. done
  317. if [[ $stale_count -gt 0 ]]; then
  318. ok "Cleaned $stale_count stale PID file(s)"
  319. fi
  320. # Check logs directory size
  321. local logs_dir="$oc_home/logs"
  322. if [[ -d "$logs_dir" ]]; then
  323. local logs_size
  324. if [[ "$(uname)" == "Darwin" ]]; then
  325. logs_size="$(du -sh "$logs_dir" 2>/dev/null | cut -f1)"
  326. else
  327. logs_size="$(du -sh "$logs_dir" 2>/dev/null | cut -f1)"
  328. fi
  329. info "Logs directory: $logs_size ($logs_dir)"
  330. # Clean old logs (> 30 days)
  331. local old_logs
  332. old_logs=$(find "$logs_dir" -name "*.log" -mtime +30 2>/dev/null | wc -l | tr -d ' ')
  333. if [[ "$old_logs" -gt 0 ]]; then
  334. find "$logs_dir" -name "*.log" -mtime +30 -delete 2>/dev/null || true
  335. ok "Cleaned $old_logs log file(s) older than 30 days"
  336. fi
  337. fi
  338. # Check workspace directory
  339. local workspace="$oc_home/workspace"
  340. if [[ -d "$workspace" ]]; then
  341. local agent_count
  342. agent_count=$(find "$workspace" -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')
  343. ((agent_count--)) # subtract the workspace dir itself
  344. info "Workspace: $agent_count agent workspace(s) in $workspace"
  345. fi
  346. else
  347. info "OpenClaw home not found at $oc_home"
  348. info "Set OPENCLAW_HOME in .env to point to your OpenClaw state directory"
  349. fi
  350. # Check gateway port
  351. local gw_host="${OPENCLAW_GATEWAY_HOST:-127.0.0.1}"
  352. local gw_port="${OPENCLAW_GATEWAY_PORT:-18789}"
  353. if nc -z "$gw_host" "$gw_port" 2>/dev/null || (echo > "/dev/tcp/$gw_host/$gw_port") 2>/dev/null; then
  354. ok "Gateway reachable at $gw_host:$gw_port"
  355. else
  356. info "Gateway not reachable at $gw_host:$gw_port (start it with: openclaw gateway start)"
  357. fi
  358. }
  359. # ── Main ──────────────────────────────────────────────────────────────────────
  360. main() {
  361. echo ""
  362. echo " ╔══════════════════════════════════════╗"
  363. echo " ║ Mission Control Installer ║"
  364. echo " ║ The mothership for your fleet ║"
  365. echo " ╚══════════════════════════════════════╝"
  366. echo ""
  367. detect_os
  368. check_prerequisites
  369. # If running from within an existing clone, use current dir
  370. if [[ -f "$(pwd)/package.json" ]] && grep -q '"mission-control"' "$(pwd)/package.json" 2>/dev/null; then
  371. INSTALL_DIR="$(pwd)"
  372. info "Running from existing clone at $INSTALL_DIR"
  373. else
  374. fetch_source
  375. fi
  376. # Ensure data directory exists
  377. mkdir -p "$INSTALL_DIR/.data"
  378. setup_env
  379. case "$DEPLOY_MODE" in
  380. docker) deploy_docker ;;
  381. local) deploy_local ;;
  382. *) die "Unknown deploy mode: $DEPLOY_MODE" ;;
  383. esac
  384. check_openclaw
  385. # ── Print summary ──
  386. echo ""
  387. echo " ╔══════════════════════════════════════╗"
  388. echo " ║ Installation Complete ║"
  389. echo " ╚══════════════════════════════════════╝"
  390. echo ""
  391. info "Dashboard: http://localhost:$MC_PORT"
  392. info "Mode: $DEPLOY_MODE"
  393. info "Data: $INSTALL_DIR/.data/"
  394. echo ""
  395. info "Credentials are in: $INSTALL_DIR/.env"
  396. echo ""
  397. if [[ "$DEPLOY_MODE" == "docker" ]]; then
  398. info "Manage:"
  399. info " docker compose logs -f # view logs"
  400. info " docker compose restart # restart"
  401. info " docker compose down # stop"
  402. else
  403. info "Manage:"
  404. info " cat $INSTALL_DIR/.data/mc.log # view logs"
  405. info " kill \$(cat $INSTALL_DIR/.data/mc.pid) # stop"
  406. fi
  407. echo ""
  408. }
  409. main "$@"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.