Configuration Reference
Complete reference of environment variables for self-hosted QAID.
QAID is configured entirely through environment variables in a .env file inside your install directory (default ~/qaid/.env). The installer writes a working .env for you with the values you provide and generates the secrets — this page documents every variable you can subsequently edit.
Required
The installer prompts for some and auto-generates the rest. Everything below is already in your ~/qaid/.env after a fresh install.
Set from install prompts
| Variable | Description |
|---|---|
CADDY_SITE_ADDRESS | Public site address — your domain (e.g. qaid.example.com) for production, or http://localhost for evaluation. Caddy uses this both as its site address and as the cue for auto-HTTPS: any value that isn't http://localhost triggers Let's Encrypt. |
FRONTEND_URL | Public URL the backend uses for OAuth redirects and email links. Derived from your domain answer (https://<your-domain> or http://localhost). |
QAID_LICENSE_KEY | Your QAID license key (provided by your administrator). Used at first boot to auto-activate; cached afterwards. |
ANTHROPIC_API_KEY | Your Anthropic API key (sk-ant-…). You can also leave this blank at install and set it later in Admin → Settings. |
Auto-generated by the installer
Written once at install time. Do not regenerate these on an existing install — JWT/session changes log every user out, and changing POSTGRES_PASSWORD breaks database authentication (the bundled Postgres only honors it on first boot).
| Variable | Generator |
|---|---|
JWT_SECRET | openssl rand -hex 32 |
JWT_REFRESH_SECRET | openssl rand -hex 32 |
SESSION_SECRET | openssl rand -hex 32 |
POSTGRES_PASSWORD | openssl rand -hex 16 |
License (advanced)
QAID_LICENSE_KEY is in Required above. The variable below is an optional override most customers never need.
| Variable | Description |
|---|---|
QAID_LICENSE_SERVER_URL | URL of the QAID license verification service. The installer sets the correct default for you — override only if your administrator has provided a private license-server endpoint. |
Proxy and TLS
The installer ships QAID with Caddy as the bundled reverse proxy and writes a Caddyfile to ~/qaid/. TLS modes (auto-HTTPS, your own cert, or bring-your-own external proxy) are configured by editing ~/qaid/Caddyfile and ~/qaid/docker-compose.yml directly — see TLS and HTTPS options for the concrete edits.
CADDY_SITE_ADDRESS (in Required) is the only Caddy-related variable in .env.
Database
Bundled PostgreSQL (default)
| Variable | Default | Description |
|---|---|---|
POSTGRES_DB | qaid | Database name |
POSTGRES_USER | qaid | Database user |
POSTGRES_PASSWORD | (required) | Database password |
POSTGRES_POOL_SIZE | 20 | Connection pool size |
External PostgreSQL
If you'd rather use managed PostgreSQL (RDS, Cloud SQL, etc), set:
| Variable | Description |
|---|---|
DATABASE_URL | Full connection string: postgresql://user:pass@host:5432/db |
For Amazon RDS, append ?sslmode=require&uselibpqcompat=true to avoid SSL certificate errors.
AI
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY | Your Anthropic API key for AI features. You can set this here or configure it later in Admin → Settings. |
QAID uses your Anthropic key directly — usage shows up on your own Anthropic invoice with no markup. See AI Costs for typical monthly ranges.
Server
| Variable | Default | Description |
|---|---|---|
PORT | 3001 | Backend server port (internal, not exposed) |
QAID_DATA_DIR | /app/data | Directory inside the container for runtime files (screenshots, snapshots, etc.). The installer mounts the qaid-data Docker volume at this path. |
OAuth (optional)
Enable single sign-on by configuring OAuth providers. Both Google and GitHub are supported.
| Variable | Description |
|---|---|
GOOGLE_CLIENT_ID | Google OAuth client ID |
GOOGLE_CLIENT_SECRET | Google OAuth client secret |
GITHUB_CLIENT_ID | GitHub OAuth client ID |
GITHUB_CLIENT_SECRET | GitHub OAuth client secret |
OAuth redirect URLs follow the pattern https://your-domain.com/api/auth/callback/{provider}.
Chrome extension (optional)
If you publish a custom Chrome extension for recording, configure these:
| Variable | Description |
|---|---|
NEXT_PUBLIC_CHROME_EXTENSION_ID | Extension ID (visible in chrome://extensions) |
NEXT_PUBLIC_CHROME_STORE_URL | Public URL where users can install the extension |
ALLOWED_EXTENSION_IDS | Comma-separated list of extension IDs allowed to communicate with the server |
Performance tuning (optional)
| Variable | Default | Description |
|---|---|---|
QAID_MAX_CONCURRENT_BROWSERS | 3 | Maximum simultaneous browser instances for test execution. Increase for faster runs if you have spare RAM. |
QAID_ANTHROPIC_TIMEOUT_MS | 60000 | Timeout for AI calls in milliseconds |
Email (optional)
Used for invitations and notifications. If not configured, those features are disabled but the rest of QAID works fine.
| Variable | Description |
|---|---|
SMTP_HOST | SMTP server hostname |
SMTP_PORT | SMTP server port (typically 587 for TLS) |
SMTP_USER | SMTP username |
SMTP_PASSWORD | SMTP password |
SMTP_FROM | "From" address for outbound mail |
Reloading config
After editing .env, recreate the affected service:
# Most config changes affect the backend
docker compose up -d --force-recreate qaid-server
# Or restart everything
docker compose down && docker compose up -dDatabase connection changes (DATABASE_URL, POSTGRES_*) require a full restart.