candela

candela is a lightweight binary that runs on a developer’s machine. It provides:

• Unified model discovery — one endpoint for local and cloud models
• Smart routing — automatically sends requests to the right backend
• Runtime management — start/stop Ollama, pull models, manage state
• Local observability — capture every LLM call to SQLite with zero cloud dependencies

Operating Modes

🏠 Solo Mode

For: Individual developers who want to run local models with full observability and zero cloud dependencies.

# ~/.config/candela/config.yaml — Solo Mode
port: 8181
lm_studio_port: 1234
runtime_backend: ollama

What you get:

• Local models via Ollama/vLLM/LM Studio on :1234
• Embedded observability — every call traced to ~/.candela/traces.db
• Management UI at http://localhost:8181/_local/
• Model pulling, health monitoring, backend discovery
• No cloud account, no authentication, no remote server needed

---

☁️ Solo + Cloud Mode

For: Individual developers who want local and cloud models (Gemini, Claude, Bedrock) without deploying a Candela server. Uses native multi-cloud auth — candela auth login handles GCP (OAuth2) and AWS (SSO/Access Keys) without requiring gcloud or aws CLI.

# ~/.config/candela/config.yaml — Solo + Cloud
runtime_backend: ollama

providers:
  - name: google
    models: [gemini-3.5-flash, gemini-2.5-pro, gemini-2.0-flash]
  - name: anthropic
    models: [claude-sonnet-4-20250514, claude-3-haiku]

vertex_ai:
  project: my-gcp-project
  region: us-central1

Prerequisites:

# GCP — native OAuth2 (no gcloud CLI needed)
candela auth login --provider gcp

# AWS — SSO or access keys (no aws CLI needed)
candela auth login --provider aws

What you get: Everything from Solo Mode, plus cloud models merged into /v1/models, smart routing (local stays local, cloud routes to Vertex AI), and all calls traced to SQLite.

Architecture:

JetBrains / Cline / curl
        │
        ▼
  LM Compat (:1234)
  /v1/models → local + cloud models
  /v1/chat/completions
        │
        ├── local model ──▶ Ollama / vLLM
        │                        │
        │                   spanCapture
        │                        │
        └── cloud model ──▶ pkg/proxy ──▶ Vertex AI (Google ADC)
                                │
                                ▼
                          SpanProcessor → SQLite (traces.db)

---

🌐 Team Mode

For: Teams that need budgeting, governance, and RBAC via a shared Candela cloud backend.

# ~/.config/candela/config.yaml — Team Mode
port: 8181
lm_studio_port: 1234
runtime_backend: ollama

remote: https://candela-xxx.a.run.app
audience: "12345678.apps.googleusercontent.com"
iap_service_account: candela-server@project.iam.gserviceaccount.com

What you get: Everything from Solo Mode, plus cloud models routed through the Candela server with team-wide cost tracking and optional budget enforcement. When iap_service_account is configured, candela uses dual-token authentication: Proxy-Authorization carries an impersonated SA OIDC token for IAP, while X-Candela-Auth carries the developer’s own OAuth2 access token so the server can identify the real user. See Authentication — IAP Dual-Token for details.

---

Installation

Homebrew

brew install candelahq/tap/candela

go install

go install github.com/candelahq/candela/cmd/candela@latest

From Source

git clone https://github.com/candelahq/candela.git
cd candela
nix develop
go run ./cmd/candela

CLI Command Reference

The candela CLI includes developer tools for lifecycle management, live observability, diagnostics, and budget analysis:

Daemon Management

Command	Description
candela start	Launch the proxy as a background daemon and write PID file
candela stop	Gracefully terminate the running background proxy
candela restart	Restart the background proxy with updated configuration
candela status	Inspect proxy status, PID, uptime, active model count, and upstream endpoints
candela run [flags]	Run proxy in the foreground with stdout logging

# Common flags for 'candela run':
candela run --config ~/.config/candela/config.yaml --port 8181

🩺 Diagnostic Health (candela doctor)

Runs an automated suite of system diagnostics to verify runtime compatibility, networking, and authentication.

# Standard diagnostic check
candela doctor

# Output full report in machine-readable JSON (useful for CI/CD or scripts)
candela doctor --json

# Automatically kill orphan/conflicting processes holding proxy ports
candela doctor --fix

Diagnostic Checks Performed:

• Version Check: Compares local CLI build with latest GitHub release.
• Configuration Validation: Verifies YAML syntax, required fields, and file permissions.
• Authentication: Checks validity of Google ADC and AWS credentials.
• Proxy Connectivity: Confirms local HTTP listeners are healthy and responding.
• Remote Server / IAP: Validates OIDC token generation and remote server reachability.
• User & Budget: Checks active user spend against daily/monthly caps.
• Local Runtime: Detects active Ollama, vLLM, or LM Studio instances and verifies installed models.
• State DB: Validates SQLite schema and database file integrity.
• Port Conflicts: Scans port 8181 and 1234 for conflicting processes.

📡 Live Trace Streaming (candela watch)

Stream live LLM spans and prompt traces in your terminal in real-time via Server-Sent Events (SSE).

# Stream all traces in human-readable table format
candela watch

# Filter by model or provider
candela watch --model "claude-sonnet-4-20250514"
candela watch --provider "google"

# Filter by project ID
candela watch --project "my-team-project"

# Stream structured JSON lines (NDJSON) for piping to jq or log collectors
candela watch --json | jq '{model: .model, cost: .cost_usd, latency_ms: .duration_ms}'

📈 Budget Runway Forecasting (candela forecast)

Analyze your spending velocity and forecast end-of-month spend and budget runway.

# Check current user's budget forecast
candela forecast

# Query forecast for a specific team member
candela forecast --user "developer@company.com"

# Output forecast metrics as JSON
candela forecast --json

Metrics Provided:

• Current Spend & Limit: Today’s spend, month-to-date spend, and configured budget.
• Daily Velocity: 7-day weighted moving average daily cost.
• Projected Month-End Spend: Forecasted total monthly cost at current run rate.
• Runway Remaining: Estimated days until daily or monthly budget exhaustion.

🔐 Native Multi-Cloud Authentication (candela auth)

Manage native Google Cloud and AWS credentials without installing gcloud or aws CLI tools:

# Authenticate via browser OAuth2
candela auth login --provider gcp
candela auth login --provider aws

# Inspect cached token status and expiration
candela auth status

# Print a fresh authorization token for script integration
candela auth token --provider gcp

---

Full Config Reference

# ── Required ──
runtime_backend: ollama             # ollama | vllm | lmstudio

# ── Optional: Network ──
port: 8181                          # main proxy port (default: 8181)
lm_studio_port: 1234                # LM compat listener (default: 1234)

# ── Optional: Direct Cloud (Solo + Cloud) ──
providers:                          # omit for local-only solo mode
  - name: google
    models: [gemini-3.5-flash, gemini-2.5-pro]
  - name: anthropic
    models: [claude-sonnet-4-20250514]

vertex_ai:
  project: my-gcp-project           # required when providers is set
  region: us-central1               # default: us-central1

# ── Optional: Team Mode (omit for Solo) ──
remote: https://candela-xxx.run.app # Candela server URL
audience: "12345678.apps..."        # IAP audience for OIDC auth
iap_service_account: sa@proj.iam.gserviceaccount.com  # SA to impersonate for IAP ID tokens

# ── Optional: Advanced ──
local_upstream: http://localhost:11434  # explicit local runtime URL
state_db_path: ~/.candela/state.db     # runtime state persistence

Smart Routing

Request model	Mode	Where it runs
llama3.2:3b	Any	Local (Ollama) — always preferred
gemini-3.5-flash	Solo + Cloud	Vertex AI (direct, via ADC)
gemini-2.5-pro	Solo + Cloud	Vertex AI (direct, via ADC)
claude-sonnet-4-20250514	Solo + Cloud	Vertex AI Anthropic
gpt-4o	Team	Cloud (via Candela server)

Note

Local models always take priority. If a model exists both locally and in cloud config, the local runtime handles it.

Management UI

Access at http://localhost:8181/_local/:

Card	Description
Health	Runtime status, start/stop controls, uptime
Models	Loaded models with size, family, quantization
Pull Model	Download new models with progress tracking
Traces	Recent LLM calls with tokens, cost, duration
Backends	Auto-detected runtimes with install hints
Settings	State DB path, reset

IDE Integration

JetBrains

1. Settings → AI Assistant → Enable “LM Studio”
2. URL is pre-configured to http://localhost:1234 — just works!
3. Select any model from the dropdown (local + cloud)

VS Code (Continue, Cline)

{
  "models": [{
    "title": "Candela Local",
    "provider": "openai",
    "apiBase": "http://localhost:1234/v1",
    "model": "llama3.2:3b"
  }]
}

curl

curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Troubleshooting

Symptom	Cause	Fix
“model not found locally and no remote server configured”	Solo Mode + unknown model	Add providers for cloud models
“vertex_ai.project is required”	providers set but no project	Add vertex_ai.project to config
“failed to get Google ADC”	ADC not configured	Run candela auth login --provider gcp
“no AWS credentials found”	AWS auth not configured	Run candela auth login --provider aws
“audience is required when remote is set”	Missing audience	Add IAP audience to config
Traces card shows “Traces not available”	Team Mode	Expected — check cloud dashboard
No models in /v1/models	Runtime not started	Start Ollama: ollama serve