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

# 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 only needs GEMINI_API_KEY directly - the other keys are consumed by the engine apps.

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: apps/engine-web/src/platform/env.ts and apps/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: apps/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

Diffs

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

Generation Assigner

Source: apps/jobs/generation-assigner/src/env.ts

Review Jobs (Generation Reviewer, Replay Reviewer)

Source: packages/review/src/env.ts

Both the generation reviewer and replay reviewer jobs re-export from @autonoma/review/env, which extends the AI, logger, and storage environments. No additional variables beyond those from the AI, logger, and storage sections.

GitHub App

These variables appear in .env.example and are used by the API server and the diffs job 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.

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. Only needed when deploying to K8s.
• 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.
• 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.
• 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.