Settings & env

Tripwire reads configuration from two places that overlap by design:

• App config — TRIPWIRE_-prefixed environment variables (pydantic-settings).
• Integration credentials — tracker tokens, the Anthropic key, the driver, and the log backend. Set them as environment variables (best for CI/headless), or via the dashboard's Settings page / the /settings API, which stores them in the database encrypted at rest and secret-masked on read.

Copy .env.example to .env to get started (docker compose auto-loads .env).

Claude / Anthropic (required)

Set one org-wide key as the admin — every engineer's run uses it, they don't bring their own. Use a dedicated Tripwire/CI key from your Anthropic workspace so spend and limits are attributed to Tripwire, not a person.

Variable	Purpose
ANTHROPIC_API_KEY	The key Claude uses to drive the browser and adjudicate checks. Required for any run.
ANTHROPIC_AUTH_TOKEN	Optional auth-token override for gateway setups. Usually unset.

App config (TRIPWIRE_ prefix)

Variable	Default	Purpose
TRIPWIRE_DATA_DIR	backend/data (/app/data in compose)	Where the default SQLite DB and run artifacts (screenshots) live.
TRIPWIRE_LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR.
TRIPWIRE_CORS_ORIGINS	localhost :3400 / :5173	JSON list of allowed dashboard origins.
TRIPWIRE_DRIVER	playwright	Execution driver: playwright (cross-platform, default) or desktop (legacy macOS).
TRIPWIRE_HEADLESS	1	Run headless. Set 0 to watch the browser.
TRIPWIRE_CDP	unset	On the legacy desktop path, 1 enables CDP-based network/trace capture.

Database

Structured data — suites, runs, issues, plans, settings, users, and API tokens — lives in a SQL database via SQLAlchemy. The default is a zero-setup SQLite file under TRIPWIRE_DATA_DIR; point at Postgres for production. Tables are created automatically on startup, and on first boot any pre-existing file-based data under TRIPWIRE_DATA_DIR is imported once. Run artifacts (screenshots) stay on the filesystem.

Variable	Default	Purpose
TRIPWIRE_DATABASE_URL	sqlite:///{data_dir}/tripwire.db	SQLAlchemy URL. For Postgres: postgresql+psycopg://user:pass@host:5432/tripwire (install the postgres extra).
TRIPWIRE_DB_POOL_SIZE	10	Postgres connection-pool size (ignored for SQLite).
TRIPWIRE_DB_MAX_OVERFLOW	20	Extra Postgres connections allowed above the pool size under burst.
TRIPWIRE_DB_POOL_TIMEOUT	30	Seconds to wait for a free Postgres connection before erroring.

Postgres is the compose default. docker compose up runs a bundled Postgres (no manual install) and applies Alembic migrations before the API starts — see Deploying. Host-native make dev-api uses a zero-setup SQLite file; that's great for a quick local loop, but SQLite serializes all writes, so don't run a shared/production instance on it. Tripwire runs as a single process — scale runs with TRIPWIRE_MAX_CONCURRENT_RUNS, not by running multiple API replicas.

Deployment edition

Variable	Default	Purpose
TRIPWIRE_DEPLOYMENT_MODE	cloud	cloud (open signup, many orgs) or selfhosted (one org created at first run, signup closed). See Editions & orgs.
TRIPWIRE_BASE_URL	dashboard origin	Public URL of this instance, used to build invitation links. Set to your real domain in production.

Auth & secrets

The API requires authentication (see Authentication). On a fresh instance the dashboard shows a "Create your admin account" screen; alternatively, set both variables below to pre-seed the admin on first boot (headless / Docker / CI) and skip that screen.

Variable	Default	Purpose
TRIPWIRE_ADMIN_EMAIL	unset	First-run admin email (used only when TRIPWIRE_ADMIN_PASSWORD is also set).
TRIPWIRE_ADMIN_PASSWORD	unset	First-run admin password. If either var is unset, use the dashboard setup screen instead.
TRIPWIRE_JWT_SECRET	auto-generated + persisted	HMAC secret for session JWTs. Set in production so sessions survive a restart / move.
TRIPWIRE_JWT_TTL_SECONDS	604800 (7 days)	Session lifetime.
TRIPWIRE_SECRET_KEY	auto-generated + persisted	Key that encrypts secret settings at rest (Fernet). Set in production so encrypted secrets survive a DB move / restore.

Execution scaling & cost control

Variable	Default	Purpose
TRIPWIRE_MAX_CONCURRENT_RUNS	2	How many runs execute in parallel (each is a browser + LLM calls).
TRIPWIRE_RUN_COST_CAP_USD	0 (off)	Abort a run once its model cost exceeds this (USD).
TRIPWIRE_DAILY_COST_CAP_USD	0 (off)	Block new runs once rolling 24h model spend exceeds this (USD).
TRIPWIRE_LLM_TIMEOUT	120	Per-request model timeout (seconds).
TRIPWIRE_LLM_RETRIES	4	Automatic retries (with backoff) on transient model errors (429 / 5xx / connection).

Run isolation (cloud)

Recommended when running the multi-tenant cloud edition; self-hosted can leave the defaults. See Editions & orgs.

Variable	Default	Purpose
TRIPWIRE_RUN_EXECUTOR	thread	thread (in-process) or subprocess (killable child with no DB access — per-run isolation).
TRIPWIRE_RUN_TIMEOUT_S	1800	Hard wall-clock timeout per run; the run is killed if it exceeds this.
TRIPWIRE_RUN_MEM_MB	0 (off)	Per-run memory cap (subprocess executor).
TRIPWIRE_RUN_CPU_S	0 (off)	Per-run CPU-time cap (subprocess executor).
TRIPWIRE_RUN_EGRESS	open	restricted blocks runs from reaching loopback / link-local / cloud-metadata / private addresses (SSRF guard).
TRIPWIRE_RUN_EGRESS_ALLOW	unset	Comma-separated extra hosts/IPs allowed when egress is restricted.

Issue trackers

Set the names for the providers you use (also writable via Settings). A provider with missing credentials is simply skipped.

Use a dedicated Tripwire service account for these tokens — set once by an admin, not a personal token. See Use a dedicated Tripwire account.

Variable	Provider	Purpose
GITHUB_TOKEN	GitHub	Service-account PAT with repo scope (or fine-grained: Issues read/write).
GITHUB_REPO	GitHub	owner/repo.
GITLAB_TOKEN	GitLab	Service-account / project-access token with api scope.
GITLAB_PROJECT	GitLab	Numeric id or url-encoded group%2Fproject.
GITLAB_URL	GitLab	Self-managed base URL (optional; default https://gitlab.com).
JIRA_BASE	Jira	https://your-org.atlassian.net.
JIRA_EMAIL	Jira	The service account's Atlassian email.
JIRA_TOKEN	Jira	Jira API token (created as that account).
JIRA_PROJECT	Jira	Project key (e.g. ENG).
FILE_ISSUES	—	External tracker(s) to also mirror to (e.g. github); the in-app Tripwire board is always written. Comma-separate for several.

See Filing issues for behavior and dedup.

Server-log backend (root cause)

Connect one backend so a failing request's trace_id resolves to the backend error. Set LOG_BACKEND and the matching config:

LOG_BACKEND	Required	Optional
loki	LOKI_URL	LOKI_SELECTOR
datadog	DATADOG_API_KEY, DATADOG_APP_KEY	DATADOG_SITE
elasticsearch	ELASTIC_URL, ELASTIC_API_KEY	ELASTIC_INDEX
http	LOG_HTTP_URL	LOG_HTTP_TOKEN
file	LOG_FILE_PATH	—

Full details and examples: Connecting server logs.

Notifications

Alert Slack or Teams when a run finishes (great for scheduled regression plans). Also configurable from the dashboard Settings page.

Variable	Default	Purpose
NOTIFY_ON	failures	When to notify: off / failures (only when a run has failures or broken cases) / always.
SLACK_WEBHOOK_URL	unset	Slack Incoming Webhook URL.
TEAMS_WEBHOOK_URL	unset	Microsoft Teams Incoming Webhook URL.

Frontend

Variable	Purpose
VITE_API_BASE	Base URL the dashboard uses to reach the API (compose / prod). In dev, Vite proxies /api → http://127.0.0.1:8400, so it's usually left unset locally.

Precedence & secrets

• Environment variables are ideal for CI and headless runs; the issue trackers and log adapters read directly from os.environ. Env always wins — a value present in the process environment takes precedence over the stored setting.
• The dashboard's Settings (stored in the database, encrypted at rest) are applied to the environment at run time for runs started through the API.
• Secrets are masked on read — tokens you store are never echoed back in plaintext, and they are encrypted in the database with TRIPWIRE_SECRET_KEY. Keep real secrets in env or a secret manager, never in git (.env is git-ignored).

Related: Authentication · Getting Started · REST API · CLI