Agent Deployment

The Atrium Agent runs as a single Docker container on your local network. It has no external dependencies — no database, no runtime, no additional services. Everything it needs is contained in the container image.

Prerequisites

• Docker Engine 24+ on a Linux host (or any system running Docker).
• Network connectivity to:
  • Your WiFi controller(s) — for RADIUS traffic (UDP port 1812 for authentication, 1813 for accounting).
  • Your firewall — for CoA/DM (UDP port 3799) or vendor REST API (HTTPS).
  • The Atrium Server — for WebSocket communication (outbound HTTPS/WSS).
• A registered agent in your Atrium instance (mTLS certificate pair).

Deployment

The Agent is distributed as a container image via ghcr.io/sprocksystems/atrium-agent.

docker run -d \
  --name atrium-agent \
  --restart unless-stopped \
  -p 1812:1812/udp \
  -p 1813:1813/udp \
  -e ATRIUM_SERVER_URL=wss://your-atrium-instance.example.com/agent/ws \
  -e ATRIUM_TENANT_ID=your-tenant-id \
  -e ATRIUM_SITE_ID=your-site-id \
  -e RADIUS_SECRET=your-radius-shared-secret \
  -v /path/to/certs:/certs:ro \
  ghcr.io/sprocksystems/atrium-agent:latest

Environment variables

Variable	Required	Description
ATRIUM_SERVER_URL	Yes	WebSocket URL of your Atrium Server's agent endpoint.
ATRIUM_TENANT_ID	Yes	Your tenant UUID.
ATRIUM_SITE_ID	Yes	The site UUID this Agent serves.
RADIUS_SECRET	Yes	RADIUS shared secret. Must match the secret configured on your WiFi controller.
RADIUS_LISTEN_ADDR	No	RADIUS listen address. Default: :1812.
TLS_CERT_FILE	Yes	Path to the client certificate for mTLS authentication.
TLS_KEY_FILE	Yes	Path to the client private key.
TLS_CA_FILE	Yes	Path to the CA certificate for server verification.

Certificate provisioning

The Agent authenticates to the Atrium Server using mutual TLS (mTLS). The certificate is issued during agent provisioning in the admin dashboard:

1. A Tenant-Admin or Site-Admin registers a new agent for a site.
2. The server generates a client certificate signed by the instance's built-in CA.
3. The certificate (cert + key + CA) is downloaded and placed on the host running the Agent container.
4. The Agent mounts the certificate directory as a read-only volume.

The certificate encodes the tenant_id and site_id. No JWT or API key is involved — the TLS handshake itself is the authentication.

One agent per site

Each site has its own Agent instance. If you have three offices, you deploy three Agents — one per office network. Each Agent only handles RADIUS requests and session management for its assigned site.

Multiple sites cannot share an Agent. The RADIUS store, firewall adapter configuration, and session tracking are all site-scoped.

Stateless and recoverable

The Agent holds active vouchers in memory. If the Agent container restarts, it reconnects to the Atrium Server and receives a full reconciliation of all active vouchers. No data is lost.

The Agent does not have a local database. It does not write to disk (except logs). All persistent state lives in the Atrium Server.

Connection lifecycle

On startup, the Agent:

1. Reads its configuration from environment variables.
2. Starts the RADIUS server on the configured port.
3. Connects to the Atrium Server via WebSocket (mTLS).
4. Sends a status event (agent.status) to announce itself.
5. Receives the current voucher set from the server (reconciliation).
6. Begins processing RADIUS requests and reporting events.

If the WebSocket connection drops (server restart, network interruption), the Agent retries automatically with exponential backoff. During disconnection:

• RADIUS continues working — the Agent authenticates against its in-memory voucher store.
• New vouchers are not received — visitors who check in while the Agent is disconnected won't get working WiFi credentials until the connection is restored.
• Events are buffered — authentication events are queued in memory (up to 10,000 messages) and sent on reconnect.

Health monitoring

The Agent reports its status to the Atrium Server every 60 seconds. The status includes uptime, active session count, RADIUS statistics (total requests, accepted, rejected), and resource usage. This data is visible in the admin dashboard's agent connection view.