Agent install and updates
The Loopback agent is the on-host component that drives WireGuard, optional firewall modules, metrics hooks, shell sessions, and update orchestration. This page is the platform-level companion to workspace operations like token minting (see Agents and remote access) and the fleet narrative (Agent and fleet management).
Document map (read this if you are new)
| Question | Where to read |
|---|---|
| Why do we install an agent? | Agent and fleet management |
| What optional modules exist? | Agent modules |
| What is the eBPF firewall module? | Host firewall (eBPF) |
| Tokens, shell, power actions | Agents and remote access |
| Mesh networking behavior | WireGuard mesh and agents |
Install and download
System routes serve:
- Install script generation for bootstrapping new hosts.
- Binary download endpoints for agent packages.
Hosts must be able to reach these URLs from their network context; air-gapped installs require operator mirroring and internal package distribution.
Hardening tips for enterprises
- Pin downloads to internal mirrors where possible.
- Verify package integrity using operator-published checksums.
- Treat install scripts like any remote bootstrap: review in staging, then promote.
Version catalog
The platform maintains a catalog of agent releases (semver). Each row typically carries:
- Channel - e.g. stable vs preview/unstable (labels vary by operator).
- Published flag - controls whether update checks offer the build.
- Upgrade eligibility - which currently running versions may move to this release (including wildcard “any” policies where used).
- Integrity material for packages (e.g. SHA-512 for Debian-class assets).
- Optional module tags (for example load-balancer firewall integration where enabled).
Why channels matter: you can run early adopters on a preview channel without risking the whole fleet.
Update check API
Dedicated update-check endpoints let a running agent ask “is there a newer published version on my channel?” Logic:
- Considers only published rows in the requested channel.
- Compares semver ordering.
- Honors upgrade eligibility for the current version.
204 responses mean no update; 200 returns metadata for the next version.
Module versions
Add-on module catalogs (for example host-integrated firewall modules) follow the same channel and upgrade eligibility semantics as the core agent, so operators can coordinate paired releases when needed.
Update deliveries (operator)
Staged update deliveries (operator-facing API) describe phased rollouts of agent or module updates across host populations. They require operator or administrator roles. Reconciliation waves progress until targets complete; this is how controlled fleet upgrades avoid thundering herds.
Buyer question to ask: “What is your maximum blast radius per wave (percent of fleet, per region, per workspace)?”
Compliance and change management
- Agent updates are infrastructure changes—treat them like kernel or systemd updates in your CAB process.
- Require release notes for module changes that touch datapath security.
- Keep rollback guidance: if a module fails, can you disable it without re-imaging the host?