Manage endpoint agent fleets
Create a fleet, issue its enrollment token, watch enrolled devices, and throw the kill switch — the console side of the OS-level endpoint agent.
- Version: 0.4
- Feature: endpoint.agent
- Role: superadmin
- Type: task
The CID222 endpoint agent enforces AI-usage policy on a managed desktop, so a laptop stays governed off the corporate network. Administration → Endpoint Agent is the console side of it: you create a fleet, take its one-time enrollment token, and watch the devices that come back.
What do I need?
- Licence
- Starter
- Role
superadmin
Prerequisites
- You are signed in as the superadmin. An admin_user is refused every call on this page, including reads.
- The appliance runs with `CID_ENABLE_LAB` set to `true`, or is an unlicensed development box. On a licensed appliance the sidebar entry is hidden.
- `JWT_SECRET` is set and persistent — each fleet's policy-signing key is encrypted with a key derived from it.
- You have a way to push an installer to the target machines: MDM, GPO, Intune, Jamf or Ansible.
Danger
This is an unfinished feature and the product says so. The page opens on a panel headed The OS-level endpoint agent is still being built, with the note Not ready to put in front of a customer yet. This page is hidden on licensed deployments. Its own status list reports the Linux agent as Pilot, the Windows agent as Not ready, macOS as Planned and the fleet console as Partial.
/assets/screenshots/endpoint-agent@0.4.pngWho can use this page
The licence key endpoint.agent is in every tier, so licensing is not what hides this page — the
lab flag is. Within the console, superadmin writes and viewer reads; an admin_user is
excluded deliberately, because the fleet list is not scoped to a department and shows every device
on the estate.
Warning
Only the fleet console is licence-gated. The agents' own enroll, policy and heartbeat API stays ungated on purpose, so a deployed fleet keeps enforcing policy if a renewal is late — the admin surface goes dark, the endpoints do not.
Create a fleet
A fleet is a group of endpoints sharing one policy, one signing key and one enrollment token.
Open the console
Select Administration → Endpoint Agent, then Open the work-in-progress console.
The header description changes to Manage OS-level AI-usage enforcement fleets (Windows / Linux) and two actions appear: Back to status and Create fleet. The console is not addressable by URL — reloading returns you to the status panel.
Name the fleet and point it at this appliance
Select Create fleet, enter a Name, and set CID endpoint to the base URL the agents reach this appliance on.
The dialog states: a group of endpoints sharing one policy, and you get a one-time enrollment token to deploy. Trailing slashes are stripped from the endpoint.
Choose what happens when the appliance is unreachable
Set Fail mode to fail-open (allow if CID unreachable) or fail-closed (block AI if CID unreachable).
fail-open is the default. Fail-closed stops AI work on the endpoint rather than letting an uninspected prompt through.
List the AI destinations
Edit AI destinations (one per line).
The dialog is prefilled with chat.openai.com, chatgpt.com, claude.ai, api.openai.com
and api.anthropic.com. Hosts are matched by suffix. This list is the last chance to get it
right — see the warning below.
Create it and take the token
Select Create fleet.
The Enrollment token & deploy commands dialog opens with the alert Copy the enrollment token now — it is shown only once. The appliance stores only the token's hash.
Copy the deploy commands
Copy the commands under Linux — add signed repo, Linux — install & enroll and Windows — unattended MSI.
The live token is substituted into them. The full rollout procedure is in Deploy and integrate.
Danger
A fleet's policy is write-once from this console. There is no policy editor: after creation, the
destinations, fail mode, selectivity, poll interval and QUIC handling can only be changed with a
direct PUT /admin/endpoint-agent/fleets/:id/policy call. Get the destination list right in the
create dialog.
Read the fleet and device tables
The Fleets table subtitle reads {n} fleets · policy polled every 300 s.
| Column | Shows |
|---|---|
| Fleet | The fleet name |
| CID endpoint | The base URL its agents call |
| Policy | The current policy version, as v3 |
| Kill-switch | A switch; on, agents stop intercepting but stay installed and enrolled |
| Status | The raw status word, in practice always active |
Selecting a row opens Devices — {fleet}, refreshed every 15 seconds.
| Column | Shows |
|---|---|
| Device | The hostname, or the first 12 characters of the device id |
| OS | What the agent reported |
| Version | The agent version |
| Applied | The policy version the device has actually applied |
| Last seen | Relative time since the last heartbeat, or never |
| Health | See below |
Health is computed in the browser, first match wins:
| Badge | Meaning |
|---|---|
| action queued | A command is waiting for the device's next heartbeat |
| policy lag | The applied version is behind the fleet's policy version |
| never seen | The device enrolled but has never heartbeated |
| stale | No heartbeat for 15 minutes |
| healthy | Everything else |
Note
The 15-minute stale window is fixed in the dashboard, not derived from the fleet's own poll interval. A fleet polling faster than the 300-second default still waits 15 minutes before a silent device is called stale.
Act on a fleet or a device
Pause enforcement across a fleet
Toggle Kill-switch on the fleet's row.
A Kill-switch enabled toast confirms it and the policy version increments. Each agent stops steering traffic on its next poll — within one poll interval, not immediately. The agent stays installed and enrolled.
Act on one device
Select Kill-switch or Uninstall on the device's row.
A Queued: kill-switch or Queued: uninstall toast confirms it, and Health shows action queued until the device's next heartbeat collects it.
Reissue the enrollment token
Select Rotate token on the fleet's row.
The token dialog reopens with a new token, shown once. The previous token stops working for new enrolments immediately; already-enrolled devices are unaffected because they hold their own keys. Any installer or MDM package carrying the old token must be rebuilt.
Danger
Delete has no confirmation. One click removes the fleet, and its devices cascade with it. The per-device gateway API keys are not removed — they survive as valid keys against the fleet's tenant and must be deleted by hand on Access keys.
How a device becomes trusted
There is no approval queue and no pending state. Possession of the fleet's enrollment token is admission:
- The agent posts the token, its device id, operating system and version to
/endpoint-agent/enroll. - The appliance matches the token's hash to an active fleet, records the device, and mints a gateway API key for that device alone, rate-limited to 600 requests a minute.
- The response carries the first signed policy bundle and the fleet's signing public key. The agent pins that key on first enrolment and verifies every later bundle against it.
- Every poll thereafter authenticates with the device's own key.
GET /endpoint-agent/policyandPOST /endpoint-agent/heartbeatboth refuse a key that does not belong to the device id in the request.
The token is fleet-wide and reusable. The agent discards it locally after a successful enrolment, but the appliance does not enforce single use — anyone holding the token can enrol another device into the fleet until you rotate it.
Warning
"Trust provisioning" also means something else on the endpoint: installing the agent's own interception certificate into the operating system and application trust stores. That is proven on Linux and is a no-op on Windows and macOS, and it belongs to the deployment procedure rather than this console. There is no fleet-wide certificate authority in 0.4, so untrusting a fleet means touching every device.
Fields reference
Create fleet
| Field | Required | Rule | What it does |
|---|---|---|---|
| Name | Yes | Free text | Identifies the fleet |
| CID endpoint | Yes | A base URL | Where its agents send traffic for inspection |
| Fail mode | Yes | fail-open (default) or fail-closed | What an agent does when the appliance is unreachable |
| AI destinations (one per line) | Yes | One host per line, suffix-matched | Which traffic the agent steers into inspection |
What the signed policy bundle carries
| Key | Default | Meaning |
|---|---|---|
version | Stamped by the appliance | Monotonic. An agent ignores a bundle no newer than the one it applied |
cidEndpoint | The fleet's endpoint | Stamped by the appliance; a policy body cannot override it |
selectivity | domain-scoped | Steer only the listed destinations, or all traffic |
failMode | fail-open | From the dialog |
destinations | From the dialog | Hosts, each with an enabled flag |
pollIntervalSec | 300, minimum 30 | The heartbeat and policy poll share this tick, jittered |
killSwitch | false | Stamped from the fleet row |
quicPolicy | block-udp-443 | Force TCP fallback, or accept a QUIC blind spot |
pinnedAppPolicy | log-only | Declared in the schema; nothing reads it yet |
Verify
- The fleet appears in Fleets with Status active and Policy
v1. - After you run the enrol command on a test machine, the device appears under Devices within one poll interval, with Health healthy and Applied matching the fleet's Policy.
- Toggle Kill-switch on. The fleet's Policy increments by one, and within a poll interval the device's Applied catches up.
- Have the test machine visit one of the listed AI destinations. The event appears on All detections with the source set to the endpoint agent, stamped with the device id by the appliance rather than claimed by the caller.
- This module writes nothing to Event logs. Creating a fleet, rotating a token, throwing a kill switch, deleting a fleet and queuing an uninstall on somebody's laptop all leave no audit row.
If it fails
- Invalid enrollment token (401) — the token does not match any active fleet. It was mistyped, or it has been rotated since the installer was built.
- Agent key does not match device (401) — the device's gateway key belongs to a different device id. Re-enrol the machine.
- Missing agent API key / Invalid agent API key (401) — the agent sent no bearer token, or one that is unknown, revoked or expired. Deleting a device's key on API Keys produces this.
- Fleet … not found (404) — the fleet was deleted while an agent was still polling it. The agent gets a 404 rather than a credential error.
- Fleet policy is missing required fields (selectivity, failMode) (400) — a policy written through the API omitted a required field. This fires on every enrolment and every poll, not at the moment the policy was saved.
- Only a superadmin can manage the endpoint agent. — your role can reach the route but not the
page. An
admin_usersees this. - This is a read-only demo account (viewer role) — actions and changes are disabled. with
READ_ONLY_ROLE— a viewer selected a control it may read but not use. - The sidebar has no Endpoint Agent entry — the appliance is licensed and the lab flag is off. The route still opens if you type it.
- A device shows stale but is online — check the machine's clock and that it can reach the fleet's CID endpoint; the console has no reachability test of its own.
Known gaps
- No audit trail. Nothing on this page writes to the event log.
- No policy editor, no staged rollout. The rollout ring is stored and validated but read by nothing; every device in a fleet gets the same bundle on its next poll.
- Windows has never run on real hardware, the installer is unsigned, and macOS is stubbed.
- A queued command is fire-and-forget. It is cleared when the heartbeat collects it, whether or not the device acted on it, and only one command can be pending at a time.
- Device counters are never populated, and the device's own reported status is stored but never shown.
- Steering by resolved address is fragile. Two hostnames sharing an address cannot be separated, a shared content-delivery address pulls unrelated traffic into inspection, and a rotating anycast address can leave traffic uninspected altogether. Treat the current Linux pilot accordingly.
- The agent does not defend itself from a local administrator. The uninstall password is a policy control, not tamper protection.
Next steps
- Deploy and integrate — the rollout procedure the token dialog's commands belong to: signed package repositories, MDM runbooks, trust provisioning and uninstall.
- All detections — where the agent's verdicts land.
- Browser extension — the lighter alternative when you only need to govern browsers.
- Access keys — where each device's own gateway key lives, and where an orphaned one is removed.
Last updated on