CLIProxy Dashboard

Real-time dashboard for monitoring CLIProxy usage, token consumption, estimated cost, and credential health.

What this project includes

• Collector (Python/Flask): polls CLIProxy Management API, computes deltas/costs, writes to PostgreSQL
• Frontend (React + Nginx): charts and analytics UI
• PostgreSQL: self-hosted DB initialized from init-db/schema.sql
• PostgREST: read-only API layer for frontend
• Skill tracker plugin distribution via marketplace + submodule (plugin/claude-skills-tracker)

Architecture

CLIProxy API → Collector (Python) → PostgreSQL
Browser → Nginx:8417
          ├── /rest/v1/*       → PostgREST:3000 → PostgreSQL (read)
          └── /api/collector/* → collector:5001 (write/trigger)

---

Quick Start (run from this repository)

1) Prerequisites

• Docker + Docker Compose v2
• CLIProxy with remote management enabled

2) Configure CLIProxy Management API

Ensure your CLIProxy config includes:

remote-management:
  allow-remote: true
  secret: "<your-management-secret>"

Quick verification:

curl -H "Authorization: Bearer <your-management-secret>" \
  http://localhost:8317/v0/management/usage

You should receive a JSON usage response.

3) Clone and initialize submodule

git clone https://github.com/leolionart/CLIProxyAPI-Dashboard.git
cd CLIProxyAPI-Dashboard
git submodule update --init --recursive

4) Configure environment

cp .env.example .env

Edit .env:

DB_PASSWORD=your_secure_password_here
CLIPROXY_URL=http://host.docker.internal:8317
CLIPROXY_MANAGEMENT_KEY=<your-management-secret>
ADMIN_PASSWORD=change-me

# Optional
COLLECTOR_INTERVAL_SECONDS=300
TIMEZONE_OFFSET_HOURS=7
ADMIN_SESSION_TTL_DAYS=30
ADMIN_SESSION_SECURE_COOKIE=false
ADMIN_SESSION_SAMESITE=Lax

Notes:

• Dashboard now requires admin login before loading UI or /rest/v1/* data.
• The browser stores only an HttpOnly session cookie; the password is never stored in browser storage.
• If you deploy behind HTTPS, set ADMIN_SESSION_SECURE_COOKIE=true.
• Default host port for PostgREST is now 8418 to avoid common conflicts on 3000. Override with POSTGREST_HOST_PORT if needed.
• ADMIN_ALLOWED_ORIGINS is optional. Leave it empty for the default same-compose setup; set it only if you want stricter Origin/Referer enforcement.

5) Start services

docker compose up -d

Open dashboard at: http://localhost:8417

Expected startup order:

1. postgres healthy
2. collector healthy (DB init + migrations)
3. postgrest starts
4. frontend starts

First data usually appears after the first collector interval.

---

Verification

docker compose ps
docker compose logs -f collector
curl -X POST http://localhost:8417/api/collector/trigger

Success signals:

• collector logs periodic snapshot collection
• collector health endpoint responds
• manual trigger returns success

---

Alternative: deploy from raw compose files only

If you don't want to clone the full repo:

mkdir cliproxy-dashboard && cd cliproxy-dashboard
curl -O https://raw.githubusercontent.com/leolionart/CLIProxyAPI-Dashboard/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/leolionart/CLIProxyAPI-Dashboard/main/.env.example
cp .env.example .env
# then edit .env and run:
docker compose up -d

---

Skill Tracker Plugin Setup

Tracker plugin is now distributed from the shared Claude skills marketplace.

• Marketplace repo: leolionart/claude-skills
• Plugin install ID: claude-skill-tracker

Inside Claude Code:

/plugin marketplace add leolionart/claude-skills
/plugin install claude-skill-tracker
/reload-plugins

Optional endpoint override (if dashboard is not local):

export CLIPROXY_COLLECTOR_URL="https://your-domain/api/collector/skill-events"

Dedupe note: do not run both marketplace plugin hook and a manual PostToolUse: Skill hook at the same time.

---

Optional: Lark Suite MCP + local skill

This repo now includes templates to enable Lark task data access from Claude Code.

1) Prepare local MCP config (do not commit secrets)

cp .mcp.json.example .mcp.json

.mcp.json is ignored by git in this repo, so keep real credentials there.

2) Set local environment variables

Use your shell profile (or export in current terminal):

export LARK_APP_ID="cli_xxx"
export LARK_APP_SECRET="your-lark-app-secret"
export LARK_DOMAIN="https://open.larksuite.com"
export LARK_TOOLSETS="preset.base,preset.task,task.v2.task.get,task.v2.task.list,task.v2.tasklist.list,task.v2.tasklist.tasks"

3) Reload Claude Code session

After saving .mcp.json and env vars, restart Claude Code (or reload) so lark-mcp can start.

4) Use repo-local skill

Skill file: .claude/skills/lark-suite/SKILL.md

Ask naturally, for example:

• "Lấy danh sách task đang open trong Lark"
• "Lấy chi tiết task theo ID ..."
• "Tóm tắt task theo trạng thái"

---

Common operations

Update services

docker compose pull
docker compose up -d

Health and smoke checks

docker compose ps
docker compose logs --tail=200 collector postgrest frontend
curl http://localhost:8417/api/collector/health
curl "http://localhost:8417/rest/v1/daily_stats?select=date,total_requests&order=date.desc&limit=1"
curl -X POST http://localhost:8417/api/collector/trigger

---

Development

Frontend (hot reload)

docker-compose.override.yml is the local dev override and is loaded automatically by docker compose. For source-only changes, prefer bind mounts + service restart. Rebuild images only when Dockerfile or dependencies changed.

docker compose up -d postgres postgrest
cd frontend
npm install
POSTGREST_HOST_PORT=8418 npm run dev

Open Vite dev UI at http://localhost:5173.

Keep the local collector running too. Vite dev proxy now checks the same auth session flow as production, so /rest/v1/* stays locked until you log in.

Collector (local)

cd collector
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
python main.py

---

Troubleshooting

Collector cannot reach CLIProxy

• Check remote-management.allow-remote: true in CLIProxy config
• Ensure CLIPROXY_MANAGEMENT_KEY matches CLIProxy secret
• Ensure CLIPROXY_URL is reachable from the collector container

Dashboard has no data

• Wait until first collection interval
• Check collector logs: docker compose logs -f collector
• Trigger manually after logging in: curl -X POST http://localhost:8417/api/collector/trigger

Login does not work

• Ensure .env contains ADMIN_PASSWORD and that it matches what you enter on the login screen
• For HTTPS deployments, set ADMIN_SESSION_SECURE_COOKIE=true; for local HTTP keep it false
• If you use a custom origin or reverse proxy, set ADMIN_ALLOWED_ORIGINS to the public dashboard origin

PostgREST errors about missing schema

• Confirm postgres is healthy before postgrest starts: docker compose ps
• If using an old pre-initialized volume, apply schema manually from init-db/schema.sql

Port 3000 already allocated

• PostgREST now defaults to host port 8418 instead of 3000
• If you want a different host port, set POSTGREST_HOST_PORT in .env
• If Vite dev is already running, restart it after changing POSTGREST_HOST_PORT

---

Key paths

• collector/main.py – collector + Flask endpoints
• collector/db.py – PostgreSQL client + migrations runner
• collector/migrations/ – DB migrations (required for schema changes)
• frontend/src/ – dashboard UI
• plugin/claude-skills-tracker/ – tracker plugin submodule (source mirror for dashboard development)
• Tracker marketplace source of truth: leolionart/claude-skills

---

License

MIT — see LICENSE.