Environment reference
Every TheSpider server environment variable
All server config is env-driven. Source of truth: server/src/http/env.ts, storage.ts, ai-adjudicator.ts.
Deployment & database
| Variable | Default | Req? | Purpose |
|---|---|---|---|
DEPLOYMENT_MODE | saas | – | onprem (single-org, license-gated) or saas (multi-tenant). |
DATABASE_URL | dev localhost | ✔ | Postgres connection string. BYO or the bundled postgres service. |
MIGRATE_ON_BOOT | 1 | – | Run Drizzle migrations at startup. 0 to skip. |
PORT | 8080 | – | Listen port (baked into the image). |
Licensing (on-prem)
| Variable | Default | Req? | Purpose |
|---|---|---|---|
LICENSE_JWT | – | on-prem | The signed license JWT. Absent ⇒ read-only. |
LICENSE_PUBLIC_KEY | embedded | – | base64url raw Ed25519 key overriding the embedded one (rotation). |
LICENSE_JWKS_URL | off | – | Opt-in JWKS rotation refresh. off/empty = fully air-gapped. |
ONPREM_ORG_SLUG | default | – | Slug of the single org created at first boot. |
ONPREM_ORG_NAME | On-Prem | – | Display name of that org. |
Telemetry
| Variable | Default | Purpose |
|---|---|---|
TELEMETRY | on | Daily+boot POST of version/usage-rollups/error-counts (never findings). off = zero outbound. |
TELEMETRY_URL | …/v1/telemetry | Where telemetry is sent when on. |
Auth & web
| Variable | Default | Req? | Purpose |
|---|---|---|---|
BETTER_AUTH_SECRET | dev secret | ✔ | Session signing secret. Set it (a warning is logged otherwise). |
BETTER_AUTH_URL | http://localhost:8080 | ✔* | Public URL (cookies / redirects / CSRF origin). Set to your real hostname. |
BETTER_AUTH_TRUSTED_ORIGINS | – | – | Extra comma-separated trusted origins. |
WEB_ROOT | /app/web (image) | – | Static SPA dir served same-origin. Set by the image; unset ⇒ API only. |
* required for any deployment users reach over a real hostname.
Storage
| Variable | Default | Purpose |
|---|---|---|
ARTIFACTS_DIR | .artifacts | On-disk artifact store (used when S3_BUCKET is unset). |
S3_BUCKET | – | Set to use S3-compatible object storage (MinIO/R2/S3) for artifacts. |
S3_ENDPOINT / S3_REGION | – | S3 endpoint / region. |
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY | – | S3 credentials. |
AI dedupe
| Variable | Default | Purpose |
|---|---|---|
AI_DEDUPE_API_KEY | – | BYO key enabling server-run AI dedupe (the paid lever). Unset ⇒ heuristics-only. |
AI_DEDUPE_BASE_URL | https://api.anthropic.com | Messages endpoint. |
AI_DEDUPE_MODEL | claude-haiku-4-5 | Cheap classification model. |
AI_DEDUPE_TIMEOUT_MS | 20000 | Per-request adjudication timeout; batched requests scale it with pair count. |
AI_DEDUPE_THRESHOLD | 0.15 | Heuristic-confidence floor before an AI call fires. |
AI_DEDUPE_DAILY_CAP | 500 | Per-org/day cap on AI-adjudicated pairs (a batched request meters its pair count). |
AI_DEDUPE_BATCH_SIZE | 20 | Max candidate pairs per adjudication request (clamped 1–20; 1 disables batching; ingest evaluates at most 12 candidates per finding). |
Upgrades that change adjudication prompt semantics bump an internal prompt version folded into the pair-decision cache key: previously cached pairs are re-adjudicated once, so expect temporarily elevated AI-dedupe usage after such an upgrade until the cache refills (bounded by
AI_DEDUPE_DAILY_CAP).Integrations & limits
| Variable | Default | Purpose |
|---|---|---|
GITHUB_WEBHOOK_SECRET | – | Optional: enables POST /v1/webhooks/github (PR → incremental campaign). |
RATE_LIMIT_CAPACITY | 120 | Per-org token-bucket default capacity. |
RATE_LIMIT_REFILL_PER_SEC | 4 | Per-org token-bucket refill. (Per-bucket overrides: `RATE_LIMIT_<CLAIM |
Next steps
- Deployment modes — how these vars compose per mode.
- On-prem deploy — a worked example.