Self-Hosting Configuration

Self-Hosting Configuration#

Self-hosted Agenta deployments are configured via a single .env file consumed by Docker Compose. The canonical template is hosting/docker-compose/oss/.env.oss.gh.example — copy it to .env.oss.gh and edit before first launch . A development-variant template (.env.oss.dev.example) mirrors the same structure.

The env file is passed to docker compose via --env-file :

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

The full variable reference lives in docs/docs/self-host/02-configuration.mdx.

Variable Categories#

First-party — Required#

Six variables that must be set before Agenta will function :

Variable	Purpose	Default
`AGENTA_LICENSE`	License type	`oss`
`AGENTA_API_URL`	Public API base URL (must end in `/api`)	`http://localhost/api`
`AGENTA_WEB_URL`	Public web frontend URL	`http://localhost`
`AGENTA_SERVICES_URL`	Public services URL	`http://localhost/services`
`AGENTA_AUTH_KEY`	Signs internal tokens / admin API auth	`replace-me` ⚠️
`AGENTA_CRYPT_KEY`	Encrypts stored secrets (e.g. LLM keys)	`replace-me` ⚠️

Generate both keys with openssl rand -hex 32 before going to production.

Changing the URL variables together — when you expose Agenta on a non-default port or domain, all three URL variables (AGENTA_API_URL, AGENTA_WEB_URL, AGENTA_SERVICES_URL) plus the Traefik variables must be updated consistently .

First-party — Registry & Service#

Variable	Purpose	Default
`DOCKER_NETWORK_MODE`	Docker networking mode	`bridge`
`POSTGRES_PASSWORD`	PostgreSQL password	`password` ⚠️
`POSTGRES_USERNAME`	PostgreSQL username	`username`

First-party — Optional#

Variable	Purpose	Default
`AGENTA_AUTO_MIGRATIONS`	Run DB migrations on startup	`true`
`AGENTA_TELEMETRY_ENABLED`	Anonymous usage telemetry	`true`
`AGENTA_API_INTERNAL_URL`	Internal API URL reachable from other containers	(empty)
`AGENTA_SERVICE_MIDDLEWARE_CACHE_ENABLED`	Cache vault/secret middleware results per request	`true`
`AGENTA_OTLP_MAX_BATCH_BYTES`	Max OTLP payload before 413 rejection	`10485760` (10 MB)
`AGENTA_SEND_EMAIL_FROM_ADDRESS`	From address for system emails	`mail@example.com`
`AGENTA_RUNTIME_PREFIX`	Prefix for runtime containers	(empty)

Third-party Infrastructure (Required)#

These point Agenta at the infrastructure services it depends on :

Traefik (Reverse Proxy)#

Variable	Default
`TRAEFIK_DOMAIN`	`localhost`
`TRAEFIK_PORT`	`80`
`TRAEFIK_HTTPS_PORT`	`443`
`TRAEFIK_UI_PORT`	`8080`

PostgreSQL (three separate databases)#

Variable	Example
`POSTGRES_URI_CORE`	`postgresql+asyncpg://username:password@postgres:5432/agenta_oss_core`
`POSTGRES_URI_TRACING`	`postgresql+asyncpg://username:password@postgres:5432/agenta_oss_tracing`
`POSTGRES_URI_SUPERTOKENS`	`postgresql://username:password@postgres:5432/agenta_oss_supertokens`

Redis, RabbitMQ, Celery#

Variable	Default
`REDIS_URL`	`redis://redis:6379/0`
`RABBITMQ_DEFAULT_USER` / `_PASS`	`guest` / `guest` ⚠️
`CELERY_BROKER_URL`	`amqp://guest@rabbitmq//`
`CELERY_RESULT_BACKEND`	`redis://redis:6379/0`

SuperTokens (Authentication)#

Variable	Default
`SUPERTOKENS_CONNECTION_URI`	`http://supertokens:3567`
`SUPERTOKENS_API_KEY`	(empty)

Third-party — Optional Integrations#

OAuth Providers#

Variable	Purpose
`GOOGLE_OAUTH_CLIENT_ID` / `_SECRET`	Google SSO
`GITHUB_OAUTH_CLIENT_ID` / `_SECRET`	GitHub SSO

Email & Communication#

Variable	Purpose
`SENDGRID_API_KEY`	Transactional email
`LOOPS_API_KEY`	Loops email automation
`CRISP_WEBSITE_ID`	In-app chat

Monitoring & Analytics#

Variable	Purpose
`POSTHOG_API_KEY`	Product analytics
`NEW_RELIC_LICENSE_KEY` / `NRIA_LICENSE_KEY`	New Relic APM

LLM Provider API Keys#

Set server-side defaults so all users on the deployment share them without configuring their own :

OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, COHERE_API_KEY, MISTRAL_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, DEEPINFRA_API_KEY, TOGETHERAI_API_KEY, PERPLEXITYAI_API_KEY, ANYSCALE_API_KEY, ALEPHALPHA_API_KEY

These are read by VaultMiddleware as environment-level fallbacks that are overridden by per-user vault entries .

SSL / TLS#

For HTTPS, use docker-compose.gh.ssl.yml and set :

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

Configuration Examples#

Local (default port 80):

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

Remote server / custom domain:

AGENTA_API_URL=https://agenta.mydomain.com/api
AGENTA_WEB_URL=https://agenta.mydomain.com
TRAEFIK_DOMAIN=agenta.mydomain.com

IP address (no domain):

AGENTA_API_URL=http://192.168.1.100/api
AGENTA_WEB_URL=http://192.168.1.100
TRAEFIK_DOMAIN=192.168.1.100

Deprecated Variables#

These still work but emit warnings; migrate before they are removed :

Deprecated	Replace With
`DOMAIN_NAME`	`AGENTA_API_URL`
`WEBSITE_DOMAIN_NAME`	`AGENTA_WEB_URL`
`BARE_DOMAIN_NAME`	`TRAEFIK_DOMAIN`
`AGENTA_PORT`	`TRAEFIK_PORT`
`SERVICE_URL_TEMPLATE`	`AGENTA_SERVICES_URL`
`POSTGRES_URI`	`POSTGRES_URI_CORE` + `POSTGRES_URI_TRACING` + `POSTGRES_URI_SUPERTOKENS`
`ALEMBIC_CFG_PATH`	`ALEMBIC_CFG_PATH_CORE` + `ALEMBIC_CFG_PATH_TRACING`

Key Source Files#

File	Purpose
`hosting/docker-compose/oss/.env.oss.gh.example`	Authoritative template for all env vars
`docs/docs/self-host/02-configuration.mdx`	Prose reference with descriptions and examples
`docs/docs/self-host/01-quick-start.mdx`	Minimal setup steps (copy, edit, launch)
`hosting/docker-compose/oss/docker-compose.gh.yml`	Main Docker Compose deployment
`hosting/docker-compose/oss/docker-compose.gh.ssl.yml`	SSL-enabled variant