.env.example

# =============================================================================
# agentbox .env.example — THE single canonical environment template.
#
# Copy to .env and fill in:   cp .env.example .env   →   ./agentbox.sh preflight
# Never commit .env (gitignored). This is the ONLY tracked runtime env template.
#
# HOW THIS WORKS ALONGSIDE agentbox.toml
#   agentbox.toml  = feature gates + toolchains, baked into the image at Nix build time.
#   .env           = secrets, API keys, host-specifics, and RUNTIME OVERRIDES of baked
#                    values. Loaded into the container by docker-compose `env_file: .env`.
#   Rule of thumb: if it's a secret or host-specific, it goes here; if it's a
#   capability toggle, it goes in agentbox.toml. A handful of vars below are
#   "override-only" (marked [override] — baked from the toml, set here only to override
#   without rebuilding.
#
# NOT in this file (by design):
#   - Per-profile env  -> workspace/profiles/<stack>/.env  (AUTO-GENERATED - don't edit)
#   - Solid-pod sidecar -> .env.solid-pods.example         (separate sidecar stack, see that file)
#   - OCI provisioning  -> .env.template.oci               (deploy-time, not runtime)
#
# Provenance (2026-07-22, PRD-024 C-8): this file is the merge target of
# docs/reference/env-consolidation-plan.md. Retired sources whose unique keys
# were folded in below: .env.template, .env.template.common, skills/env.sample,
# skills/echoloop/.env.example, skills/ontology-enrich/.env.example. Each retired
# file now carries a deprecation-pointer header back to this file rather than
# being deleted (append-only culture) - see docs/reference/env-consolidation-plan.md S1.
#
# Legend:  (required) must set before `up`   (optional) safe default   [override] overrides a toml-baked default
# =============================================================================

# -- Image ---------------------------------------------------------------------
# Empty = locally built image (default after `agentbox.sh up --build`).
AGENTBOX_IMAGE_REF=

# -- AI provider keys (at least ANTHROPIC_API_KEY) -----------------------------
ANTHROPIC_API_KEY=            # (required) https://console.anthropic.com/
ANTHROPIC_BASE_URL=           # (optional) override the Anthropic endpoint (e.g. route via Z.AI)
OPENAI_API_KEY=              # (optional)
OPENAI_BASE_URL=             # (optional) OpenAI-compatible gateway override
GOOGLE_API_KEY=              # (optional) Google / Gemini - CANONICAL name
OPENROUTER_API_KEY=          # (optional) OpenRouter, 100+ models - https://openrouter.ai/keys
DEEPSEEK_API_KEY=            # (optional)
DEEPSEEK_BASE_URL=           # (optional)
OLLAMA_BASE_URL=             # (optional) local/remote Ollama
OLLAMA_MODEL=                # (optional)
GITHUB_TOKEN=                # (optional) GitHub integration
CRATES_TOKEN=                # (optional) crates.io publish
E2B_API_KEY=                 # (optional) E2B cloud sandboxes
# Compatibility aliases - code still reads these in places (name drift, to be
# consolidated to the canonical names above). Set an alias only if a skill needs it:
#   GOOGLE_GEMINI_API_KEY  (-> GOOGLE_API_KEY)     GEMINI_API_KEY (-> GOOGLE_API_KEY)

# -- Z.AI consultant (api.z.ai sidecar) ----------------------------------------
ZAI_API_KEY=                 # (optional) web-summary / consultant tier
ZAI_ANTHROPIC_API_KEY=       # (optional) route Claude calls via Z.AI for cost savings
ZAI_URL=                     # (optional) endpoint override; read directly by web-summary,
                             #   comfyui, terracraft, project-primer. Default when unset:
                             #   https://api.z.ai/api/anthropic (per-token) or set to
                             #   https://api.z.ai/api/coding/paas/v4 for flat-rate billing.
ZAI_TIMEOUT=60               # (optional) web-summary request timeout, seconds
ZAI_BASE_URL=                # (optional) (X) DISTINCT from ZAI_URL - only claude-zai/wrapper
                             #   reads this name; ZAI_URL is read everywhere else (drift to
                             #   fix in code, kept separate deliberately for now).

# -- Skill API keys: search / research -----------------------------------------
CERAMIC_API_KEY=             # (optional) ceramic-search - https://platform.ceramic.ai/keys  <- was missing everywhere
PERPLEXITY_API_KEY=          # (optional) perplexity, perplexity-research, web-researcher, ontology-enrich
CONTEXT7_API_KEY=            # (optional) context7 docs MCP (free tier works keyless)
BRAVE_API_KEY=               # (optional) web-researcher Brave backend

# -- Skill API keys: media / art / video ---------------------------------------
FAL_KEY=                     # (optional) OpenMontage / fal.ai
ELEVENLABS_API_KEY=          # (optional)
SUNO_API_KEY=                # (optional)
HEYGEN_API_KEY=              # (optional)
RUNWAY_API_KEY=              # (optional)
PEXELS_API_KEY=              # (optional)
PIXABAY_API_KEY=             # (optional)
REMOVEBG_API_KEY=            # (optional) Nano-Banana art skill
DEEPGRAM_API_KEY=            # (optional) echoloop transcription
OPENROUTER_KEY=              # (optional) (X) DISTINCT from OPENROUTER_API_KEY - the Nano-Banana
                             #   art skill reads OPENROUTER_KEY; general routing reads
                             #   OPENROUTER_API_KEY. Kept separate deliberately (drift to fix in code).

# -- Skill: comfyui (image generation) ------------------------------------------
COMFYUI_URL=                 # (optional) default http://localhost:8188 - read by skills/comfyui
COMFYUI_OUTPUT_DIR=          # (optional) default /home/devuser/ComfyUI/output - skills/comfyui/mcp-server
COMFYUI_OUTPUTS=             # (optional) (X) DISTINCT from COMFYUI_OUTPUT_DIR - management-api's
                             #   comfyui-manager.js reads this name instead (drift to fix in code).
SALAD_API_KEY=               # (optional) comfyui distributed compute - Salad Cloud
SALAD_ORG_NAME=              # (optional) Salad Cloud organisation, default 'default-org'

# -- Skill config: social / defense / meetings / ontology ----------------------
REDDIT_CLIENT_ID=            # (optional) reddit MCP; anonymous works without keys
REDDIT_CLIENT_SECRET=
REDDIT_USERNAME=
REDDIT_PASSWORD=
LINKEDIN_TIMEOUT=5000
DEFENSE_MCP_DRY_RUN=true
DEFENSE_MCP_REQUIRE_CONFIRMATION=true
DEFENSE_MCP_ALLOWED_DIRS=/tmp,/home,/var/log
DEFENSE_MCP_LOG_LEVEL=info
ECHOLOOP_LLM_PROVIDER=anthropic
ECHOLOOP_TRANSCRIBER=local
ECHOLOOP_WHISPER_MODEL=base.en
ECHOLOOP_WHISPER_DEVICE=cpu
ECHOLOOP_SYSTEM_DEVICE=      # (optional) blank = auto-detect
ECHOLOOP_MIC_DEVICE=         # (optional) blank = auto-detect
ECHOLOOP_LOG_DIR=/tmp/echoloop-sessions
CBM_CACHE_DIR=/home/devuser/.cache/codebase-memory-mcp   # codebase-memory MCP index storage
IMAGEMAGICK_TIMEOUT=300      # (optional) imagemagick MCP operation timeout, seconds
DOCKER_SOCKET_PATH=/var/run/docker.sock   # (optional) override if the socket is remounted elsewhere
ONTOLOGY_ENRICH_UK_ENGLISH=true
ONTOLOGY_ENRICH_RATE_LIMIT=10
ONTOLOGY_ENRICH_CITATION_MIN_RELEVANCE=0.7
ONTOLOGY_ENRICH_AUTO_ROLLBACK=true
ONTOLOGY_ENRICH_KG_ROOT=mainKnowledgeGraph/pages
ONTOLOGY_ENRICH_LOG_LEVEL=INFO
ONTOLOGY_ENRICH_LOG_FILE=logs/enrichment.log

# -- Service ports (gui-tools sidecar; blender/qgis proxies) -------------------
BLENDER_PORT=9876
QGIS_PORT=9877
QGIS_HOST=localhost
QGIS_TIMEOUT=60
PBR_PORT=9878
MCP_TCP_PORT=9500            # (optional) VisionClaw MCP TCP discovery port

# -- Private email-search gateway ----------------------------------------------
# Enable [skills.email_search] in agentbox.toml; the entrypoint auto-registers the
# server when the gateway's /health is reachable. Token is runtime-only.
AGENTBOX_EMAIL_GATEWAY_TOKEN=    # (optional) bearer token issued by the gateway host
AGENTBOX_EMAIL_GATEWAY_URL=      # (optional) overrides agentbox.toml gateway_url

# -- Management API ------------------------------------------------------------
MANAGEMENT_API_KEY=          # (optional) blank = auto-generate at first boot (recommended)
MANAGEMENT_API_AUTH_MODE=hybrid   # hybrid (Bearer OR NIP-98) | strict-nip98 (planned)
MANAGEMENT_API_URL=          # (optional) override the internal URL agents call

# -- RuVector PostgreSQL (memory) ----------------------------------------------
# Must match the password ruvector-postgres was initialised with, in all three places
# (this var, docker-compose.override.yml, agentbox.toml conninfo). Source from here.
RUVECTOR_PG_PASSWORD=        # (required if adapters.memory = external)
RUVECTOR_USE_EXTERNAL=true

# -- Embeddings / Xinference ([override] baked from toml; override only) -----------------
XINFERENCE_ENDPOINT=
EMBEDDING_MODEL=

# -- GPU -----------------------------------------------------------------------
NVIDIA_VISIBLE_DEVICES=all   # 'all' | comma indices | stable GPU-<uuid>
NVIDIA_DRIVER_CAPABILITIES=compute,utility,graphics

# -- Nostr / sovereign identity ------------------------------------------------
# Provide AGENTBOX_NSEC (bech32, preferred) OR AGENTBOX_PRIVKEY_HEX. If both empty,
# the entrypoint generates a keypair at boot into the sovereign-identities volume.
AGENTBOX_NSEC=
AGENTBOX_PRIVKEY_HEX=
AGENTBOX_NPUB=               # operator pubkey (bech32); overrides the toml operator value
AGENTBOX_PUBKEY=             # operator pubkey (hex), where a hex form is needed
NOSTR_RELAYS=                # comma-separated; put the deployment's primary relay FIRST

# -- Sovereign mesh: embedded relay + admin ([override] baked from toml; override only) --
AGENTBOX_RELAY_BIND=
# AGENTBOX_ADMIN_PUBKEY=
# AGENTBOX_ALLOWED_PUBKEYS=

# -- Sovereign mesh: Nostr session mirror --------------------------------------
# Per-turn live mirror (config/hooks/nostr-live-mirror.cjs). Silent no-op unless a
# recipient pubkey is set. AGENTBOX_LIVE_MIRROR=0 disables.
AGENTBOX_LIVE_MIRROR=
AGENTBOX_MIRROR_CHILD=
AGENTBOX_MIRROR_KEY_TAG=
AGENTBOX_MIRROR_RECIPIENT_PUBKEY=
NOSTR_MIRROR_RELAY=

# -- Per-User Agent Fabric (PUAF) / forum agents (opt-in, off by default) -------
JUNKIEJARVIS_ENABLED=
PER_USER_AGENTS_ENABLED=

# -- Ontology augmentation (PRD-020 consultant seam) ---------------------------
ONTOLOGY_INJECT=             # (optional) PUSH breadcrumb per turn (needs the cache built)
CONSULT_ONTOLOGY_AUGMENT=    # (optional) PULL seam for consultants

# -- Networking (Tailscale federation; optional) -------------------------------
TAILSCALE_AUTHKEY=           # blank = Tailscale disabled (default)
TAILSCALE_HOSTNAME=agentbox

# -- Resource limits (referenced by docker-compose.override.yml) ---------------
AGENTBOX_CPU_LIMIT=
AGENTBOX_MEM_LIMIT=
AGENTBOX_CPU_RESERVE=
AGENTBOX_MEM_RESERVE=

# -- External project mounts (up to PROJECT_DIR_10) ----------------------------
PROJECT_DIR=                 # -> /home/devuser/workspace/project
PROJECT_DIR_2=               # -> /home/devuser/workspace/project2
HOST_CLAUDE_DIR=             # host ~/.claude bind (read-write single source of truth)

# -- Agent identity / misc -----------------------------------------------------
AGENTBOX_AGENT_ID=
TZ=Europe/London

# =============================================================================
# REMOVED from the canonical env (retired - do NOT reintroduce):
#   TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID / TELEGRAM_MIRROR   (CTM retired -> Nostr mirror)
#   gemini-user / openai-user / zai-user multi-user model     (single devuser now)
#   GEMINI_FLOW_* , ROUTER_MODE / *_BUDGET , ragflow network  (legacy turbo-flow)
#   PLAYWRIGHT_* / CHROMIUM_PATH / SCREENSHOT_DIR / VIEWPORT_* / agent-browser
#                                                              (browsercontainer sidecar now;
#                                                               skills/playwright is deprecated
#                                                               local-Chrome residue, see
#                                                               agentbox/CLAUDE.md)
#   VISIONCLAW_HOST / VISIONCLAW_COMPOSE_PATH                  (MAD-era; host-project specifics
#                                                               never belong in this tracked
#                                                               template - agentbox/CLAUDE.md
#                                                               "no host-project specifics")
# Host-project specifics (relay URLs, operator keys) live in the real .env only,
# never in this tracked template.
#
# MERGED into this file from now-retired templates (2026-07-22, PRD-024 C-8):
#   .env.template, .env.template.common, skills/env.sample,
#   skills/echoloop/.env.example, skills/ontology-enrich/.env.example
# Each retains a deprecation-pointer stub at its old path (append-only culture)
# rather than being deleted; see docs/reference/env-consolidation-plan.md.
# KEPT SEPARATE (distinct scopes, cross-referenced, not merged here):
#   .env.solid-pods.example / .env.solid-pods.template  (solid-pod sidecar)
#   .env.template.oci                                    (OCI deploy-time provisioning)
# =============================================================================