.env.example

# DashClaw Environment Variables
# Copy this file to .env.local and fill in your values

# ─── REQUIRED ──────────────────────────────────────────────────────────────────
# These must be set for DashClaw to start.

# PostgreSQL connection string
# Local: docker compose up -d db → postgresql://dashclaw:dashclaw@localhost:5432/dashclaw
# Hosted: Neon free tier → https://neon.tech
DATABASE_URL=<YOUR_DATABASE_URL>

# API key that protects /api/* endpoints (maps to org_default)
DASHCLAW_API_KEY=<YOUR_SECRET_API_KEY>

# 32-character string used to encrypt sensitive settings
ENCRYPTION_KEY=<random-32-char-string-here>

# NextAuth base URL and signing secret
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=<random-32-char-secret>

# ─── RECOMMENDED ───────────────────────────────────────────────────────────────

# Password for the local admin account (skip OAuth for solo/self-hosted use)
# DASHCLAW_LOCAL_ADMIN_PASSWORD=<your-strong-password>

# Cron endpoint secret (generate: openssl rand -hex 32)
# CRON_SECRET=<random-64-char-hex>

# ─── OPTIONAL: Deployment ──────────────────────────────────────────────────────

# self_host (default) | demo (read-only sandbox for dashclaw.io)
# DASHCLAW_MODE=self_host
# NEXT_PUBLIC_DASHCLAW_MODE=self_host

# Force DB driver: "postgres" (TCP) or "neon" (serverless). Auto-detected by default.
# DASHCLAW_DB_DRIVER=postgres

# Override which org DASHCLAW_API_KEY maps to (default: org_default)
# DASHCLAW_API_KEY_ORG=org_default

# Restrict CORS to your deployment domain
# ALLOWED_ORIGIN=https://your-app.vercel.app

# Trust x-forwarded-for from a reverse proxy for rate limiting
# TRUST_PROXY=false

# Change the HTTP port (default: 3000)
# PORT=3000

# ─── OPTIONAL: Rate Limiting ───────────────────────────────────────────────────

# Distributed rate limiting via Upstash Redis (recommended for multi-instance)
# UPSTASH_REDIS_REST_URL=https://...
# UPSTASH_REDIS_REST_TOKEN=...

# Per-IP rate limit tuning (in-memory, single-instance)
# DASHCLAW_DISABLE_RATE_LIMIT=true
# DASHCLAW_RATE_LIMIT_WINDOW_MS=60000
# DASHCLAW_RATE_LIMIT_MAX=1000

# SSRF protection — comma-separated trusted webhook domains
# WEBHOOK_ALLOWED_DOMAINS=slack.com,discord.com

# ─── OPTIONAL: Phase 2b JWT replay protection ──────────────────────────────────
# Closes the capture-and-replay gap left by Phase 2 (signature-only verification).
# Design by @piiiico in issue #120. Only effective when the JWT carries a `jti`
# claim AND verifyJwt returned `verified` (signature OK + not expired + not nbf).
#
# off          — skip the replay check entirely (or you run replay protection upstream)
# best_effort  — default — block confirmed replays; allow if jti is missing
#                or the store is unreachable (Phase 2 fail-soft posture)
# required     — also block when the store is unreachable or jti is missing
# DASHCLAW_JTI_REPLAY_PROTECTION=best_effort
#
# Reject JWTs whose exp is more than this many seconds in the future. Tokens
# with very long lifetimes defeat the replay seen-set (it grows unbounded).
# Default 86400 (24h). Allow ±60s skew on the cap.
# DASHCLAW_JTI_MAX_TTL_SECONDS=86400

# ─── OPTIONAL: Realtime ────────────────────────────────────────────────────────

# memory (default, single-instance) | redis (cross-instance pub/sub)
# REALTIME_BACKEND=memory
# REDIS_URL=redis://localhost:6379
# REALTIME_REPLAY_WINDOW_SECONDS=600
# REALTIME_REPLAY_MAX_EVENTS=1000
# REALTIME_ENFORCE_REDIS=false

# ─── OPTIONAL: OAuth Providers ─────────────────────────────────────────────────

# GitHub OAuth — https://github.com/settings/developers
# GITHUB_ID=<your-github-oauth-app-client-id>
# GITHUB_SECRET=<your-github-oauth-app-client-secret>

# Google OAuth — https://console.cloud.google.com/apis/credentials
# GOOGLE_ID=<your-google-oauth-client-id>
# GOOGLE_SECRET=<your-google-oauth-client-secret>

# OIDC Provider (e.g. Authentik, Keycloak)
# OIDC_ISSUER_URL=<your-oidc-issuer-url>
# OIDC_CLIENT_ID=<your-oidc-client-id>
# OIDC_CLIENT_SECRET=<your-oidc-client-secret>
# OIDC_DISPLAY_NAME=Authentik

# ─── OPTIONAL: Billing ─────────────────────────────────────────────────────────

# Stripe — https://dashboard.stripe.com/apikeys
# STRIPE_SECRET_KEY=<your-stripe-secret-key>
# NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=<your-stripe-publishable-key>
# STRIPE_WEBHOOK_SECRET=<your-stripe-webhook-signing-secret>
# STRIPE_PRICE_PRO=<price_xxx>
# STRIPE_PRICE_BUSINESS=<price_xxx>

# ─── OPTIONAL: Alerts ──────────────────────────────────────────────────────────

# Resend email alerts — https://resend.com
# RESEND_API_KEY=<your-resend-api-key>
# ALERT_FROM_EMAIL=alerts@example.com

# ─── OPTIONAL: Analytics ───────────────────────────────────────────────────────

# Vercel Web Analytics (auto-enabled on Vercel; opt-in elsewhere)
# NEXT_PUBLIC_ENABLE_VERCEL_ANALYTICS=true

# ─── OPTIONAL: Agent Security ──────────────────────────────────────────────────

# Require signed agent actions (true by default in production)
# ENFORCE_AGENT_SIGNATURES=true

# Require agents to be pre-registered before submitting actions
# DASHCLAW_CLOSED_ENROLLMENT=false

# ─── OPTIONAL: Claude Code Hook + SDK clients ─────────────────────────────────
# Used by hooks/dashclaw_pretool.py, hooks/dashclaw_posttool.py,
# hooks/dashclaw_stop.py, scripts/install-hooks.mjs, examples/, and the SDK
# starter snippets. DASHCLAW_BASE_URL points at YOUR DashClaw instance —
# typically https://my-dashclaw.vercel.app or http://localhost:3000.

# DASHCLAW_BASE_URL=http://localhost:3000
# DASHCLAW_URL=http://localhost:3000          # Legacy alias — MCP server + older docs
# DASHCLAW_AGENT_ID=claude-code
# DASHCLAW_HOOK_MODE=enforce                  # enforce | observe
# DASHCLAW_PERMISSION_MODE=danger             # danger | safer (controls bash classification strictness)
# DASHCLAW_GUARD_TIMEOUT=2.5                  # seconds — guard call timeout
# DASHCLAW_APPROVAL_TIMEOUT=30                # seconds — Stop hook approval poll timeout
# Controls hook behavior when /api/guard is unreachable (network failure, instance down).
# Values: block (default, fail closed — destructive actions blocked during outage),
#         warn  (proceed with a loud stderr warning — actions logged for backfill),
#         allow (proceed silently — not recommended, defeats the audit promise).
# All outages write to ~/.dashclaw/orphan-actions.jsonl for backfill on recovery.
# DASHCLAW_GUARD_UNAVAILABLE_POLICY=block
# DASHCLAW_GOVERNED_CATEGORIES=execution,orchestration,file_io,interactive,mcp
# DASHCLAW_WORKSPACE=/path/to/your/project    # Optional override; defaults to cwd

# ─── OPTIONAL: Semantic Guard (required for semantic_check policies) ────────────
# Without a key, semantic_check policies fall back to require_approval (safe middle path).
# Set GUARD_LLM_KEY to a dedicated key (preferred), or OPENAI_API_KEY / ANTHROPIC_API_KEY as fallbacks.
# GUARD_LLM_KEY=sk-...
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
# GUARD_LLM_BASE_URL=https://api.openai.com/v1
# GUARD_LLM_MODEL=gpt-4o-mini
# DASHCLAW_GUARD_FALLBACK=require_approval

# ─── OPTIONAL: Tuning knobs ────────────────────────────────────────────────────
# DASHCLAW_DB_POOL_MAX=10            # Postgres pool max connections (default 10)
# AGENT_ONLINE_WINDOW_MS=120000      # ms an agent counts as "online" since last heartbeat (default 120000)
# GUARD_WEBHOOK_SECRET=<random>      # HMAC secret for outbound guard webhook signing

# ─── OPTIONAL: Telegram approval bridge ────────────────────────────────────────
# Feature is off when TELEGRAM_BOT_TOKEN is unset. Run `npm run telegram:setup` to populate.
# TELEGRAM_BOT_TOKEN=                 # from @BotFather
# TELEGRAM_ADMIN_CHAT_ID=             # numeric chat ID allowed to approve
# TELEGRAM_WEBHOOK_SECRET=            # 32+ random chars; verifies inbound callbacks (openssl rand -hex 32)
# TELEGRAM_APPROVER_ORG_ID=           # org id — auto-discovered via DASHCLAW_API_KEY in `npm run telegram:setup`
# DASHCLAW_ALERTS_TELEGRAM=false      # explicit kill-switch when token is present

# ─── OPTIONAL: Discord approval bridge ─────────────────────────────────────────
# Feature is off when DISCORD_BOT_TOKEN is unset. Registration is a Developer Portal UI step.
# DISCORD_BOT_TOKEN=                  # from Discord Developer Portal -> Bot -> Reset Token
# DISCORD_PUBLIC_KEY=                 # 64-char hex from Developer Portal -> General Information
# DISCORD_APPROVER_USER_ID=           # numeric Discord user ID allowed to approve
# DISCORD_APPROVER_ORG_ID=            # org id — same value as TELEGRAM_APPROVER_ORG_ID in single-admin setups
# DASHCLAW_ALERTS_DISCORD=false       # explicit kill-switch when token is present

# Optional: Discord webhook URL for launch-window new-connect alerts (DOG-04 telemetry).
# Fires once per org on its first /connect completion. Payload is masked
# org_id + agent_id + timestamp — no secrets, no PII. Distinct from
# DASHCLAW_ALERTS_DISCORD (which is the bridge kill-switch, not a URL).
# DASHCLAW_NEW_CONNECT_WEBHOOK=

# ─── OPTIONAL: Hosted provisioning (operator-only, self-host deploys leave OFF) ──
# When DASHCLAW_HOSTED=true the deployment exposes /api/hosted/* routes that
# mint trial workspaces on demand. Self-host users should leave this unset —
# they create orgs via /api/orgs with their own admin API key.
# DASHCLAW_HOSTED=false
# TURNSTILE_SECRET_KEY=                       # Cloudflare Turnstile secret; unset = dev bypass
# NEXT_PUBLIC_TURNSTILE_SITE_KEY=             # Client-side Turnstile widget site key (pairs with TURNSTILE_SECRET_KEY)
# HOSTED_TRIAL_DAYS=30                        # Trial duration in days
# HOSTED_TRIAL_ACTION_CAP=10000               # Max governed actions per trial
# HOSTED_PROVISION_MAX_PER_IP_PER_DAY=5       # Per-IP provisioning rate limit (rolling day)
# HOSTED_CLEANUP_SECRET=                      # Shared secret for cron-invoked /api/hosted/cleanup (X-Cleanup-Secret header)
# CRON_SECRET=                                # Vercel cron auth (Authorization: Bearer); pairs with /api/hosted/cleanup
# HOSTED_SMOKE_BASE_URL=                      # Default URL for `npm run hosted:smoke`