Agents

An agent probes services inside your own network — private APIs, internal hosts, anything the public internet cannot reach — and reports the results to WireWatch. It enrols with a single-use token, authenticates with mTLS, and connects outbound only, so no inbound port has to be opened.

One agent serves one organisation. Its certificate names your organisation and nothing else, so the blast radius of a compromised agent is your own network and never another tenant’s.

An enrolled agent is a probe location like any WireWatch region: you pick it when you create a monitor, and results arrive from it the same way.

The release you are installing

Releases live at https://github.com/WireWatch/agent-releases (public, no account needed). The container image is ghcr.io/wirewatch/agent (public, anonymous pull). Current release: agent-v0.1.3, agent version 0.1.3.

Platforms are linux/amd64 and linux/arm64 only. macOS and Windows are out of scope.

Step 1 — get your enrolment token

In the app, Agents → Add agent. The panel issues a one-time token, shows it exactly once, and renders the command for the route you pick. The token expires; issue a new one if it does.

If the command shows the literal <your-server-url> instead of a real host, the control plane has no agent URL configured. That is a server-side configuration gap, not something you can work around — the agent has nowhere to enrol.

Step 2 — pick a route

Route	Use it when
Docker	the host can run containers. One line, no unit file — the right one for most hosts
Kubernetes	you already run a cluster in the network you want probed
Linux binary	the host cannot run containers: corporate policy, an older distribution, an appliance, a single-board machine on a factory floor

Every route obtains the same signed artifact and enrols the same way. Verify it before you run it — the checksum and signature steps are the same for all three and are written once, in Verify a release.

Step 3 — confirm it works

1. The agent appears in Agents in the app, online.
2. Restart it (the command is on the route’s page). It stays online, with no new token.
3. Create a monitor whose location is that agent and whose target is a private address the platform probes cannot reach. Results arrive from the agent and the monitor reads up.

A revoked, used or expired token is refused at enrolment, and the agent says so in as many words — agent enroll: enrollment token rejected (invalid/used/expired). Nothing is persisted, so the fix is always a fresh token.

Everything the agent logs goes to stderr: the terminal for the binary route, docker logs for Docker, kubectl logs for Kubernetes.