What it does

Identity — rename the computer, join the domain (resuming across the reboot), add the owner to the local administrators.
Workflow steps — scripts with expected results, reboots, waits for a service or port, and the building blocks of configuration runs.
Operations — remote scripts from the VM page, disk-usage scans, guest disk expansion.
Metrics — CPU, memory and per-volume disk usage every few seconds.
Self-update — downloads new builds from the portal, checks their signature against your release key and restarts itself.

Install it in a template

Copy the agent binary and its config.toml into one folder in the template.
Fill in config.toml (below) — at least backend_url, backend_pubkey and release_pubkey. No enrollment secret is needed.
In Templates, switch on One-time agent enrollment token for this template, so every clone gets its own enrollment token.
Register the service with the install script from the release, then shut down and convert the VM to a template.

PowerShell

.\install-agent.ps1 -InstallDir 'C:\Program Files\Verlocx\Agent'

Keep the template not domain-joined, and let every clone get its own SMBIOS UUID — Verlocx sets a unique one per VM, and that UUID is how the portal recognises the agent.

config.toml

Key	Meaning
`backend_url`	WebSocket address of the backend, e.g. `wss://verlocx-backend.example.com:8787/ws/agent`. Use a DNS name you can move.
`backend_pubkey`	The backend's Ed25519 public key (hex) from `server.pub`. The agent trusts no other server.
`release_pubkey`	Public key of your release key (64 hex, from `release.pub`). The agent installs only updates signed with it — see Agent releases.
`bootstrap_secret`	Optional, legacy. A shared enrollment secret, accepted only while the backend runs with `allow_bootstrap_enrollment = true`. Leave it out of new templates — anyone who can read the file could enroll agents with it.
`agent_key_path`	Where the agent keeps its private key (default `agent.key`, next to the config). Created on first start.
`update_url`	Optional: `https://verlocx.example.com/api/agent/manifest` — checks for new builds at boot and once a day.
`override_uuid`	Testing only: use a fixed identity instead of the SMBIOS UUID.

config.tomlTOML

1backend_url    = "wss://verlocx-backend.example.com:8787/ws/agent"2backend_pubkey = "d17f…0ff0"3release_pubkey = "8a3c…91be"4agent_key_path = "agent.key"5update_url     = "https://verlocx.example.com/api/agent/manifest"

First start and enrollment

On first boot the agent enrolls once; from then on it authenticates with its own key. It shows up in Fleet and on its VM's page within seconds.

It creates its own key pair (once, kept on the VM).
It connects outbound to backend_url and checks the backend's identity against backend_pubkey.
It sends its VM's SMBIOS UUID, its public key and the enrollment token it reads from the VM's SMBIOS SKU field. Verlocx wrote that token when it cloned the VM: random, bound to this UUID, valid for 24 hours and usable once. The backend stores the key for that UUID and the portal clears the token.
Every later connection: the backend challenges, the agent signs with its key — no token or secret is used again.

The token only enrolls, once, as that one VM. It can't act as the portal — the portal has its own secret on a listener guests can't reach — and it can't take over an enrolled VM: a UUID that is already enrolled with a different key is refused. After reinstalling the agent on the same VM, Offboard it in Fleet with Let the agent re-enroll switched on, then stop and start the VM so it picks up the new token.

VMs that weren't cloned by Verlocx have no token. They can enroll with a bootstrap_secret while the backend still allows it (allow_bootstrap_enrollment, see Configuration); once every template uses tokens, switch that off and rotate the secret.

Updates

The portal serves agent builds from AGENT_RELEASE_DIR, but only a release you signed offline with your release key — without one, Fleet → Update agent says “no signed release published” and why. Agents with an update_url check at boot and once a day; Update agent updates one right away. The agent checks the release signature against release_pubkey, installs only a newer version, verifies the SHA-256, swaps the binary and restarts its service. The backend can't sign updates, so a compromised server or guest can't push code to your agents.

Feature	Needs agent
Deployment workflows, configuration runs, scripts with expectations	`0.0.33+`
Local-admin check by group SID (no false failures for existing members)	`0.0.34+`
Offline-signed updates (release_pubkey), one-time enrollment tokens, domain join that renames an already joined guest instead of joining again	`0.0.36+`

Logs

The agent writes rolling log files to a logs folder next to its binary — connection, identity check, enrollment, update checks and every command it runs.

Moving to another backend

Only backend_url changes if the new server uses the same keys. A configuration run can rewrite it on every VM at once — or point backend_url at a DNS name and move the name instead. See Back up and move.

Template checklist

Windows is updated and the agent service starts automatically.
config.toml points at your backend and carries its public key and your release_pubkey — and no bootstrap_secret.
The template runs agent 0.0.36 or newer and has One-time agent enrollment token switched on in Templates.
The VM is not joined to the domain and has no fixed hostname you rely on.
No agent.key is left in the agent folder — every clone must create its own.
The template is shut down cleanly before you convert it.

Troubleshooting

Log says	Meaning
can't connect / timed out	Port `8787` blocked between the guest and the Verlocx server, or the wrong `backend_url`.
backend identity mismatch	`backend_pubkey` doesn't match the backend's `server.pub` — wrong key, or the backend got a new key.
enrollment rejected	No valid token — expired (24 hours), already used, or the template doesn't have One-time agent enrollment token on. With a `bootstrap_secret`: it differs from the backend's, or the backend has `allow_bootstrap_enrollment = false`.
no enrollment token in SMBIOS and no bootstrap_secret	The VM's SMBIOS carries no token. Switch the template rule on and clone again, or offboard with re-enroll and stop/start the VM.
already enrolled with another key	This VM's identity is enrolled with a different key — e.g. the agent was reinstalled. Offboard the agent in Fleet, then it enrolls again.
authenticated, but the VM shows offline	The VM in Verlocx has a different SMBIOS UUID than the guest reports — e.g. a VM cloned outside Verlocx.
update check failed	The portal's `/api/agent/manifest` isn't reachable on 443, or no signed release is published.
update refused: no release key / bad signature	`release_pubkey` is missing, malformed, or doesn't match the key the release was signed with.

Verlocx agent