Configuration

← Back to README

Configuration is managed through infrastructure/.env.

Environment Variables

Infrastructure (set in infrastructure/.env)

Variable	Required	Description	Default / Example
DOMAIN	Yes	Base domain for your installation	example.com
DASHBOARD_SUBDOMAIN	Yes	Dashboard subdomain	dashboard
API_SUBDOMAIN	Yes	API subdomain	api
DASHBOARD_URL	Yes	Full dashboard URL (used for OAuth callbacks, Telegram links)	https://dashboard.example.com
API_URL	Yes	Full API URL (used for proxy model config)	https://api.example.com
DATABASE_URL	Yes	PostgreSQL connection string	postgresql://user:pass@host:5432/db
POSTGRES_PASSWORD	Yes	PostgreSQL password	Generated by installer
JWT_SECRET	Yes	JWT signing secret (min 32 chars)	Generated by installer
MANAGEMENT_API_KEY	Yes	CLIProxyAPI management API key (min 16 chars)	Generated by installer
INSTALL_DIR	Yes	Absolute path to project root	Set by installer
TZ	No	Server timezone	UTC

Dashboard (set in infrastructure/.env or container environment)

Variable	Required	Description	Default
CLIPROXYAPI_MANAGEMENT_URL	No	Internal management API URL	http://cliproxyapi:8317/v0/management
NODE_ENV	No	Runtime environment	development
JWT_EXPIRES_IN	No	JWT token expiration time	7d
LOG_LEVEL	No	Pino log level (fatal, error, warn, info, debug, trace)	info
LOG_DIR	No	Directory for log file storage	<cwd>/logs
CLIPROXYAPI_CONTAINER_NAME	No	Docker container name used only for the cosmetic uptime indicator (via docker inspect). Liveness is determined by probing CLIPROXYAPI_MANAGEMENT_URL, so this can be left at its default under Docker Swarm or Kubernetes — uptime simply reads as unknown when the name does not resolve.	cliproxyapi
DOCKER_HOST	No	Docker socket proxy URL (for container management)	tcp://docker-proxy:2375
GITHUB_REPO	No	GitHub repo for update checks	itsmylife44/cliproxyapi-dashboard
SYNC_TOKEN_MAX_AGE_DAYS	No	Config sync token expiration in days	90
COLLECTOR_API_KEY	No	API key for automated usage collection cron service (64-char hex)	Generated by installer
BACKUP_SCHEDULER_KEY	No	API key for the backup scheduler cron service (64-char hex)	Generated by installer
ALLOW_LOCAL_PROVIDER_URLS	No	Permit custom providers to target localhost / RFC1918 (Ollama, LM Studio, llama.cpp). Cloud metadata (169.254.169.254, 100.100.100.200) stays blocked.	false

Dashboard-Only Mode

When installed with ./install.sh --dashboard-only, the dashboard uses infrastructure/docker-compose.dashboard-only.yml and connects to an existing CLIProxyAPI instead of starting the bundled proxy container. The existing CLIProxyAPI can run in Docker, directly on a host, or on another server.

Set these values to match your existing proxy:

Variable	Description
CLIPROXYAPI_MANAGEMENT_URL	Existing CLIProxyAPI management endpoint, ending in /v0/management; it must be reachable from inside the dashboard container
MANAGEMENT_API_KEY	Existing CLIProxyAPI management key/password
API_URL	Public URL clients should use for the existing CLIProxyAPI API

The dashboard-only compose file exposes the dashboard on 127.0.0.1:3000 and adds host.docker.internal for same-host CLIProxyAPI installs. If you only have the public OpenAI-compatible API URL and no management endpoint/key, dashboard management features cannot operate.

Perplexity Sidecar

Variable	Required	Description	Default
PERPLEXITY_SIDECAR_SECRET	No	Shared secret for sidecar authentication (min 16 chars)	—
PERPLEXITY_COOKIES	No	Perplexity Pro session cookies	—

Webhook / Deploy (optional, for CI/CD)

Variable	Required	Description	Default
WEBHOOK_HOST	No	Webhook server URL for deploy triggers	http://localhost:9000
DEPLOY_SECRET	No	Secret for deploy webhook authentication	—

CLIProxyAPI Configuration

CLIProxyAPI configuration lives in infrastructure/config/config.yaml. The dashboard provides a structured UI for editing it, but you can also edit the file directly:

api-keys:
  - "sk-your-api-key-here"

providers:
  - name: "claude"
    type: "claude"
    # Provider-specific configuration...
  
  - name: "gemini"
    type: "gemini"
    api-key: "YOUR_GEMINI_API_KEY"
    # Provider-specific configuration...

Dashboard Settings

Dashboard-specific settings are managed through the Settings page in the UI:

• User management (admin password)
• Config Sync token management
• Theme preferences

Config Sync

The dashboard can automatically sync your OpenCode configurations to your local machine using the companion plugin.

How It Works

1. Generate a Sync Token: Navigate to Settings -> Config Sync in the dashboard
2. Install the Plugin: Add opencode-cliproxyapi-sync to your OpenCode plugins
3. Configure: Create ~/.config/opencode-cliproxyapi-sync/config.json with your dashboard URL and sync token
4. Auto-Sync: On every OpenCode startup, the plugin checks for config changes and updates your local opencode.json and oh-my-openagent.json

Plugin Installation

npx opencode install opencode-cliproxyapi-sync

Or add manually to your opencode.json:

{
  "plugin": [
    "opencode-cliproxyapi-sync",
    "oh-my-openagent@latest"
  ]
}

The plugin supports OCX profiles — each profile can have its own sync config.

For full plugin documentation, see opencode-cliproxyapi-sync.

Usage Collection

The dashboard automatically collects usage statistics from CLIProxyAPI every 5 minutes using a dedicated cron service.

How It Works

1. Usage Collector Service: Runs as a Docker container with cron job
2. Collection Endpoint: POST /api/usage/collect fetches data from CLIProxyAPI
3. Data Storage: Usage records stored in PostgreSQL with deduplication
4. Dashboard Display: View statistics on the Usage page

Required Configuration

• COLLECTOR_API_KEY: Authentication key for the cron service (automatically generated during installation)

Troubleshooting

If usage data isn't appearing in your dashboard:

1. Check collector service: docker compose ps usage-collector
2. Verify API key: grep COLLECTOR_API_KEY infrastructure/.env
3. View logs: docker compose logs usage-collector
4. Manual trigger: Click "Refresh" on Usage page (admin only)

For detailed troubleshooting and advanced configuration, see infrastructure/docs/USAGE_COLLECTION.md.

Scheduled Backups

The dashboard can create scheduled database backups via a dedicated cron service that mirrors the usage collector. Configure the schedule under Settings → Backup.

How It Works

1. Backup Scheduler Service: backup-scheduler container ticks every 5 minutes
2. Scheduled Endpoint: POST /api/admin/backup/scheduled is idempotent — it only creates a backup when the configured cron time has elapsed
3. Retention: Old SCHEDULED backups are removed according to the retention setting (days)
4. Time Zone: The cron expression is evaluated using the container's TZ (falls back to UTC on invalid TZ)

Required Configuration

• BACKUP_SCHEDULER_KEY: Bearer token for the scheduler service (auto-generated during installation)
• At least one admin user must exist; backups are attributed to the oldest admin

Upgrading Existing Deployments

Installs that predate the scheduler need the new key and service added manually:

# Add the key if missing
grep -q '^BACKUP_SCHEDULER_KEY=' infrastructure/.env || \
  echo "BACKUP_SCHEDULER_KEY=$(openssl rand -hex 32)" >> infrastructure/.env

# Start the new container
cd infrastructure && docker compose up -d backup-scheduler

Troubleshooting

1. Scheduler running? docker compose ps backup-scheduler
2. Key present? grep BACKUP_SCHEDULER_KEY infrastructure/.env
3. Logs: docker compose logs backup-scheduler and dashboard logs for BACKUP_SCHEDULED_TICK
4. Schedule enabled? Settings → Backup — verify "Enabled" and the next run timestamp

Config Sharing

Share your configuration with others:

• Publish: Generate a unique share code (format: XXXX-XXXX) for your config
• Subscribe: Enter a share code to sync with a publisher's model selection
• Automatic Sync: Subscribers see publisher's models on page reload
• Subscriber Isolation: Subscribers keep their own MCP servers and plugins
• Mutual Exclusivity: Users can be either publisher OR subscriber, not both