Site Agents

A site agent connects one datacenter to the panel. It runs on a small Linux host inside the datacenter and:

builds a WireGuard tunnel to the panel, through which the panel reaches the BMCs, switches and PDUs of that site,
keeps the list of addresses the panel may reach in sync with the BMCs, switches and PDUs TrixOS knows at that site, and enforces it in its firewall,
serves DHCP and TFTP to servers that have an install job running, and proxies their boot files and callbacks to the panel.

The agent pulls: it sends a heartbeat to the panel every 60 seconds over HTTPS (version, tunnel state, uptime and, from version 1.3.0, CPU, load, memory and disk usage for the dashboard) and fetches its configuration. It accepts WireGuard only from the panel and nothing from the out-of-band network.

Do I need one?

You need an agent when the panel is not in the same layer-2 network as the servers it installs, which is the normal case. A panel that sits directly in the provisioning network can serve PXE itself with the Compose profile pxe (docker compose --profile pxe up -d and PXE_ENABLED=true); see Safety switches.

Install an agent

Prepare a Debian or Ubuntu host with one interface in the network your servers PXE-boot from (default eth0) and one in the out-of-band network (default eth1). Then, in System → Agents, choose Install agent for the site (or Reinstall in its menu). The panel can install it for you over SSH, or give you a command to run.

Over SSH

Enter the host (name or IP the panel can reach) and the SSH port, then Check host key. The panel connects only far enough to read the host’s key and shows its fingerprint (SHA256:…). Compare it on the host, e.g. ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub, and tick The fingerprint matches. Nothing is sent before this step.
Enter the user — root, or a user with sudo — and its password, or a private key (with its passphrase). With a key and a user other than root, sudo must work without a password (NOPASSWD).
Install agent starts a job: the panel logs in (only if the host key is still the one you confirmed), runs the installer as root with a fresh one-time token and shows its output in the dialog. The job ends when the agent has registered and sent its first report; it also appears under Jobs as Agent install (SSH).

The panel remembers the confirmed key for the site. If a later installation meets a different key, it warns you and goes on only after you confirm that the host was replaced or reinstalled. The password or key is used only for this job: it is kept encrypted in the job until the job ends, then deleted; it is never stored with the site and never written to a log. The installer’s output is logged with password and token masked.

With a command

Choose Run a command in the dialog. The panel shows a command with a one-time token that is valid for one hour.
Run the command as root on the agent host:
Terminal window
```
curl -fsSL https://panel.example.com/agent/install.sh | bash -s -- --panel https://panel.example.com --token <site>.<token>
```
Options: --public-if IF (interface the servers PXE-boot from), --oob-if IF (interface in the BMC network), --panel-ip IP (the panel’s address for WireGuard, needed when the panel’s DNS name points to a proxy or CDN).
On a new host, the installer creates a WireGuard key and prints two commands: one puts the panel’s public key into /etc/wireguard/wg0.conf on the agent, the other adds the agent as a peer on the panel (the installer prints it with the real values):
Terminal window
```
wg set wg0 peer <agent public key> endpoint <agent address>:51820 allowed-ips <agent tunnel address>/32,<oob network>
```
System → Agents shows the agent online within a minute, with its last heartbeat, the tunnel handshake and how many forwarding targets it has.

System → Agents lists every site as a row: state, name, host and version, CPU / memory / disk, the last report and the actions. Click a row to open its details (reasons for its state, usage graphs, public IP, uptime, tunnel, forwarding targets, PXE); which rows are open is remembered in your browser. Search and paging appear once there are many sites.

The installer adds the packages it needs (wireguard-tools, nftables, dnsmasq-base, ipxe, nginx, curl, python3) and installs the systemd service trixos-agent.

How PXE works with an agent

When a job needs PXE (install, rescue, hardware collection, disk wipe, password reset):

The job arms PXE for the server’s MAC address. The agent starts its DHCP/TFTP service for exactly that MAC; every other DHCP request is ignored.
The job waits until the agent confirms that it serves the MAC, sets the server’s next boot to PXE and power-cycles it.
The server gets its address and iPXE from the agent and loads its boot script, kernels and installer files over HTTP from the agent, which forwards them through the tunnel to the panel. The panel caches the boot files.
When the job finishes, PXE is disarmed and the agent stops answering that server.

The agent’s line in System → Agents shows the PXE state: ready with the boot-file URL, the number of armed jobs it is serving, or the problem that stops it. From agent version 1.2.0 the agent also reports the DHCP and TFTP events of each armed server, including PXE attempts from other NICs, which the job page shows as a boot timeline (PXE diagnosis).

Commands on the agent host

Command	What it does
`trixos-agent status`	Version, WireGuard state and forwarding targets as JSON
`trixos-agent version`	Installed agent version
`trixos-agent export [FILE]`	Identity bundle for moving the agent (Move a site agent)
`systemctl status trixos-agent`	Service state; logs with `journalctl -u trixos-agent`

Addresses below the line # --- local --- in /etc/trixos/bmc-allowed.txt are kept as manual extras; the lines above it are managed by the panel.

Remove an agent or a site

System → Agents → ⋯ → Remove agent revokes the agent’s token: the agent can no longer report or forward, and servers at that site are reached directly until an agent is installed again. Then stop it on its host with systemctl disable --now trixos-agent wg-quick@wg0. Delete site works once the agent is removed and no servers, racks, subnets, switches or PDUs belong to the site any more.