null
/
Mission-Control
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Mission-Control/README.md

203 lines
9.9 KiB
Markdown
Raw Blame History

# Mission Control
A monitoring dashboard for [OpenClaw](https://github.com/openclaw/openclaw) gateways — built with Python/FastAPI and Next.js.
## What It Does
Mission Control connects to your OpenClaw gateways via their RPC endpoints and gives you a single place to see:
- **How much you're spending** — per-model cost breakdowns, cost trends, which model is burning your budget
- **Whether your gateway is healthy** — online/offline status, CPU, RAM, disk, uptime
- **What your cron jobs are doing** — schedules, last run, next fire, failures
- **Which sessions are active** — model, type, context usage, token counts
- **What your sub-agents are up to** — cost, duration, status at a glance
- **How costs are trending** — daily charts, 7d/30d comparisons, acceleration signals
It polls your gateways in the background, stores everything in PostgreSQL, and serves it through REST endpoints ready for the frontend dashboard.
## Current Status
**Version:** 0.0.4 (dev branch)
**Phase:** Phase 2 — backend monitoring collection and API endpoints are live. Frontend dashboard panels are next.
### What's Working
- **Backend API** — 97+ endpoints across boards, agents, gateways, tasks, organizations, approvals, and more (forked from base platform)
- **Gateway data collection** — background service polls `usage.cost`, `cron.list`, `sessions.list`, `sessions.preview`, `health`, and `status` RPC endpoints and upserts into PostgreSQL
- **7 monitoring models** — CostSnapshot, CronJobStatus, SessionEvent, SubAgentRun, SystemHealthMetric, AlertRule, AlertEvent
- **10 CRUD monitoring endpoints** — paginated, org-scoped read endpoints for all monitoring models
- **2 summary endpoints** — cost-summary and cost-breakdown (latest snapshot per gateway, per-model percentage breakdown)
- **Data processing functions** — `ModelName()`, `BuildDailyChart()`, `BuildAlerts()`, `BuildCostBreakdown()`, `FmtTokens()` ported from Go
- **Event parser** — `parse_session_event()` and `format_tool_status()` ported from TypeScript
- **WebSocket** — `/ws/agents` with initial snapshot (last 50 events) + background polling
- **Auth** — Clerk for production, local token auth for dev (`AUTH_MODE=local`)
- **Next.js frontend** — boards, tasks, agents, gateways, organizations, approvals pages (base platform UI)
### What's Not Yet Built
These are the remaining monitoring summary endpoints (tracked in FUTURE.md):
- Health summary (`/api/v1/monitoring/health-summary`)
- Cron summary (`/api/v1/monitoring/cron-summary`)
- Sessions summary (`/api/v1/monitoring/sessions-summary`)
- Sub-agents summary (`/api/v1/monitoring/sub-agents-summary`)
- Cost trends (`/api/v1/monitoring/trends`)
And the frontend dashboard panels that consume these endpoints.
## Architecture
```
OpenClaw Gateway(s)
│
│ RPC (usage.cost, cron.list, sessions.list, health, status)
▼
GatewayCollectorService ← background asyncio task
│
│ upsert into PostgreSQL
▼
Monitoring Models ← CostSnapshot, CronJobStatus, SessionEvent, SubAgentRun, SystemHealthMetric, AlertRule, AlertEvent
│
│ API endpoints + data_processing transforms
▼
REST API (/api/v1/monitoring/*) ← cost-summary, cost-breakdown, CRUD endpoints, more coming
│
│ WebSocket (/ws/agents)
▼
Next.js Frontend ← boards, tasks, agents + upcoming monitoring dashboard
```
**Stack:**
- Backend: Python 3.12 / FastAPI / SQLModel / PostgreSQL / Redis
- Frontend: Next.js 16 / React 19 / Tailwind CSS / shadcn/ui / TanStack React Query
- Auth: Clerk (production) or local token (dev)
- API client: orval-generated TypeScript hooks
**Source repos** (for reference, not imported):
- `mudrii/openclaw-dashboard` (Go) — dashboard panels and data processing logic
- `jaffer1979/openclaw-pixel-agents-dashboard` (Node/Express) — session watching and event parsing
All Go/Node logic is ported to Python. No new backend languages.
## API Reference
### Monitoring Endpoints
| Endpoint | Method | Description | Status |
|----------|--------|-------------|--------|
| `/api/v1/monitoring/cost-summary` | GET | Cost overview per gateway (latest snapshot) | ✅ Live |
| `/api/v1/monitoring/cost-breakdown` | GET | Per-model cost breakdown ranked by spend | ✅ Live |
| `/api/v1/monitoring/cost-snapshots` | GET | Paginated cost snapshot records | ✅ Live |
| `/api/v1/monitoring/cron-jobs` | GET | Paginated cron job status records | ✅ Live |
| `/api/v1/monitoring/sessions` | GET | Paginated session event records | ✅ Live |
| `/api/v1/monitoring/health` | GET | Paginated system health metrics | ✅ Live |
| `/api/v1/monitoring/sub-agents` | GET | Paginated sub-agent run records | ✅ Live |
| `/api/v1/monitoring/health-summary` | GET | Gateway health overview | 🔜 Pending |
| `/api/v1/monitoring/cron-summary` | GET | Cron jobs overview | 🔜 Pending |
| `/api/v1/monitoring/sessions-summary` | GET | Active sessions overview | 🔜 Pending |
| `/api/v1/monitoring/sub-agents-summary` | GET | Sub-agent activity overview | 🔜 Pending |
| `/api/v1/monitoring/trends` | GET | Cost trend charts (7d/30d) | 🔜 Pending |
All endpoints support `?gateway_id=` filtering and are org-scoped via `require_org_member`.
### WebSocket
| Endpoint | Description |
|----------|-------------|
| `/ws/agents` | Real-time agent events (initial 50-event snapshot + 2s polling) |
### Platform Endpoints (97+)
The base platform provides full CRUD for: boards, tasks, agents, gateways, organizations, approvals, board groups, board memory, board webhooks, tags, skills marketplace, and more. See the OpenAPI docs at `/docs` when running.
## Quick Start
```bash
git clone ssh://forgejo/null/Mission-Control.git
cd Mission-Control
cp .env.example .env # edit LOCAL_AUTH_TOKEN and other vars
docker compose up -d
```
Backend runs on port 8080, frontend on 3037, PostgreSQL on 5432, Redis on 6379.
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `AUTH_MODE` | `local` | `local` for token auth, `clerk` for production |
| `LOCAL_AUTH_TOKEN` | — | Required when `AUTH_MODE=local` |
| `BACKEND_PORT` | `8000` | Backend API port |
| `FRONTEND_PORT` | `3037` | Frontend dev server port |
| `POSTGRES_DB` | `mission_control` | Database name |
| `POSTGRES_USER` | `postgres` | Database user |
| `POSTGRES_PASSWORD` | `postgres` | Database password |
| `POSTGRES_PORT` | `5432` | PostgreSQL port |
| `DB_AUTO_MIGRATE` | `true` | Run Alembic migrations on startup |
| `CORS_ORIGINS` | `http://localhost:3037` | Allowed CORS origins |
| `COLLECTION_INTERVAL_COST` | `300` | Seconds between cost collection |
| `COLLECTION_INTERVAL_CRON` | `60` | Seconds between cron collection |
| `COLLECTION_INTERVAL_SESSION` | `30` | Seconds between session collection |
| `COLLECTION_INTERVAL_HEALTH` | `60` | Seconds between health collection |
| `RQ_REDIS_URL` | `redis://redis:6379/0` | Redis URL for webhook worker |
## Project Structure
```
Mission-Control/
├── compose.yml # Docker Compose (db, redis, backend, frontend, webhook-worker)
├── .env # Environment config
├── PROJECT.md # 4-phase implementation plan
├── STRUCTURE.md # Agent roles and project structure
├── FUTURE.md # Prioritized backlog
├── VERSION.md # Version history
├── DEVELOPMENT_LOG.md # Agent work tracking
├── HISTORY.md # Changelog
├── sources/ # Reference repos (Go, Node) — not imported
│ ├── dashboard-tracking/ # mudrii/openclaw-dashboard (Go)
│ └── pixel-agents/ # jaffer1979/openclaw-pixel-agents-dashboard (Node)
└── src/
├── backend/
│ ├── app/
│ │ ├── api/ # API routes (monitoring, boards, agents, gateways, etc.)
│ │ ├── core/ # Config, auth, logging, rate limiting, security
│ │ ├── db/ # Session, pagination, query manager
│ │ ├── models/ # SQLModel database models (30+ tables)
│ │ ├── schemas/ # Pydantic request/response schemas
│ │ ├── services/
│ │ │ ├── monitoring/ # Collector, data processing, event parser, RPC models
│ │ │ │ ├── gateway_collector.py # Background RPC poller
│ │ │ │ ├── data_processing.py # ModelName, BuildDailyChart, BuildCostBreakdown, etc.
│ │ │ │ ├── event_parser.py # Session event parser
│ │ │ │ └── models.py # Pydantic RPC response models
│ │ │ └── openclaw/ # Gateway RPC, provisioning, lifecycle, coordination
│ │ └── main.py # FastAPI app + lifespan (collector start/stop)
│ ├── migrations/ # Alembic migrations
│ ├── scripts/ # Seed, export, sync scripts
│ └── tests/ # pytest test suite
└── frontend/
└── src/
├── app/ # Next.js App Router pages
├── components/ # React components (atoms/molecules/organisms/templates)
├── api/ # orval-generated TypeScript API client
├── auth/ # Clerk + local auth
├── hooks/ # Custom React hooks
├── lib/ # Utilities
└── proxy.ts # Dev proxy config
```
## Git Workflow
- **`main`** — stable/release branch
- **`dev`** — working branch (all development happens here)
```bash
git checkout dev
# ... make changes ...
git add -A && git commit -m "type: description"
git push origin dev
```
## License
MIT
Reference in New Issue View Git Blame Copy Permalink