.env.example

# Claude Code home directory (default: ~/.claude)
# Override this if your Claude Code data is in a different location, e.g.:
#   CLAUDE_HOME=~/.codefuse/engine/cc
# CLAUDE_HOME=~/.claude

# ── Server / network ────────────────────────────────────────────────────────
# Port to listen on (default: 4820)
# DASHBOARD_PORT=4820

# Interface to bind. SECURITY: defaults to 127.0.0.1 (loopback) so the dashboard
# is NOT reachable from the network out of the box (GHSA-gr74-4xfh-6jw9). The
# server reads transcripts, exports all data, and can spawn `claude`, so binding
# it to the network without auth exposes all of that. Only widen the bind if you
# understand the risk — and set DASHBOARD_TOKEN when you do.
#   DASHBOARD_HOST=0.0.0.0          # bind all interfaces (LAN-reachable)

# Optional auth token. When set, every /api/* request and the WebSocket must
# present it (Authorization: Bearer <token>, x-dashboard-token header, or
# ?token=). Strongly recommended whenever DASHBOARD_HOST is non-loopback. Unset
# by default — the loopback bind is the trust boundary.
#   DASHBOARD_TOKEN=change-me-to-a-long-random-string

# File-backed alternative for Docker/Kubernetes secrets. The direct value above
# wins when both are set.
#   DASHBOARD_TOKEN_FILE=/run/ccam-secrets/dashboard-token

# Optional independent token for /api/hooks/* ingestion. Keep this separate from
# DASHBOARD_TOKEN when hooks arrive through a remote HTTPS endpoint. Localhost
# hooks remain zero-config when neither value is set.
#   DASHBOARD_HOOK_TOKEN=change-me-to-another-long-random-string
#   DASHBOARD_HOOK_TOKEN_FILE=/run/ccam-secrets/hook-token

# Extra Host-header names allowed besides loopback (comma-separated). Needed when
# you bind to a LAN and reach the dashboard by hostname/IP — entries here pass
# the anti-DNS-rebinding Host allowlist. Also required when Prometheus-in-Docker
# scrapes a host-native dashboard:
#   DASHBOARD_ALLOWED_HOSTS=host.docker.internal
#   DASHBOARD_ALLOWED_HOSTS=dashboard.internal,192.168.1.50

# Writable dotenv path used when Settings persists Claude/Codex home overrides.
# Containers default to /app/config/.env; native runs default to repo-root .env.
#   DASHBOARD_ENV_PATH=/app/config/.env

# ── Remote hook client ──────────────────────────────────────────────────────
# Hook handlers post to localhost by default. Set a URL only when forwarding
# live hooks to a remote/cloud dashboard. Non-loopback URLs must use HTTPS and
# must also supply the dedicated hook token.
#   CCAM_DASHBOARD_URL=https://agent-monitor.example.com
#   CCAM_HOOK_TOKEN=change-me-to-the-dashboard-hook-token
#   CCAM_HOOK_TOKEN_FILE=/path/to/hook-token

# ── MCP HTTP transport ──────────────────────────────────────────────────────
# Dashboard credential used by the MCP service when calling protected CCAM APIs.
#   MCP_DASHBOARD_API_TOKEN_FILE=/run/ccam-secrets/dashboard-token
#
# Independent client credential for the MCP HTTP/SSE transport. /health remains
# unauthenticated for probes; /mcp, /sse, and /messages require this token.
#   MCP_HTTP_AUTH_TOKEN=change-me-to-a-long-random-string
#   MCP_HTTP_AUTH_TOKEN_FILE=/run/ccam-secrets/mcp-token

# ── Background sweeps / sync ─────────────────────────────────────────────────
# Minutes of inactivity before an active session is marked "abandoned" by the
# periodic maintenance sweep (default: 180 = 3h).
#   DASHBOARD_STALE_MINUTES=180

# Idle-working timeout (seconds) for recovering a turn cancelled with Esc BEFORE
# any output (which leaves no transcript marker). When the main agent has been
# "working" with no tool in flight and neither a hook nor the transcript has
# advanced for this long, the watchdog moves the session to Waiting (default: 120).
#   DASHBOARD_WORKING_IDLE_SECONDS=120

# Dead-session liveness reap. The watchdog lists running `claude` CLI processes
# (ps + lsof on macOS, /proc on Linux) and completes any active session whose
# cwd has no live claude process — recovering sessions whose SessionEnd hook
# was lost because the dashboard was down when the user quit (e.g. Ctrl+C).
# Set to 0 to disable (do this when hooks arrive from another machine); it is
# auto-disabled on Windows and inside containers (default: enabled).
#   DASHBOARD_LIVENESS_PROBE=1

# Idle gate (seconds) for WATCHDOG-TICK liveness reaps: a session is only
# completed when its transcript hasn't been written for at least this long
# (the last hook write is the fallback clock when no transcript exists on
# disk), so mid-turn or just-resumed sessions never flicker out on a transient
# probe miss. The startup passes skip this gate entirely — at boot the probe
# alone decides, so sessions quit moments before launch clear immediately
# (default: 60).
#   DASHBOARD_LIVENESS_IDLE_SECONDS=60

# Poll interval (ms) for the continuous ~/.claude/projects sync that surfaces
# projects added after startup whose sessions never flow through hooks. The
# fs.watch watcher fires near-instantly regardless; this poll is the safety net.
# Set to 0 to disable the poll while leaving the watcher running (default: 30000).
#   DASHBOARD_SESSION_SYNC_MS=30000

# ── Codex monitoring ────────────────────────────────────────────────────────
# Optional alternate Codex home. Defaults to CODEX_HOME or ~/.codex. The
# Settings page saves this dashboard-only override and re-arms live monitoring
# immediately; rollouts under sessions/ are ingested incrementally and never uploaded.
#   DASHBOARD_CODEX_HOME=/path/to/.codex

# Safety-net poll for append-only Codex rollout JSONL files. Hooks notify the
# server immediately; this catches sessions when hooks are not installed.
# Set to 0 to disable the poll (the filesystem watcher still runs when available).
#   DASHBOARD_CODEX_SYNC_MS=4000

# ── Remote Data Sources (SSH multi-machine collection) ───────────────────────
# The dashboard can pull Claude Code and Codex history from other machines over SSH:
# it independently stages ~/.claude/projects and ~/.codex/sessions (plus Codex's
# lightweight session_index.jsonl title index), feeds each through its local
# importer, and tags imported sessions with the source. Authentication defers entirely to the host's
# own SSH stack (~/.ssh/config, ssh-agent, keys, known_hosts) — no passwords or
# secrets are stored here.

# Poll interval (ms) for the background poller that syncs each enabled remote
# source. Set to 0 to disable the poller (manual / on-demand syncs still work)
# (default: 15000 = 15s).
#   DASHBOARD_REMOTE_SYNC_MS=15000

# Per-source timeout (ms) for a single remote sync (SSH/SCP or WSL tar pull + import) before
# it is aborted (default: 600000 = 10min).
#   DASHBOARD_REMOTE_SYNC_TIMEOUT_MS=600000

# Timeout (ms) for the Test SSH probe that verifies a remote source is
# reachable (default: 15000 = 15s).
#   DASHBOARD_REMOTE_TEST_TIMEOUT_MS=15000

# Freshness window (ms) for a remote source session's live status. On each sync,
# a remote session whose mirrored transcript changed within this window is kept
# active; once the mirror stops advancing for longer, it is reconciled to
# completed. Remote sessions get no live hooks, so this replaces local liveness;
# a failed, unavailable, or stuck provider falls back to the normal stale sweep.
# (default: 600000 = 10min).
#   DASHBOARD_REMOTE_ACTIVE_WINDOW_MS=600000