.env.example

# agentloom dev stack overrides.
#
# Copy this file to .env to override the docker-compose.yml defaults shown
# below (Compose auto-loads .env from the project root). .env is gitignored —
# never commit it. These are throwaway local-dev values only; deployed
# environments configure credentials out-of-band (env/secret manager).

# Postgres credentials and database name.
POSTGRES_USER=agentloom
POSTGRES_PASSWORD=agentloom
POSTGRES_DB=agentloom

# Host ports the services are published on. Change these if they clash with
# a Postgres/Redis instance already running on your machine. AGENTLOOM_API_PORT
# is where the `app` profile (make up-app) publishes the api server.
# AGENTLOOM_REDIS_CHAOS_PORT publishes the dedicated chaos Redis the
# sustained chaos suite restarts mid-test (ticket 5.8) — separate so the
# blip never disturbs the shared test Redis.
AGENTLOOM_POSTGRES_PORT=5432
AGENTLOOM_REDIS_PORT=6379
AGENTLOOM_REDIS_CHAOS_PORT=6380
AGENTLOOM_API_PORT=8080

# Host interface the api port binds to (ticket 6.2). Loopback by default —
# a dev stack carrying a bootstrap credential shouldn't listen on all
# interfaces. Set 0.0.0.0 to expose it deliberately.
#AGENTLOOM_API_BIND=127.0.0.1

# Connection strings for the Go tooling. The Makefile auto-loads this file,
# so `make migrate-up` / `make test-integration` see these too — keep them in
# sync with the credentials and ports above when you change either.
# AGENTLOOM_POSTGRES_DSN: target of cmd/migrate (make migrate-up/down).
# AGENTLOOM_TEST_POSTGRES_DSN: admin DSN the integration-test harness uses to
# create and drop its per-test databases.
# AGENTLOOM_REDIS_ADDR: Redis address for the agentloom binaries themselves;
# AGENTLOOM_TEST_REDIS_ADDR: the deliberately separate address the
# integration tests use, so re-pointing dev tools never redirects tests.
# AGENTLOOM_TEST_CHAOS_REDIS_ADDR: the dedicated chaos Redis the sustained
# chaos suite connects to (and restarts) — keep it pointing at the
# redis-chaos compose service, never at a Redis anything else uses.
AGENTLOOM_POSTGRES_DSN=postgres://agentloom:agentloom@localhost:5432/agentloom?sslmode=disable
AGENTLOOM_TEST_POSTGRES_DSN=postgres://agentloom:agentloom@localhost:5432/agentloom?sslmode=disable
AGENTLOOM_REDIS_ADDR=localhost:6379
AGENTLOOM_TEST_REDIS_ADDR=localhost:6379
AGENTLOOM_TEST_CHAOS_REDIS_ADDR=localhost:6380

# Queue key names (ADR-005 defaults shown). Overriding exists for test
# isolation — the crash-recovery suite runs real worker processes against
# per-test keys — not for production sharding.
#AGENTLOOM_QUEUE_STREAM=steps:ready
#AGENTLOOM_QUEUE_GROUP=workers
#AGENTLOOM_QUEUE_DELAYED_KEY=sched:delayed

# Queue consumer tuning (ADR-005 tuning table; defaults shown). BATCH is the
# XREADGROUP COUNT (and the per-tick XAUTOCLAIM bound); BLOCK is the
# XREADGROUP BLOCK timeout (a Go duration) and also bounds consumer shutdown
# latency.
#AGENTLOOM_QUEUE_CONSUMER_BATCH=16
#AGENTLOOM_QUEUE_CONSUMER_BLOCK=5s

# Lease machinery (ADR-005 tuning table; defaults shown). LEASE_TTL is the
# XAUTOCLAIM min-idle threshold — a PEL entry idle longer than this is an
# expired lease. HEARTBEAT_INTERVAL and RECLAIM_INTERVAL default to derived
# values (LEASE_TTL/3 and LEASE_TTL/2) when unset, preserving the
# two-missed-beats-precede-expiry margin under a TTL-only override.
# POISON_THRESHOLD is the delivery count above which an entry is diverted to
# the poison path. The janitor deletes consumer records with an empty PEL
# idle beyond JANITOR_IDLE_THRESHOLD, every JANITOR_INTERVAL.
#AGENTLOOM_QUEUE_LEASE_TTL=30s
#AGENTLOOM_QUEUE_HEARTBEAT_INTERVAL=10s
#AGENTLOOM_QUEUE_RECLAIM_INTERVAL=15s
#AGENTLOOM_QUEUE_POISON_THRESHOLD=5
#AGENTLOOM_QUEUE_JANITOR_INTERVAL=10m
#AGENTLOOM_QUEUE_JANITOR_IDLE_THRESHOLD=1h

# Delayed delivery (ADR-005 tuning table; default shown). PROMOTER_TICK is
# the period between promotion passes moving due entries from the
# sched:delayed sorted set onto the ready stream; delayed delivery serves
# backoffs and timeouts measured in seconds-to-days, so sub-second
# precision buys nothing.
#AGENTLOOM_QUEUE_PROMOTER_TICK=1s

# Stream retention (ADR-005; default shown). TRIM_INTERVAL is the period
# between XTRIM passes removing entries the consumer group has delivered
# and acked (XACK clears the lease ledger, not the stream). Pending and
# undelivered entries are never trimmed; retention is a memory concern,
# not correctness.
#AGENTLOOM_QUEUE_TRIM_INTERVAL=1m

# Worker deployable (cmd/worker; default shown). HEALTH_INTERVAL is the
# period between health log lines (worker liveness + stream depth + PEL
# size).
#AGENTLOOM_WORKER_HEALTH_INTERVAL=1m

# Depth-gauge sampling (ticket 7.2): how often the worker samples queue
# ready depth / stream length / PEL size / delayed count, the outbox
# backlog, and the active-consumer count into its Prometheus gauges.
# Only used when AGENTLOOM_OBS_METRICS_ADDR is set; the default bounds
# gauge staleness to ~10s.
#AGENTLOOM_WORKER_METRICS_SAMPLE_INTERVAL=10s

# Test executors (ticket 6.2). The binary's default is false — the
# filesystem-writing test executors (counter, effectful_echo) append to
# arbitrary submitter-chosen paths, so production workers don't register
# them. docker-compose.yml overrides this to true for the dev stack (the
# crash demo's fixtures need them); set false here to try the hardened
# registry locally.
#AGENTLOOM_WORKER_TEST_EXECUTORS=true

# API deployable (cmd/api; defaults shown). ADDR is the listen address;
# the read/write/idle timeouts bound one connection's lifecycle;
# SHUTDOWN_TIMEOUT bounds the graceful drain on SIGINT/SIGTERM.
#AGENTLOOM_API_ADDR=:8080
# TEST_EXECUTORS mirrors the worker knob for the GET /v1/plugins catalog
# (ticket 8.1, ADR-009): set both alike so the listing matches what the
# fleet executes. docker-compose.yml ties it to the worker's value.
#AGENTLOOM_API_TEST_EXECUTORS=true
#AGENTLOOM_API_READ_TIMEOUT=10s
#AGENTLOOM_API_WRITE_TIMEOUT=30s
#AGENTLOOM_API_IDLE_TIMEOUT=2m
#AGENTLOOM_API_SHUTDOWN_TIMEOUT=15s

# Telemetry (ticket 7.1, ADR-008; defaults shown — everything off).
# METRICS_ADDR starts the admin listener serving /metrics and /healthz;
# empty means no listener (docker-compose.yml sets :9090 in-network for
# the app services). OTEL_ENABLED turns on OTLP trace export to
# OTEL_ENDPOINT — `make up-obs` sets it for the compose stack, where the
# endpoint is jaeger:4317. SAMPLE_RATIO is the ParentBased ratio in
# (0, 1].
#AGENTLOOM_OBS_METRICS_ADDR=
#AGENTLOOM_OBS_OTEL_ENABLED=false
#AGENTLOOM_OBS_OTEL_ENDPOINT=localhost:4317
#AGENTLOOM_OBS_OTEL_INSECURE=true
#AGENTLOOM_OBS_OTEL_SAMPLE_RATIO=1.0
# PPROF_ENABLED mounts net/http/pprof on the admin listener
# (GET /debug/pprof/...) for load-test profiling (ticket 19.x). Off by
# default; the load overlay (docker-compose.load.yml) turns it on. The
# admin port is in-network only, so the profiles are never host-reachable.
#AGENTLOOM_OBS_PPROF_ENABLED=false

# Host ports the obs profile (make up-obs) publishes its UIs on, loopback
# by default: Prometheus, Grafana, and the Jaeger UI.
#AGENTLOOM_PROMETHEUS_PORT=9090
#AGENTLOOM_GRAFANA_PORT=3000
#AGENTLOOM_JAEGER_PORT=16686

# API root key (tickets 6.1/6.2, ADR-007): the bootstrap admin credential.
# Every /v1 route requires a scoped bearer key, so a fresh stack needs this
# to mint its first real key. Generate your own sk_-shaped value, e.g.
#   printf 'sk_%s\n' "$(openssl rand 32 | basenc --base64url | tr -d '=')"
# then use it to `ctl keys create` a real admin key and unset this. It is
# a secret — never commit a real value, this file included.
#AGENTLOOM_API_ROOT_KEY=

# Run event WebSocket ticket signing (ticket 16.3, ADR-018). The API mints a
# short-lived signed ticket at POST /v1/runs/{id}/ws-ticket that the browser
# passes to GET /v1/runs/{id}/ws (keeping long-lived keys out of URLs). Empty
# secret = a random per-process secret is generated at boot: fine for a single
# instance, but a multi-replica deployment must set a shared value so a ticket
# minted on one replica is accepted on another. It is a secret — never commit a
# real value. TTL is clamped to [5s, 1h]; default 60s.
#AGENTLOOM_API_WS_TICKET_SECRET=
#AGENTLOOM_API_WS_TICKET_TTL=60s

# Cross-origin WebSocket allowlist (ticket 18.1, ADR-018). The M18 dashboard
# runs on its own origin and dials the API's /ws endpoints directly (a Next.js
# proxy cannot forward an upgrade), so its host must be allowlisted here. A
# comma-separated list of host patterns (a `*` wildcard is supported). Empty =
# same-host upgrades only (the pre-18.1 behaviour); compose defaults it to the
# local dev origins. The API key never rides the upgrade — a proxy-minted
# ws-ticket is the credential.
#AGENTLOOM_API_WS_ORIGINS=localhost:*,127.0.0.1:*

# Model provider API keys (tickets 8.3/8.4, ADR-009). Empty = provider
# unconfigured; the stack boots fine without either. Compose passes these
# to both the api service (so GET /v1/plugins lists the provider) and the
# worker (which routes llm steps to it from 8.6) — set them here to keep
# both in sync. Secrets — never commit real values.
#AGENTLOOM_ANTHROPIC_API_KEY=
#AGENTLOOM_OPENAI_API_KEY=

# Mock provider (ticket 8.5): a deterministic, offline, keyless provider
# addressed as model "mock/...". Compose defaults it on (true) so llm
# steps run reproducibly in CI/demos without a real key; set false to
# drop it from the fleet. The binaries default off.
#AGENTLOOM_LLM_MOCK_ENABLED=true

# Optional mock script (ticket 14.5): scripted matching rules + response
# sequences that replace the mock's echo, so an offline run drives real
# behavior — e.g. the flagship example's writer⇄critic loop, which only
# iterates when the critic returns a scripted revise verdict. Inline JSON,
# or point AGENTLOOM_LLM_MOCK_SCRIPT_FILE at a file (mutually exclusive).
# Empty = echo-only. `make demo-research` sets the inline form for you.
#AGENTLOOM_LLM_MOCK_SCRIPT=
#AGENTLOOM_LLM_MOCK_SCRIPT_FILE=

# Built-in tools (ticket 8.7, ADR-009). http_request's allowlist is the
# SSRF guard: an empty allowlist (the default) denies every host, so
# http_request is inert until you name the hosts it may reach here
# (comma-separated; a bare host allows any port, "host:port" pins one).
# The worker enforces these; json_transform needs no config. The compose
# worker leaves the allowlist empty by default — set it to opt hosts in.
#AGENTLOOM_TOOLS_HTTP_ALLOWLIST=api.example.com,news.example.com:8443
#AGENTLOOM_TOOLS_HTTP_TIMEOUT=30s
#AGENTLOOM_TOOLS_HTTP_MAX_RESPONSE_BYTES=1048576

# Approval-notification webhook (ticket 15.5, ADR-017). OPTIONAL and off by
# default. When AGENTLOOM_NOTIFY_WEBHOOK_URL is set, a parked human_approval
# step POSTs a signed (HMAC-SHA256) notification to it — best-effort (a
# webhook failure never affects run correctness) and effectively-once via the
# side-effect journal. The secret is REQUIRED when a URL is set (an unsigned
# webhook cannot be authenticated); the receiver verifies the
# X-Agentloom-Signature ("v1=<hex>") over "<X-Agentloom-Timestamp>.<body>" and
# may dedupe on X-Agentloom-Delivery-Id (the approval id). Only the worker
# reads these.
#AGENTLOOM_NOTIFY_WEBHOOK_URL=https://hooks.example.com/agentloom/approvals
#AGENTLOOM_NOTIFY_WEBHOOK_SECRET=change-me
#AGENTLOOM_NOTIFY_WEBHOOK_TIMEOUT=5s
#AGENTLOOM_NOTIFY_WEBHOOK_MAX_ATTEMPTS=3

# Fleet-wide resource limits (ticket 9.1, ADR-010). The named external
# resources whose request/token throughput the worker fleet governs across
# all processes. Supply the JSON either inline (AGENTLOOM_RESOURCES) or as a
# file path (AGENTLOOM_RESOURCES_FILE) — exactly one, never both. Unset =
# every resource unlimited (limits are protective opt-in; an unknown
# resource is not throttled). A resource is named "<provider>:<model>" by
# the resolved provider ("anthropic:claude-sonnet-5", "mock:sim-1") or
# "tool:<name>"; "<provider>:*" limits every model of a provider. Each limit
# is per-minute with an optional burst ceiling. The 9.2 middleware enforces
# these at the worker: before a cost-bearing step's provider call it acquires
# the resource's request+token buckets; a denial defers the step (throttle →
# delayed requeue, no failure), an impossible request perm-fails, a Redis
# error fails open.
#AGENTLOOM_RESOURCES={"resources":[{"name":"anthropic:claude-sonnet-5","requests":{"per_minute":60},"tokens":{"per_minute":200000,"burst":400000}},{"name":"openai:*","requests":{"per_minute":120}}]}
#AGENTLOOM_RESOURCES_FILE=/etc/agentloom/resources.json
# Redis key namespace for the resource buckets (test-isolation knob).
#AGENTLOOM_RESOURCES_KEY_PREFIX=ratelimit:resource
# Throttle requeue math (ADR-010): a rate-limited step's re-dispatch delay is
# clamp(retry_after, floor, cap) plus additive jitter of up to jitter_frac ×
# the clamped delay. Floor guards a hot requeue loop; cap bounds the wait.
#AGENTLOOM_RESOURCES_THROTTLE_FLOOR=500ms
#AGENTLOOM_RESOURCES_THROTTLE_CAP=5m
#AGENTLOOM_RESOURCES_THROTTLE_JITTER_FRAC=0.20

# Response cache (ticket 9.5, ADR-011). The worker's read-through/write-through
# middleware ahead of the rate limiter: identical deterministic steps (a
# temperature=0 llm call, a pure tool) hit the cache and skip the provider and
# the limiter entirely. Enabled by default (the worker already needs Redis; the
# API never reads the cache, so ADR-002 is untouched). Set ENABLED=false to run
# every step uncached. KEY_PREFIX is the Redis namespace (and the bust-by-prefix
# root); DEFAULT_TTL applies to an opted-in step with no cache.ttl (≤ 30d);
# MAX_VALUE_BYTES skips (does not store) an oversized value.
#AGENTLOOM_CACHE_ENABLED=true
#AGENTLOOM_CACHE_KEY_PREFIX=cache
#AGENTLOOM_CACHE_DEFAULT_TTL=24h
#AGENTLOOM_CACHE_MAX_VALUE_BYTES=1048576

# Event pub/sub publish path (ticket 16.2, ADR-018). After a transaction
# commits, the worker and API fan the new event envelopes out to Redis pub/sub
# best-effort — a per-run channel `<prefix>:run:{id}` and a firehose
# `<prefix>:firehose` — the low-latency delivery hint under the durable Postgres
# event log. A publish failure or a full buffer never affects the engine
# transaction; consumers dedupe/order by (run_id, seq) and heal any miss via a DB
# backfill. Enabled by default (both deployables already reach Redis; a down
# Redis just degrades the hint, ADR-002 holds). Set ENABLED=false to run with
# only the durable log. Tail a run with `redis-cli SUBSCRIBE events:run:<id>`.
#AGENTLOOM_EVENTS_PUBSUB_ENABLED=true
#AGENTLOOM_EVENTS_CHANNEL_PREFIX=events
#AGENTLOOM_EVENTS_PUBLISH_BUFFER=1024
#AGENTLOOM_EVENTS_PUBLISH_TIMEOUT=2s

# Pricing catalog (ticket 10.1, ADR-012). The worker's M10 cost model prices
# LLM attempts and priced tools against a versioned $/1M-token catalog keyed by
# the ADR-010 resource name (<provider>:<model>, <provider>:*, tool:<name>).
# Embedded defaults (incl. a mock:* wildcard) work with no configuration; an
# operator override is merged onto them by resource name — supply it inline
# (AGENTLOOM_PRICING) or as a file path (AGENTLOOM_PRICING_FILE), exactly one,
# never both. UNKNOWN_MODEL_POLICY governs a model with no catalog entry:
# `estimate` (default) prices it at the catalog fallback rate and emits a
# cost_unknown_model warning event; `fail` blocks it pre-flight (permanent).
#AGENTLOOM_PRICING={"schema_version":1,"models":[{"name":"anthropic:claude-sonnet-5","effective_from":"2025-08-01","input_per_mtok":3.0,"output_per_mtok":15.0}],"fallback":{"input_per_mtok":30.0,"output_per_mtok":60.0}}
#AGENTLOOM_PRICING_FILE=/etc/agentloom/pricing.json
#AGENTLOOM_COST_UNKNOWN_MODEL_POLICY=estimate

# ctl CLI (cmd/ctl). Base URL of the api server `ctl submit`/`ctl watch`
# talk to; --api overrides per invocation. AGENTLOOM_API_KEY is the bearer
# credential ctl presents on every request (submit needs the submit scope,
# watch needs read, keys needs admin); --key overrides per invocation.
#AGENTLOOM_API_URL=http://localhost:8080
#AGENTLOOM_API_KEY=

# Load environment (ticket 19.1). Consumed only by docker-compose.load.yml
# via `make load-up` (docs/load/plan.md). AGENTLOOM_LOAD_WORKERS scales the
# worker fleet (default 8); AGENTLOOM_LOAD_OTEL turns OTel trace export on
# under load (off by default — sampling overhead confounds CPU profiles).
#AGENTLOOM_LOAD_WORKERS=8
#AGENTLOOM_LOAD_OTEL=false