4. Region agent

The agent is a single Go binary on a small virtual machine inside the region. It holds the Proxmox and edge credentials and connects outbound to the control plane.

The machine

Property	Guidance
Base	Ubuntu LTS, minimal
Size	2 vCPU, 2 GB memory, 20 GB disk is comfortable
Network	Reach the Proxmox API and the edge device; outbound HTTPS to the control plane
Inbound	None. Nothing connects to it

Give it a stable address on your management network, and treat it as infrastructure — it is not a tenant resource.

Caution

Tag this machine as a platform component. The deletion job refuses to destroy a machine carrying a platform role even when told to, and that guard exists because of a real near-miss: a stale row once pointed at the identifier of a region’s own agent.

Install

# on the agent VM
sudo curl -fsSL -o /usr/local/sbin/zone9-agent-update \
  https://github.com/<org>/<agent-repo>/releases/latest/download/zone9-agent-update
sudo chmod +x /usr/local/sbin/zone9-agent-update
sudo /usr/local/sbin/zone9-agent-update --install

That installs the binary, a systemd unit and a timer. From then on the agent keeps itself current.

Credentials

Environment file, root-owned, mode 0600:

ZONE9_API_URL=https://<panel-host>/api/v1
ZONE9_AGENT_TOKEN=<registration token from the panel>

ZONE9_PVE_<REGION>_URL=https://<proxmox-node>:8006
ZONE9_PVE_<REGION>_TOKEN=zone9-rw@pve!ctl=<secret>

ZONE9_FORTI_<REGION>_URL=https://<edge>
ZONE9_FORTI_<REGION>_TOKEN=<token>

These never leave this machine. That is the central property of agent mode: a compromise of the control plane does not hand over your hypervisor.

Never run a shell trace on a script that sources this file, and never use a verbose HTTP client without filtering the authorization header. Both print secrets into logs that outlive the session.

Registering

Create a region registration token in the panel, put it in the environment file, and start the agent. It registers, reports its version, and begins claiming jobs for its region only — every control-plane endpoint verifies that the resource belongs to the region the token identifies.

sudo systemctl status zone9-agent
sudo journalctl -u zone9-agent -n 50

Self-updating

The timer checks the published release every few minutes. When the version differs it downloads the binary, verifies its checksum, runs it once to confirm it reports the expected version, keeps the previous binary as a fallback, restarts the service, and rolls back if the service does not come up. Two runs cannot overlap.

Nothing is pushed: the agent decides when to look. Trigger one immediately with:

sudo /usr/local/sbin/zone9-agent-update && zone9-agent --version

If the agent is down

Nothing already provisioned is affected — machines run, traffic flows, appliances keep polling the API directly. New jobs queue and run when it returns.

The panel shows the agent’s last heartbeat. A region whose agent has been quiet is the first thing to check when creations appear stuck rather than failed.

Access

Reaching the agent for maintenance is your decision. Production reaches it through the panel’s console rather than opening SSH from outside — the console works even when the machine’s network does not, which is exactly when you need it.