Environment variables

Every config field has an environment-variable equivalent. This is the recommended way to configure the agent in Docker. Env vars win over YAML, and you don’t have to mount and edit a config file inside the container.

Variable reference

Variable	Default	Description
LOG_LEVEL	info	Log verbosity: debug, info, warn (or warning), error. Case-insensitive. Unrecognised value fails startup.
DATA_DIR	/var/lib/atreoagent	Persistent data directory.
WG_PORT	51820	WireGuard UDP listen port.
WG_FIREWALL_ENABLED	true	Confine tunnel peers to the proxy ports plus any granted exposed-port app ports, on both IPv4 and IPv6. Fails closed: if iptables/ip6tables is unavailable or the rules can’t be applied, the agent refuses to start. Set false only if you genuinely can’t run them (exposes every 0.0.0.0/::-bound host port to every paired peer; discouraged).
WG_UPNP_ENABLED	true	Master switch for automatic inbound-port opening (PCP, NAT-PMP, UPnP, and the IPv6 firewall pinhole). If disabled or unsupported, set up a manual port forward instead.
WG_PCP_ENABLED	true	Try PCP (RFC 6887) first when opening the port, for both IPv4 and IPv6. Set false to skip PCP and use only NAT-PMP/UPnP. Accepts true/false/1/0.
WG_IPV6_PINHOLE_ENABLED	true	Open an IPv6 firewall pinhole for the WireGuard port so the AAAA endpoint is reachable. Set false to manage the gateway firewall manually. Accepts true/false/1/0.
ENDPOINT_IP	(auto-detected)	Public IP override. Normally unset; atreoLINK detects your IP from the agent’s connection.
ENDPOINT_PORT	(auto-detected)	Public port override.
RELAY_ENABLED	true	Use the CGNAT relay as a fallback when the agent has no reachable public inbound path. Automatic and fallback-only — direct paths always win. Set false to opt this agent out of relaying entirely.
RELAY_FORCE	false	Keep a relay session up even when a direct path exists, so a relay endpoint is always available to hand to clients (clients still prefer LAN/direct). Useful for offering a relay config alongside a direct one; not needed for normal use.
PROXY_ENABLED	true	Enable the built-in HTTPS reverse proxy.
PROXY_HTTP_PORT	80	HTTP port.
PROXY_HTTPS_PORT	443	HTTPS port.
PROXY_AUTH_PORT	9091	Forward-auth endpoint port.
PROXY_TRUSTED_PROXIES	(empty)	Comma-separated CIDRs of external proxies allowed to set X-Forwarded-For / X-Forwarded-Host. See Forward auth.
NOTIFY_PORT	9876	Notification API port.
SMTP_ENABLED	false	Enable the built-in SMTP server.
SMTP_LISTEN	0.0.0.0:2525	SMTP bind address.
SMTP_CATCH_ALL	(empty)	Fallback recipient for mail whose RCPT TO matches no member. Must be an existing member’s atreoLINK email; if it isn’t a member, unknown mail is still rejected and a warning is logged. Empty (default) rejects unknown recipients with 550. See Catch-all recipient.
SMTP_MAX_MESSAGE_BYTES	1048576	Max accepted SMTP message size in bytes.
SMTP_RATE_PER_MINUTE	50	Per-source-IP SMTP rate limit.
SMTP_TLS_ENABLED	false	Advertise STARTTLS using a self-signed cert (TLS 1.3). See STARTTLS.
SMTP_TRUSTED_NETWORKS	loopback + RFC1918 + link-local + ULA + tunnel subnet	Comma-separated CIDRs allowed to connect to the SMTP gateway. Source IPs outside the list are rejected before AUTH. See Source-IP allowlist for the full default list.

Note

proxy.trusted_networks (the reverse-proxy ACL bypass) is YAML-only — there’s no env-var override. The separate smtp.trusted_networks allowlist does have one: SMTP_TRUSTED_NETWORKS. Everything else in the config file has a matching env var.

Usage with Docker Compose

services:
  atreoagent:
    image: ghcr.io/atreolabs/atreoagent:latest
    container_name: atreoagent
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    environment:
      - PROXY_ENABLED=false       # Use your own reverse proxy
      - WG_PORT=51821             # Custom WireGuard port
      - ENDPOINT_IP=203.0.113.10  # Static public IP
      - ENDPOINT_PORT=51821       # Static public port
      - SMTP_ENABLED=true         # Enable LAN SMTP gateway
      - SMTP_LISTEN=192.168.1.10:2525  # Bind to LAN only
    volumes:
      - ./agent-data:/var/lib/atreoagent

Router without UPnP/NAT-PMP

atreoLINK detects your public IP from the agent’s authenticated connection and keeps the DDNS record current. If your router has no UPnP/NAT-PMP (or you turn it off), forward the WireGuard UDP port manually; the tunnel works as soon as the port is reachable:

WG_UPNP_ENABLED=false   # optional: stop the agent attempting auto port-mapping

Note

Set endpoint_ip / ENDPOINT_IP only for CGNAT or proxied setups where the auto-detected address is wrong. When set it takes precedence over the detected address.

See Manual port forwarding for the full walkthrough.

SMTP server

The built-in SMTP server lets self-hosted apps that only support email notifications deliver them through atreoLINK as encrypted push notifications. Off by default. See Built-in SMTP server.

SMTP_ENABLED=true
SMTP_LISTEN=192.168.1.10:2525

Danger

Never forward port 2525 through your router, and don’t widen SMTP_TRUSTED_NETWORKS to public IP space. The gateway binds 0.0.0.0:2525 by default and rejects any source IP outside its allowlist before AUTH — the allowlist, not the bind address, is what keeps the gateway LAN-only. TLS is off by default; with SMTP_TLS_ENABLED=true the AUTH exchange is encrypted via STARTTLS, but the cert is self-signed. See Built-in SMTP server.

Precedence

Resolution order, later wins:

1. Built-in defaults.
2. Values in config.yaml (if the file exists).
3. Environment variables.

The config file remains the source of pairing-derived data (device_token, device_id, apps_hostname). Env vars are for tunables, not pairing data.