From 554d6256c8747a4b208368df4b902577fa8d0565 Mon Sep 17 00:00:00 2001 From: Abhimanyu Saharan Date: Fri, 13 Feb 2026 00:41:32 +0530 Subject: [PATCH] docs: update README for clarity and improved structure --- README.md | 131 ++++++++++++++++++++++++++---------------------------- 1 file changed, 64 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 9817e228..3cabdc41 100644 --- a/README.md +++ b/README.md @@ -2,115 +2,112 @@ [![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**. +OpenClaw Mission Control is the centralized operations and governance platform for running OpenClaw across teams and organizations, with unified visibility, approval controls, and gateway-aware orchestration. +It gives operators a single interface for work orchestration, agent and gateway management, approval-driven governance, and API-backed automation. -image +Mission Control dashboard -## Active development +## Platform overview -OpenClaw Mission Control is under active development. Expect breaking changes and incomplete features as we iterate. +Mission Control is designed to be the day-to-day operations surface for OpenClaw. +Instead of splitting work across multiple tools, teams can plan, execute, review, and audit activity in one system. -- 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 +Core operational areas: -## Architecture (high level) +- Work orchestration: manage organizations, board groups, boards, tasks, and tags. +- Agent operations: create, inspect, and manage agent lifecycle from a unified control surface. +- Governance and approvals: route sensitive actions through explicit approval flows. +- Gateway management: connect and operate gateway integrations for distributed environments. +- Activity visibility: review a timeline of system actions for faster debugging and accountability. +- API-first model: support both web workflows and automation clients from the same platform. -Mission Control is a small, service-oriented stack: +## Use cases -- **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) +- Multi-team agent operations: run multiple boards and board groups across organizations from a single control plane. +- Human-in-the-loop execution: require approvals before sensitive actions and keep decision trails attached to work. +- Distributed runtime control: connect gateways and operate remote execution environments without changing operator workflow. +- Audit and incident review: use activity history to reconstruct what happened, when it happened, and who initiated it. +- API-backed process integration: connect internal workflows and automation clients to the same operational model used in the UI. -## Documentation +## What makes Mission Control different -Start with the docs landing page: -- [Docs landing](./docs/README.md) +- Operations-first design: built for running agent work reliably, not just creating tasks. +- Governance built in: approvals, auth modes, and clear control boundaries are first-class. +- Gateway-aware orchestration: built to operate both local and connected runtime environments. +- Unified UI and API model: operators and automation act on the same objects and lifecycle. +- Team-scale structure: organizations, board groups, boards, tasks, tags, and users in one system of record. -Operational deep dives: -- Deployment: [Deployment guide](./docs/deployment/README.md) -- Production notes: [Production notes](./docs/production/README.md) -- Troubleshooting: [Troubleshooting](./docs/troubleshooting/README.md) +## Who it is for -## Authentication +- Platform teams running OpenClaw in self-hosted or internal environments. +- Operations and engineering teams that need clear approval and auditability controls. +- Organizations that want API-accessible operations without losing a usable web UI. -Mission Control supports two auth modes via `AUTH_MODE`: +## Get started in minutes -- `local`: shared bearer token auth for self-hosted deployments -- `clerk`: Clerk JWT auth +### Prerequisites -`local` mode requires: -- backend: `AUTH_MODE=local`, `LOCAL_AUTH_TOKEN=` -- frontend: `NEXT_PUBLIC_AUTH_MODE=local`, then enter the token in the login screen +- Docker Engine +- Docker Compose v2 (`docker compose`) -`clerk` mode requires: -- backend: `AUTH_MODE=clerk`, `CLERK_SECRET_KEY=` -- frontend: `NEXT_PUBLIC_AUTH_MODE=clerk`, `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=` - -## Deployment modes - -### 1) Self-host (Docker Compose) - -**Prerequisites:** Docker + Docker Compose v2 (`docker compose`) +### 1. Configure environment ```bash cp .env.example .env +``` -# REQUIRED for local auth mode: -# set LOCAL_AUTH_TOKEN to a non-placeholder value with at least 50 characters. +Before startup: -# 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). +- Set `LOCAL_AUTH_TOKEN` to a non-placeholder value (minimum 50 characters) when `AUTH_MODE=local`. +- Ensure `NEXT_PUBLIC_API_URL` is reachable from your browser. -# Auth defaults in .env.example are local mode. -# For production, set LOCAL_AUTH_TOKEN to a random value with at least 50 characters. -# For Clerk mode, set AUTH_MODE=clerk and provide Clerk keys. +### 2. Start Mission Control +```bash docker compose -f compose.yml --env-file .env up -d --build ``` -Open: -- Frontend: http://localhost:3000 +### 3. Open the application + +- Mission Control UI: http://localhost:3000 - Backend health: http://localhost:8000/healthz -Stop: +### 4. Stop the stack ```bash docker compose -f compose.yml --env-file .env down ``` -Useful ops: +## Authentication -```bash -# Tail logs -docker compose -f compose.yml --env-file .env logs -f --tail=200 +Mission Control supports two authentication modes: -# Rebuild a single service -docker compose -f compose.yml --env-file .env up -d --build backend +- `local`: shared bearer token mode (default for self-hosted use) +- `clerk`: Clerk JWT mode -# Reset data (DESTRUCTIVE: deletes Postgres volume) -docker compose -f compose.yml --env-file .env down -v -``` +Environment templates: -### 2) Contributor local dev loop (DB in Docker, apps on host) +- Root: [`.env.example`](./.env.example) +- Backend: [`backend/.env.example`](./backend/.env.example) +- Frontend: [`frontend/.env.example`](./frontend/.env.example) -This is the fastest workflow for contributors: run Postgres via Docker, and run the backend + frontend in dev mode. +## Documentation -See: [Development workflow](./docs/03-development.md) +Complete guides for deployment, production, troubleshooting, and testing are in [`/docs`](./docs/). -## Testing and CI parity +## Project status -- Testing guide: [Testing guide](./docs/testing/README.md) -- Coverage policy: [Coverage policy](./docs/coverage-policy.md) +Mission Control is under active development. -From repo root: +- Features and APIs may change between releases. +- Validate and harden your configuration before production use. -```bash -make help -make setup -make check -``` +## Contributing + +Issues and pull requests are welcome. + +- [Contributing guide](./CONTRIBUTING.md) +- [Open issues](https://github.com/abhi1693/openclaw-mission-control/issues) ## License