Local Agents
Set up Local Agents to relay power, SNMP, PXE boot, OS install, IPMI, and Redfish commands to dedicated servers on private management networks.
What a Local Agent is
A Local Agent is a lightweight service that runs on a server inside your datacenter and acts as a bridge between FluxBilling and your private management network. It relays automation commands — power control, SNMP monitoring, PXE boot, OS installation, IPMI, and Redfish requests — to dedicated servers whose management interfaces (BMC/IPMI, switches, PDUs) live on a private network and are not reachable from the public internet. Without an agent in that network, automation cannot talk to the hardware behind it.
How to reach this page
Open Settings from the admin sidebar, then in the settings navigation scroll to the Infrastructure group and click Local Agents. The page opens with a short explanation banner (“What is a Local Agent?”) at the top and a Registered Agents list below it.
Local Agents only appear when the inventory feature is enabled for your platform. If you do not see the Infrastructure group (with Bare Metal and Local Agents) in Settings, that feature is turned off.
Registering a new agent
Each agent is installed onto a server you already control inside the target network. FluxBilling connects to that server over SSH and installs the agent for you — there is no manual command to copy and run.
- Click Add Agent (top right of the Registered Agents header).
- Give the agent a Name — a label you will recognise, such as the rack or site it serves.
- Under Locations, tick one or more locations this agent will serve. At least one is required. Devices belonging to those locations become available for the agent to manage.
- Enter the SSH Host — the address of the server inside the network where the agent will be installed. Optionally adjust User (defaults to
root) and Port (defaults to22). - Choose an Authentication method: Password (enter the SSH password) or SSH Key (paste a private key).
- Click Register Agent. The agent record is created and the installation panel opens automatically.
The host you point the agent at must be able to reach the private management interfaces of your devices — for example a small utility box on the same network as your BMCs and switches.
Add Agent fields
| Field | Required | What it does |
|---|---|---|
| Name | Yes | A label for the agent shown throughout the panel. |
| Locations | Yes | One or more locations the agent serves; their devices become assignable to it. |
| SSH Host | Yes | Address of the in-network server where the agent will be installed. |
| User | No | Login user for the SSH connection. Defaults to root. |
| Port | No | SSH port. Defaults to 22. |
| Authentication | Yes | Password or SSH Key. Selecting SSH Key reveals a field to paste a private key. |
Installing the agent
The installation panel runs the install over the SSH connection you provided and streams progress back into the panel.
- Click Test SSH first to confirm FluxBilling can reach the host and log in. A success message shows basic details about the connected machine; a failure message explains what went wrong (wrong credentials, unreachable host, and so on).
- Click Install to begin. A progress bar tracks the installation steps (shown as “Step X of 7”), and each completed step is listed with a green check as it finishes.
- When the agent is installed and reports in, the panel shows a completion message. Click Done to close it.
If you ever need to repair or upgrade an agent, open its detail view and use the Reinstall button to run the same flow again. From the list, agents that are still Pending or in an error state also show a quick Install button on their row.
Agent status
Every agent row carries a colour-coded status badge so you can see at a glance whether it is healthy:
| Status | Meaning |
|---|---|
| Online | The agent is connected and sending regular heartbeats — ready to relay commands. |
| Pending | Registered but not yet connected; waiting for installation to complete or for its first heartbeat. |
| Installing | Installation is in progress. |
| Offline | The agent was online before but has stopped reporting in. |
| Error | Installation or operation failed. An error message is shown so you can act on it. |
Alongside the status, each row shows the SSH host, how long ago the last heartbeat arrived, the number of devices the agent manages, and — when work is underway — a count of active jobs. A Default badge and a location pill also appear on the row where applicable.
Working with an agent
Click any agent in the list to open its detail view. A Back to agents link returns you to the list, and a refresh control re-reads the latest state. The detail view is organised into tabs.
Info tab
The Info tab summarises the agent and exposes its main toggle:
| Item | What it shows |
|---|---|
| Status | Current connection status badge. |
| Location | The location the agent serves. |
| Version | The installed agent version. |
| Last Heartbeat | How long ago the agent last reported in. |
| Capabilities | The protocols the agent has detected it can use (see below). |
| Installed | The date the agent was installed. |
| Default Agent | A toggle that auto-assigns newly added devices at this location to this agent. |
When an agent connects it reports the management protocols it supports. These appear as Capabilities badges:
- IPMI — out-of-band power and sensor control on server BMCs.
- SNMP — polling switches, PDUs, and other network gear.
- Redfish — modern BMC management API.
- HTTP Server — serving boot and installation files locally.
- SSH — shell access to managed hosts.
- DHCP — address assignment during network boot.
- Serial — serial-over-LAN console bridging.
Devices tab
The Devices tab lists the hardware in the agent's location(s) and lets you control which devices it handles. Each device shows its name and management IP. Use the inline Assign link to make this agent responsible for a device, or Unassign to remove it. A device already handled by another agent shows that agent's name instead. The Assign all unassigned shortcut, shown when applicable, attaches every currently unassigned device in one click.
Each device is managed by exactly one agent. Assigning a device that is currently on another agent moves responsibility; the Devices tab always reflects where each device currently sits.
Jobs tab
The Jobs tab is a live activity log of the commands the agent has carried out — provisioning, reinstalls, power actions, health checks, console access, IPMI and Redfish requests, SNMP operations, and more. Each entry shows the job type, a status badge (Queued, Claimed, In Progress, Completed, Failed, Timeout, or Cancelled), the affected device and its management IP, a short detail (such as the power action or the boot image), how long the job took, and when it was created. Failed jobs display the error message so you can troubleshoot. The most recent jobs are shown first.
Installation Log tab
If installation details are available, an Installation Log tab appears listing each completed install step. This is useful for confirming a clean install or reviewing what happened during setup.
Removing an agent
To remove an agent, click the trash icon on its row in the list and confirm. Removing an agent uninstalls it from the host and unlinks all of its devices. Be sure another agent covers those devices first, or their out-of-band automation will stop working.
Tips and gotchas
- Always Test SSH before installing. It catches credential and reachability problems early, before the install starts.
- One agent can be a single point of failure for a rack. If power-cycle uptime matters, deploy more than one agent per site so device control survives a single host going down.
- Mark a default agent per location. With the Default Agent toggle on, any new device added at that location is automatically assigned to this agent — saving you from assigning each one by hand.
- Watch the heartbeat. An agent that slips from Online to Offline means its host or network path is down — automation for its devices will stall until it returns.