Skip to main content

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:

VariableDescriptionDefault
AGENTA_LICENSELicense type (oss for open source)oss
AGENTA_API_URLBase URL for the API backendhttp://localhost/api
AGENTA_WEB_URLBase URL for the web frontendhttp://localhost
AGENTA_SERVICES_URLURL prefix for Agenta serviceshttp://localhost/services
AGENTA_AUTH_KEYAuthentication key for internal servicesreplace-me
AGENTA_CRYPT_KEYEncryption key for sensitive datareplace-me

First-party (Registry & Service)​

Configuration for Docker and database connections:

VariableDescriptionDefault
AGENTA_WEB_IMAGE_TAGDocker image tag for the web frontendlatest
AGENTA_API_IMAGE_TAGDocker image tag for the API backendlatest
DOCKER_NETWORK_MODEDocker networking mode_(empty)_ (which falls back to bridge)
POSTGRES_PASSWORDPostgreSQL database passwordpassword
POSTGRES_USERNAMEPostgreSQL database usernameusername

First-party (Optional)​

Optional Agenta-specific configurations:

VariableDescriptionDefault
ALEMBIC_AUTO_MIGRATIONSEnable automatic database migrations (legacy: AGENTA_AUTO_MIGRATIONS)true
AGENTA_PRICINGEnable pricing features(empty)
AGENTA_DEMOSEnable demo applications(empty)
AGENTA_RUNTIME_PREFIXPrefix for runtime containers(empty)
AGENTA_TELEMETRY_ENABLEDEnable telemetry collectiontrue
AGENTA_SEND_EMAIL_FROM_ADDRESSFrom address for system emailsmail@example.com
AGENTA_API_INTERNAL_URLInternal API URL for services(empty)
AGENTA_SERVICE_MIDDLEWARE_CACHE_ENABLEDEnable middleware caching in the chat and completion servicestrue
AGENTA_ALLOWED_DOMAINSComma-separated list of email domains allowed to authenticate; when set, all other domains are rejected(empty)
AGENTA_OTLP_MAX_BATCH_BYTESMax OTLP batch size before requests are rejected with 41310485760 (10MB)

Third-party (Required)​

Essential third-party service configurations:

Traefik (Reverse Proxy)​

VariableDescriptionDefault
TRAEFIK_DOMAINDomain for Traefik routinglocalhost
TRAEFIK_PORTHTTP port for Traefik80
TRAEFIK_UI_PORTPort for Traefik dashboard8080
TRAEFIK_HTTPS_PORTHTTPS port for Traefik443

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.

VariableDescriptionDefault
REDIS_URISingle Redis URL used when the split URLs are not providedredis://redis:6379/0
REDIS_URI_VOLATILECaches/PubSub channels; falls back to REDIS_URIredis://redis-volatile:6379/0
REDIS_URI_DURABLEQueues/Streams; falls back to REDIS_URIredis://redis-durable:6381/0

PostgreSQL (Database)​

VariableDescriptionExample
POSTGRES_URI_SUPERTOKENSSuperTokens database connectionpostgresql://username:password@postgres:5432/agenta_oss_supertokens
POSTGRES_URI_CORECore database connectionpostgresql+asyncpg://username:password@postgres:5432/agenta_oss_core
POSTGRES_URI_TRACINGTracing database connectionpostgresql+asyncpg://username:password@postgres:5432/agenta_oss_tracing

Database Migrations​

VariableDescriptionDefault
ALEMBIC_CFG_PATH_CORECore database migration config/app/oss/databases/postgres/migrations/core/alembic.ini
ALEMBIC_CFG_PATH_TRACINGTracing database migration config/app/oss/databases/postgres/migrations/tracing/alembic.ini

SuperTokens (Authentication)​

VariableDescriptionDefault
SUPERTOKENS_API_KEYSuperTokens API key(empty)
SUPERTOKENS_CONNECTION_URISuperTokens service URLhttp://supertokens:3567

Analytics​

VariableDescriptionExample
POSTHOG_API_KEYPostHog analytics keyphc_xxxxxxxx

Third-party (TLS/SSL)​

Required for HTTPS/SSL configuration:

VariableDescriptionExample
AGENTA_SSL_DIRDirectory for SSL certificates/home/user/ssl_certificates

Third-party (Optional)​

Optional port and service configurations:

Port Overrides​

VariableDescriptionDefault
NGINX_PORTNginx port (when using Nginx)80
POSTGRES_PORTPostgreSQL port5432
SUPERTOKENS_PORTSuperTokens port3567

OAuth providers​

VariableDescription
GOOGLE_OAUTH_CLIENT_IDGoogle OAuth client ID
GOOGLE_OAUTH_CLIENT_SECRETGoogle OAuth client secret
GITHUB_OAUTH_CLIENT_IDGitHub OAuth client ID
GITHUB_OAUTH_CLIENT_SECRETGitHub OAuth client secret

Email & Communication​

VariableDescription
SENDGRID_API_KEYSendGrid 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 VariableNew Variable(s)Migration Note
AGENTA_PORTTRAEFIK_PORTPort configuration moved to Traefik
BARE_DOMAIN_NAMETRAEFIK_DOMAINDomain configuration moved to Traefik
DOMAIN_NAMEAGENTA_API_URLMore specific API URL configuration
WEBSITE_DOMAIN_NAMEAGENTA_WEB_URLMore specific web URL configuration
SERVICE_URL_TEMPLATEAGENTA_SERVICES_URLSimplified service URL template
POSTGRES_DB(removed)Database names now hardcoded
POSTGRES_URIPOSTGRES_URI_CORE, POSTGRES_URI_TRACING, POSTGRES_URI_SUPERTOKENSSplit into separate database connections
ALEMBIC_CFG_PATHALEMBIC_CFG_PATH_CORE, ALEMBIC_CFG_PATH_TRACINGSplit 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:

  1. Update your environment file with the new variable names
  2. Remove the deprecated variables from your configuration
  3. 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​

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

Getting Help​

For configuration assistance: