Observatory Dashboard Guide

lean-ctx provides two dashboards that are often confused. The Local Observatory is a built-in HTTP server running on your machine, while the Cloud Dashboard at api.leanctx.com syncs data across devices. This guide covers both in detail.

Local Observatory

The Observatory is a built-in HTTP server that ships with every lean-ctx installation. It runs locally at 127.0.0.1:3333 by default and provides a real-time web UI plus a full REST API for inspecting token savings, agent activity, knowledge graphs, file heatmaps, and more.

Starting the Dashboard

# Start with defaults (127.0.0.1:3333)
lean-ctx dashboard

# Start for a specific project
lean-ctx dashboard --project=myproject

# Custom port
LEAN_CTX_PORT=4444 lean-ctx dashboard

# Bind to all interfaces (requires bearer token)
LEAN_CTX_HOST=0.0.0.0 lean-ctx dashboard

Once running, open http://127.0.0.1:3333 in your browser to access the web UI.

Dashboard Tabs

Configuration

Security

When bound to 127.0.0.1 (default), the Observatory accepts unauthenticated requests - it's only reachable from your own machine.

When you bind to a non-localhost address (e.g. LEAN_CTX_HOST=0.0.0.0), lean-ctx automatically generates a bearer token stored at ~/.lean-ctx/dashboard.token. All API requests must include this token:

# Read the token
TOKEN=$(cat ~/.lean-ctx/dashboard.token)

# Use it in API requests
curl -H "Authorization: Bearer $TOKEN" http://your-host:3333/api/stats

REST API - Stats & Analytics

All endpoints return JSON and are available at http://HOST:PORT/api/...

# Token statistics
curl http://127.0.0.1:3333/api/stats
# {"tokens_saved": 142857, "savings_pct": 87.3, "sessions": 12, ...}

# Gain report
curl http://127.0.0.1:3333/api/gain
# {"tasks": [...], "heatmap": {...}, "total_gain": 0.87}

REST API - Agents & Knowledge

# Active agents
curl http://127.0.0.1:3333/api/agents
# {"agents": [{"id": "a1b2", "status": "active", "task": "refactoring"}]}

# Knowledge graph
curl http://127.0.0.1:3333/api/knowledge
# {"entries": [...], "connections": [...]}

# MCP live data
curl http://127.0.0.1:3333/api/mcp

REST API - Graphs & Heatmaps

# Dependency graph
curl http://127.0.0.1:3333/api/graph
# {"nodes": [...], "edges": [...]}

# File access heatmap
curl http://127.0.0.1:3333/api/heatmap
# {"files": [{"path": "src/main.rs", "reads": 47, "last": "2025-04-23T..."}]}

REST API - Search & Symbols

# Search symbols
curl "http://127.0.0.1:3333/api/symbols?q=parse&kind=fn"
# {"symbols": [{"name": "parse_config", "kind": "fn", "file": "src/config.rs"}]}

# Full-text search (BM25)
curl "http://127.0.0.1:3333/api/search?q=authentication&limit=10"
# {"results": [{"file": "src/auth.rs", "score": 4.2, "snippet": "..."}]}

REST API - Session & Pipeline

# Session state
curl http://127.0.0.1:3333/api/session
# {"session_id": "s_abc123", "calls": 47, "project": "lean-ctx"}

# Pipeline metrics
curl http://127.0.0.1:3333/api/pipeline-stats
# {"stages": [{"name": "read", "avg_ms": 12, "calls": 234}]}

# Context ledger
curl http://127.0.0.1:3333/api/context-ledger
# {"budget": 128000, "used": 42000, "entries": [...]}

REST API - System

# Version info
curl http://127.0.0.1:3333/api/version
# {"version": "3.5.1", "build": "2026-05-06", "platform": "aarch64-apple-darwin"}

# Health check
curl http://127.0.0.1:3333/api/pulse
# {"uptime_s": 3600, "memory_mb": 24, "connections": 1}

Cloud Dashboard

The Cloud Dashboard at api.leanctx.com provides a centralized view of your lean-ctx usage across all devices. It requires authentication via email verification and syncs a subset of data from your local sessions.

Features

• Authentication - Email-verified accounts with secure token-based auth
• Cross-device sync - View aggregated stats from all your machines
• Adaptive models - Cloud-trained compression models that improve over time
• CSV export - Download session data and token statistics as CSV
• Estimated costs - Dollar-amount cost estimates based on your LLM provider rates

Local vs Cloud - What Syncs?

Privacy note: Your source code never leaves your machine. The Cloud Dashboard only receives aggregated metrics (token counts, timing data, compression ratios) - not file contents, knowledge entries, or code snippets.