Endpoint & Agent Management

Scope

If enrollment and host ownership are fuzzy, every downstream operation becomes harder to trust. This page keeps the operator-facing lifecycle model and strips private API or setup references.

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:

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).

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 across multiple endpoints. Select endpoints using the checkboxes, then choose an action:

Available Bulk Actions:

• Run Script: Execute a saved script on all selected endpoints
• Run Command: Execute an ad-hoc command on all selected endpoints
• Service Control: Start, stop, restart, enable, or disable a service on selected endpoints
• Install Software: Install a package on selected endpoints
• Assign Group: Add selected endpoints to an endpoint group
• Assign Fingerprint Policy: Apply a fingerprint baseline policy
• Delete Selected: Permanently remove selected endpoints (requires endpoints.manage permission)

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