Configuration of Environment Variables

This guide covers all environment variables used to configure Agenta. These variables control various aspects of the platform, from core functionality to third-party integrations.

Configuration File Location

The default environment variables are specified in hosting/docker-compose/oss/.env.oss.gh (or hosting/docker-compose/oss/.env.oss.dev for development).

You can specify your own environment file using the --env-file flag when running docker compose:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file .my-env-file --profile with-web --profile with-traefik up -d

Variable Categories

First-party (Required)

These variables are essential for Agenta to function properly:

Variable	Description	Default
`AGENTA_LICENSE`	License type (oss for open source)	`oss`
`AGENTA_API_URL`	Base URL for the API backend	`http://localhost/api`
`AGENTA_WEB_URL`	Base URL for the web frontend	`http://localhost`
`AGENTA_SERVICES_URL`	URL prefix for Agenta services	`http://localhost/services`
`AGENTA_AUTH_KEY`	Authentication key for internal services	`replace-me`
`AGENTA_CRYPT_KEY`	Encryption key for sensitive data	`replace-me`

First-party (Registry & Service)

Configuration for Docker and database connections:

Variable	Description	Default
`AGENTA_WEB_IMAGE_TAG`	Docker image tag for the web frontend	`latest`
`AGENTA_API_IMAGE_TAG`	Docker image tag for the API backend	`latest`
`DOCKER_NETWORK_MODE`	Docker networking mode	`_(empty)_` (which falls back to `bridge`)
`POSTGRES_PASSWORD`	PostgreSQL database password	`password`
`POSTGRES_USERNAME`	PostgreSQL database username	`username`

First-party (Optional)

Optional Agenta-specific configurations:

Variable	Description	Default
`ALEMBIC_AUTO_MIGRATIONS`	Enable automatic database migrations (legacy: `AGENTA_AUTO_MIGRATIONS`)	`true`
`AGENTA_PRICING`	Enable pricing features	(empty)
`AGENTA_DEMOS`	Enable demo applications	(empty)
`AGENTA_RUNTIME_PREFIX`	Prefix for runtime containers	(empty)
`AGENTA_TELEMETRY_ENABLED`	Enable telemetry collection	`true`
`AGENTA_SEND_EMAIL_FROM_ADDRESS`	From address for system emails	`mail@example.com`
`AGENTA_API_INTERNAL_URL`	Internal API URL for services	(empty)
`AGENTA_SERVICE_MIDDLEWARE_CACHE_ENABLED`	Enable middleware caching in the chat and completion services	`true`
`AGENTA_ALLOWED_DOMAINS`	Comma-separated list of email domains allowed to authenticate; when set, all other domains are rejected	(empty)
`AGENTA_OTLP_MAX_BATCH_BYTES`	Max OTLP batch size before requests are rejected with 413	`10485760` (10MB)

Sandbox Runner (Custom Evaluators)

Agenta executes custom evaluator code in a sandboxed environment. You can choose between local execution or remote execution using Daytona sandboxes.

Variable	Description	Default
`AGENTA_SERVICES_SANDBOX_RUNNER`	Code execution backend for custom evaluators. Set to `local` or `daytona`.	`local`
`DAYTONA_API_KEY`	Your Daytona API key. Required when using Daytona. Get one from https://app.daytona.io	(empty)
`DAYTONA_API_URL`	Daytona API endpoint.	`https://app.daytona.io/api`
`DAYTONA_TARGET`	Daytona region for sandbox execution (e.g., `eu`, `us`).	Value of `AGENTA_REGION`, or `eu`
`DAYTONA_SNAPSHOT`	Snapshot ID that defines the sandbox environment. Required when using Daytona.	(empty)

When to use Daytona: Local execution runs code directly on the API server. This is simpler but runs in the same process as the API. Daytona runs code in isolated containers with their own dependencies. Use Daytona for production deployments or when you need stronger isolation.

Third-party (Required)

Essential third-party service configurations:

Traefik (Reverse Proxy)

Variable	Description	Default
`TRAEFIK_DOMAIN`	Domain for Traefik routing	`localhost`
`TRAEFIK_PORT`	HTTP port for Traefik	`80`
`TRAEFIK_UI_PORT`	Port for Traefik dashboard	`8080`
`TRAEFIK_HTTPS_PORT`	HTTPS port for Traefik	`443`

Redis (Task Queue, Caching & Sessions)

Use REDIS_URI when you have a single Redis, or split to two instances with the volatile/durable URLs below.

Variable	Description	Default
`REDIS_URI`	Single Redis URL used when the split URLs are not provided	`redis://redis:6379/0`
`REDIS_URI_VOLATILE`	Caches/PubSub channels; falls back to `REDIS_URI`	`redis://redis-volatile:6379/0`
`REDIS_URI_DURABLE`	Queues/Streams; falls back to `REDIS_URI`	`redis://redis-durable:6381/0`

PostgreSQL (Database)

Variable	Description	Example
`POSTGRES_URI_SUPERTOKENS`	SuperTokens database connection	`postgresql://username:password@postgres:5432/agenta_oss_supertokens`
`POSTGRES_URI_CORE`	Core database connection	`postgresql+asyncpg://username:password@postgres:5432/agenta_oss_core`
`POSTGRES_URI_TRACING`	Tracing database connection	`postgresql+asyncpg://username:password@postgres:5432/agenta_oss_tracing`

Database Migrations

Variable	Description	Default
`ALEMBIC_CFG_PATH_CORE`	Core database migration config	`/app/oss/databases/postgres/migrations/core/alembic.ini`
`ALEMBIC_CFG_PATH_TRACING`	Tracing database migration config	`/app/oss/databases/postgres/migrations/tracing/alembic.ini`

SuperTokens (Authentication)

Variable	Description	Default
`SUPERTOKENS_API_KEY`	SuperTokens API key	(empty)
`SUPERTOKENS_CONNECTION_URI`	SuperTokens service URL	`http://supertokens:3567`

Analytics

Variable	Description	Example
`POSTHOG_API_KEY`	PostHog analytics key	`phc_xxxxxxxx`

Third-party (TLS/SSL)

Required for HTTPS/SSL configuration:

Variable	Description	Example
`AGENTA_SSL_DIR`	Directory for SSL certificates	`/home/user/ssl_certificates`

Third-party (Optional)

Optional port and service configurations:

Port Overrides

Variable	Description	Default
`NGINX_PORT`	Nginx port (when using Nginx)	`80`
`POSTGRES_PORT`	PostgreSQL port	`5432`
`SUPERTOKENS_PORT`	SuperTokens port	`3567`

OAuth providers

Variable	Description
`GOOGLE_OAUTH_CLIENT_ID`	Google OAuth client ID
`GOOGLE_OAUTH_CLIENT_SECRET`	Google OAuth client secret
`GITHUB_OAUTH_CLIENT_ID`	GitHub OAuth client ID
`GITHUB_OAUTH_CLIENT_SECRET`	GitHub OAuth client secret

Email & Communication

Variable	Description
`SENDGRID_API_KEY`	SendGrid email service API key

Deprecated Variables

⚠️ Warning: The following variables are deprecated and will be removed in future releases. I'd recommend migrating them to the new variables listed below:

Deprecated Variable	New Variable(s)	Migration Note
`AGENTA_PORT`	`TRAEFIK_PORT`	Port configuration moved to Traefik
`BARE_DOMAIN_NAME`	`TRAEFIK_DOMAIN`	Domain configuration moved to Traefik
`DOMAIN_NAME`	`AGENTA_API_URL`	More specific API URL configuration
`WEBSITE_DOMAIN_NAME`	`AGENTA_WEB_URL`	More specific web URL configuration
`SERVICE_URL_TEMPLATE`	`AGENTA_SERVICES_URL`	Simplified service URL template
`POSTGRES_DB`	(removed)	Database names now hardcoded
`POSTGRES_URI`	`POSTGRES_URI_CORE`, `POSTGRES_URI_TRACING`, `POSTGRES_URI_SUPERTOKENS`	Split into separate database connections
`ALEMBIC_CFG_PATH`	`ALEMBIC_CFG_PATH_CORE`, `ALEMBIC_CFG_PATH_TRACING`	Split migration configs
`AGENTA_HOST`	(removed)	No longer needed

Migration of Deprecated Environment Variables

When you start Agenta with deprecated variables, you'll see a warning message. To migrate:

Update your environment file with the new variable names
Remove the deprecated variables from your configuration
Restart Agenta to apply the changes

Example migration:

# Old (deprecated)
AGENTA_PORT=80
BARE_DOMAIN_NAME=mydomain.com
DOMAIN_NAME=http://mydomain.com
SERVICE_URL_TEMPLATE=http://localhost:80/services/{path}

# New (current)
TRAEFIK_PORT=80
TRAEFIK_DOMAIN=mydomain.com
AGENTA_API_URL=http://mydomain.com/api
AGENTA_WEB_URL=http://mydomain.com
AGENTA_SERVICES_URL=http://mydomain.com/services

Configuration Examples

Local Development

AGENTA_LICENSE=oss
AGENTA_API_URL=http://localhost/api
AGENTA_WEB_URL=http://localhost
TRAEFIK_DOMAIN=localhost
TRAEFIK_PORT=80

Production with Custom Domain

AGENTA_LICENSE=oss
AGENTA_API_URL=https://agenta.mydomain.com/api
AGENTA_WEB_URL=https://agenta.mydomain.com
TRAEFIK_DOMAIN=agenta.mydomain.com
TRAEFIK_PORT=80
TRAEFIK_HTTPS_PORT=443
AGENTA_SSL_DIR=/home/user/ssl_certificates

Production with IP Address

AGENTA_LICENSE=oss
AGENTA_API_URL=http://192.168.1.100/api
AGENTA_WEB_URL=http://192.168.1.100
TRAEFIK_DOMAIN=192.168.1.100
TRAEFIK_PORT=80

Security Considerations

Replace default secrets: Always change AGENTA_AUTH_KEY, AGENTA_CRYPT_KEY, and SUPERTOKENS_API_KEY in production
Secure database credentials: Use strong passwords for POSTGRES_PASSWORD
Use HTTPS in production: Configure SSL/TLS for production deployments

Troubleshooting

Common Issues

Services can't connect: Verify database URIs and service URLs are correct
Authentication failures: Check that auth keys match across services
SSL certificate issues: Ensure AGENTA_SSL_DIR points to a directory with proper permissions
Deprecated variable warnings: Follow the migration guide to update your configuration

Getting Help

For configuration assistance:

Check the GitHub issues
Join our Slack community

Configuration File Location​

Variable Categories​

First-party (Required)​

First-party (Registry & Service)​

First-party (Optional)​

Sandbox Runner (Custom Evaluators)​

Third-party (Required)​

Traefik (Reverse Proxy)​

Redis (Task Queue, Caching & Sessions)​

PostgreSQL (Database)​

Database Migrations​

SuperTokens (Authentication)​

Analytics​

Third-party (TLS/SSL)​

Third-party (Optional)​

Port Overrides​

OAuth providers​

Email & Communication​

Deprecated Variables​

Migration of Deprecated Environment Variables​

Configuration Examples​

Local Development​

Production with Custom Domain​

Production with IP Address​

Security Considerations​

Troubleshooting​

Common Issues​

Getting Help​