Networking Configuration

This guide explains Agenta's network topology, how containers communicate with each other, and the environment variables that control networking behavior and connectivity.

Network Topology

Agenta uses a Docker-based network architecture with a dedicated bridge network for container communication and Traefik as the reverse proxy for external access.

                        ┌─────────────────────────────────────┐
                        │            External Users           │
                        └─────────────────┬───────────────────┘
                                          │ HTTPS/HTTP
                        ┌─────────────────▼───────────────────┐
                        │        Host Server (80/443)         │
                        └─────────────────┬───────────────────┘
                                          │
┌─────────────────────────────────────────▼───────────────────────────────────┐
│                           agenta-network (bridge)                           │
│                                                                             │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                      Traefik (Reverse Proxy)                          │  │
│  │              HTTP: 80 -> HTTPS: 443 -> Dashboard: 8080               │  │
│  │                   SSL termination and routing                         │  │
│  └─┬─────────────────────┬─────────────────────┬─────────────────────────┘  │
│    │                     │                     │                            │
│    │ /                   │ /api/               │ /services/                  │
│    ▼                     ▼                     ▼                            │
│  ┌─────────────┐  ┌─────────────┐   ┌────────────────────┐                 │
│  │     Web     │  │     API     │   │   Services API     │                 │
│  │   :3000     │  │   :8000     │   │      :80           │                 │
│  └─────────────┘  └──────┬──────┘   └────────────────────┘                 │
│                          │                                                  │
│                          │ Redis queues / streams                           │
│                          ▼                                                  │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                            Worker Pool                               │   │
│  │   worker-evaluations, worker-tracing, worker-webhooks,              │   │
│  │   worker-events, cron                                                 │   │
│  └─────────────────────────┬────────────────────────────────────────────┘   │
│                            │                                                │
│                            ▼                                                │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                     Infrastructure Layer                             │   │
│  │                                                                      │   │
│  │ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐    │   │
│  │ │   PostgreSQL      │ │      Redis        │ │   SuperTokens     │    │   │
│  │ │     :5432         │ │   :6379 / :6381   │ │      :3567        │    │   │
│  │ │ Core + Tracing DB │ │ queues + caching   │ │ auth + sessions   │    │   │
│  │ └───────────────────┘ └───────────────────┘ └───────────────────┘    │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Container Communication Patterns

External Access Flow

Internet → Traefik (80/443) → Internal Services
├── / → web:3000 (Frontend)
├── /api/ → api:8000 (Backend API)
└── /services/ → services:80 (includes completion/chat endpoints)

Internal Service Communication

Web Container:
├── → api:8000 (Backend API calls)
└── → services:80 (Playground and model interaction endpoints)

API Container:
├── → postgres:5432 (Database operations)
├── → redis-volatile:6379, redis-durable:6381 (queues, streams, caching)
├── → supertokens:3567 (Authentication)
└── → worker pool (Task delegation via queues/streams)

Worker Pool:
├── → redis-volatile:6379, redis-durable:6381 (task and event consumption)
├── → postgres:5432 (Data access)
├── → api:8000 (coordination and shared backend logic)
└── → external webhook destinations (worker-webhooks)

Network Environment Variables

External Access Configuration

These variables control how external users access Agenta:

Variable	Purpose	Example	Description
`TRAEFIK_DOMAIN`	Domain routing	`localhost`, `agenta.mydomain.com`	Primary domain for routing
`TRAEFIK_PORT`	HTTP port	`80`	External HTTP port
`TRAEFIK_HTTPS_PORT`	HTTPS port	`443`	External HTTPS port
`AGENTA_API_URL`	API endpoint	`http://localhost/api`	External API URL
`AGENTA_WEB_URL`	Frontend URL	`http://localhost`	External frontend URL
`AGENTA_SERVICES_URL`	Services URL	`http://localhost/services`	External services URL template
`AGENTA_API_INTERNAL_URL`	Internal API URL between services and backend	`http://api:8000/api`	Internal API URL
`DOCKER_NETWORK_MODE`	Docker network mode hint for runtime URL logic	`bridge`	Should be `bridge` for compose-based deployments

Internal Service Communication

These variables configure how containers communicate internally. Use REDIS_URI for a single Redis instance, or split with the volatile/durable URLs for separate caches and queues.

Variable	Purpose	Example	Description
`POSTGRES_URI_CORE`	Core database	`postgresql+asyncpg://user:pass@postgres:5432/agenta_core`	Core database connection
`POSTGRES_URI_TRACING`	Tracing database	`postgresql+asyncpg://user:pass@postgres:5432/agenta_tracing`	Tracing database connection
`POSTGRES_URI_SUPERTOKENS`	Auth database	`postgresql://user:pass@postgres:5432/agenta_supertokens`	SuperTokens database connection
`REDIS_URI`	Single Redis (fallback)	`redis://redis:6379/0`	Used when split URLs are not set
`REDIS_URI_VOLATILE`	Redis for caches/channels	`redis://redis-volatile:6379/0`	Falls back to `REDIS_URI`
`REDIS_URI_DURABLE`	Redis for queues/streams	`redis://redis-durable:6381/0`	Falls back to `REDIS_URI`
`SUPERTOKENS_CONNECTION_URI`	Auth service	`http://supertokens:3567`	SuperTokens service URL

Port Mapping (Optional)

These variables control external port exposure for direct access:

Variable	Default	Purpose	Description
`POSTGRES_PORT`	`5432`	Database access	External PostgreSQL port (development)
`NGINX_PORT`	`80`	Alternative proxy	Nginx port (when using Nginx)

Traffic Routing Rules

Traefik Routing Configuration

Frontend Routing

# Route: / → web:3000
Rule: Host(`${TRAEFIK_DOMAIN}`) && PathPrefix(`/`)
Target: web:3000
Processing: Direct forwarding
SSL: Automatic (production)

API Routing

# Route: /api/ → api:8000
Rule: Host(`${TRAEFIK_DOMAIN}`) && PathPrefix(`/api/`)
Target: api:8000
Processing: Strip `/api` prefix
Middleware: Path prefix stripping

Services Routing

# Route: /services/ -> services:80
Rule: Host(`${TRAEFIK_DOMAIN}`) && PathPrefix(`/services/`)
Target: services:80
Processing: Strip `/services` prefix

# Examples served by the same services container:
# /services/completion/* -> services:80/completion/*
# /services/chat/* -> services:80/chat/*

SSL/TLS Configuration

Development (HTTP)

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

Production (HTTPS)

TRAEFIK_PORT=80
TRAEFIK_HTTPS_PORT=443
AGENTA_SSL_DIR=/path/to/certificates
AGENTA_API_URL=https://agenta.mydomain.com/api
AGENTA_WEB_URL=https://agenta.mydomain.com

SSL Certificate Management

Automatic: Let's Encrypt via Traefik (HTTP challenge)
Storage: ${AGENTA_SSL_DIR}/acme.json
Renewal: Automatic every 60-90 days
Redirect: HTTP → HTTPS automatic

::: info Network Security The services are isolated within Docker bridge network. None of the services are exposed to the host network (except Traefik) :::

Troubleshooting Network Issues

Connection Testing

# Test database connectivity
docker exec :container-name: nc -zv postgres 5432

# Test Redis connectivity
docker exec :container-name: redis-cli -h redis-volatile -p 6379 ping
docker exec :container-name: redis-cli -h redis-durable -p 6381 ping

Port Conflicts

# Check port usage
sudo netstat -tulpn | grep :80
sudo lsof -i :443

# View container port mappings
docker ps --format "table {{.Names}}\t{{.Ports}}"

Traefik Routing Issues

# Access Traefik dashboard
http://localhost:8080

# Check Traefik logs
docker logs :container-name:

# Verify service registration
curl -s http://localhost:8080/api/http/services

DNS Resolution

# Test external domain resolution
nslookup agenta.mydomain.com
dig agenta.mydomain.com +short

# Test from multiple DNS servers
nslookup agenta.mydomain.com 8.8.8.8
nslookup agenta.mydomain.com 1.1.1.1

Network Topology​

Container Communication Patterns​

External Access Flow​

Internal Service Communication​

Network Environment Variables​

External Access Configuration​

Internal Service Communication​

Port Mapping (Optional)​

Traffic Routing Rules​

Traefik Routing Configuration​

Frontend Routing​

API Routing​

Services Routing​

SSL/TLS Configuration​

Development (HTTP)​

Production (HTTPS)​

SSL Certificate Management​

Troubleshooting Network Issues​

Connection Testing​

Port Conflicts​

Traefik Routing Issues​

DNS Resolution​

Network Topology

Container Communication Patterns

External Access Flow

Internal Service Communication

Network Environment Variables

External Access Configuration

Internal Service Communication

Port Mapping (Optional)

Traffic Routing Rules

Traefik Routing Configuration

Frontend Routing

API Routing

Services Routing

SSL/TLS Configuration

Development (HTTP)

Production (HTTPS)

SSL Certificate Management

Troubleshooting Network Issues

Connection Testing

Port Conflicts

Traefik Routing Issues

DNS Resolution