Dashboard Setup

The dashboard provides real-time visibility into plan execution, war-room status, memory, and agent activity. It consists of a FastAPI backend and a Next.js frontend.

Architecture

Browser ──► Next.js (:3000) ──► FastAPI Backend (:9000)
                                      │
                                      ├── War-room file polling
                                      ├── Memory ledger queries
                                      ├── SSE event streams
                                      └── Plan management API

Quick start

1. Install backend dependencies.

   uv sync --project dashboard --extra dev --frozen

2. Install frontend dependencies.

   cd dashboard/fe
   bun install --frozen-lockfile

3. Configure environment. Create or edit ~/.ostwin/.env:

   ANTHROPIC_API_KEY="sk-ant-..."
   OSTWIN_API_KEY="your-dashboard-api-key"

4. Start the backend. uv run --project dashboard python -m dashboard.api — serves on http://localhost:3366.

5. Start the frontend. cd dashboard/fe && bun run dev — serves on http://localhost:3000.

Custom ports

Backend

DASHBOARD_PORT=8080 uv run --project dashboard python -m dashboard.api

Frontend

DASHBOARD_URL=http://localhost:8080 npm run dev

Update DASHBOARD_URL whenever you change the backend port.

API routes

Route group	Prefix	Purpose
Plans	/api/plans	Create, list, run, inspect plans
Rooms	/api/rooms	War-room status, progress, artifacts
Channels	/api/channels	Read/post channel messages
Memory	/api/memory	Query and search memory ledger
Skills	/api/skills	List, search, toggle skills
Roles	/api/roles	List and inspect role definitions
MCP	/api/mcp	MCP server config and status
Settings	/api/settings	Dashboard and engine configuration
System	/api/system	Health checks, version info

SSE real-time updates

The dashboard uses Server-Sent Events for live updates:

Event	Description
room:status	War-room state changed
room:progress	Progress updated
channel:message	New channel message
plan:complete	Plan finished execution

Tip

SSE connections auto-reconnect on failure. If the backend restarts, the frontend picks up the stream again within seconds.

Dashboard features

Plan view

• DAG visualization with dependency edges
• Wave grouping showing parallel execution
• Per-epic status badges and progress bars

Room inspector

• Live channel message feed with role colors
• Progress bar with percentage and status
• Artifact file browser with content preview

Memory search

• Full-text search across all entries
• Filter by kind, room, tags, or role
• Superseded entry tracking

Authentication

# Set in ~/.ostwin/.env
OSTWIN_API_KEY="your-secret-key"

Privileged API and MCP requests require this key in the X-API-Key header, the case-insensitive Bearer authorization scheme, or the dashboard’s same-origin HttpOnly cookie. WebSocket admission is authenticated by default.

Caution

If OSTWIN_API_KEY is missing, privileged routes fail closed. The only setup exception is an explicit development-mode request proven to come directly from loopback. Never set OSTWIN_DEV_MODE on an exposed deployment.

Production security baseline

Use a TLS-terminating reverse proxy or managed ingress and configure the dashboard’s trust boundary explicitly:

OSTWIN_API_KEY="at-least-32-random-characters"
OSTWIN_BASE_URL="https://dashboard.example.gov"
OSTWIN_ALLOWED_HOSTS="dashboard.example.gov"
OSTWIN_WS_STRICT="true"
OSTWIN_SECURE_COOKIES="true"
OSTWIN_TRUSTED_TLS_PROXY="true"
RATE_LIMIT_ENABLED="true"

RATE_LIMIT_ENABLED is off by default so that local and shared-egress deployments are not throttled by a per-peer bucket; production deployments must set it explicitly as shown above. Authentication brute-force budgets (login, re-auth, password reset, admin reset) are enforced separately and are never affected by this flag.

OSTWIN_TRUSTED_TLS_PROXY=true is an operator assertion that TLS terminates at a trusted ingress; it does not make arbitrary forwarding headers trustworthy. The application deliberately uses the directly connected peer for rate limiting. Put a distributed limiter at the ingress for multi-replica or internet-facing deployments.

Host names and browser-extension origins are exact-match allowlists. Add every external dashboard hostname to OSTWIN_ALLOWED_HOSTS; wildcards are rejected. Interactive OpenAPI/Swagger routes are disabled by default and can only be enabled in explicit development mode.

Production deployment

1. Build the frontend. cd dashboard/fe && bun run build

2. Serve static files. The backend auto-detects dashboard/fe/out/ and serves it.

3. Set environment variables. Apply the production security baseline above and set DASHBOARD_PORT=3366 if the default is unsuitable.

4. Run behind a reverse proxy (nginx/Caddy) for TLS and domain routing.

Troubleshooting

Symptom	Cause	Fix
Backend 404s	Wrong working directory	Run from project root
Frontend can’t reach API	Port mismatch	Check DASHBOARD_URL
SSE not updating	Proxy buffering	Disable response buffering
Empty room list	No war-rooms	Run a plan first
Import errors	Missing deps	uv sync --project dashboard --frozen

Environment loading

The backend loads env vars from (first match wins):

1. ~/.ostwin/.env — global install config
2. ./.env — current working directory
3. OS environment — already set in shell

Set ANTHROPIC_API_KEY once in ~/.ostwin/.env and it works for both the engine and dashboard.