.env.example

# HelixCode Docker Environment Configuration
# Copy this file to .env and modify as needed

# Database Configuration
# CONST-042 / CONST-053: placeholders only — copy this file to .env (mode 0600,
# gitignored) and replace every CHANGE_ME with a real, locally-generated secret.
# Never commit a real credential, not even as an example value.
HELIX_DATABASE_PASSWORD=CHANGE_ME_db_password
HELIX_AUTH_JWT_SECRET=CHANGE_ME_jwt_secret
HELIX_REDIS_PASSWORD=CHANGE_ME_redis_password

# Port Configuration
HELIX_API_PORT=8080
HELIX_SSH_PORT=2222
HELIX_WEB_PORT=3000

# Network Configuration
HELIX_NETWORK_MODE=standalone  # standalone or distributed
HELIX_AUTO_PORT=false          # Automatically adjust ports if occupied

# Optional: External Database (if not using included PostgreSQL)
# HELIX_DATABASE_URL=postgres://user:pass@host:port/database?sslmode=disable

# Optional: External Redis (if not using included Redis)
# HELIX_REDIS_URL=redis://user:pass@host:port/database

# ============================================================================
# LLMsVerifier Configuration
# ============================================================================
HELIX_VERIFIER_ENABLED=false
HELIX_VERIFIER_ENDPOINT=http://localhost:8081
HELIX_VERIFIER_API_KEY=
HELIX_VERIFIER_TIMEOUT=30s
HELIX_VERIFIER_CACHE_TTL=5m
HELIX_VERIFIER_POLLING_INTERVAL=60s
HELIX_VERIFIER_MIN_SCORE=6.0
HELIX_MODELS_DEV_ENDPOINT=https://api.models.dev

# ============================================================================
# Provider API Keys (Cloud Providers)
# ============================================================================
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GEMINI_API_KEY=
DEEPSEEK_API_KEY=
GROQ_API_KEY=
MISTRAL_API_KEY=
XAI_API_KEY=
OPENROUTER_API_KEY=

# ============================================================================
# Local Provider Configuration
# ============================================================================
# Whether HelixLLM may auto-download local model weights on boot. Read by
# submodules/helix_llm (internal/shared/config/config.go ModelsAutoDownload),
# whose struct default is TRUE — so leaving this unset means the gateway
# performs a real multi-GB download before it binds.
#
# `false` opts out of local-model downloads entirely; cloud providers are
# unaffected. scripts/systemd/helixllm-gateway.service documents `.env` as the
# place to set it, and the live gateway on this host runs with `false` — but
# the value was only ever in the (gitignored) `.env`, so a fresh clone silently
# inherited the auto-download default instead. Recorded here so the tracked
# template carries the deployment's actual intent (§11.4.77: an excluded file
# needs a reproducible way to get its content back).
HELIX_MODELS_AUTO_DOWNLOAD=false

# Ollama. Read by the server's default LLM route (internal/server/llm_generate.go
# envOllamaHost). Unset ⇒ http://localhost:11434, Ollama's standard port.
HELIX_OLLAMA_HOST=http://localhost:11434

# Local llama.cpp (`llama-server`) OpenAI-compatible endpoint. Read by the
# server's `llamacpp` LLM route (internal/server/llm_generate.go
# envLlamaCppHost). Base URL only — do NOT append "/v1"; the provider's
# endpoint defaults already carry that prefix.
#
# Select it per request with {"provider":"llamacpp", ...} on
# POST /api/v1/llm/generate, or make it the server-wide default with
# HELIX_LLM_PROVIDER=llamacpp.
#
# NOTE the port: 18434, NOT llama.cpp's upstream default of 8080. 8080 is the
# port HelixCode's OWN API server binds, so pointing this at 8080 makes the
# server POST completions to itself (measured: HTTP 502 "llama.cpp returned
# status 404"). 18434 is this project's live local llama.cpp port — see
# config/llmsverifier/config.yaml's `llamacpp` row, served by
# helixllm-coder.service — and it matches what the sibling `helixllm`/`local`
# route defaults to, so both local routes agree. Unset ⇒ falls back to
# HELIX_LLM_LOCAL_OPENAI_ENDPOINT, then to http://localhost:18434.
HELIX_LLAMA_CPP_HOST=http://localhost:18434

# Optional: Worker Configuration
# WORKER_CAPABILITIES=code-generation,testing,llm-inference
# WORKER_MAX_TASKS=5

# §11.4.151/.155 release-tag + recording-corpus prefix (project name).
# Operator decision 2026-07-07: the release/version form is `helix-code-<ver>`
# (kebab-case), e.g. `helix-code-1.0.0-dev-0.0.1` / big release `helix-code-1.0.0-dev`.
# This supersedes the earlier `helixcode-vN.N.N` tag prefix. The authoritative
# value lives in the gitignored `.env` (§11.4.151 resolution order: .env wins).
HELIX_RELEASE_PREFIX=helix-code

# ============================================================================
# Local adaptive serving — LLM routing, cloud gate, and the wire facades
# (spec 002 / gap-ledger HXC-002-F3-01..04)
# ============================================================================

# Which provider the SERVER resolves when a request does not name one.
# Leave EMPTY to fall through to `llm.default_provider` in config.yaml, which
# ships empty by default so nothing routes to a paid cloud provider implicitly.
# Recognised local selectors: `helixllm` / `local` (llama.cpp coder on :18434),
# `gateway` / `helixllm-gateway` (the HelixLLM gateway, below).
# NOTE: a value here that names no known provider is a SERVER-side fault and is
# reported as HTTP 500, not 400 — the caller did not cause it.
HELIX_LLM_PROVIDER=

# The HelixLLM gateway speaks OpenAI-compatible HTTP over TLS and, unlike the
# bare coder endpoint, emits STRUCTURED tool_calls — which is what makes
# tool-using clients work through the facades below.
# Default when unset: https://127.0.0.1:8443/v1
HELIX_LLM_GATEWAY_ENDPOINT=

# CA certificate used to verify the gateway's (self-signed) TLS certificate.
# When unset, the server looks for the repo-relative
# `submodules/helix_llm/certs/cert.pem`, which `make certs` generates and which
# is gitignored — so a fresh clone MUST either run `make certs` or point this at
# its own CA. TLS verification is never disabled; an untrusted cert fails closed.
HELIX_LLM_GATEWAY_CA_CERT=

# Bearer credential(s) for the OpenAI-compatible and Anthropic-compatible wire
# facades (POST /v1/chat/completions, POST /v1/messages). COMMA-SEPARATED for
# rotation — any one value authenticates.
#
# CONST-042/CONST-035: these routes drive real LLM calls, so the facade is
# FAIL-CLOSED — with no key configured EVERY request is rejected 401, including
# one carrying a bearer token. That is deliberate: it is why an unconfigured
# deployment cannot be driven by anyone who can reach the port.
#
# Generate a real value into your gitignored `.env` (mode 0600), never here:
#     printf 'HELIX_WIRE_FACADE_API_KEYS=%s\n' "$(openssl rand -hex 32)" >> .env
#
# SECURITY: `server.address` ships as 0.0.0.0 and the facade is plain HTTP, so
# this credential crosses the network in clear on every interface. Bind
# 127.0.0.1, or front the facade with TLS, before exposing this host.
# Shipped EMPTY on purpose: an empty value means NO key is configured, which is
# the fail-closed state described above. setup.sh generates a unique per-install
# secret into your gitignored .env; a hand-copied .env stays fail-closed until
# you fill it in. A shared default here would be a published credential.
HELIX_WIRE_FACADE_API_KEYS=

# Bearer credential(s) for the HelixLLM GATEWAY (helixllm-gateway.service,
# :8443) — again inbound, again COMMA-SEPARATED for rotation, and again never
# an outbound provider key. The FIRST entry is the current one by convention:
# scripts/export_gateway_keys.sh hands that entry to local CLI clients, so a
# rotation is "put the new key first, keep the old one second until callers
# have rolled over, then drop it".
#
# Its interaction with HELIX_AUTH_JWT_SECRET is the part worth knowing, because
# the failure it prevents is a lockout rather than an outage. HelixLLM's auth
# is self-gating per credential (internal/shared/config.AuthConfig):
#
#     JWT unset,  keys unset  ->  open access
#     JWT unset,  keys set    ->  API key required
#     JWT set,    keys unset  ->  JWT required          <-- see below
#     both set                ->  either one accepted
#
# The third row is a trap. POST /v1/auth/token — the only endpoint that MINTS a
# JWT — is itself inside the authenticated group, so a deployment with a signing
# secret and no API key has no way in at all: every request 401s, including the
# token exchange that would have issued the credential. Setting a key here is
# what makes the token exchange reachable and gives ordinary OpenAI-wire clients
# (which have no way to obtain this server's JWT) a credential they can present.
#
# Never put HELIX_AUTH_JWT_SECRET in a client's hands as a substitute: it mints
# a valid token for ANY subject. The API key is the scoped, revocable half of
# the pair, and it is the half that belongs outside the server process.
#
# Shipped EMPTY on purpose — empty means "no key configured", which for THIS
# variable alone (see the truth table) is open access rather than fail-closed,
# so a hand-copied .env behaves exactly as an unconfigured HelixLLM always has.
# setup.sh generates a unique per-install value into your gitignored .env; a
# shared default here would be a published credential.
HELIX_AUTH_API_KEYS=

# Cloud providers are gated OFF by default (`llm.cloud.enabled: false`). The
# gate is deliberately NOT bindable from the environment — flipping it is a
# config-file decision an operator makes explicitly, not something a stray
# exported variable can do. To enable, set `llm.cloud.enabled: true` in
# config.yaml AND supply the relevant provider key above.