CLIProxyAPI Dashboard

Proxy-only control plane for CLIProxyAPI

Next.js 16 / React 19 dashboard for provider credentials, proxy runtime settings, usage history, quotas, updates, logs, and safe container operations.

Quick Start · Docs · Features · Development

This repository is a workspace-structured monorepo with the active application in apps/dashboard/.

Current state:

• apps/dashboard/ is the runnable Next.js app and remains the primary surface for dashboard UI/API behavior
• root scripts proxy to the app workspace through npm workspaces (for example, npm run dev runs the dashboard workspace script)
• npm run build:collector is available at the repository root and delegates to the dashboard workspace collector build
• the embedded usage collector runtime lives under apps/dashboard/src/server/jobs/workers/usage-collector/ and is packaged into the dashboard image
• packages/* now holds shared contracts and foundations (api-contracts, auth-contracts, config, db, logger, shared, usage-contracts) used by the refactored structure

The bundled deployment is a four-service Docker stack:

Operational boundaries:

• apps/dashboard/: application code, Prisma schema, local source-dev workflow, and load-bearing Next instrumentation entrypoints (src/instrumentation.ts, src/instrumentation-node.ts)
• apps/dashboard/src/server/jobs/workers/usage-collector/: embedded worker runtime sources that are packaged into the dashboard image
• packages/: shared workspace modules for contracts, db foundations, config, and logging
• infrastructure/: production compose stack, runtime config, manage.sh, backup/restore ops, webhook helpers
• apps/dashboard/scripts/runtime/: dashboard runtime scripts (entrypoint.sh, collector bootstrap)
• apps/dashboard/tools/dev/: local source-dev orchestration scripts and dev compose assets
• docs/: canonical documentation set

Default bundled endpoints:

• Dashboard: http://127.0.0.1:3000
• Proxy API: http://127.0.0.1:8317

OAuth callback ports remain published because upstream login flows require them.

Common public ingress shape:

flowchart TD
    internet["Internet"]
    nginx["Nginx reverse proxy"]
    dashboard["Dashboard<br/>127.0.0.1:3000"]
    proxy["CLIProxyAPI<br/>127.0.0.1:8317"]
    postgres["PostgreSQL<br/>internal Docker network"]
    dockerproxy["docker-socket-proxy<br/>internal Docker network"]

    internet --> nginx
    nginx -->|"dashboard host"| dashboard
    nginx -->|"API host"| proxy
    dashboard -->|"Prisma"| postgres
    dashboard -->|"Docker API allowlist"| dockerproxy
    dashboard -->|"CLIPROXYAPI_MANAGEMENT_URL<br/>/v0/management/*"| proxy

The repo now ships infrastructure/nginx/cliproxyapi-dashboard.http.conf.template as the starter config for this split-host ingress pattern.

git clone https://github.com/quanpersie2001/cliproxyapi-dashboard.git
cd cliproxyapi-dashboard
./setup-local.sh
# Windows: .\setup-local.ps1

This creates a root .env, generates config.local.yaml, and starts the stack from docker-compose.local.yml. Then open http://localhost:3000, create the first admin user, connect providers, and issue client API keys.

Useful commands:

./setup-local.sh --down
./setup-local.sh --reset

cd apps/dashboard
./tools/dev/dev-local.sh
# Windows: .\tools\dev\dev-local.ps1

The source-dev workflow starts PostgreSQL and CLIProxyAPI in Docker, applies Prisma bootstrap and migrations, writes apps/dashboard/.env.local, and runs npm run dev:embedded so the Next.js dev server and embedded usage collector companion start together.

Source-dev endpoints:

• Dashboard: http://localhost:3000
• Proxy API: http://localhost:28317
• PostgreSQL: localhost:5433

curl -fsSL https://raw.githubusercontent.com/quanpersie2001/cliproxyapi-dashboard/main/install.sh | sudo bash

The same install.sh file works in both modes:

• from a repo checkout: sudo ./install.sh
• as a one-file bootstrap: curl .../install.sh | sudo bash

When run as a one-file bootstrap, it installs a minimal production bundle into /opt/cliproxyapi-dashboard by default, preserves existing runtime state files when re-run, and then continues the interactive installer.

The installed tree is intentionally small:

• install.sh
• infrastructure/
• generated runtime files such as infrastructure/.env, infrastructure/docker-compose.override.yml, and backups/

The installer accepts either full URLs like https://dash.example.com or bare hostnames like dash.example.com, and normalizes them automatically.

To install into a different path:

curl -fsSL https://raw.githubusercontent.com/quanpersie2001/cliproxyapi-dashboard/main/install.sh | sudo env INSTALL_DIR=/srv/cliproxyapi-dashboard bash

The bundled installer currently:

• installs Docker Engine and Compose if missing
• generates stack secrets
• writes infrastructure/.env
• optionally installs Nginx and renders a split-host HTTP reverse proxy config from the public dashboard/API URLs you entered
• optionally configures firewall rules, backup cron, and the dashboard deploy webhook

After install:

cd infrastructure
./manage.sh up
./manage.sh ps
./manage.sh logs dashboard

The canonical documentation hub lives at docs/README.md.

Run from the repository root (delegates to apps/dashboard/):

npm run dev
npm run typecheck
npm run lint
npm test
npm run build
npm run build:collector

Equivalent direct run inside apps/dashboard/ is still supported.

Implementation notes:

• Prisma client generation is wired into predev, prebuild, and pretest
• The production image uses apps/dashboard/scripts/runtime/entrypoint.sh to bootstrap core tables at startup with a PostgreSQL advisory lock
• The bundled deployment runs an embedded resident usage collector worker; POST /api/usage/collect is an authenticated fast trigger/wake seam
• GET /api/usage remains a compatibility route, but new code should use GET /api/usage/history

The release flow is split into three stages:

• ci.yml runs on pull requests and main pushes to gate changes with lint, typecheck, tests, app build, and a Docker build smoke test
• release.yml is a manual workflow_dispatch that only creates or updates the Release Please PR
• publish.yml publishes images from dashboard-v* tags or an explicit workflow dispatch, builds amd64 on ubuntu-latest and arm64 on ubuntu-24.04-arm, merges a multi-arch manifest in GHCR, and updates version.json
• manual publish.yml runs can rebuild an existing tag for recovery, but they do not move latest or rewrite version.json
• release.yml dispatches publish.yml automatically after a release is created when RELEASE_PLEASE_TOKEN is absent; if the secret is configured, the normal tag-push trigger handles publish instead

MIT