Install atreoAGENT

atreoAGENT runs in a single Docker container. The recommended deployment is via Docker Compose.

Docker Compose

1. Create a project directory on your server:

   mkdir atreoagent && cd atreoagent

2. Create docker-compose.yml:

   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
       volumes:
         - ./agent-data:/var/lib/atreoagent
         # Optional: mount the Docker socket to allow using container names in app
         # InternalURL (e.g. http://jellyfin:8096) without exposing ports.
         # The agent queries the Docker API read-only to resolve names to IPs.
         # - /var/run/docker.sock:/var/run/docker.sock:ro
       environment:
         # WireGuard port (default: 51820)
         # WG_PORT: "51820"
   
         # Auto port-mapping via NAT-PMP/UPnP (default: true). Set false if your
         # router has none and you forward the WG UDP port manually instead.
         # See /agent/manual-port-forwarding/.
         # WG_UPNP_ENABLED: "false"
   
         # Public IP OVERRIDE. Only for CGNAT/proxied control paths where the
         # auto-derived address is wrong. Leave unset in the normal case.
         # ENDPOINT_IP: ""
         # ENDPOINT_PORT: "51820"
   
         # Built-in proxy ports (defaults: 80/443/9091)
         # PROXY_HTTP_PORT: "80"
         # PROXY_HTTPS_PORT: "443"
         # PROXY_AUTH_PORT: "9091"
   
         # Disable the built-in proxy if using your own (Caddy/Traefik/nginx)
         # PROXY_ENABLED: "false"
   
         # Tunnel firewall (default: enabled). Keep it on: it fails closed, so
         # the agent refuses to start if iptables/ip6tables can't be configured.
         # Disable only if you genuinely can't run them — this exposes every host
         # port to every paired peer.
         # WG_FIREWALL_ENABLED: "false"
   
         # Built-in SMTP server (off by default; LAN only).
         # See /agent/smtp/ before enabling.
         # SMTP_ENABLED: "true"
         # SMTP_LISTEN: "192.168.1.10:2525"

   The bind mount creates an agent-data/ directory next to your docker-compose.yml. Everything the agent persists (keys, certs, ACL cache, config) lives there, so it’s easy to back up, inspect, or share with other containers.

3. Start the agent:

   docker compose up -d

4. Watch the logs for your pairing URL:

   docker logs -f atreoagent

   You’ll see something like:

   atreoAGENT v1.0.0
   Generating device keypair...
   Pairing required.
   Open this URL in a browser signed in to atreoLINK:
   https://app.atreolink.com/approve/abc123#<pair-token>
   Waiting for approval...

5. Open that URL in a browser where you’re signed in to your atreoLINK account, and approve. See Pair your server for the full walkthrough.

6. You’re done. The agent configures WireGuard, obtains wildcard TLS certificates, and starts the reverse proxy automatically.

Tip

All persistent state (keys, certificates, ACL cache, config) lives in the agent-data/ directory next to your compose file. Back it up if you ever want to migrate to different hardware. Restoring it on the new host lets the agent come up without re-pairing.

Building from source

If you’d rather build the image yourself:

git clone https://github.com/atreoLABS/atreoAGENT.git
cd atreoAGENT
docker compose up -d --build

Verifying the install

After pairing, the startup log shows the agent’s main subsystems coming online:

Device paired successfully
WireGuard interface up on 100.64.0.1/24, fd00:64::1/64 (wg-atreo)
NAT-PMP: mapped external port 51820 -> internal 51820
TLS certificate obtained for *.alice.atreo.link
HTTPS proxy listening on :443
Forward-auth listening on :9091
Notification API listening on :9876
Tunnel connected to atreoLINK

You can also check the live status with:

docker exec atreoagent atreoagent status

Listening ports

Port	Protocol	Purpose	Bound to
51820	UDP	WireGuard tunnel	0.0.0.0 (public)
80	TCP	HTTP redirect to 443	0.0.0.0
443	TCP	HTTPS reverse proxy	0.0.0.0
9091	TCP	Forward-auth endpoint	tunnel IP 100.64.0.1
9876	TCP	Notification API	0.0.0.0 (LAN reachable; bearer-token gated)
2525	TCP	SMTP-to-push gateway	configurable, off by default

The SMTP port is off unless you enable it; if you do, bind it to a LAN interface only (why).

What’s installed

After installation:

• A persistent Docker container named atreoagent.
• A bind-mounted agent-data/ directory next to your compose file containing all keys, certificates, and config.
• A WireGuard interface called wg-atreo on the host.