TLS certificates

atreoAGENT automatically obtains and renews wildcard TLS certificates from Let’s Encrypt. The same flow covers the default *.<yourname>.atreo.link subdomain and any custom domain you’ve attached.

How it works (default subdomain)

1. The agent generates an ACME account key on first startup.
2. It registers with Let’s Encrypt using the email from your config.
3. It requests a wildcard certificate for *.<yourname>.atreo.link.
4. The DNS-01 challenge is completed through atreoLINK’s DNS relay. The agent sends the challenge token to atreoLINK, which sets the _acme-challenge TXT record in the operator-controlled zone.
5. The certificate and key are saved to the certs/ directory.

How it works (custom domain)

When you’ve attached a custom domain, the same flow runs for *.your-domain.com, with one extra hop in DNS:

1. The user adds two CNAMEs at their registrar: *.your-domain.com to tunnel.atreo.link, and _acme-challenge.your-domain.com to acme.<deviceId>.atreo.link.
2. The agent requests a certificate for *.your-domain.com.
3. atreoLINK writes the ACME TXT into the acme.<deviceId>.atreo.link zone (which atreoLINK controls).
4. Let’s Encrypt follows the CNAME chain from _acme-challenge.your-domain.com to atreoLINK’s zone and validates the TXT.
5. The agent receives the certificate.

atreoLINK never needs API access to the user’s DNS zone; the CNAMEs delegate the challenge.

Certificate files

The ACME account key lives in the agent’s keys/ directory (alongside the device and WireGuard private keys); per-suffix certificates and registration metadata live under certs/<suffix>/:

File	Contents
keys/acme_account.key	ACME account private key (PEM).
certs/<suffix>/registration.json	ACME registration metadata for this suffix.
certs/<suffix>/fullchain.pem	TLS certificate (full chain).
certs/<suffix>/privkey.pem	TLS private key (PEM).

When a custom domain is active, the agent serves both the legacy <yourname>.atreo.link cert and the custom-domain cert via SNI dispatch; each suffix has its own subdirectory. The browser sees the right certificate based on the hostname it asks for.

On load, the agent parses each certificate and refuses to use it if its SANs don’t include *.<suffix> for the registered suffix. A swapped-on-disk cert can’t quietly take over a suffix.

Auto-renewal

The agent checks certificate expiration daily. If a certificate expires within 30 days, it initiates a renewal using the same DNS-01 flow.

If renewal fails for the same suffix three consecutive runs (roughly three days), the agent sends a push notification to the owner so a DNS or registrar problem is noticed before the cert actually expires. See Custom domains → Renewal failures for the operator-facing detail.

CNAME-delegated DNS-01 propagation

When validating a CNAME-delegated challenge, the agent’s pre-check has to follow the CNAME to atreoLINK’s zone rather than the user’s. The agent uses public DNS (1.1.1.1, 8.8.8.8) for this lookup.

Using certificates with external proxies

If you use your own reverse proxy (Caddy, Traefik, nginx), you can reference the agent’s certificates directly. With the recommended bind-mount layout, they’re on the host at:

./agent-data/certs/fullchain.pem
./agent-data/certs/privkey.pem

Caution

If you’re running the proxy in a separate Docker container, bind-mount the same directory read-only:

volumes:
  - /path/to/agent-data/certs:/atreo-certs:ro

DNS-01 vs HTTP-01

atreoAGENT uses DNS-01 (not HTTP-01) because:

• It supports wildcard certificates (one cert for all apps).
• It doesn’t require port 80 to be publicly accessible.
• The challenge is completed through atreoLINK’s DNS relay (or the CNAME delegation for custom domains), so no inbound connections are needed.