Self-hosting
Environment variables
Reference for every configuration option across the API, web app, and database package.
Three env files configure an Iris deployment. Each app ships a commented .env.example to copy from.
| Variable | Required | Default | Description |
|---|
DATABASE_URL | Yes | postgresql://iris:iris@localhost:5432/iris | PostgreSQL connection string |
| Variable | Required | Default | Description |
|---|
PORT | No | 3000 | Port the NestJS API listens on |
WEB_URL | Yes | http://localhost:3001 | URL of the web app (CORS / trusted origin) |
| Variable | Required | Default | Description |
|---|
BETTER_AUTH_SECRET | Yes | — | Session signing secret (openssl rand -hex 32). Must match the web app's value. |
BETTER_AUTH_URL | Yes | http://localhost:3001 | Public URL of the web app |
| Variable | Required | Default | Description |
|---|
REDIS_URL | Yes | redis://localhost:6379 | Redis connection for the Bull queue |
| Variable | Required | Default | Description |
|---|
BROWSER_ENV | No | LOCAL | LOCAL (Playwright on this machine) or BROWSERBASE |
BROWSERBASE_API_KEY | When BROWSERBASE | — | From browserbase.com |
BROWSERBASE_PROJECT_ID | When BROWSERBASE | — | Browserbase project to run sessions in |
| Variable | Required | Default | Description |
|---|
GEMINI_API_KEY | Yes | — | From Google AI Studio |
GOOGLE_GENERATIVE_AI_API_KEY | Yes | — | Same key, read by the AI SDK |
AGENT_MODEL | No | google/gemini-2.5-flash | Model used by the browser agent |
Defaults match the bundled docker-compose.yml; override for external storage.
| Variable | Default | Description |
|---|
MINIO_ENDPOINT | localhost | MinIO/S3 host |
MINIO_PORT | 9000 | MinIO/S3 port |
MINIO_ACCESS_KEY | minioadmin | Access key |
MINIO_SECRET_KEY | minioadmin | Secret key |
MINIO_BUCKET | iris-artifacts | Bucket for screenshots and frames |
MINIO_USE_SSL | false | Use HTTPS to reach the endpoint |
MINIO_PUBLIC_URL | http://localhost:9000 | URL browsers use to load stored artifacts |
| Variable | Default | Description |
|---|
HELICONE_API_KEY | — | Leave empty to call Gemini directly (no observability) |
HELICONE_BASE_URL | https://generativelanguage.hconeai.com | Helicone proxy endpoint |
| Variable | Required | Default | Description |
|---|
NEXT_PUBLIC_API_URL | Yes | http://localhost:3000 | URL of the NestJS API |
BETTER_AUTH_SECRET | Yes | — | Must match BETTER_AUTH_SECRET in apps/api/.env |
Used by Prisma CLI commands (pnpm db:generate, pnpm db:migrate, pnpm db:studio).
| Variable | Required | Default | Description |
|---|
DATABASE_URL | Yes | postgresql://iris:iris@localhost:5432/iris | Same value as the API's |