Skip to main content

​
Enrollment & Installer Packages

An installer package is the unit you build to deploy the agent. It bundles the platform, the tags and group a device should join, and a dedicated enrollment key — so the install command is self-contained.

​
Creating a package

In Admin → Agent Registry → OS Agents, create a package with: On save, SecureAI auto-generates a dedicated API key scoped to agent:enroll and stores it as the package’s enrollment key, so the install command needs no separate credential. Deleting the package deactivates that key.

​
Enrollment groups (auto-pin)

The package’s enrollment group is a hard pin: a device that enrolls with the package is bound to that group on first contact. Group membership then drives which policy the device resolves.

​
The enrollment handshake

When the agent first runs it calls POST /enroll using the enrollment key and sends its machine id, hostname, OS, architecture, version, fingerprint, and capabilities. The backend:
  1. Registers (or matches) the device.
  2. Issues a per-device token, shown once, that authenticates all subsequent calls.
  3. Returns the runtime configuration (resolved policy, egress settings, routing, etc.).
The per-device token rotates on every enroll. A device that has been revoked cannot re-enroll — the enroll response reports revoked: true, and the device stays cut off until an admin re-enables it.

​
Backend URL resolution

The agent calls home to BACKEND_URL. On the server side the effective URL is resolved from forwarded/request-origin headers and can be overridden with the SECUREAI_AGENT_URL environment variable, which is useful behind reverse proxies.

​
Managing enrolled devices

From the OS Agents tab you can, per device: send a command, revoke / re-enable, delete, assign a group, and link/unlink an owner user. Bulk operations are supported. Command delivery is over a WebSocket channel with a heartbeat-queue fallback (commands queued while a device is offline are delivered on its next heartbeat, with a 1-hour TTL).