Remote Agents
The private-network half of the dashboard: the agents that poll out of a site for work, and the hypervisor connections they carry it out against. They share a page because a connection reached through an agent is named in that agent's own file — so the two are usually filled in together. Feature guide.
Containerised agents that run inside a private network and poll out to this dashboard for work — so on-premises hypervisors can be discovered and managed without opening a single inbound firewall rule. Each agent authenticates with an Ed25519 key it generates itself; no reusable credential ever crosses the wire.
Enrolment codes are blocked
Fix it in Settings → Integrations → Remote Agents, which shows the pinned audience and offers a reset.
Remote agents are not enabled
Turn them on in
Settings → Integrations → Remote Agents.
Enabling publishes /api/agent for agents to reach,
so terminate TLS in front of the dashboard first — see
the remote agent docs.
You cannot see the agent list
Registering and revoking agents is administrator work; the connections they reach are governed separately.
Enrolled Agents
Migrating to SPIRE moves the key into memory: on a cloud VM nothing is stored at all,
and on a bare Docker host only SPIRE's own hourly-rotated key remains. A migrated
agent can then fetch its hypervisor credentials from the dashboard per job
(dashboard_secret: true), so none are stored on its host.
This dashboard releases the credentials it holds only to SPIRE-attested agents, so jobs on these agents that need one are refused until they migrate.
| Name | Site | Status | Registered by | Source IP | Version | Last seen | Running | ||
|---|---|---|---|---|---|---|---|---|---|
|
|||||||||
Register Agent
Enrolment code for
Shown once. It expires in 15 minutes and can only be redeemed a single time.
The agent image is Linux; on Windows it runs in Docker Desktop's Linux VM, so keep Docker Desktop in Linux containers mode. See Running on Windows.
Alternative: keep the code out of docker inspect
Mounts the code as a file instead of an environment variable, so nothing durable in
Docker's metadata holds it. Follows the toggle above. To keep the code out of your
shell history too, create agent-enroll-code with an
editor — just the code, on one line — and paste only the
docker run that follows.
Save it as plain ASCII or UTF-8 without a byte-order mark — Notepad's "Unicode" and "UTF-8 with BOM" options both produce a file the agent cannot read. PowerShell also writes its history to disk as you type, so an editor is the only way to keep the code out of it.
The agent needs a policy.yaml naming the networks it may
scan — it refuses all work without one. See
the remote agent docs
for a starting file.
Migrate to SPIRE
New SPIRE join token for
Its SPIRE identity expired while its host was offline, and a join token works only
once. Only the token changes: leave the rest of the agent's
.env and its spire/bootstrap.crt as they are.
The SPIRE entries exist and the agent is bound to
.
Its current key keeps working until it first attests, so nothing breaks in between.
The join token below is shown once, works once, and expires in minutes.
-
In the agent's
.env, replace theSPIRE_JOIN_TOKEN=line with: -
Recreate its containers. Never
down -v: that deletes the SPIRE agent's data.
-
On the agent host, beside its
docker-compose.yml, save the trust bundle asspire/bootstrap.crt: -
Add these to the agent's
.env: -
Restart it with the SPIRE overlay:
Needs agent image 2.6.0 or newer, and outbound access to the SPIRE server's port (8081) — a TLS-inspecting proxy needs a bypass for it. To go back, use Re-enrol: it clears the SPIRE binding and issues a fresh code.
Discover via
Unauthenticated probes only — a TCP connect and a protocol banner. Nothing ever attempts a login. The agent will refuse any target outside its own policy file.
Probes never authenticate, so a WinRM answer identifies Windows — not necessarily a Hyper-V host. Those findings are marked possible only.