Skip to main content

Configuration of Environment Variables

This guide lists the env vars in the same order as the .example files in hosting/docker-compose. These variables control various aspects of the platform, from core functionality to third-party integrations.

Kubernetes / Helm

If you deployed Agenta using the Helm chart, configuration is done through values.yaml rather than environment variables. See the Deploy on Kubernetes guide for the full Helm values reference. The environment variables listed below still apply — the Helm chart maps its values to the same variables internally.

Configuration file location​

Defaults live in hosting/docker-compose/*/env.*.example. Use --env-file to point to your own file.

Environment file sections (in file order)​

Agenta - License​

Controls OSS vs EE behavior and defaults.

VariablePurposeDefault
AGENTA_LICENSELicense type (oss or ee)oss

Agenta - Secrets​

Used for internal authorization and encryption. Change in production.

VariablePurposeDefault
AGENTA_AUTH_KEYAuthorization keyreplace-me
AGENTA_CRYPT_KEYEncryption keyreplace-me

Agenta - Endpoints​

Public URLs and internal API URL.

VariablePurposeDefault
AGENTA_WEB_URLWeb URLhttp://localhost
AGENTA_API_URLAPI URLhttp://localhost/api
AGENTA_SERVICES_URLServices URLhttp://localhost/services
AGENTA_API_INTERNAL_URLInternal API URL(empty)

Agenta - Images​

Override Docker image names or tags.

VariablePurposeDefault
AGENTA_WEB_IMAGE_NAMEWeb image nameagenta-web
AGENTA_WEB_IMAGE_TAGWeb image taglatest
AGENTA_API_IMAGE_NAMEAPI image nameagenta-api
AGENTA_API_IMAGE_TAGAPI image taglatest
AGENTA_SERVICES_IMAGE_NAMEServices image nameagenta-services
AGENTA_SERVICES_IMAGE_TAGServices image taglatest

Agenta - OTLP​

Tracing batch size limit.

VariablePurposeDefault
AGENTA_OTLP_MAX_BATCH_BYTESMax OTLP batch bytes10485760

Agenta - API​

Basic backend options.

VariablePurposeDefault
AGENTA_DEMOSEnable demos(empty)
AGENTA_ALLOWED_DOMAINSAllowed email domains(empty)

Agenta - Services​

Middleware cache and sandbox runner.

VariablePurposeDefault
AGENTA_SERVICES_MIDDLEWARE_CACHE_ENABLEDEnable cachetrue
AGENTA_SERVICES_SANDBOX_RUNNERlocal or daytonalocal

Network - Traefik​

Reverse proxy and TLS settings.

VariablePurposeDefault
TRAEFIK_PROTOCOLhttp or httpshttp
TRAEFIK_DOMAINHostnamelocalhost
TRAEFIK_PORTHTTP port80
TRAEFIK_UI_PORTDashboard port8080
TRAEFIK_HTTPS_PORTHTTPS port443
TRAEFIK_SSL_DIRSSL cert dir/home/user/ssl_certificates

Network - Nginx​

Only used if you enable Nginx.

VariablePurposeDefault
NGINX_PORTNginx port80

Docker - Compose​

Project name affects container naming.

VariablePurposeDefault
COMPOSE_PROJECT_NAMECompose project nameagenta-oss-dev

Databases - Postgres​

User, password, ports, and connection strings.

VariablePurposeDefault
POSTGRES_USERDB userusername
POSTGRES_PASSWORDDB passwordpassword
POSTGRES_PORTDB port5432
POSTGRES_URI_CORECore DB URIpostgresql+asyncpg://username:password@postgres:5432/agenta_oss_core
POSTGRES_URI_TRACINGTracing DB URIpostgresql+asyncpg://username:password@postgres:5432/agenta_oss_tracing
POSTGRES_URI_SUPERTOKENSSuperTokens DB URIpostgresql://username:password@postgres:5432/agenta_oss_supertokens

Databases - Alembic (migrations)​

Controls migrations and config paths.

VariablePurposeDefault
ALEMBIC_AUTO_MIGRATIONSAuto migrationstrue
ALEMBIC_CFG_PATH_CORECore alembic path/app/oss/databases/postgres/migrations/core/alembic.ini
ALEMBIC_CFG_PATH_TRACINGTracing alembic path/app/oss/databases/postgres/migrations/tracing/alembic.ini

Databases - Redis​

Use one Redis or split to volatile/durable.

VariablePurposeDefault
REDIS_URISingle Redis URIredis://redis:6379/0
REDIS_URI_VOLATILEVolatile Redis URIredis://redis-volatile:6379/0
REDIS_URI_DURABLEDurable Redis URIredis://redis-durable:6381/0

Authentication - SuperTokens​

Auth service connection and email auth toggle.

VariablePurposeDefault
SUPERTOKENS_API_KEYSuperTokens API key(empty)
SUPERTOKENS_CONNECTION_URISuperTokens URLhttp://supertokens:3567
SUPERTOKENS_EMAIL_DISABLEDDisable email authfalse

Authentication - Email providers​

Used for email login (OTP).

VariablePurposeDefault
SENDGRID_API_KEYSendGrid key(empty)
SENDGRID_FROM_ADDRESSSendGrid sender(empty)

Authentication - OIDC providers​

Set the provider pairs you use.

VariablePurpose
GOOGLE_OAUTH_CLIENT_IDGoogle client ID
GOOGLE_OAUTH_CLIENT_SECRETGoogle client secret
GOOGLE_WORKSPACES_OAUTH_CLIENT_IDGoogle Workspaces client ID
GOOGLE_WORKSPACES_OAUTH_CLIENT_SECRETGoogle Workspaces client secret
GOOGLE_WORKSPACES_HDGoogle Workspaces hosted domain
GITHUB_OAUTH_CLIENT_IDGitHub client ID
GITHUB_OAUTH_CLIENT_SECRETGitHub client secret
APPLE_OAUTH_CLIENT_IDApple client ID
APPLE_OAUTH_CLIENT_SECRETApple client secret
APPLE_KEY_IDApple key ID
APPLE_TEAM_IDApple team ID
APPLE_PRIVATE_KEYApple private key
DISCORD_OAUTH_CLIENT_IDDiscord client ID
DISCORD_OAUTH_CLIENT_SECRETDiscord client secret
FACEBOOK_OAUTH_CLIENT_IDFacebook client ID
FACEBOOK_OAUTH_CLIENT_SECRETFacebook client secret
GITLAB_OAUTH_CLIENT_IDGitLab client ID
GITLAB_OAUTH_CLIENT_SECRETGitLab client secret
GITLAB_BASE_URLGitLab base URL
BITBUCKET_OAUTH_CLIENT_IDBitbucket client ID
BITBUCKET_OAUTH_CLIENT_SECRETBitbucket client secret
LINKEDIN_OAUTH_CLIENT_IDLinkedIn client ID
LINKEDIN_OAUTH_CLIENT_SECRETLinkedIn client secret
OKTA_OAUTH_CLIENT_IDOkta client ID
OKTA_OAUTH_CLIENT_SECRETOkta client secret
OKTA_DOMAINOkta domain
AZURE_AD_OAUTH_CLIENT_IDAzure AD client ID
AZURE_AD_OAUTH_CLIENT_SECRETAzure AD client secret
AZURE_AD_DIRECTORY_IDAzure AD directory ID
BOXY_SAML_OAUTH_CLIENT_IDBoxyHQ SAML client ID
BOXY_SAML_OAUTH_CLIENT_SECRETBoxyHQ SAML client secret
BOXY_SAML_URLBoxyHQ SAML URL
TWITTER_OAUTH_CLIENT_IDTwitter client ID
TWITTER_OAUTH_CLIENT_SECRETTwitter client secret

Billing - Stripe [ee-only]​

Only for EE deployments.

VariablePurposeDefault
STRIPE_API_KEYStripe API key(empty)
STRIPE_WEBHOOK_SECRETStripe webhook secret(empty)
STRIPE_WEBHOOK_TARGETStripe webhook target(empty)
STRIPE_PRICINGStripe pricing JSON(empty)

Proxy - LLM Providers​

API keys for the LLM proxy.

VariablePurpose
OPENAI_API_KEYOpenAI key
ANTHROPIC_API_KEYAnthropic key
COHERE_API_KEYCohere key
GROQ_API_KEYGroq key
GEMINI_API_KEYGemini key
MISTRAL_API_KEYMistral key
ALEPHALPHA_API_KEYAleph Alpha key
ANYSCALE_API_KEYAnyscale key
DEEPINFRA_API_KEYDeepInfra key
OPENROUTER_API_KEYOpenRouter key
PERPLEXITYAI_API_KEYPerplexity key
TOGETHERAI_API_KEYTogether key

Sandbox - Daytona​

Used when AGENTA_SERVICES_SANDBOX_RUNNER=daytona.

VariablePurposeDefault
DAYTONA_API_KEYDaytona API key(empty)
DAYTONA_API_URLDaytona API URLhttps://app.daytona.io/api
DAYTONA_TARGETRegion (AGENTA_REGION or eu)eu
DAYTONA_SNAPSHOTSnapshot IDdaytona-small

Analytics - PostHog​

Analytics key for OSS.

VariablePurposeDefault
POSTHOG_API_KEYPostHog keyphc_xxxxxxxx

Self-hosting basics​

  • Pick a file: hosting/docker-compose/oss/env.oss.dev.example (development) or hosting/docker-compose/oss/env.oss.gh.example. EE has matching env.ee.*.example.
  • Copy it and edit the values you need.
  • Use it with 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

Key environments variables for self-hosting:

  • AGENTA_LICENSE
  • AGENTA_AUTH_KEY
  • AGENTA_CRYPT_KEY
  • AGENTA_WEB_URL
  • AGENTA_API_URL
  • AGENTA_SERVICES_URL
  • AGENTA_API_INTERNAL_URL
  • TRAEFIK_PROTOCOL
  • TRAEFIK_DOMAIN
  • TRAEFIK_PORT
  • TRAEFIK_HTTPS_PORT
  • TRAEFIK_SSL_DIR
  • POSTGRES_URI_CORE
  • POSTGRES_URI_TRACING
  • POSTGRES_URI_SUPERTOKENS
  • REDIS_URI (or REDIS_URI_VOLATILE + REDIS_URI_DURABLE)

Deprecated variables​

These are deprecated and will be removed later:

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
TRAEFIK_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: