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.

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_COMPLETION_IMAGE_NAMECompletion image nameagenta-completion
AGENTA_COMPLETION_IMAGE_TAGCompletion image taglatest
AGENTA_CHAT_IMAGE_NAMEChat image nameagenta-chat
AGENTA_CHAT_IMAGE_TAGChat 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: