.env.example

# Terrence — Environment Configuration
#
# Copy this to .env and adjust for your deployment.
# Terrence runs without any environment variables set (development defaults).
# The variables below enable specific features.

# ── Required for production ──────────────────────────────────
# NODE_ENV=production
# PUBLIC_URL=https://terraform.example.com

# ── Authentication ───────────────────────────────────────────
# Bootstrap an initial admin account on first start.
# Password must be at least 10 characters.
# ADMIN_PASSWORD=change-me-to-something-secure
# Solo-admin recovery: with ADMIN_PASSWORD set, reset the named site-admin
# account at boot and force a password change at next login. Anything else
# (flag unset, unknown or non-admin user) leaves the instance untouched.
# One-shot per distinct password: a consumed marker in storage makes a
# repeated identical configuration a no-op. Remove both variables after
# a successful recovery.
# TERRENCE_ADMIN_PASSWORD_RESET=1

# One-time bootstrap secret for POST /admin/initial-admin-user.
# IACT_TOKEN=
# The reference installer's ?token= query form is OPT-IN (default is the
# header-only flow: X-IACT-Token or Authorization: Bearer). Enable only if
# you use the reference installer, which cannot send headers.
# IACT_QUERY_TOKEN_ENABLED=0

# Enable local user registration via POST /api/v2/users.
# When unset (default), only ADMIN_PASSWORD bootstrap can create
# the first admin. Registration is opt-in.
# TERRENCE_ENABLE_LOCAL_SIGNUP=true

# ── Remote syslog (RFC 5424) ─────────────────────────────────
# Forward structured logs to a remote collector over UDP (RFC 5426) or
# TCP (RFC 6587, octet-counted). Unset disables remote shipping entirely.
#   TERRENCE_SYSLOG_TARGET=udp://logs.example.com:514
#   TERRENCE_SYSLOG_TARGETS=udp://logs.example.com:514,tcp://logs.example.com:601
# TERRENCE_SYSLOG_TARGETS takes precedence when set and non-empty; the singular
# TERRENCE_SYSLOG_TARGET is the single-destination fallback. Entries are
# separated by commas or newlines; invalid entries are ignored.
# TERRENCE_SYSLOG_TARGETS=
# TERRENCE_SYSLOG_TARGET=
# Independent level filter for the remote sink ("error"|"warn"|"info"|"debug").
# Defaults to LOG_LEVEL when unset — e.g. keep debug locally but ship warn+.
# TERRENCE_SYSLOG_LEVEL=warn
# Message shape: "rfc5424" (default, meta as dotted structured-data params)
# or "json" (the entry as a JSON message body, auto-extracted by Splunk and
# other json sourcetypes). Site Admin logging settings override when set.
# TERRENCE_SYSLOG_FORMAT=json
# Hostname reported in the syslog header. Defaults to /etc/hostname.
# TERRENCE_SYSLOG_HOSTNAME=terrence-prod-1
# App name reported in the syslog header. Default: terrence
# TERRENCE_SYSLOG_APP=terrence
# Site Admin logging settings override each of these values at runtime. The
# Site Admin enabled=false switch disables environment-configured sinks.

# ── Disaster recovery / maintenance ───────────────────────────
# Start UI and API without executing queued jobs. Pending runs stay
# queued; nothing is claimed or executed while this is set. Useful
# for draining a node or recovering a database. Ops equivalent of
# "drain mode": set it, start, inspect, then unset and restart.
# TERRENCE_DISABLE_WORKER=1

# Worker queue poll interval in milliseconds. Lower is snappier (runs
# start sooner) but queries the DB more often; raise it on low-power
# homelab boxes. Default 1500; invalid, empty, or sub-100ms values fall back to 1500.
# TERRENCE_WORKER_POLL_MS=1500
# Auto-destroy scan interval (default 30000; minimum 5000). Runs on its own
# cadence so the fast queue poll never pays for the full-table sweep.
# TERRENCE_AUTO_DESTROY_POLL_MS=30000
# Health-assessment discovery interval (default 60000; minimum 5000).
# TERRENCE_ASSESSMENT_POLL_MS=60000
# Shutdown drain grace: how long SIGTERM waits for in-flight executions
# before checkpointing (default 6000; maximum 25000).
# TERRENCE_DRAIN_GRACE_MS=6000
# Parallel local runs (default 5).
# TERRENCE_RUN_CONCURRENCY=5
# Retention for saved plans (default 7 days). Interrupted-apply recovery
# copies are kept until recovered and never time-pruned.
# TERRENCE_RECOVERY_RETENTION_MS=604800000
# TERRENCE_VERSION_CACHE_TTL_MS=86400000 (how long fetched tofu/terraform
#   version lists are reused; the tofu path paginates the full GitHub release
#   history, so keep this long to avoid refetching after restarts; 0 never
#   reuses a cached list)
# Token for release enumeration (either name works). Behind shared IPs the
# unauthenticated GitHub rate budget burns through deep paging and binary
# downloads stall; setting a token raises the ceiling.
# GITHUB_TOKEN=
# Binary archive downloads (60-100 MiB): per-attempt timeout and retries.
# Raise the timeout on slow links; unknown versions fail fast without retrying.
# TERRENCE_BINARY_DOWNLOAD_TIMEOUT_MS=120000
# TERRENCE_BINARY_DOWNLOAD_RETRIES=2


# ── Database resilience ──────────────────────────────────────
# Postgres statement/lock/idle-in-transaction timeouts (milliseconds).
# Server-side fail-safes: a stuck query, contended lock, or idle
# transaction is killed and the pool connection recycled (todos 287/288).
# SQLite uses busy_timeout (5000ms) and WAL; these only affect Postgres.
# TERRENCE_DB_STATEMENT_TIMEOUT_MS=30000
# TERRENCE_DB_LOCK_TIMEOUT_MS=10000
# TERRENCE_DB_IDLE_IN_TRANSACTION_TIMEOUT_MS=60000
# Token-hash secret for multi-replica deployments. If unset, a 256-bit secret
# is generated once in STORAGE_DIR/.token-hash-secret.
# TERRENCE_TOKEN_HASH_SECRET=

# ── Audit & diagnostics ──────────────────────────────────────
# Record token minting, SSH key access, and sensitive variable reads in
# the audit log. Raw state downloads are always audited; this flag adds
# the especially-sensitive operations on top.
# AUDIT_STRICT=1
#
# Self-host diagnostics: bun run backend/scripts/doctor.ts checks kernel/
# sandbox support, storage, SQLite integrity, DNS, VCS/CA reachability,
# and config presence. --json for machine output, --fail to exit 1 on any
# failed check.

# ── Session & encryption ──────────────────────────────────────
# ENCRYPTION_PASSWORD=<stable-secret>

# ── CORS ─────────────────────────────────────────────────────
# CORS_ORIGIN=https://terraform.example.com

# ── VCS Integration (GitHub App) ─────────────────────────────
# GITHUB_APP_ID=
# GITHUB_APP_SLUG=
# GITHUB_APP_PRIVATE_KEY=
# GITHUB_WEBHOOK_SECRET=
# GITHUB_APP_HTTP_URL=https://github.com
# GITHUB_APP_API_URL=https://api.github.com
# OAuth client endpoint URLs must use HTTPS. This opt-in is honored only when
# NODE_ENV=development (and in tests); it is ignored otherwise. Never enable
# it in production.
# TERRENCE_ALLOW_INSECURE_OAUTH_URLS=false
# Allow configured VCS URLs to target private-network addresses. Off by
# default; enabling this permits private-network VCS requests and increases
# the risk of server-side request forgery. Use only in trusted environments.
# TERRENCE_ALLOW_PRIVATE_VCS_URLS=false

# ── Cost Estimation ──────────────────────────────────────────
# INFRACOST_ENABLED=true
# # API key for Infracost price lookups. Required when estimation is enabled;
# # without it breakdowns fail (the run itself still succeeds).
# INFRACOST_API_KEY=
# # Infracost version to run; managed on demand into <STORAGE_DIR>/binaries/infracost/<version>/
# INFRACOST_VERSION=0.10.45
# # Optional: absolute path override for the Infracost executable (used as-is
# # instead of the managed binary in INFRACOST_VERSION).
# INFRACOST_BINARY=/path/to/infracost

# ── Policy Checks (OPA / Sentinel) ─────────────────────────
# OPA version to run; managed on demand into <STORAGE_DIR>/binaries/opa/<version>/
# the first time a workspace with OPA policies runs (digest-verified).
# OPA_VERSION=1.20.2
# # Optional: absolute path override for the OPA executable (used as-is
# # instead of the managed binary; an override that resolves to nothing
# # reports the check unreachable, it never triggers a download).
# OPA_BINARY_PATH=/path/to/opa
# # Sentinel is proprietary with no public download, so it stays
# # bring-your-own: install it and point this at the binary (or put it on PATH).
# SENTINEL_BINARY_PATH=/path/to/sentinel

# ── Core server ──────────────────────────────────────────────
# HTTP listen port.
# PORT=3000
# Database connection. file: paths select SQLite; postgres:// or
# postgresql:// strings select the PostgreSQL backend.
# DATABASE_URL=file:./storage/terrence.db
# Directory for archives, state, binaries, and the version cache. Must persist.
# STORAGE_DIR=./storage
# Log verbosity (error|warn|info|debug). Site Admin logging settings can
# override it at runtime.
# LOG_LEVEL=info
# Public URL of the instance (webhook callbacks, redirects, registry host).
# PUBLIC_URL=https://terraform.example.com
# Secret for signed URL tokens (state downloads); generated into STORAGE_DIR
# when unset. Lifetime of signed download URLs in seconds (default 300).
# SIGNED_URL_SECRET=<stable-secret>
# SIGNED_URL_TTL_SECONDS=300

# ── System API ───────────────────────────────────────────────
# Administrative surface (node inventory, diagnostics, support bundles).
# Bound to loopback by default; set 0.0.0.0 only behind a loopback-only
# container publish (see docker-compose.yml). Non-loopback hosts require
# SYSTEM_API_TLS_CERT + SYSTEM_API_TLS_KEY.
# SYSTEM_API_HOST=127.0.0.1
# SYSTEM_API_PORT=8443
# SYSTEM_API_TLS_CERT=/path/to/cert.pem
# SYSTEM_API_TLS_KEY=/path/to/key.pem

# ── Run sandbox and execution ────────────────────────────────
# Run sandbox (Landlock, Linux >= 5.13). Unset means "sandbox required".
# Set to false to disable (see docker-compose.unsandboxed.yml for the
# explicit opt-out). Any other value, including "warn", leaves it required.
# TERRENCE_RUN_SANDBOX=false
# Run network policy (allow|deny). Default allow; deny blocks TCP bind/connect
# for run processes (needs Landlock ABI >= 4). TCP-only: UDP, DNS and other
# socket families are NOT restricted. Invalid values fail startup.
# TERRENCE_RUN_NET_POLICY=allow
# Executor backend selection (empty = default local executor).
# TERRENCE_EXECUTOR_BACKEND=
# Minimum Landlock ABI the health gate requires before advertising sandbox
# support (default: runner minimum).
# TERRENCE_SANDBOX_MIN_ABI=
# Path to the landlock runner binary (default: bundled build).
# TERRENCE_LANDLOCK_RUNNER=
# Agent binary self-update source (URL + expected SHA256 + version pin).
# TERRENCE_AGENT_UPDATE_URL=
# TERRENCE_AGENT_UPDATE_SHA256=
# TERRENCE_AGENT_UPDATE_VERSION=

# ── Outbound access and proxies ──────────────────────────────
# Extra hosts/CIDRs permitted to receive outbound VCS/registry/webhook
# traffic beyond the built-in private-address blocks.
# TERRENCE_OUTBOUND_ALLOW_HOSTS=
# TERRENCE_OUTBOUND_ALLOW_CIDRS=
# Allow outbound requests to private network addresses (default off).
# TERRENCE_ALLOW_PRIVATE_URLS=false
# Trust X-Forwarded-For from these proxy CIDRs (comma-separated).
# TERRENCE_TRUSTED_PROXY_CIDRS=
# Strict Content-Security-Policy for the served UI (default off).
# TERRENCE_CSP_STRICT=1

# ── Rate limits ──────────────────────────────────────────────
# Global API rate limit (requests per 1s window) when API rate limiting is
# enabled in Site Admin settings.
# RATE_LIMIT_MAX=60
# Sensitive-endpoint bucket (login, token mint, MFA).
# RATE_LIMIT_SENSITIVE_MAX=
# SSO login page bucket.
# RATE_LIMIT_SSO_GET_MAX=
# SCIM settings/mapping buckets.
# RATE_LIMIT_SCIM_SETTINGS_MAX=
# RATE_LIMIT_SCIM_MAPPING_MAX=
# Workspace run-history burst/duration buckets.
# RATE_LIMIT_WORKSPACE_RUN_HISTORY_MAX=
# RATE_LIMIT_WORKSPACE_RUN_HISTORY_DURATION_MS=

# ── More VCS ─────────────────────────────────────────────────
# GITLAB_WEBHOOK_SECRET=
# BITBUCKET_WEBHOOK_SECRET=

# ── Operations and clustering ──────────────────────────────────
# Node identity/address reported in readiness responses.
# TERRENCE_NODE_ID=terrence-node-1
# TERRENCE_NODE_ADDRESS=
# Override readiness status: draining or maintenance marks the node draining.
# TERRENCE_NODE_STATUS=
# Threshold for slow database query logging (default 1000).
# TERRENCE_DB_SLOW_QUERY_MS=1000
# Advertised TFE compatibility version (default 2.5.0; keep dotted).
# TERRENCE_COMPATIBILITY_VERSION=2.5.0
# Site-admin application token for tfectl admin commands.
# TFE_TOKEN=
# Application API address for tfectl (default http://localhost:3000).
# TFE_ADDRESS=
# System API address/token for tfectl (address defaults to the app host on 8443).
# TFE_SYSTEM_ADDRESS=
# TFE_SYSTEM_TOKEN=

# ── Compatibility surface ────────────────────────────────────
# Pinned TFE/TFP API versions advertised to clients (defaults track the
# supported provider release).
# TERRENCE_TFE_COMPATIBILITY_VERSION=
# TERRENCE_TFP_API_VERSION=
# Force regeneration of the provider surface catalog at startup.
# TERRENCE_PROVIDER_SURFACE_FORCE=1