Skip to main content

Help

Agents

Agents are lightweight programs you run on your own network to monitor devices that aren't accessible from the public internet, behind firewalls, on private networks, or at remote locations. Installing one takes a single docker run command or the Linux binary installer, both generated for you with your token already filled in. A Docker Compose configuration with Watchtower is offered as an optional third method if you would rather have the agent image updated automatically.

Requirements

Agents run anywhere the Docker command or the Linux binary installer works, including:

  • Linux servers (Ubuntu, Debian, CentOS, RHEL, etc.)
  • Windows Server with Docker Desktop
  • macOS with Docker Desktop
  • Raspberry Pi or other ARM-based systems
  • Virtual machines (VMware, Hyper-V, Proxmox, etc.)

Minimum requirements: 1 CPU core, 512 MB RAM, and network access to your devices

How many devices per agent?

A single agent comfortably polls around 250 devices at the default 60-second interval, and operators regularly run up to 500 on one agent when the devices answer quickly. SNMP devices that walk large tables, full MAC and ARP tables on a switch, wireless client lists on an AP, count for several ordinary devices. The limit that arrives first is burstiness: when a poll cycle lands more results at once than the ingest queue can hold, TowerOps refuses the overflow and the agent retries it on the next cycle, so the result is late rather than lost.

An agent over its practical limit shows it directly rather than pretending to be fine: its status badge gains a Dropping marker on the Agents page, and its detail page counts how many results were refused in the last hour. Sustained refusals, not CPU, are the signal to split its targets across a second agent.

Getting Started

1

Create an Agent Token

Open the Agents page and select New Agent, then press Create agent token. The token authenticates your agent with TowerOps and is shown only once, inside the install command.

2

Copy the Install Command

Once the token exists, TowerOps shows the install commands with your token already filled in. Pick the method you want:

  • Docker: one docker run command, publishing 162/udp so devices can send SNMP traps to the agent.
  • Binary: a script that installs the agent and a systemd unit on Linux, without Docker.
  • Compose (optional): a docker-compose.yml with Watchtower if you want the agent image updated automatically. It looks like this: 
services:
  towerops-agent:
    image: ghcr.io/towerops-app/towerops-agent:latest
    container_name: towerops-agent
    restart: unless-stopped
    ports:
      - "162:162/udp"
    environment:
      - TOWEROPS_API_URL=https://staging.towerops.net/
      - TOWEROPS_AGENT_TOKEN=your-token-here # paste the token shown by Agents → New Agent
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
      - "com.centurylinklabs.watchtower.scope=towerops"

  watchtower:
    image: containrrr/watchtower:latest
    container_name: towerops-watchtower
    restart: unless-stopped
    environment:
      - WATCHTOWER_POLL_INTERVAL=43200
      - WATCHTOWER_LABEL_ENABLE=true
      - WATCHTOWER_SCOPE=towerops
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_LOG_LEVEL=info
      - DOCKER_API_VERSION=1.44
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

The agent is lightweight, it uses minimal CPU and memory. Watchtower belongs only to the Compose variant: it checks for a new agent image every 12 hours and mounts the Docker socket, which is a privileged mount. Docker and Binary installs pick up a new version when you re-run their install command.

3

Run It

Run the copied command on the machine that can reach your devices: 

# paste the token shown by Agents → New Agent
docker run -d \
  --name towerops-agent \
  --restart unless-stopped \
  -p 162:162/udp \
  -e TOWEROPS_API_URL='https://staging.towerops.net/' \
  -e TOWEROPS_AGENT_TOKEN='your-token-here' \
  ghcr.io/towerops-app/towerops-agent:latest

That's it. The agent will connect to TowerOps within seconds and start polling your local devices. The install panel shows the connection status while you wait, and the agent appears on the Agents page once it is online.

4

Assign Devices to an Agent

You can assign devices to your agent in several ways:

  • Per Organization: Set a default agent for all devices in your organization
  • Per Site: Set a default agent for all devices at a specific site
  • Per Device: Select the agent when creating or editing individual devices

Exactly one agent polls a device, chosen from the first of those levels that names one: device, then site, then organization, and finally the deployment's global default cloud poller. The organization default lives on the Agents tab of Organization Settings, where Apply Default Agent to All Devices pushes it to every device; the site default lives in the site's form.

Devices assigned to an agent will be monitored from your local network instead of from the cloud.

Security Note

Agents use secure WebSocket connections to communicate with TowerOps. The agent token is only stored as a hash, and the plaintext is shown once when the token is created, so keep it confidential. The agent needs outbound HTTPS access (port 443) to connect to TowerOps, and accepting SNMP traps from your devices requires inbound UDP port 162 on the agent's host.

Managing Agents

The Agents page lists every token in your organization and shows:

  • Name, with a Cloud badge for application-wide cloud pollers and a Debug badge for agents allowed to run remote debug sessions
  • Status: Online, Stale (with elapsed minutes), Offline, or Never connected, plus a Dropping marker when the agent is having poll results refused
  • Devices, split into direct assignments and devices inherited through a site or organization default
  • Last seen time, its IP address, and the agent version, flagged Outdated when a newer release exists
  • Created date, plus View Setup to re-open the install instructions and Delete to remove the agent

Important

If an agent goes offline, devices assigned to it are not monitored, they keep their last-known status and are flagged "Agent offline" on the device list until the agent comes back online. TowerOps raises an agent offline alert automatically once an agent has been quiet for 10 minutes, following the same routing as your other alerts, and resolves it when the agent checks in again. The agent detail page shows how many devices are affected and offers a Reassign control to move all of them to another agent or a cloud poller without deleting the token.

Sections