Endpoint & Agent Management

Scope

How to deploy the agent, view and group endpoints, run remote sessions and bulk actions, read endpoint health, and rotate agent keys.

Covers: agent deployment, endpoint viewing, endpoint groups, remote operations, tags, key rotation, agent configuration

Deploying the Agent

Prerequisites

• Organization created with a secret
• Go agent binary for the target OS/architecture

Get the Organization Secret

Each organization has a unique secret used for agent authentication. Find it in the organization settings or via: The secret field is the value the agent needs.

What Happens During Registration

The agent will:

3. Begin sending heartbeats every 60 seconds
4. Start collecting and reporting endpoint information

Verifying Agent Health

After installation, verify the agent is communicating:

When Inventory Looks Wrong or Incomplete

Inventory arrives as versioned snapshots. Three things explain most of what you will see when it does not match the machine.

“The endpoint’s inventory is stale.” Each upload carries the time the agent collected it, and the backend applies snapshots in that order. A snapshot older than the one already applied is acknowledged and thrown away rather than written, so a retry that arrives late can never roll inventory backwards. The upload. A run of stale verdicts means the endpoint’s clock is behind — fix time sync on the endpoint.

“Some rows are missing from a big fleet member.” Each section has a row cap (software 15,000, services and patches 5,000, event logs and startup programs 2,000, processes 500, interfaces/drives/printers 512). An endpoint over a cap sends the top of the section — for processes, the heaviest by CPU then memory — and reports the true count. Check endpoint_server.inventory_truncated_sections on the endpoint: a value there means the inventory is incomplete, not wrong. Raise the cap in backend/core/ingest/caps.py and agent/pkg/hostinfo/caps.go together;

“The agent reports 413 for endpoint-info.” That is the backend refusing an over-cap section, and the message names the section, the count it saw and the cap. It means the two cap tables have drifted out of sync.

“Inventory has not updated since a control job.” Restarting a service or killing a process triggers a refresh of only the affected sections (services/processes for service and process control, users/groups for user and group control), coalesced so a burst of control jobs produces one upload. The rest of the inventory refreshes on its normal cadence — by default every four hours, plus a forced full sync once a day.

a. Remote Access Sessions

The platform provides three remote access channels: terminal, file browser, and desktop. All use WebSocket connections with first-message JWT authentication (tokens are never passed in URL query parameters).

When the UI and API are hosted on different origins, clients must open these WebSockets against the API origin, not the current page origin.

PAM checkouts can launch into these same Endpoint Details and Remote Desktop flows. That handoff keeps the checkout token in in-memory navigation state rather than the URL, and the normal remote-access readiness contract still decides whether the session can start.

The Endpoint Details page now uses the backend-provided remote_access_status contract to decide whether Terminal, Files, and Desktop are available. An endpoint being online is not enough by itself. The UI shows explicit blocked reasons when permission, feature flags, endpoint feature overrides, tunnel connectivity, or agent capability declaration prevent a channel from starting.

Terminal

Credential modes:

• agent_user (default): Run as the agent’s system user
• su: Switch to a specified user (credentials message sent after auth)
• pam_checkout: Use a checked-out PAM credential (include pam_session_token in auth message). The checked-out username/password is used to launch the shell under that identity on the agent, not as the agent service user.

The browser does not treat the terminal as connected on WebSocket open alone. It waits for explicit session readiness from the backend/agent path before showing the terminal as live. If startup, credential switch, timeout, or tunnel teardown fails, the operator-facing error identifies the real failing boundary instead of collapsing to a generic disconnect.

Sessions auto-close after 8 hours (max duration) or 30 minutes of inactivity.

File Browser

Capabilities: Directory listing, file read/write, upload/download, create/delete/rename. Blocks access to sensitive files (the relevant workflow, private keys).

Deleting files and folders: The agent deletes permanently; there is no recycle bin. Clicking the delete icon opens a confirmation dialog:

• A file: type and confirm.
• A folder and everything in it: type and confirm. The console also asks the server for a one-time authorization for that exact folder on that exact server, which needs a sign-in from the last few minutes. If your sign-in is older, the dialog offers Re-authenticate and return.

Sessions auto-close after 4 hours (max duration) or 15 minutes of inactivity.

Desktop

The desktop path does not silently downgrade a requested rdp session to console, and it does not cosmetically rewrite desktop auth modes to another name. Unsupported or runtime-blocked requests fail closed with the agent-advertised reason surfaced to the operator. The browser also keeps the session in connecting state until the agent confirms desktop_ready. If the agent reports a different desktop mode than the one requested, the UI treats that as a fatal contract violation and immediately closes the session instead of continuing under the wrong mode.

Linux desktop console can also report non-fatal runtime warnings. When the readiness contract includes input_available = false, capture is available but keyboard or mouse injection is not; the Endpoint Details flow warns before connect and the resulting session is view-only. When X11/display access itself is missing, desktop stays blocked with an explicit runtime-prerequisite message instead of falling back or pretending the session can start.

Linux rdp / New Session is now conditionally shipped for prepared Tier 1 endpoints. The mode stays fail-closed unless org/account policy enables Linux multi-session prep, the endpoint has completed the explicit prep/install workflow, and the agent proves both XRDP session primitives and helper launch readiness. When one of those prerequisites is missing, the platform surfaces explicit blockers:

• linux_multisession_toggle_disabled — org/account policy has not enabled Linux multi-session prep.
• linux_multisession_prep_not_installed — required prep/install workflow has not completed on the endpoint.
• linux_multisession_helper_or_session_unavailable — XRDP helper/session primitives are not ready.

Sessions auto-close after 8 hours (max duration) or 30 minutes of inactivity.

Session Recordings

Terminal sessions produce asciicast v2 recordings. Desktop sessions produce binary .cadresdr recordings. Both are accessible via:

Bulk Operations

The Endpoints page supports multi-select for batch operations. Select devices using the checkboxes, then choose an action.

Available bulk actions

Action	Permission you need	What the dialog asks for
Assign Group	endpoint_groups.edit	Nothing extra
Assign Fingerprint Policy	fingerprint permissions	Nothing extra

Deleting a device record is permanent: its jobs, inventory, sessions and group memberships go with it, and nothing in the console restores them.

Why the dialog asks for these things

These are registered destructive actions. The server enforces them, so a script or API client meets the same checks as the console

• The count you type is the number of devices the server measured. A confirmation typed for 40 devices cannot authorize 60.

• The fresh sign-in (step-up) must be under five minutes old. It authorizes this one action on this exact set of devices — for a script or command, also this exact script or command. If the dialog says your sign-in is too old, choose Re-authenticate and return.

• If any selected device is gone or outside your access, the whole batch is refused with “One or more of the selected devices do not exist or are outside your access.” Nothing runs. Reload the list, select again and resubmit.

Remote Access Readiness

Operator-visible blocked states include:

• permission denied
• feature disabled for the organization or endpoint
• tunnel disconnected
• capability manifest missing
• unsupported channel, mode, or credential mode
• runtime prerequisite missing
• Linux multi-session toggle/prep/session blockers:
• linux_multisession_toggle_disabled
• linux_multisession_prep_not_installed
• linux_multisession_unsupported_distro_package_manager
• linux_multisession_helper_or_session_unavailable

When the agent can provide a concrete runtime blocker, the UI now shows that detail directly instead of a generic connection error.

Desktop availability is now driven by the agent-advertised mode/auth matrix inside remote_access_status, not just by backend OS inference. If the agent says a desktop mode or credential mode is unsupported, the Endpoint Details page and the backend both fail closed on that exact path.

• Linux desktop console requires an accessible X11 display. The agent could not find /tmp/.X11-unix/X0 on this endpoint.

If the display is present but input helpers are unavailable, desktop may remain available in view-only mode. In that case the connection modal warns before connect and the desktop session itself repeats the runtime warning so the operator knows capture works but input injection does not.

XRDP teardown is best-effort. The agent stops the desktop helper and verifies whether the XRDP session still exists, but upstream xrdp-sesadmin kill:sid remains unimplemented, so lingering XRDP sessions should be treated as an operator-visible runtime follow-up rather than a guaranteed automatic cleanup.

If you see that message, use terminal or file browser instead, or start/restore the endpoint’s graphical session before retrying desktop.

Agent Key Rotation

If an agent’s Ed25519 signing key needs to be rotated (compromise, periodic rotation):

This updates the stored public key. The agent must already be using the new key for subsequent requests.

Plan Limit — Agent Registration

1. Contact the account admin to upgrade the subscription plan
2. Or decommission unused endpoints to free up capacity

Software Reconciliation

View software reconciliation analysis for an endpoint (compare installed software against the software library):

Returns authorized, unauthorized, and untracked software on the endpoint. Requires software.view permission.

On-Demand Compliance Check

Trigger a compliance check for a specific endpoint without waiting for the scheduled scan:

Requires compliance.manage permission. Returns the scan results immediately.

OOB Auto-Detection

When an agent reports endpoint information, the system automatically detects out-of-band management interfaces based on the hardware manufacturer:

• Dell servers get iDRAC assigned
• HP/HPE servers get iLO assigned
• Supermicro servers get assigned
• Lenovo servers get XCC assigned
• Cisco servers get assigned

Cross-References

Topic	Document