openclaw-mission-control/README.md

# OpenClaw Mission Control

[![CI](https://github.com/abhi1693/openclaw-mission-control/actions/workflows/ci.yml/badge.svg)](https://github.com/abhi1693/openclaw-mission-control/actions/workflows/ci.yml)

Mission Control is the **web UI and HTTP API** for operating OpenClaw. It’s designed for teams that want a clear control plane for managing **boards**, **tasks**, **agents**, **approvals**, and (optionally) **gateway connections**.

## Active development

OpenClaw Mission Control is under active development. Expect breaking changes and incomplete features as we iterate.

- Use at your own risk for production workloads.
- We welcome **bug reports**, **feature requests**, and **PRs** — see GitHub Issues: https://github.com/abhi1693/openclaw-mission-control/issues

## Architecture (high level)

Mission Control is a small, service-oriented stack:

- **Frontend:** Next.js (default http://localhost:3000)
- **Backend:** FastAPI (default http://localhost:8000)
- **Database:** Postgres
- **Gateway integration (optional):** WebSocket protocol documented in [Gateway WebSocket protocol](./docs/openclaw_gateway_ws.md)

## Documentation

Start with the docs landing page:
- [Docs landing](./docs/README.md)

Operational deep dives:
- Deployment: [Deployment guide](./docs/deployment/README.md)
- Production notes: [Production notes](./docs/production/README.md)
- Troubleshooting: [Troubleshooting](./docs/troubleshooting/README.md)

## Authentication (Clerk)

**Clerk is currently required**.

You must configure Clerk keys for:
- the frontend (`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`)
- the backend (`CLERK_SECRET_KEY`)

See: [Deployment guide](./docs/deployment/README.md#clerk-auth-notes).

## Deployment modes

### 1) Self-host (Docker Compose)

**Prerequisites:** Docker + Docker Compose v2 (`docker compose`)

```bash
cp .env.example .env

# REQUIRED: the browser must be able to reach the backend.
# NEXT_PUBLIC_API_URL must be reachable from the *browser* (host), not an internal Docker network name.
# Missing/blank NEXT_PUBLIC_API_URL will break frontend API calls (e.g. Activity feed).

# REQUIRED: Clerk config.
# Provide real Clerk values via frontend/.env (recommended) and backend/.env.

docker compose -f compose.yml --env-file .env up -d --build
```

Open:
- Frontend: http://localhost:3000
- Backend health: http://localhost:8000/healthz

Stop:

```bash
docker compose -f compose.yml --env-file .env down
```

Useful ops:

```bash
# Tail logs
docker compose -f compose.yml --env-file .env logs -f --tail=200

# Rebuild a single service
docker compose -f compose.yml --env-file .env up -d --build backend

# Reset data (DESTRUCTIVE: deletes Postgres volume)
docker compose -f compose.yml --env-file .env down -v
```

### 2) Contributor local dev loop (DB in Docker, apps on host)

This is the fastest workflow for contributors: run Postgres via Docker, and run the backend + frontend in dev mode.

See: [Development workflow](./docs/03-development.md)

## Testing and CI parity

- Testing guide: [Testing guide](./docs/testing/README.md)
- Coverage policy: [Coverage policy](./docs/coverage-policy.md)

From repo root:

```bash
make help
make setup
make check
```

## License

This project is licensed under the MIT License. See [`LICENSE`](./LICENSE).