Manage Orb agents

An Orb agent runs on your infrastructure and performs the discovery that feeds NetBox Assurance. You register it in the NetBox Labs Console, start it with one command, and from then on manage it under Fleet management → Orb agents.

Public Preview - Fleet Management is in Public Preview for NetBox Cloud customers. Contact your account team to enable it for your organization.

Before you begin

A host that can run containers with Docker or Podman, with outbound network access to NetBox Labs and network reach to the devices you intend to discover.
If you plan to run device discovery, a HashiCorp Vault or OpenBao instance holding your device credentials. See Manage device credentials.

Agent states

Agents send a heartbeat every 5 seconds, and each one marks the agent online. The Console checks for silent agents once a minute, and marks any agent that has not been heard from for five minutes as stale.

State	What it means	What to do
New	Registered in the Console, not yet started.	Run the provisioning command on your host.
Online	Reporting normally.	Nothing.
Offline	The agent stopped cleanly. It reports this state itself, as the last thing it does before disconnecting.	Nothing, if you stopped it on purpose. Run it again when you need it.
Stale	The agent went silent without stopping cleanly: a crash, a killed container, a host that lost power, or a dropped outbound connection.	Check the container is running and can reach NetBox Labs outbound. Discovery is not running on this agent.

Register an Orb agent

Registration is two steps. The first creates the agent record; the second gives you the command that starts it.

Go to Fleet management → Orb agents and select New Agent.
On Agent details, enter a Name.
Add Labels if you want them, as key and value pairs. Labels help you organize and filter a growing fleet.
Select Save & Continue.

The Console then shows the Next steps page, with the provisioning command and a status check.

Start the agent

On the Next steps page, under 1. Run provisioning command, choose the Docker or Podman tab and copy the command.

Copy the client secret before you leave this page. It is shown once and cannot be retrieved afterwards. If you lose it, register the agent again and use the new values.

Run the command on the host that will run the agent. It looks like this, with the three fleet values filled in by the Console:

docker run \
  --rm \
  --net=host \
  --env FLEET_AUTH_URL='<supplied by the Console>' \
  --env FLEET_CLIENT_ID='<supplied by the Console>' \
  --env FLEET_CLIENT_SECRET='<supplied by the Console>' \
  netboxlabs/orb-agent:latest run

Copy the command from the Console rather than from this page.

If you use a vault, the command the Console gives you also carries a block of ORB_SECRETS_MANAGER__ variables, with comments explaining how to fill them in. Those settings are what lets the agent resolve the credential references you store in the Console, so the vault details here and the references there have to match. Manage device credentials explains how the two halves fit together. If you are not using a vault, delete those lines before running the command.

Under 2. Check agent status, watch for the agent to come online. It can take up to a minute, and the page refreshes on its own. Continue to agent details stays disabled until the agent reports in, which makes it a reliable signal that the agent really connected.

Monitor your fleet

Fleet management → Orb agents lists every agent with its Orb agent name, Status, Last heartbeat time, and Labels.

Check this list when deviations stop arriving. An agent that has gone stale is not running discovery, and NetBox will quietly drift out of date until it comes back.

Organize your fleet with labels

Labels are key and value pairs you attach to an agent, added when you register it. Use them to record where an agent runs or what it is for, then filter the agent list by them as the fleet grows.

Troubleshooting

The agent never appears after registration. The command did not run, or the host cannot reach NetBox Labs outbound. Check the container logs on the host and confirm outbound access.

The agent shows offline or stale. The container has stopped, or it has lost its outbound connection. Restart it and watch the Last heartbeat time column.

The agent is online but a job fails on authentication. The agent is fine and the credential is the problem. Check that the vault settings in the provisioning command match the references stored in the Console.

What's next

Add a device credential
Create a Discovery job

Getting help

Contact your account team or NetBox Labs support.

On this page