.env.example

# ─── Resonant — local environment secrets ─────────────────────────────────────
# Copy this file to `.env` (gitignored) and fill in only what you need.
# Almost everything here is OPTIONAL: most config lives in `resonant.yaml`, and
# secrets like the model credential and integration tokens are normally set from
# the in-app Settings UI (stored in the local DB), not here. Env vars WIN over
# both the YAML and the DB where they overlap.
#
# Nothing in this file is required to boot. A fresh install runs with an empty
# password (open on loopback) and no integrations.

# ── Auth ──────────────────────────────────────────────────────────────────────
# Login password for the app's auth gate. Empty = no password (loopback only).
# Overrides auth.password in resonant.yaml.
APP_PASSWORD=
# Dev escape hatch: with AUTH_DEV_OPEN=true AND no password configured, protected
# routes pass without a session. Leave unset in any networked deployment.
AUTH_DEV_OPEN=

# ── Agent credential ──────────────────────────────────────────────────────────
# The model credential for the in-app agent. Normally set via Settings (stored in
# the DB). If you prefer env, set your Anthropic API key here; when present it is
# used and the OAuth/host-managed vars below are cleared.
ANTHROPIC_API_KEY=
# Set automatically by a Claude Code host environment — leave unset for a normal
# API-key or subscription setup.
CLAUDE_CODE_OAUTH_TOKEN=
CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST=

# ── Identity / agent overrides (usually set in resonant.yaml instead) ─────────
COMPANION_NAME=
USER_NAME=
# IANA timezone, e.g. Europe/London. Overrides identity.timezone.
TZ=
# Absolute path the agent runs in (its home dir). Overrides agent.cwd.
AGENT_CWD=
# Model slug for interactive turns. Overrides agent.model.
AGENT_MODEL=
# Context-card namespace the `res` CLI writes the companion card under.
# Defaults to "companion"; the user card uses "user". Only change if you know why.
RESONANT_NAMESPACE=

# ── Server ────────────────────────────────────────────────────────────────────
# HTTP port / host / DB path. Override resonant.yaml server.* .
PORT=
HOST=
DB_PATH=
# Port the `res` CLI dials the backend on (defaults to the server port).
RESONANT_PORT=

# ── Write-gate roots (agent PreToolUse write allowlist) ───────────────────────
# Override hooks.* in resonant.yaml. EXTRA_WRITE_PATHS is comma-separated.
WORKSPACE_ROOT=
VAULT_PATH=
EXTRA_WRITE_PATHS=

# ── Internal loopback token ───────────────────────────────────────────────────
# Shared secret for the backend's /internal/* routes (agent + `res` CLI). If
# unset, a random token is auto-generated and persisted to data/.internal-token.
# Only set this to pin a known value across the agent's .mcp.json and the CLI.
INTERNAL_TOKEN=

# ── Voice (optional; voice.enabled must also be true in resonant.yaml) ─────────
ELEVENLABS_API_KEY=      # ElevenLabs TTS key
ELEVENLABS_VOICE_ID=     # ElevenLabs voice id to speak in
GROQ_API_KEY=            # Groq (STT / fast inference) key
HUME_API_KEY=            # Hume (prosody/expression) key

# ── Channels (optional; the matching *.enabled must be true in resonant.yaml) ──
DISCORD_BOT_TOKEN=       # Discord bot token (can also be set in Settings/DB)
TELEGRAM_BOT_TOKEN=      # Telegram bot token (can also be set in Settings/DB)
GIPHY_API_KEY=           # Optional: Giphy key for the Telegram /gif command

# ── Google Workspace (optional; google.enabled must be true in resonant.yaml) ──
GOOGLE_CLIENT_ID=        # Desktop OAuth client id (from your Google Cloud project)
GOOGLE_CLIENT_SECRET=    # Desktop OAuth client secret
# Fixed secret used to encrypt stored Google refresh tokens at rest. If unset, a
# random key is auto-generated and persisted to data/.google-key.
GOOGLE_TOKEN_SECRET=

# ── Web push (optional) ───────────────────────────────────────────────────────
# VAPID keypair for browser push notifications. Generate with `npx web-push`.
VAPID_PUBLIC_KEY=
VAPID_PRIVATE_KEY=
VAPID_CONTACT=           # mailto: or https: contact for the push subscription

# ── Diagnostics / runtime (rarely needed) ─────────────────────────────────────
NODE_ENV=                # "production" in a real deployment; unset = development
BUILD_ID=                # Stamped into the version banner; auto "dev" if unset
MEASURE_THINKING=        # "1" logs thinking-token timing for perf debugging

# NOTE: the Mind service credential (mind.api_key) is NOT read from env — it is
# stored in the local DB and set from the Settings UI. It never lives in this file.