Settings & env

Upliftr reads configuration from two places that overlap by design:

• App config, UPLIFTR_-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 Upliftr/CI key from your Anthropic workspace so spend and limits are attributed to Upliftr, 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 (UPLIFTR_ prefix)

Variable	Default	Purpose
UPLIFTR_DATA_DIR	backend/data (/app/data in compose)	Where the default SQLite DB and run artifacts (screenshots) live.
UPLIFTR_LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR.
UPLIFTR_CORS_ORIGINS	localhost :3400 / :5173	JSON list of allowed dashboard origins.
UPLIFTR_CDP	unset	1 enables CDP-based network/trace capture during runs.

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 UPLIFTR_DATA_DIR; point at Postgres for production. Tables are created automatically on startup, and on first boot any pre-existing file-based data under UPLIFTR_DATA_DIR is imported once. Run artifacts (screenshots) stay on the filesystem.

Variable	Default	Purpose
UPLIFTR_DATABASE_URL	sqlite:///{data_dir}/upliftr.db	SQLAlchemy URL. For Postgres: postgresql+psycopg://user:pass@host:5432/upliftr (install the postgres extra).
UPLIFTR_DB_POOL_SIZE	10	Postgres connection-pool size (ignored for SQLite).
UPLIFTR_DB_MAX_OVERFLOW	20	Extra Postgres connections allowed above the pool size under burst.
UPLIFTR_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. Upliftr runs as a single process, scale runs with UPLIFTR_MAX_CONCURRENT_RUNS, not by running multiple API replicas.

Deployment edition

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

White-label / OEM

Rebrand every user-facing surface so a platform can present the engine as its own. See White-labeling.

Variable	Default	Purpose
UPLIFTR_PRODUCT_NAME	Upliftr	Product name on filed tickets, HTML reports, email, API metadata, /health.
UPLIFTR_DOCS_URL	https://docs.upliftr.io	Docs base for help links shown in root-cause hints.
UPLIFTR_SUITE_EXT	upliftr.yaml	Suite-file extension tag.

MCP transport

Variable	Default	Purpose
UPLIFTR_MCP_TRANSPORT	stdio	stdio (local editors) | http (streamable-http) | sse (remote agentic platforms). See IDE & MCP.
UPLIFTR_MCP_HOST / UPLIFTR_MCP_PORT	0.0.0.0 / 8930	Bind address / port for the HTTP & SSE transports.

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
UPLIFTR_ADMIN_EMAIL	unset	First-run admin email (used only when UPLIFTR_ADMIN_PASSWORD is also set).
UPLIFTR_ADMIN_PASSWORD	unset	First-run admin password. If either var is unset, use the dashboard setup screen instead.
UPLIFTR_JWT_SECRET	auto-generated + persisted	HMAC secret for session JWTs. Set in production so sessions survive a restart / move.
UPLIFTR_JWT_TTL_SECONDS	604800 (7 days)	Session lifetime.
UPLIFTR_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
UPLIFTR_MAX_CONCURRENT_RUNS	2	How many runs execute in parallel (each is a browser + LLM calls).
UPLIFTR_RUN_COST_CAP_USD	0 (off)	Abort a run once its model cost exceeds this (USD).
UPLIFTR_DAILY_COST_CAP_USD	0 (off)	Block new runs once rolling 24h model spend exceeds this (USD).
UPLIFTR_LLM_TIMEOUT	120	Per-request model timeout (seconds).
UPLIFTR_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
UPLIFTR_RUN_EXECUTOR	thread	thread (in-process) or subprocess (killable child with no DB access, per-run isolation).
UPLIFTR_RUN_TIMEOUT_S	1800	Hard wall-clock timeout per run; the run is killed if it exceeds this.
UPLIFTR_RUN_MEM_MB	0 (off)	Per-run memory cap (subprocess executor).
UPLIFTR_RUN_CPU_S	0 (off)	Per-run CPU-time cap (subprocess executor).
UPLIFTR_RUN_EGRESS	open	restricted blocks runs from reaching loopback / link-local / cloud-metadata / private addresses (SSRF guard).
UPLIFTR_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 Upliftr service account for these tokens, set once by an admin, not a personal token. See Use a dedicated Upliftr 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 Upliftr 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	,

Tuning (optional, apply to all backends):

Variable	Default	Purpose
LOG_WINDOW_S	180	Lookback window (seconds) when correlating a trace_id.
LOG_REQUERY_DELAYS	off	Re-query with back-off before concluding no_logs_matched, for shippers that batch. Comma seconds, e.g. 5,15.

Trace ids are matched in all common representations automatically (W3C hex, dashed UUID, Datadog decimal), and a diagnosis is only full-confidence when a matched line actually contains an error/5xx marker.

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 UPLIFTR_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