A single Docker image for running the Agentio Gateway with three deployment modes:

Export your agentio configuration locally:

agentio config export

This outputs two environment variables:

• AGENTIO_KEY - Encryption key (64 hex characters)
• AGENTIO_CONFIG - Encrypted configuration blob

From the repository root:

docker build -f docker/Dockerfile -t agentio-gateway .

Best for: Servers behind NAT, home labs, no public IP needed.

1. Create a tunnel in Cloudflare Zero Trust Dashboard
2. Configure the tunnel to point to http://localhost:7890
3. Copy the tunnel token

docker run -d \
  --name agentio-gateway \
  -e AGENTIO_KEY=your_key_here \
  -e AGENTIO_CONFIG=your_config_here \
  -e CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiYWNj... \
  -v agentio-data:/data \
  --restart unless-stopped \
  agentio-gateway

Best for: VPS or server with public IP and domain name.

Requirements:

• Port 443 accessible from the internet
• DNS A record pointing to your server

docker run -d \
  --name agentio-gateway \
  -e AGENTIO_KEY=your_key_here \
  -e AGENTIO_CONFIG=your_config_here \
  -e DOMAIN=gateway.example.com \
  -p 443:443 \
  -v agentio-data:/data \
  -v agentio-certs:/certs \
  --restart unless-stopped \
  agentio-gateway

Caddy automatically obtains and renews Let's Encrypt certificates using TLS-ALPN-01 challenge (no port 80 needed).

Best for: Local development, testing, or behind an external reverse proxy.

docker run -d \
  --name agentio-gateway \
  -e AGENTIO_KEY=your_key_here \
  -e AGENTIO_CONFIG=your_config_here \
  -p 7890:7890 \
  -v agentio-data:/data \
  --restart unless-stopped \
  agentio-gateway

The container includes a health check on the /health endpoint:

docker inspect --format='{{.State.Health.Status}}' agentio-gateway

# View logs
docker logs agentio-gateway

# Follow logs
docker logs -f agentio-gateway

docker pull agentio-gateway:latest
docker stop agentio-gateway
docker rm agentio-gateway
# Re-run with same docker run command

If you're using WhatsApp and need to pair a new device:

1. Ensure the gateway is running and accessible
2. Access the pairing endpoint: GET /whatsapp/pair/{profile}
3. Scan the QR code with WhatsApp

For remote gateways, you can use teleport to migrate existing WhatsApp sessions:

# On your local machine with an authenticated WhatsApp session
agentio gateway teleport https://your-gateway.example.com

Verify your environment variables are set correctly:

docker exec agentio-gateway env | grep AGENTIO

Check cloudflared logs:

docker logs agentio-gateway 2>&1 | grep cloudflared

Ensure:

• Port 443 is accessible from the internet
• DNS is correctly configured
• Domain resolves to your server's IP

Check Caddy logs:

docker logs agentio-gateway 2>&1 | grep caddy

Check if the gateway process is running:

docker exec agentio-gateway ps aux