Skip to main content

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/register with a body of {"token": "vopk_...", "agentType": "kubernetes" | "linux", "nodeName": "worker-1"}. The response holds agentKey and agentName. 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_....

RequestPurpose
POST /api/v1/agent/heartbeatSent 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/inventoryMultipart upload. Form field meta holds the asset description, sbom the SBOM document.
POST /api/v1/agent/inventory/placeRecords 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/syncLists every asset key the agent currently sees. The server removes the placements of that agent that are not listed.
POST /api/v1/agent/fimSent 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}/downloadDownloads an agent release, for updates.
GET /api/v1/agent/windows-updates/planWindows 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/reportWindows 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"
}
  • kind is host or container. 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, and container:<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.