Install an agent

An agent is a small program that runs on a machine inside a network you want to discover. It connects out to the MiniPAM server over a WebSocket, waits for work, and streams results back.

Put an agent in each network (broadcast domain) you want to scan: ARP scanning only sees the local network. See Where to run an agent, including Proxmox containers.

You need the admin role and the Discovery workspace feature.

1. Create the agent in MiniPAM

1. Select the agent's site in the Active site selector.

2. Open Administration → Agents and choose Create agent.

3. Enter a Name, and a Token of your choosing. Use a long random value:

   openssl rand -hex 32

4. Leave both Allowed Imports ticked (Create networks and Create netdevices) unless you want to stop this agent's automatic imports from creating those records.

The token is the agent's password. Anyone who has it can connect as this agent. Give each machine its own agent and token: two machines that share a token keep replacing each other's connection.

2. Get the agent binary

Pre-alpha

Prebuilt agent binaries for Linux will be published on the project's GitHub Releases page with the public release, planned for Q1 2027. Until then, build the agent yourself.

You need Go, a C compiler, and the libpcap headers (libpcap-dev on Debian and Ubuntu, libpcap-devel on Fedora; macOS already has them).

cd app-agent
go build -o minipam-agent .
./minipam-agent version

To build the self-contained Linux packages that the installer below expects, see deployments/linux/agent/README.md in the repository.

3. Install it as a service (Linux)

Copy the package to the target machine and run its installer:

tar -xzf minipam-agent-linux-amd64.tar.gz
sudo sh minipam-agent/install.sh \
  --server ws://minipam.lan:8091/ws/agent \
  --key YOUR_AGENT_TOKEN

--key takes the agent's token: open it in Administration → Agents and choose Reveal.

The installer works on Debian, Ubuntu, Raspberry Pi OS, Fedora, CentOS/RHEL (systemd) and Alpine (OpenRC). It installs nmap (skip with --no-nmap), creates an unprivileged minipam user and the minipam-agent service with only the network capabilities ARP scanning needs, and writes the server address and token to /etc/minipam/agent.env and the module settings to /etc/minipam/config.yaml.

Run the installer again to update. It replaces the binary and keeps your settings. --uninstall removes the service; add --purge to remove settings and the user too.

Check the service with systemctl status minipam-agent and journalctl -u minipam-agent -f.

Or run it by hand

./minipam-agent run server \
  --address ws://minipam.lan:8091/ws/agent \
  --key YOUR_AGENT_TOKEN \
  --config config.yaml

Always pass --address; the built-in default is out of date. The config file is required, and can start from deployments/linux/agent/config.yaml.

If the server is behind an HTTPS reverse proxy, use wss:// and the proxy's address, for example wss://minipam.example.com/ws/agent.

4. Check the connection

Back in Administration → Agents, the agent shows as online within a few seconds, with the modules it supports and the network information it reported: hostname, interfaces, addresses, and routes.

If the connection drops, the agent reconnects by itself for about an hour, then needs a restart. Not connecting? See An agent stays offline.

What an agent can do

• netinfo: the host's interfaces, addresses, routes, and DNS.
• ARP netscan: hosts on a directly attached IPv4 network.
• ping: reachability.
• port probe: one TCP or UDP port. Needs nmap; UDP also needs root.
• nmap enrichment: services, products, certificates, and optionally OS details. Needs nmap; OS detection also needs root (nmap-enrichment).

The agent decides what it is willing to do, in its own configuration file. See What an agent can do and Agent CLI and configuration.

Scan responsibly

Only scan networks you administer. Scans, especially nmap enrichment, generate traffic that other people's security tools will notice.

Demo mode

Demo mode replays recorded discovery data through a normal connection, without touching a real network. It is for trying MiniPAM out and for development:

./minipam-agent run demo --address ws://localhost:8091/ws/agent

Create an agent in MiniPAM with the token demo-agent-token first.

Next: review what the agent discovers.