Environment Variables

Quick Start - Minimum for Local Development

To get the API and UI running locally, you need a surprisingly small set of variables. Copy .env.example to .env at the repo root and fill in these essentials:

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/autonoma

# Redis
REDIS_URL=redis://localhost:6379

# API server
API_PORT=4000
SCENARIO_ENCRYPTION_KEY=any-string-at-least-1-char

# Google OAuth (create credentials at console.cloud.google.com)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# GitHub OAuth (optional - create an OAuth app at github.com/settings/developers)
GITHUB_CLIENT_ID=your-github-oauth-client-id
GITHUB_CLIENT_SECRET=your-github-oauth-client-secret

# AI model keys (needed for test execution)
GEMINI_API_KEY=your-gemini-key
GROQ_KEY=your-groq-key
OPENROUTER_API_KEY=your-openrouter-key

# S3-compatible storage (can use MinIO locally)
S3_BUCKET=autonoma-local
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin

Everything else has sensible defaults or is optional for local development. The sections below cover every variable in detail.

How Environment Variables Work in This Project

Every app and package defines its environment variables in a dedicated env.ts file using createEnv from @t3-oss/env-core. This gives you:

• Zod validation at startup - the process crashes immediately if a required variable is missing or malformed, rather than failing mysteriously at runtime.
• Type safety - env.DATABASE_URL is typed as string, not string | undefined. No more process.env.DATABASE_URL! casts.
• Composability - packages export their env object, and apps extend them. For example, the API server’s env.ts extends the database, storage, logger, and billing envs, inheriting all their variables.

You should never read process.env directly in application code. Always import from the nearest env.ts:

// Good
import { env } from "./env";
const port = env.API_PORT;

// Bad - bypasses validation
const port = process.env.API_PORT;

The emptyStringAsUndefined: true option is enabled everywhere, so setting a variable to an empty string is treated the same as not setting it at all.

For boolean variables, the codebase uses z.stringbool() which accepts "true", "false", "1", "0", "yes", and "no".

Core API Server

Source: apps/api/src/env.ts

The API server extends the database, storage, logger, and billing environments, so all variables from those sections apply here too.

Frontend (UI)

Source: apps/ui/src/env.ts

The frontend uses Vite’s import.meta.env and requires the VITE_ prefix for all variables.

Database

Source: packages/db/src/env.ts

AI Services

Source: packages/ai/src/env.ts

These keys are required by the execution engines (web and mobile) and any service that runs AI inference. The API server does not run inference itself, so it needs none of them.

Storage (S3)

Source: packages/storage/src/env.ts

Used for storing screenshots, video recordings, test artifacts, and other binary assets.

Logging and Observability

Source: packages/logger/src/env.ts

Billing (Stripe)

Source: packages/billing/src/env.ts

Billing is entirely optional. When STRIPE_ENABLED is false (the default), all billing features are disabled and no other Stripe variables are needed.

Kubernetes and Workflows

Source: packages/k8s/src/env.ts and packages/workflow/src/env.ts

These variables are only needed in production or when running engine jobs on Kubernetes. Not required for local development.

The workflow package also reads:

Engine - Web (Playwright)

Source: packages/engine-web/src/platform/env.ts and packages/engine-web/src/execution-agent/env.ts

The web engine extends the AI, database, logger, and storage environments. All variables from those sections apply.

Engine - Mobile (Appium)

Source: packages/engine-mobile/src/platform/env.ts

The mobile engine extends the AI, database, logger, and storage environments. All variables from those sections apply.

Jobs

Execution Agent Runner

Source: packages/engine/src/execution-agent/runner/env.ts

Run Completion Notification

Source: apps/jobs/run-completion-notification/src/env.ts

Worker - Diffs

Source: apps/workers/diffs/src/env.ts

Diffs analysis and resolution run as Temporal activities in the @autonoma/worker-diffs worker. AI model keys come from the AI Services section; this worker adds the GitHub App credentials it needs to clone repositories and read PRs.

GitHub App

These variables appear in .env.example and are used by the API server and the diffs worker for GitHub integration features (repository connections, PR-triggered test runs).

Authentication

These variables are referenced in .env.example for the Better Auth integration used by the API server.

OAuth proxying

A provider only redirects to callback URLs registered with it ahead of time, and an alpha environment’s hostname is minted per PR - so it can never be one of them. Instead, every deployed environment sends the provider production’s callback URL and gets the resulting profile handed back, encrypted and short-lived, at its own origin, where it mints its own session. Production’s own APP_URL matches OAUTH_PROXY_PRODUCTION_URL, so it skips proxying and serves the callback for the fleet.

Two things about this are easy to get wrong:

• Leave both unset locally. Local dev has its own OAuth apps, and enabling the proxy would mean configuring production to hand encrypted session payloads to a developer’s machine.
• OAUTH_PROXY_PRODUCTION_URL is not a plain on/off switch. Setting it without every participating environment sharing the same OAUTH_PROXY_SECRET breaks sign-in on the non-production environments.

OAUTH_PROXY_SECRET is deliberately separate from BETTER_AUTH_SECRET: it is shared across environments, so a leak must not also be able to forge sessions. It falls back to BETTER_AUTH_SECRET when unset, which works but widens the blast radius.

Tips for Local Development

What you can skip entirely:

• Billing - Leave STRIPE_ENABLED=false (the default). No Stripe keys needed.
• Analytics - Omit POSTHOG_KEY and VITE_POSTHOG_KEY. Analytics calls become no-ops.
• Sentry - Omit SENTRY_DSN and VITE_SENTRY_DSN. Error tracking is disabled gracefully.
• Kubernetes - Omit NAMESPACE. The API defaults it to local; only @autonoma/k8s needs a real one.
• OAuth proxying - Omit OAUTH_PROXY_PRODUCTION_URL and OAUTH_PROXY_SECRET. Local dev signs in against its own OAuth apps.
• GitHub App - Omit all GITHUB_APP_* variables unless you are working on GitHub integration.
• Temporal - Omit VITE_TEMPORAL_URL. The UI hides workflow links when this is unset.

What uses defaults that just work:

• ALLOWED_ORIGINS defaults to http://localhost:3000 - correct for local dev.
• VITE_API_URL defaults to http://localhost:4000 - correct for local dev.
• APP_URL defaults to http://localhost:3000 - correct for local dev.
• NODE_ENV defaults to development.
• AGENT_VERSION defaults to latest.

What you must provide:

• DATABASE_URL - there is no default. You need a running PostgreSQL instance.
• REDIS_URL - there is no default. You need a running Redis instance.
• GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET - required for authentication. Create OAuth credentials in the Google Cloud Console.
• GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET - optional. Set both to add GitHub as a second sign-in option; see Development Setup for the OAuth app steps.
• SCENARIO_ENCRYPTION_KEY - any non-empty string works locally.
• BETTER_AUTH_SECRET - generate one with openssl rand -hex 32.
• BETTER_AUTH_URL - set to http://localhost:4000. The origin only; appending /v1 404s every auth endpoint.
• AI keys (GEMINI_API_KEY, GROQ_KEY, OPENROUTER_API_KEY) - required if you are running test execution. Not needed if you are only working on the UI or API without triggering test runs.
• S3 credentials - required for artifact storage. Use MinIO locally.