.env.example

# Hecate runtime
# Copy to `.env` when you want local overrides or secrets. `just dev` sources
# `.env` when present, but a clean checkout can run without one.

# Server
# This is the client-facing gateway address for Codex/Claude-style traffic.
# Provider BASE_URL values below are upstream model endpoints, not this gateway URL.
# Binds to loopback by default. Override to 0.0.0.0:8765 only when you
# also set HECATE_ALLOW_NON_LOOPBACK_BIND=1 and put a reverse proxy,
# firewall, or equivalent access-control layer in front of it.
# The Docker image overrides to 0.0.0.0 because the container's network
# is itself the boundary.
HECATE_ADDRESS=127.0.0.1:8765
HECATE_ALLOW_NON_LOOPBACK_BIND=0
# Browser requests must either come from the same host as the gateway or from
# one of these explicit origins. `just dev` supplies the Vite hot-reload origins
# automatically; set this for custom dev servers or reverse-proxy frontends.
# HECATE_ALLOWED_ORIGINS=http://127.0.0.1:5173,http://localhost:5173
# Optional shared runtime token for Hecate-native `/hecate/v1/*` control-plane
# APIs. Provider-compatible `/v1/*` inference endpoints and `/healthz` stay
# unchanged. Hecate-aware clients send it as `X-Hecate-Runtime-Token`; the
# operator UI reads `hecate.runtimeToken` from sessionStorage/localStorage when
# you enable this. Strongly recommended when binding beyond loopback with
# configured provider credentials.
# HECATE_RUNTIME_TOKEN=
# Optional shared token for provider-compatible inference ingress:
# GET /v1/models, POST /v1/chat/completions, and POST /v1/messages. Clients
# may send it as `Authorization: Bearer ...` or `x-api-key: ...`. It does not
# protect `/hecate/v1/*`, `/healthz`, or OTLP `/v1/traces|metrics|logs`.
# The operator UI reads `hecate.inferenceToken` from sessionStorage/localStorage
# when you enable this. Strongly recommended when exposing `/v1/*` beyond
# loopback with configured provider credentials.
# HECATE_INFERENCE_TOKEN=

# Optional client-facing URL written to `hecate.runtime.json` for helper
# processes such as `hecate-acp`. Leave empty for normal local dev; the gateway
# derives http://127.0.0.1:<port> from HECATE_ADDRESS. Set this when the listen
# address is not the URL clients should use, e.g. Docker or a reverse proxy.
# HECATE_PUBLIC_URL=http://127.0.0.1:8765

# Operator-facing name for this Hecate runtime host. The UI defaults to the
# machine hostname and shows this label in the status bar so a remote browser
# can tell where files, tasks, and External Agents are running.
# HECATE_RUNTIME_HOST_LABEL=MacBook

# DataDir is where the gateway puts auto-generated state. The runtime-host file
# stores the stable runtime ID here. The bootstrap file stores the generated
# settings encryption key here unless
# HECATE_BOOTSTRAP_FILE is set explicitly.
#
# Leave commented out unless you need to override:
#   - Local source dev (`just dev`, `just run`): defaults to `.data` —
#     relative to the repo root, gitignored.
#   - Docker (`docker compose up`): the image bakes in `/data` as the
#     mounted volume; setting this here would override that and break
#     the bootstrap-file path inside the container.
# HECATE_DATA_DIR=.data
HECATE_BOOTSTRAP_FILE=

# Storage backend for Hecate-owned state.
# memory | sqlite | postgres
# Local source dev defaults to memory. Docker overrides this to sqlite so the
# /data volume keeps settings, projects, runtime history, tasks, and chats.
# Hosted/cloud-runtime deployments can use postgres; set HECATE_POSTGRES_URL
# or DATABASE_URL below.
HECATE_BACKEND=memory

# Settings
HECATE_CONTROL_PLANE_KEY=control-plane
# Encryption key for persisted provider API keys. Leave empty to let the
# gateway auto-generate one on first run (also stored in the bootstrap
# file). Set explicitly to override.
HECATE_CONTROL_PLANE_SECRET_KEY=

# Providers
# `PROVIDER_<NAME>_*` env vars seed the runtime provider registry on
# boot and are also auto-imported into the persisted Providers tab so
# operators can see and manage them through the UI. On subsequent
# boots the auto-import skips any provider already present in the
# Providers tab, so operator edits made via the UI are never
# overwritten by environment values. Env vars are a first-boot
# convenience; the Providers tab is the source of truth thereafter.
# See docs/providers.md for the full lifecycle.
#
# For client integration recipes (Codex / Claude Code), see docs/client-integration.md.
#
# Built-in preset names:
#   anthropic, cohere, deepseek, fireworks, gemini, groq, huggingface, llamacpp, lmstudio, localai, mistral, nvidia, ollama, openai, perplexity, together_ai, xai, zai
#
# Runtime support today:
#   - OpenAI-compatible chat + /v1/models discovery
#   - Anthropic native Messages API + /v1/models discovery
#
# Model selection is not configured in env. Hecate discovers provider catalogs
# from provider APIs and stores operator-selected models in Connections / chat state.

# Cloud providers
PROVIDER_ANTHROPIC_API_KEY=

PROVIDER_COHERE_API_KEY=

PROVIDER_DEEPSEEK_API_KEY=

PROVIDER_FIREWORKS_API_KEY=

PROVIDER_GEMINI_API_KEY=

PROVIDER_GROQ_API_KEY=

PROVIDER_HUGGINGFACE_API_KEY=

PROVIDER_MISTRAL_API_KEY=

PROVIDER_NVIDIA_API_KEY=

PROVIDER_OPENAI_API_KEY=

PROVIDER_PERPLEXITY_API_KEY=

PROVIDER_TOGETHER_AI_API_KEY=

PROVIDER_XAI_API_KEY=

PROVIDER_ZAI_API_KEY=

# Local providers
# Set BASE_URL to configure local runtime endpoints.
PROVIDER_LLAMACPP_BASE_URL=http://127.0.0.1:8080/v1
PROVIDER_LMSTUDIO_BASE_URL=http://127.0.0.1:1234/v1
PROVIDER_LOCALAI_BASE_URL=http://127.0.0.1:8080/v1
PROVIDER_OLLAMA_BASE_URL=http://127.0.0.1:11434/v1

# Provider execution
HECATE_PROVIDER_MAX_ATTEMPTS=2
HECATE_PROVIDER_RETRY_BACKOFF=200ms
HECATE_PROVIDER_FAILOVER_ENABLED=true
HECATE_PROVIDER_HEALTH_FAILURE_THRESHOLD=3
HECATE_PROVIDER_HEALTH_COOLDOWN=30s
# Mark a provider `degraded` (route diagnostics surface it as
# `provider_slow`) when successful calls take at-or-above this duration.
# Degraded providers stay routable but lose to healthy peers in router
# scoring. 0 disables the latency tier; healthy/unhealthy is then driven
# only by the failure-threshold + cooldown above. See docs/providers.md.
HECATE_PROVIDER_HEALTH_LATENCY_DEGRADED_THRESHOLD=0

# Provider health history. Backs the event log behind
# GET /hecate/v1/providers/history (state transitions: success, slow_success,
# failure, cooldown_opened, cooldown_recovered, failover_triggered,
# failover_selected). _LIMIT is the default page size for the endpoint.
HECATE_PROVIDER_HISTORY_LIMIT=100

# Anthropic prompt-cache markers. When enabled (default), the Anthropic
# adapter auto-attaches `cache_control: {"type":"ephemeral"}` to the
# last `system` block and the last `tools` entry on every outbound
# Messages-API request. Anthropic then caches the static prefix
# (system instructions + tool catalog) and serves it back at ~10% of
# the fresh-input rate on subsequent requests in the same session.
# Long agent_loop runs and Hecate Chat threads see a 60-90% input-cost
# drop with no latency penalty — caller-supplied cache_control on
# message blocks is preserved untouched. Set to `false` to disable
# auto-marking for cost-tier comparisons or when debugging a
# suspected cache-related upstream issue. Caching never harms
# correctness; the toggle exists for cost analysis, not safety.
HECATE_PROVIDER_ANTHROPIC_CACHE_ENABLED=true

# Projects use the embedded Cairnline coordination store. There is no Projects
# backend selector or migration switch. Hecate keeps execution references,
# context snapshots, and runtime overlays in HECATE_BACKEND; portable project
# identity, work, roles, assignments, artifacts, handoffs, and approved project
# memory live in Cairnline's SQLite database under HECATE_DATA_DIR.

# Chat sessions
# Chat state lives in the storage backend selected by HECATE_BACKEND:
#   - regular chat sessions + messages
#   - external-adapter chat sessions + messages
#   - external-adapter approvals + grants
# When HECATE_BACKEND=sqlite or postgres, the gateway runs a startup reconcile
# pass that flips any pending approvals from a prior process to
# status=timed_out, path=startup_reconcile — process-local waiters can't be
# resurrected, so the operator UI is never shown stale "actionable" rows.

# Task runtime
# Task/run/step/artifact/approval/event state lives in HECATE_BACKEND.
# Comma-separated approval classes: shell_exec,git_exec,file_write,network_egress,read_file,all_tools
# Default gates shell, git, and file tasks. Operators who relied on git/file tasks
# running unattended must set this explicitly (e.g. shell_exec, or empty for no gates).
HECATE_TASK_APPROVAL_POLICIES=shell_exec,git_exec,file_write
HECATE_TASK_QUEUE_WORKERS=1
HECATE_TASK_QUEUE_BUFFER=128
HECATE_TASK_QUEUE_LEASE_SECONDS=30
# How often the periodic reconciler scans for runs stuck in "running"
# past 3× the lease duration and re-queues them automatically.
# Accepts Go duration strings (e.g. "30s", "1m"). Default 30s.
HECATE_TASK_RECONCILE_INTERVAL=30s
# 0 means unlimited.
HECATE_TASK_MAX_CONCURRENT_PER_TENANT=0
# Cap on agent_loop LLM round-trips per run. Runaway-cost safety net.
HECATE_TASK_AGENT_LOOP_MAX_MODEL_CALLS=8
# Optional exact executables for native read-only code intelligence. Empty
# discovers the allowlisted provider from the gateway's trusted global PATH.
# Values must be absolute regular executables outside the active project
# boundary. TypeScript requires the native TypeScript 7+ `tsc --lsp` build.
# Windows currently requires direct `.exe` paths and rejects command shims.
HECATE_CODEINTEL_GOPLS_PATH=
HECATE_CODEINTEL_TSC_PATH=
HECATE_CODEINTEL_AST_GREP_PATH=
# Optional native browser runtime for browser-enabled Hecate task presets.
# Set only an absolute Chromium-compatible executable path; empty disables it.
# This is local-runtime only and always approval-gated. Static browser evidence
# keeps scripts disabled; a separately granted browser interaction runs one
# fully declared exact-origin accessibility click/wait flow with scripts on.
# Neither is available to Hecate Chat or External Agents. One timeout spans
# preflight, browser startup, and capture or interaction.
# Hecate cancels after observing 4 MiB of response data; browser/socket buffers
# can already hold additional bytes when cancellation reaches Chromium.
HECATE_TASK_BROWSER_EXECUTABLE=
HECATE_TASK_BROWSER_TIMEOUT=20s
# Keep false unless browser-enabled preset origins intentionally resolve to a
# private/local address. This applies to static inspection and interaction and
# is not an OS-level browser network sandbox.
HECATE_TASK_BROWSER_ALLOW_PRIVATE_IPS=false
# Optional native `web_search` agent_loop tool. Empty provider keeps the tool
# out of the model catalog. Supported providers: brave, tavily, exa. Provider
# aliases BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, and EXA_API_KEY are accepted
# when HECATE_TASK_WEB_SEARCH_API_KEY is empty.
HECATE_TASK_WEB_SEARCH_PROVIDER=
HECATE_TASK_WEB_SEARCH_API_KEY=
HECATE_TASK_WEB_SEARCH_ENDPOINT=
HECATE_TASK_WEB_SEARCH_TIMEOUT=15s
HECATE_TASK_WEB_SEARCH_MAX_RESULTS=5
HECATE_TASK_WEB_SEARCH_SAFE_SEARCH=moderate
HECATE_TASK_WEB_SEARCH_COUNTRY=
HECATE_TASK_WEB_SEARCH_SEARCH_LANG=
# Cap on how many `mcp_servers` an agent_loop task may declare. Each
# entry produces one MCP client (subprocess for stdio, persistent
# connection for http) so this is a per-task resource ceiling, not a
# global one.
HECATE_TASK_MAX_MCP_SERVERS_PER_TASK=16
# Shared MCP client cache amortizes subprocess spawn cost across runs
# that share the same upstream config.
# _MAX_ENTRIES: distinct cached upstreams the cache holds at once;
# inserts at-or-over the cap evict the least-recently-used entry.
# _PING_INTERVAL: how often the cache proactively pings idle entries
# to detect wedged-but-alive subprocesses; 0 disables the loop.
# _PING_TIMEOUT: per-ping deadline; failure or timeout evicts.
HECATE_TASK_MCP_CLIENT_CACHE_MAX_ENTRIES=256
HECATE_TASK_MCP_CLIENT_CACHE_PING_INTERVAL=60s
HECATE_TASK_MCP_CLIENT_CACHE_PING_TIMEOUT=5s
# Global agent_loop system prompt — broadest layer of the three-layer
# composition (global → workspace CLAUDE.md|AGENTS.md → per-task).
# Empty disables the global layer; the others still apply.
HECATE_TASK_AGENT_SYSTEM_PROMPT=

# External-adapter approval mode (Codex / Claude Code / Cursor Agent).
# One of:
#   prompt — ask the operator (default; safe).
#   auto   — auto-approve every adapter RequestPermission. Danger mode
#            kept for batch / CI / smoke runs. Logged at WARN on startup.
#   deny   — auto-reject every adapter RequestPermission. Audit /
#            compliance.
# In prompt mode, approval requests appear in Chats and can also be
# resolved through the Agent Chat approval REST endpoints. If nobody
# resolves the request before the timeout below, the adapter receives
# ACP Cancelled. Operators who depend on headless auto-approve behavior
# must set this to `auto` explicitly.
HECATE_AGENT_ADAPTER_APPROVAL_MODE=prompt
# How long a pending approval waits before resolving to ACP Cancelled.
# Accepts Go duration strings (e.g. "5m", "30s"). Default 5m.
HECATE_AGENT_ADAPTER_APPROVAL_TIMEOUT=5m
# ACP terminal callbacks for External Agents. Off by default because
# terminal/create runs a command in the selected workspace. When enabled,
# terminal/create is approval-gated before spawn. Remote runtime mode also
# requires HECATE_REMOTE_ALLOW_ACP_TERMINALS=1.
HECATE_AGENT_ADAPTER_TERMINALS=false
HECATE_REMOTE_ALLOW_ACP_TERMINALS=false
# Per-session turn ceiling for chat sessions. 0 = unlimited (default).
# When exceeded, POST /hecate/v1/chat/sessions/{id}/messages returns HTTP 422
# with code "chat.session_limit_exceeded".
HECATE_CHAT_MAX_TURNS_PER_SESSION=0
# Optional wall-clock ceiling for an chat session. 0s = unlimited
# (default). When exceeded, POST /hecate/v1/chat/sessions/{id}/messages returns
# HTTP 422 with code "chat.session_duration_limit_exceeded".
HECATE_CHAT_MAX_SESSION_DURATION=0s
# Optional idle auto-close timeout for chat sessions. 0s disables the
# sweeper and request-time idle guard (default). When exceeded before a sweep,
# POST /hecate/v1/chat/sessions/{id}/messages returns HTTP 422 with code
# "chat.session_idle_timeout"; the sweeper closes stale sessions as
# cancelled.
HECATE_CHAT_IDLE_TIMEOUT=0s
# Optional override for Hecate-managed ACP launcher scripts used by Codex /
# Claude Code when direct adapter binaries are not on PATH. Empty uses the
# platform user-cache location.
HECATE_AGENT_ADAPTERS_DIR=
# Rate limiting — process-local token bucket on /v1/chat/completions
# and /v1/messages. Off by default. When enabled, every response
# (allowed or 429) carries X-RateLimit-Limit / X-RateLimit-Remaining /
# X-RateLimit-Reset. In the single-user no-auth runtime, requests share
# the same local-operator bucket. See docs/runtime-api.md
# "Rate-limit headers" for shape.
HECATE_RATE_LIMIT_ENABLED=false
HECATE_RATE_LIMIT_RPM=60
# 0 falls back to RPM (one minute's worth of refill as the burst).
HECATE_RATE_LIMIT_BURST=0

# agent_loop `http_request` tool — outbound HTTP from agents.
# Defaults are conservative; broaden by config.
HECATE_TASK_HTTP_TIMEOUT=30s
HECATE_TASK_HTTP_MAX_RESPONSE_BYTES=262144
# Block private IPs (10/8, 172.16/12, 192.168/16, loopback, link-local).
# Set to true to permit agents to reach internal sidecars / the gateway's
# own admin API. Document the threat model before flipping this on.
HECATE_TASK_HTTP_ALLOW_PRIVATE_IPS=false
# Comma-separated allowlist of exact hostnames the agent can reach.
# Empty = all public hosts allowed. No subdomain wildcarding.
HECATE_TASK_HTTP_ALLOWED_HOSTS=

# Sandbox per-call output cap (Layer 1 defensive hardening).
# Applied to each shell / git / file subprocess the gateway spawns.
# Combined stdout+stderr cap per command (bytes). Commands that exceed
# this limit are killed and return an error. 0 disables the cap.
# Default: 4 MiB. See docs/sandbox.md.
HECATE_TASK_MAX_OUTPUT_BYTES=4194304
#
# CPU / file-descriptor / address-space caps are not configured here —
# RLIMIT_* applied per-call would shrink the long-running gateway
# itself. Run the gateway under systemd (CPUQuota=, LimitNOFILE=,
# MemoryMax=) or in a container (docker run --cpus= --memory=) to cap
# the gateway and every subprocess it spawns.

# Layer 2 (OS-level isolation via bwrap / sandbox-exec) is auto-detected
# at gateway startup — no env var. On Linux it activates when
# /usr/bin/bwrap is present and a probe call succeeds; on macOS it is
# always active (sandbox-exec ships on every macOS install). The active
# mode is logged at startup and exposed on /healthz under
# sandbox.os_isolation. See docs/sandbox.md for the layer model.

# Shell network egress — applies to shell_exec / git_exec when a
# task has SandboxNetwork=true. The default deny-all gate stays in
# force when SandboxNetwork=false; these only refine WHICH
# destinations are reachable when network IS allowed. Same semantics
# as the http_request knobs above; best-effort static URL parsing,
# clever obfuscation can bypass.
HECATE_TASK_SHELL_ALLOW_PRIVATE_IPS=false
HECATE_TASK_SHELL_ALLOWED_HOSTS=

# Governance / usage tracking
HECATE_DENY_ALL=false
HECATE_MAX_PROMPT_TOKENS=64000
HECATE_MODEL_REWRITE_TO=
HECATE_ROUTE_MODE=any
HECATE_ALLOWED_PROVIDERS=
HECATE_DENIED_PROVIDERS=
HECATE_ALLOWED_MODELS=
HECATE_DENIED_MODELS=
HECATE_ALLOWED_PROVIDER_KINDS=
HECATE_USAGE_HISTORY_LIMIT=20

# Retention
HECATE_RETENTION_ENABLED=false
HECATE_RETENTION_INTERVAL=15m
HECATE_RETENTION_TRACES_MAX_AGE=24h
HECATE_RETENTION_TRACES_MAX_COUNT=2000
HECATE_RETENTION_USAGE_EVENTS_MAX_AGE=720h
HECATE_RETENTION_USAGE_EVENTS_MAX_COUNT=200
HECATE_RETENTION_AUDIT_EVENTS_MAX_AGE=720h
HECATE_RETENTION_AUDIT_EVENTS_MAX_COUNT=500
# Provider health history rows accumulate one per state transition per
# provider (success/failure/cooldown/failover). The sweep deletes rows
# older than MAX_AGE and trims to the most-recent MAX_COUNT globally.
HECATE_RETENTION_PROVIDER_HISTORY_MAX_AGE=168h
HECATE_RETENTION_PROVIDER_HISTORY_MAX_COUNT=10000
# `model.call.completed` events are emitted once per LLM round-trip,
# so a long agent run accumulates them quickly. The sweep deletes model-call
# rows older than MAX_AGE, then trims to the most-recent MAX_COUNT
# globally. Other event types (run.started/finished, approval.*) are
# never touched. Set MAX_COUNT=0 to disable the count cap (TTL only).
HECATE_RETENTION_MODEL_CALL_EVENTS_MAX_AGE=168h
HECATE_RETENTION_MODEL_CALL_EVENTS_MAX_COUNT=100000
# External-adapter approval history. Only RESOLVED rows are pruned;
# pending rows are caller state, not history, and stay until the
# startup reconcile pass flips them. Operator-authored grants are
# NEVER pruned by this subsystem — only their own ExpiresAt drives
# deletion (operator intent outlives normal retention windows).
HECATE_RETENTION_CHAT_APPROVALS_MAX_AGE=720h
HECATE_RETENTION_CHAT_APPROVALS_MAX_COUNT=10000

# OpenTelemetry
HECATE_OTEL_SERVICE_NAME=hecate
HECATE_OTEL_SERVICE_VERSION=
HECATE_OTEL_SERVICE_INSTANCE_ID=
HECATE_OTEL_DEPLOYMENT_ENVIRONMENT=
# Optional shared OTLP settings. When set, Hecate derives per-signal HTTP
# endpoints as /v1/traces, /v1/metrics, and /v1/logs. With grpc transport,
# the same host:port endpoint is used for every enabled signal.
HECATE_OTEL_ENDPOINT=
HECATE_OTEL_HEADERS=
HECATE_OTEL_TIMEOUT=5s
HECATE_OTEL_TRANSPORT=http
HECATE_OTEL_TRACES_ENABLED=false
HECATE_OTEL_TRACES_ENDPOINT=
HECATE_OTEL_TRACES_HEADERS=
HECATE_OTEL_TRACES_TIMEOUT=5s
HECATE_OTEL_TRACES_TRANSPORT=http
HECATE_OTEL_TRACES_SAMPLER=parentbased_always_on
HECATE_OTEL_TRACES_SAMPLER_ARG=1.0
HECATE_OTEL_METRICS_ENABLED=false
HECATE_OTEL_METRICS_ENDPOINT=
HECATE_OTEL_METRICS_HEADERS=
HECATE_OTEL_METRICS_TIMEOUT=5s
HECATE_OTEL_METRICS_TRANSPORT=http
HECATE_OTEL_METRICS_INTERVAL=30s
# Optional SDK exemplar filter for trace-from-metric pivots in supporting backends:
# trace_based (default), always_on, or always_off.
HECATE_OTEL_METRICS_EXEMPLAR_FILTER=trace_based
HECATE_OTEL_LOGS_ENABLED=false
HECATE_OTEL_LOGS_ENDPOINT=
HECATE_OTEL_LOGS_HEADERS=
HECATE_OTEL_LOGS_TIMEOUT=5s
HECATE_OTEL_LOGS_TRANSPORT=http

# Trace body capture — when true, the gateway records (redacted)
# request and response bodies as span attributes. Off by default
# because bodies can be large and include PII. See docs/telemetry.md
# for the redaction rules and where the bodies surface.
HECATE_TRACE_BODIES=false
# Per-body cap when capture is on. Bodies past this limit are
# truncated with an ellipsis marker on the span attribute.
HECATE_TRACE_BODY_MAX_BYTES=4096

# SQLite — single-file durable store. One file is shared across every
# Hecate-owned durable subsystem when HECATE_BACKEND=sqlite. Parent directory
# auto-created. Pure-Go driver, no CGO needed.
#
# Leave SQLITE_PATH commented unless overriding (same logic as
# HECATE_DATA_DIR above): source dev defaults to `.data/hecate.db`,
# the docker image bakes in `/data/hecate.db`.
# HECATE_SQLITE_PATH=.data/hecate.db
HECATE_SQLITE_TABLE_PREFIX=hecate
HECATE_SQLITE_BUSY_TIMEOUT=5s

# Postgres — hosted/cloud-runtime durable store. One database connection is
# shared across every Hecate-owned durable subsystem when
# HECATE_BACKEND=postgres. Keep DSNs in a secret manager; they often contain
# credentials.
# HECATE_POSTGRES_URL=postgres://hecate:hecate@localhost:5432/hecate?sslmode=disable
# DATABASE_URL can be used instead of HECATE_POSTGRES_URL.
HECATE_POSTGRES_TABLE_PREFIX=hecate
HECATE_POSTGRES_MAX_OPEN_CONNS=10
HECATE_POSTGRES_MAX_IDLE_CONNS=5

# Logging
LOG_LEVEL=INFO