Installing an agent

An agent is one binary and a service definition. The portal packages both, together with a credential, so installation is running one script.

Supported platforms

ARMv7 is on the list for a reason: a small board in a branch office is often the most honest vantage point you can get, because it sits where the users sit rather than in the comms room.

Getting the pack

Open Settings → Agents → Add an agent. The setup wizard asks for your agent type, platform, and setup options, then provides a download and instructions. Connection credentials are created and included automatically; you do not need to create, copy, or save a token.

The archive contains the agent binary, the rsctl diagnostic tool, a SHA256SUMS file, a starter configuration, install and uninstall scripts, and an enrollment token.

Choose One device for a package to install within 24 hours. Keep the last step open to see when that device comes online or needs administrator approval. Choose Many devices to download a reusable package with a rollout window (up to 30 days) and device limit (2–500). Distribute the same original ZIP to hosts running the selected OS and architecture.

Choose Golden image / VDI to name a desktop pool and prepare a clean image. Each customized clone connects with its own identity. The source image stays offline; follow clones in Agents → Pools after deployment.

If installation is not configured for your organisation, ask your administrator to enable it before using the wizard.

Install with a script

Open Agents → Add an agent from your HTTPS portal, then follow the same setup steps used for a package:

1. In Agent type, choose Install with a script.
2. In Platform, choose Linux, macOS, or Windows and the processor architecture. The latest published release is selected by default; you can choose another release.
3. In Setup, choose capabilities, rollout limits, and any advanced settings.
4. In Install, select Generate install command, then Copy install command.

Paste the single line into a terminal with sudo access on Linux/macOS, or PowerShell opened as administrator on Windows. Linux/macOS also requires curl and unzip.

The command includes connection credentials and your selected settings automatically. It checks that the host matches the chosen platform, downloads the selected release, and installs the agent as a background service that starts at boot. Devices appear in Agents as they connect. You do not need to download files separately, edit configuration, or copy a token into the command.

Use the same command on one or many machines. By default, a rollout allows up to 100 devices to enroll within 7 days of generating the command. Change the device limit (2–500), install window, capabilities, or labels in Setup. Each command targets the selected OS and architecture; create another for a different platform. Going back preserves your choices. If you change them, generate a new command in Install. Keep the command available for your rollout and share it only with authorized installers. After leaving the page, generate a new command if you did not save the original.

Script installation supports native Linux, macOS, and Windows builds, including the optional capabilities shown in Setup. Use a package for Docker or golden images. Review or revoke a script rollout in Agents → Deployment access. Expiry and revocation stop new enrollments; agents already installed keep working.

Deploying a fleet

Add an agent → Many devices creates a complete package for a rollout. Choose capabilities and labels once, then push the original ZIP through MDM or send it to users. Users extract it and run the installer; they do not need a portal account or to enter a token.

For a command-based rollout, use Add an agent → Install with a script. For existing credential management, open Agents → Deployment access. Its Custom deployment automation section provides credentials for deployment tools that manage their own access:

• Install token: short-lived (1, 7 or 30 days) and capped at a number of hosts. Package and script setup create these automatically; revoke a token when its rollout is complete.
• Tenant token (account key): no expiry or token use limit; tenant admission quotas still apply. Rotate it when it may have leaked; already-enrolled agents keep their own credential and do not need to rejoin.

Custom deployment automation → Use a saved token accepts either token and provides a complete reusable package or a copyable command. The universal command selects the latest published build for the host’s platform and installs the standard agent as a boot service. Downloads do not consume device slots; each new host consumes a slot when it enrolls. Tokens are checked again at enrollment.

Each host creates a random installation identity and uses its hostname as the display name. Reboots and installer reruns preserve that identity. Never bake the enrollment state directory into a golden image or redistribute files from an enrolled machine. Distribute the original download.

For MDM, run "Install Service.cmd" /quiet as SYSTEM or administrator on Windows, or sh ./install-service as root on Linux/macOS. The Windows quiet mode does not prompt for elevation or pause, and returns a nonzero exit code on failure. The package carries its bootstrap token; distribute it only to machines allowed to join the organization.

Universal commands

For a ready-to-run single line, use Add an agent → Install with a script. For a deployment tool that supplies its own secret, create a tenant token in Deployment access → Custom deployment automation and use the examples below. The token has the form client_id:client_secret. It is shown only when created; save it in your deployment secret store. Both scripts require HTTPS. Replace the example portal URL below with your own portal origin.

Linux/macOS (requires curl, unzip, and sudo access):

ROUTESPEAR_TOKEN='PASTE_TENANT_TOKEN_HERE'
curl -fsSL 'https://portal.example/v1/portal/install.sh' | sudo sh -s -- --server 'https://portal.example' --token "$ROUTESPEAR_TOKEN"

Windows (run PowerShell as administrator):

$env:ROUTESPEAR_TOKEN = 'PASTE_TENANT_TOKEN_HERE'
& ([scriptblock]::Create((Invoke-RestMethod 'https://portal.example/v1/portal/install.ps1'))) -Server 'https://portal.example' -Token $env:ROUTESPEAR_TOKEN

The download request sends the token in an Authorization header, not a URL. Service installation completes before asynchronous enrollment; check the portal for connected or pending-approval status.

After the rollout, revoke the install token so a copy that leaked cannot admit more machines. Rotating an account key leaves the old one working until you revoke it, so hosts that have not picked up the new file are not locked out.

Installing

Docker on Linux

In Add an agent → Platform, choose Docker on Linux and the host’s x86_64 or ARM64 processor. Extract the downloaded ZIP on that host and run:

sudo sh ./install-docker

Install Docker Engine and its Compose plugin first, and enable Docker at boot. The installer checks the local engine and architecture, verifies the packaged binaries, builds a small runtime image, and starts the agent. The first build needs internet access. Credentials and agent binaries are excluded from the image build context; the package uses the selected published agent release.

Host networking and raw-probe permission are configured automatically. The agent can discover interfaces in the host’s default network namespace and use their source addresses. It shares the host’s network isolation boundary; the container does not receive privileged mode, the Docker socket, or host filesystem access. The process runs as container root with only NET_RAW retained. Source address selection still follows host routing and does not guarantee a particular WAN interface. Host networking does not turn container process/disk metrics into host metrics.

The installer supports local, rootful Docker Engine on Linux. It rejects Docker Desktop, rootless engines, user-namespace remapping, remote endpoints, and mismatched CPUs. Use a native agent for Windows/macOS adapters, or choose the separate Docker Desktop on Windows option below for container-based measurements. This package supports built-in network checks and optional JavaScript scripts; browser checks, User Browser Sessions and host interpreters require the native package.

Files are installed in /var/lib/routespear/docker-agent. Keep its state/ directory: enrollment identity and queued measurements survive container recreation and installer reruns. runtime/ holds binaries and plugin settings and permits agent self-updates. Reinstalling a package replaces the binaries with that package’s release while preserving state. Never copy an installed directory to another host; distribute the original rollout ZIP instead.

cd /var/lib/routespear/docker-agent
sudo docker compose ps
sudo docker compose logs --tail=100 agent
sudo docker compose restart agent
# Remove the container while keeping enrollment and queued data:
sudo docker compose down

Verify the agent connects and reports the intended host interfaces in the portal. Control and ingest addresses must resolve from the host network; Compose bridge service names are not available in this mode.

Docker Desktop on Windows

In Add an agent → Platform, choose Docker Desktop on Windows and the processor matching your Docker Linux engine (x86_64 or ARM64). Install and start Docker Desktop in Linux containers mode, extract the ZIP, and open PowerShell in its folder:

powershell -NoProfile -ExecutionPolicy Bypass -File .\install-docker.ps1

The installer verifies the binaries, builds the runtime image, and starts the agent with normal container networking. The first build needs internet access. The package supports one installation per local Docker engine; remote engines and Windows containers are rejected. Enable Docker Desktop to start when you sign in if needed. The agent runs only while Desktop’s engine is running; this does not install a Windows service.

The default agent hostname ends in -docker. Measurements and interface inventory come from the Linux container/VM, with Docker’s NAT and networking limits. ICMP, TTL replies and LAN discovery can be limited. Use the native Windows package for physical adapters, Windows host metrics, desktop sessions, browser checks or host interpreters. Built-in network checks and JavaScript scripts are available in the container. Desktop host networking is not enabled. See Docker Desktop networking.

Control and ingest addresses must be reachable from the container. localhost means the container itself. For a service on the Windows host, an administrator may need to configure host.docker.internal or another reachable address with matching TLS certificates; the installer does not rewrite endpoints.

The management folder is $env:LOCALAPPDATA\RouteSpear\DockerAgent. Enrollment and queued data live in routespear-desktop-state; writable agent binaries live in routespear-desktop-runtime so self-updates retain Linux file permissions. These external Docker volumes survive container recreation and compose down. Keep both volumes and the management folder. Do not reset Docker data or copy enrolled volumes to another computer; distribute the original rollout ZIP for new agents. Rerunning the installer replaces binaries with the package’s release while retaining enrollment and queued measurements.

cd "$env:LOCALAPPDATA\RouteSpear\DockerAgent"
docker compose ps
docker compose logs --tail=100 agent
docker compose restart agent
# Remove the container while keeping its persistent volumes:
docker compose down

Native service

Unpack the archive and keep every file together, the scripts expect their siblings. Then run the installer with administrator or root privilege, which installing a system service requires.

unzip routespear-agent-*-install.zip -d routespear-agent
cd routespear-agent
sudo sh ./install-service

./start-agent

unzip routespear-agent-*-install.zip -d routespear-agent
cd routespear-agent
sudo sh ./install-service

./start-agent

Expand-Archive -Path .\routespear-agent-*.zip -DestinationPath .\routespear-agent
Set-Location .\routespear-agent
& '.\Install Service.cmd'

On Linux this writes a systemd unit at /etc/systemd/system/routespear-agent.service and enables it. On macOS it writes a launchd daemon at /Library/LaunchDaemons/com.routespear.agent.plist and bootstraps it. On Windows it registers the RouteSpear Agent service and adds an inbound firewall rule for ICMP time-exceeded messages.

On a Unix host with neither systemd nor launchd (a minimal container image, an unusual init) the script stops and tells you to use ./start-agent. It does not pretend to have installed something it did not.

Where things land

The agent writes its spool and its credential here and nowhere else.

Privileges

Raw socket access is the difference between a full path measurement and a partial one. The agent runs unprivileged wherever it can and reports what it lost when it cannot, rather than falling back quietly.

sudo setcap cap_net_raw+ep /var/lib/routespear/agent/routespear-agent

Then ask the host what it can actually do:

./routespear-agent -print-capabilities

./routespear-agent -print-capabilities

.\routespear-agent.exe -print-capabilities

This prints the probe transport it would use and every capability graded present, degraded or absent, each with the mechanism as the reason. Run it before concluding that a host is a poor vantage point, capabilities explains what the grades mean, and most surprises in path measurement turn out to be capability surprises.

Verifying the download

Each archive ships a SHA256SUMS file.

sha256sum -c SHA256SUMS

shasum -a 256 -c SHA256SUMS

Get-FileHash -Algorithm SHA256 .\routespear-agent.exe
Get-Content .\SHA256SUMS

Uninstalling

sudo ./uninstall-service

sudo ./uninstall-service

It stops and removes the service and leaves the files in place, so removing an agent does not also destroy the evidence of why you were removing it. Delete the install directory to remove the data and logs as well.

Installing without the pack

Everything the scripts do is available as flags, which is what you want for configuration management, container images or golden images. See the CLI reference.

One caution for image building: an agent’s identity is keyed on a stable fingerprint, and cloning a host that has already enrolled produces two agents claiming to be one. Bake the binary into images, not the credential.

Next

• Managing agents
• Capabilities
• Troubleshooting