Agent protocol
This page is for people who write or debug an agent. The shared definitions are in
internal/protocol, and both the agents and the server import that package. A change there is a
change to the agent API.
Registration
An agent has no key until it registers. There are two ways in:
- Enrollment link:
POST /api/v1/install/register. The installer of a host sends the one-time token of the link and receives the agent's key. - Cluster token:
POST /api/v1/agent/registerwith a body of{"token": "vopk_...", "agentType": "kubernetes" | "linux", "nodeName": "worker-1"}. The response holdsagentKeyandagentName. Every start of a Kubernetes agent registers again and gets a new key.
The server stores only a hash of the key. The key is returned once.
Requests from an agent
All requests after registration carry the agent key in Authorization: Bearer vopa_....
| Request | Purpose |
|---|---|
POST /api/v1/agent/heartbeat | Sent every heartbeatInterval. Body: version, hostname, os, arch, distro, container, ipAddress, and osBuild on Windows (such as 10.0.26100.9445). The response may carry an update to install. |
POST /api/v1/agent/inventory | Multipart upload. Form field meta holds the asset description, sbom the SBOM document. |
POST /api/v1/agent/inventory/place | Records a container whose image the server already has. The answer says whether it has the SBOM, so the agent can skip the scan and the upload. Kubernetes agents only. |
POST /api/v1/agent/inventory/sync | Lists every asset key the agent currently sees. The server removes the placements of that agent that are not listed. |
POST /api/v1/agent/fim | Sent every fimInterval when fimPaths is set. Body: every watched file with its path, sha256, size and mode. The response counts the added, modified and deleted files since the previous scan. |
GET /api/v1/agent/releases/{version}/{os}/{arch}/download | Downloads an agent release, for updates. |
GET /api/v1/agent/windows-updates/plan | Windows agents only. Asked about once an hour. The response lists the updates the policy approves now (kb, build, kind), and restartAllowed, which says whether a pending restart may happen now. |
POST /api/v1/agent/windows-updates/report | Windows agents only. Sent after each update run. Body: installed (KB numbers), failed (kb and error), rebootPending, and error for a run that could not finish. |
The meta field is JSON:
{
"kind": "container",
"name": "checkout",
"cluster": "prod-eu-1",
"namespace": "shop",
"pod": "checkout-7d9f8c6b5-x2k4q",
"container": "checkout",
"image": "registry.example.com/shop/checkout:1.8.2",
"imageId": "sha256:...",
"collectedAt": "2026-10-30T12:00:00Z"
}
kindishostorcontainer. Host agents send hosts. Kubernetes agents send containers and their node as a host. The server rejects any other combination.- The asset key identifies an asset inside one agent:
host:<name>for a host, andcontainer:<cluster>/<namespace>/<pod>/<container>for a container. - The response is
{"status": "accepted", "assetKey": "..."}when the SBOM is new and queued for a scan, or"unchanged"when the identical SBOM is already known.
The SBOM is a JSON document in a format the server's SBOM reader recognises, such as CycloneDX, SPDX or
Syft JSON; the server records which format it read. Its size is limited by MAX_SBOM_MB.
Images the server already has
An image is scanned once, however many containers and nodes run it. Before a Kubernetes agent scans and
uploads the SBOM of an image, it sends the container to POST /api/v1/agent/inventory/place. When the
server already has the SBOM, the answer is known: true and the agent does not scan or upload the image.
Otherwise the agent uploads the SBOM as usual.
Synchronisation
The Kubernetes agent sends POST /api/v1/agent/inventory/sync with its list of asset keys whenever its
view of the node changes, such as a pod that went away. The server removes the placements of that agent
that are not in the list and answers with the number removed. An image that no container runs any more
loses its findings with its SBOM. An image that another node still runs stays.
Releases and updates
The heartbeat response can carry an update with the version, the URL of the release, its SHA-256
checksum and its size. The agent downloads the release from the URL, checks the checksum, replaces its
binary and restarts. An agent that runs in a container ignores the update; see
Agent updates.