Installation

Detailed installation instructions for Mission Control including prerequisites, environment configuration, and deployment options.

Prerequisites

Mission Control requires Node.js 20+ (LTS recommended) and pnpm for dependency management.

Node.js

Install Node.js 20 or later from nodejs.org or use a version manager:

nvm

nvm install 20
nvm use 20

Verify installation:

node --version  # Should show v20.x.x or higher

pnpm

Mission Control uses pnpm for fast, efficient dependency management. Install pnpm using one of these methods:

npm

npm install -g pnpm

Verify installation:

pnpm --version  # Should show 8.x.x or higher

Native Build Tools

Mission Control uses better-sqlite3 which requires native compilation. Install build tools for your platform:

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y python3 make g++

Development Setup

1. Clone Repository

   git clone https://github.com/builderz-labs/mission-control.git
   cd mission-control
   
2. Install Dependencies

   pnpm install
   

   This installs all dependencies and compiles native modules. The process takes 1-2 minutes on first run.

   The better-sqlite3 module is compiled during installation. If compilation fails, ensure you have the required build tools installed.

3. Configure Environment

   Copy the example environment file:

   cp .env.example .env
   

   Edit .env with your configuration. See Environment Variables for details.

4. Start Development Server

   pnpm dev
   

   The server starts at http://localhost:3000. Changes to source files trigger automatic recompilation.

Production Deployment

Direct Deployment

Build and run Mission Control directly on your server:

1. Install Dependencies

   pnpm install --frozen-lockfile
   

   The --frozen-lockfile flag ensures reproducible builds by using the exact versions in pnpm-lock.yaml.

2. Build Application

   pnpm build
   

   Creates an optimized production build in .next/. Build time is typically 2-3 minutes.

   The production build bundles platform-specific native binaries. Build on the same OS and architecture as your target server. A build created on macOS will not work on Linux.

3. Start Production Server

   pnpm start
   

   The server binds to 0.0.0.0:3005 by default. Override with environment variables:

   PORT=8080 pnpm start
   

Docker Deployment

Deploy Mission Control using Docker for isolation and portability:

docker build -t mission-control .
docker run -p 3000:3000 \
  -v mission-control-data:/app/.data \
  -e AUTH_USER=admin \
  -e AUTH_PASS=your-secure-password \
  -e API_KEY=your-api-key \
  mission-control

The Docker image uses a multi-stage build with node:20-slim, compiles native modules inside the container, and runs as non-root user nextjs.

Persistent Data

Mount a volume to persist the SQLite database across container restarts:

docker run -v /path/to/data:/app/.data mission-control

docker-compose

Create docker-compose.yml:

docker-compose.yml

version: '3.8'

services:
  mission-control:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - mission-control-data:/app/.data
    environment:
      - AUTH_USER=admin
      - AUTH_PASS=your-secure-password
      - API_KEY=your-api-key
      - MC_ALLOWED_HOSTS=localhost,yourdomain.com
    restart: unless-stopped

volumes:
  mission-control-data:

Start with:

docker-compose up -d

Environment Variables

Configure Mission Control via environment variables in .env:

Authentication

Variable	Required	Default	Description
AUTH_USER	No	admin	Initial admin username (seeded on first run)
AUTH_PASS	Yes	-	Initial admin password
AUTH_PASS_B64	No	-	Base64-encoded password (overrides AUTH_PASS)
API_KEY	Yes	-	API key for headless/programmatic access
AUTH_SECRET	No	-	Legacy cookie secret (backward compatibility)

Change AUTH_PASS and API_KEY from defaults before production deployment. These credentials provide full administrative access.

Password with special characters:

If your password contains #, quote it or use base64 encoding:

Quoted

AUTH_PASS="my#password"

Network Access

Variable	Required	Default	Description
PORT	No	3000 (Docker) / 3005 (direct)	HTTP server port
MC_ALLOWED_HOSTS	No	localhost,127.0.0.1	Comma-separated host allowlist for production
MC_ALLOW_ANY_HOST	No	false	Bypass host allowlist (development only)
MC_TRUSTED_PROXIES	No	-	Comma-separated IPs for X-Forwarded-For parsing

In production mode, Mission Control blocks requests unless the Host header matches MC_ALLOWED_HOSTS. Use wildcards like *.example.com or 100.* for Tailscale IPs.

OpenClaw Integration

Variable	Required	Default	Description
OPENCLAW_HOME	No*	-	Path to .openclaw directory
OPENCLAW_GATEWAY_HOST	No	127.0.0.1	Gateway WebSocket host
OPENCLAW_GATEWAY_PORT	No	18789	Gateway WebSocket port
OPENCLAW_GATEWAY_TOKEN	No	-	Server-side gateway auth token
NEXT_PUBLIC_GATEWAY_TOKEN	No	-	Browser-side gateway auth token
OPENCLAW_MEMORY_DIR	No	-	Agent memory directory (see note below)

OPENCLAW_HOME is required for memory browser, log viewer, and gateway config features. Point to your OpenClaw installation directory.

Memory Browser Configuration:

OpenClaw stores agent memory in workspace directories, not $OPENCLAW_HOME/memory/. Set OPENCLAW_MEMORY_DIR to your agents root:

OPENCLAW_MEMORY_DIR=/home/you/clawd-agents

This makes the Memory Browser show daily logs, MEMORY.md, and other markdown files from all agent workspaces.

Data Paths

Variable	Required	Default	Description
MISSION_CONTROL_DATA_DIR	No	.data	Data directory (database, logs)
MISSION_CONTROL_DB_PATH	No	.data/mission-control.db	SQLite database path
MISSION_CONTROL_TOKENS_PATH	No	.data/mission-control-tokens.json	Token usage log path

Google OAuth (Optional)

Variable	Required	Default	Description
GOOGLE_CLIENT_ID	No	-	Server-side Google OAuth client ID
NEXT_PUBLIC_GOOGLE_CLIENT_ID	No	-	Browser-side Google OAuth client ID

Create OAuth credentials in Google Cloud Console. Set authorized origins to your Mission Control URL and redirect URI to https://yourdomain.com/api/auth/google.

Claude Code Integration (Optional)

Variable	Required	Default	Description
MC_CLAUDE_HOME	No	~/.claude	Path to Claude Code home directory

Mission Control automatically discovers Claude Code sessions from ~/.claude/projects/ and extracts token usage from JSONL transcripts.

Data Retention (Optional)

Control how long Mission Control retains historical data (in days, 0 = keep forever):

MC_RETAIN_ACTIVITIES_DAYS=90
MC_RETAIN_AUDIT_DAYS=365
MC_RETAIN_LOGS_DAYS=30
MC_RETAIN_NOTIFICATIONS_DAYS=60
MC_RETAIN_PIPELINE_RUNS_DAYS=90
MC_RETAIN_TOKEN_USAGE_DAYS=90

Reverse Proxy Setup

Deploy Mission Control behind a reverse proxy with TLS for any network-accessible deployment. Never expose the application directly to the internet.

Caddy (Recommended)

Caddy automatically provisions TLS certificates via Let’s Encrypt:

Caddyfile

mission-control.yourdomain.com {
    reverse_proxy localhost:3005
}

Start Caddy:

caddy run --config Caddyfile

nginx

Configure nginx with manual certificate management:

nginx.conf

server {
    listen 443 ssl http2;
    server_name mission-control.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3005;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket support
    location /api/events {
        proxy_pass http://localhost:3005;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

If using nginx as a reverse proxy, configure trusted proxies:

.env

MC_TRUSTED_PROXIES=127.0.0.1,10.0.0.0/8

Troubleshooting

”Module not found: better-sqlite3”

Native compilation failed. Install build tools:

# Ubuntu/Debian
sudo apt-get install -y python3 make g++

# Then reinstall
rm -rf node_modules
pnpm install

“Invalid ELF header” or “Mach-O” errors

The native binary was compiled on a different platform. Rebuild on the target OS:

rm -rf node_modules .next
pnpm install
pnpm build

Database locked errors

Only one Mission Control instance can access the SQLite database at a time. Ensure no other processes are using .data/mission-control.db.

”Gateway error: origin not allowed”

The gateway is rejecting connections from Mission Control. Add your dashboard URL to the gateway’s allowed origins in openclaw.json:

openclaw.json

{
  "gateway": {
    "controlUi": {
      "allowedOrigins": ["http://localhost:3000"]
    }
  }
}

Restart the gateway after making changes.

”Gateway error: device identity required”

Device identity signing requires a secure browser context (HTTPS or localhost). Access Mission Control over HTTPS or use localhost instead of 127.0.0.1.

Development Commands

Mission Control includes several development commands:

pnpm dev              # Start development server
pnpm build            # Build for production
pnpm start            # Start production server
pnpm typecheck        # Run TypeScript type checking
pnpm lint             # Run ESLint
pnpm test             # Run Vitest unit tests
pnpm test:watch       # Run tests in watch mode
pnpm test:e2e         # Run Playwright E2E tests
pnpm quality:gate     # Run all checks (lint, typecheck, test, build, e2e)

Run pnpm quality:gate before submitting pull requests to ensure all checks pass.

Next Steps

Quickstart

Register your first agent and explore the dashboard

API Reference

Complete documentation for all 66 REST endpoints

Security Guide

Security best practices and hardening

Integrations

Connect OpenClaw, Claude Code, and custom agents