.env.example

# Brigade environment variables — copy to `.env` and adjust as needed.
#
# Every entry is OPTIONAL. Brigade boots with sensible defaults when nothing
# is set. Uncomment + edit only the lines you want to override.
#
# Tip: a stale or absent `.env` is always safe — Brigade reads the live
# `process.env`, not this file. Loaders like `dotenv` populate `process.env`
# from `.env` before Brigade starts.

# ───────────────────────────────────────────────────────────────────────────
# 1. Storage / paths
# ───────────────────────────────────────────────────────────────────────────

# Where Brigade keeps everything (config, agents, sessions, logs).
# Default: `~/.brigade`. Override for per-tenant isolation or alt installs.
# BRIGADE_STATE_DIR=

# Explicit path to `brigade.json` — overrides the `<state-dir>/brigade.json`
# default. Useful when sharing one config across multiple state dirs.
# BRIGADE_CONFIG_PATH=

# Named workspace profile — when set (and not "default") the default agent's
# workspace becomes `<state-dir>/workspace-<name>/`. Per-agent workspaces are
# unaffected (each agent always has its own dir under `agents/<id>/`).
# BRIGADE_PROFILE=

# Override the install-tree skills root (the "bundled" scan root).
# Test fixtures use this; advanced users normally leave it unset.
# BRIGADE_BUNDLED_SKILLS_DIR=

# Storage mode: `filesystem` (default) or `convex`.
# When set to `convex`, also set BRIGADE_CONVEX_URL.
# The mode is resolved at boot from a sticky sentinel and freezes for the
# process — changing this requires a gateway restart.
# BRIGADE_MODE=filesystem

# Bypass the sentinel/mode mismatch refusal (one-shot diagnostics only).
# Lets you run a filesystem command even when the sentinel says convex (or
# vice-versa) without clearing the sentinel first. Use with caution.
# BRIGADE_FORCE_MODE=1

# ───────────────────────────────────────────────────────────────────────────
# 2. Gateway / network
# ───────────────────────────────────────────────────────────────────────────

# WebSocket port the gateway daemon binds to.
# Default: 7777. Change if 7777 collides with another service on the host.
# BRIGADE_PORT=7777

# Verbosity: trace | debug | info | warn | error | fatal
# Default: info.
# BRIGADE_LOG_LEVEL=info

# Mirror gateway logs to stderr. 0/off = silent, 1/on = always print.
# Default: auto (on when stderr is a TTY).
# BRIGADE_LOG_CONSOLE=

# Extra connect-side debug output (verbose WS frames + reconnect tracing).
# Set to 1 to enable, leave unset for normal use.
# BRIGADE_DEBUG=

# Routing decisions debug log (which agent picked up which message).
# Set to 1 to enable.
# BRIGADE_LOG_ROUTING=

# Override the host-environment tag in the system prompt's runtime line
# (e.g. "linux", "macos", "windows", or a custom label). When unset, Brigade
# auto-detects from `process.platform`.
# BRIGADE_HOST_ENV=

# ───────────────────────────────────────────────────────────────────────────
# 3. Agent loop / model behaviour
# ───────────────────────────────────────────────────────────────────────────

# Seconds to wait for the model to produce its NEXT token before giving up
# and surfacing an "idle timeout" error to the operator.
# Default: 90. Raise for slow providers / large reasoning budgets.
# BRIGADE_LLM_IDLE_TIMEOUT_SECONDS=90

# Milliseconds between post-turn memory-consolidation passes.
# Default: gateway-internal. Leave unset unless you know why you're changing it.
# BRIGADE_CONSOLIDATE_INTERVAL_MS=

# Disable Pi's playwright-based `browser` tool. Set to 1 if your host can't
# launch a headless browser (no display server, locked-down CI, etc.).
# BRIGADE_DISABLE_BROWSER_TOOL=

# Disable the OFF-hot-path memory-extraction pass that runs after every turn.
# Set to 1 to skip extraction entirely (e.g. cost-sensitive runs).
# BRIGADE_DISABLE_MEMORY_EXTRACT=

# Disable the heartbeat scheduler (the daemon that wakes agents periodically).
# Set to 1 for ephemeral / one-shot runs that don't want background activity.
# BRIGADE_DISABLE_HEARTBEAT=

# Persist the sub-agent inbox to JSONL. Auto-on at gateway boot; set to 0
# to keep the inbox in-memory only (lost on restart).
# BRIGADE_ENABLE_INBOX_PERSIST=1

# Memory recall embedder. Controls whether fact recall uses a learned embedding
# model (true-synonymy) or the zero-dep model-free HRR (lexical, air-gap safe).
#
#   model-free          (default) — no external dep, no network, always works.
#                        Recall is BM25-primary; paraphrases score lower but the
#                        engine still surfaces exact-match and near-match facts.
#   auto               — try local model first, then OpenAI, degrade to HRR.
#   openai-256         — OpenAI text-embedding-3-small (256-dim Matryoshka).
#                        Requires OPENAI_API_KEY.
#   local-embeddinggemma — embeddinggemma-300m via node-llama-cpp (offline/air-gap
#                          once the GGUF is cached). Requires `npm i node-llama-cpp`
#                          and the GGUF auto-downloaded on first use.
#
# The gateway logs which embedder loaded at startup. Check with `brigade doctor`.
# BRIGADE_MEMORY_EMBEDDER=model-free

# Override the headless browser binary path. Auto-detected by default
# (chromium / msedge / chrome on PATH).
# BRIGADE_BROWSER_EXECUTABLE=

# Force headless mode for the `browser` tool. Set to 1 to force; leave unset
# for auto-detect.
# BRIGADE_BROWSER_HEADLESS=

# ───────────────────────────────────────────────────────────────────────────
# 4. TUI / rendering
# ───────────────────────────────────────────────────────────────────────────

# Milliseconds between paints while a model reply is streaming. Larger value
# = less flicker + smoother scroll-back on slow terminals (Windows Terminal,
# tmux, ssh); smaller value = snappier token-by-token feel on fast terminals
# (iTerm, Alacritty, recent Kitty). Clamped to ≥16.
# Default: 150.
# BRIGADE_STREAM_RENDER_MS=150

# ───────────────────────────────────────────────────────────────────────────
# 5. Encryption (Convex mode)
# ───────────────────────────────────────────────────────────────────────────

# At-rest encryption master key — a 64-char hex string (32 bytes).
# When set, every Convex byte column (credentials, persona, memory, cron
# payloads, transcripts) is sealed with AES-256-GCM before it leaves the
# process. Generate with: `brigade encrypt init` or:
#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Resolution order: env var → key file → off.
# BRIGADE_ENCRYPTION_KEY=

# Previous key for rotation. Reads try the primary key first, then this one.
# Once everything has been re-sealed, drop this variable.
# See: docs/convex-mode.md → Key rotation
# BRIGADE_ENCRYPTION_KEY_OLD=

# Override the path to the encryption key file (auto-generated by `brigade
# encrypt init`). Defaults to the OS config dir outside `~/.brigade` so
# `rm -rf ~/.brigade` doesn't destroy the key.
# BRIGADE_ENCRYPTION_KEY_FILE=

# ───────────────────────────────────────────────────────────────────────────
# 6. Convex backend
# ───────────────────────────────────────────────────────────────────────────

# Convex deployment URL. Implies convex storage mode (overrides
# BRIGADE_MODE). For the self-hosted backend: http://127.0.0.1:3210
# Start it with: `brigade convex dev` (or `npm run convex:dev` from source).
# BRIGADE_CONVEX_URL=

# Strict-zero mode for convex storage. Logs (or throws on) any write to
# `~/.brigade/` outside the allowlist (sentinel + workspace).
#   warn    (default in convex mode) — log violations, continue running
#   enforce — violations THROW, halting the operation
# BRIGADE_STRICT_MODE=warn