Private Agents

Overview

For a side-by-side of private agents vs. shared agents, see the Agent Types overview.

This page documents the project-scoped Frontend API (authenticated with a project API key or dashboard session). The router also exposes a parallel API-key-authed management surface at /:project_id/v1/management/join-keys and /:project_id/v1/management/agents; see the API reference for details. Defaults may differ between the two surfaces.

Agent Fields

The following fields describe an enrolled agent. They are returned by the agent list and detail API endpoints.

Join Key Management

Join keys are secure tokens that authorize a backend agent to enroll in your project. Each key is tied to a specific project, carries a region assignment, and expires after a configurable TTL (maximum 1 hour). Keys can be single-use or multi-use.

API Endpoints

Join Key Fields

The following fields are accepted when creating a join key (POST).

The response for a create request includes the full key value exactly once. It cannot be retrieved later because only the SHA-256 hash is stored.

The list and detail responses include the following join key fields:

Join Key API Examples

In the examples below, replace proj_ABC123 with your project external id (e.g. proj_a1b2c3d4). The route parameter is named :projectId and accepts the project external id.

Create a Join Key

List Join Keys

Get a Join Key

Revoke a Join Key

Agent API

Agents are enrolled automatically using a join key (see Agent Enrollment). Once enrolled, you can list, view, update, and remove agents via the following endpoints.

PATCH Request Body

All fields are optional. Only provided fields are updated.

Agent API Examples

List Agents

Get Agent Details

Suspend an Agent

Resume an Agent

Get Agent Events

Remove an Agent

Agent Enrollment

To enroll a private agent:

1. Create a join key in the dashboard or via the API (see Join Key API Examples).
2. Save the full key value immediately, it is shown only once.
3. Run the XIM agent with the enroll subcommand, passing the join key.
4. The agent authenticates with the router and establishes a secure encrypted connection.
5. The agent transitions to active status and begins sending heartbeats. It is then ready to receive inference requests.

After enrollment, start the agent in serve mode to begin handling inference requests. See the XIM Deployment guide for detailed setup instructions.

Agent Monitoring

The agent dashboard at /agents provides real-time visibility into your enrolled agents:

• Heartbeat status: whether each agent is actively communicating with the router.
• Current load: active request count and capacity.
• Model information: which model is loaded and its serving state.
• Event history: per-agent log of significant lifecycle events.

Programmatic Access

For programmatic snapshot access to your fleet, use the documented REST endpoint GET /api/v1/projects/:projectId/agents (see Agent API) with a project API key.

Heartbeat Tracking

The router tracks the last_heartbeat_at timestamp for each agent. An agent with a heartbeat older than the staleness threshold (default 30 seconds; configurable via XEROTIER_FRONTEND_HEARTBEAT_TIMEOUT_SECONDS) is considered disconnected and excluded from routing decisions until it reconnects and resumes sending heartbeats. The effective status shown in the dashboard and API is derived from both the stored status and heartbeat freshness.

Agent Lifecycle

Agents transition through the following status states. The status field in the database reflects the stored lifecycle state. The effective_status is computed at runtime from the stored status and heartbeat freshness.

Allowed Transitions

State Diagram

stateDiagram-v2
    [*] --> pending: join key issued
    pending --> active: enrollment handshake
    pending --> dead: join key expired
    active --> suspended: PATCH status=suspended
    active --> disconnected: heartbeat timeout
    active --> dead: extended absence
    disconnected --> active: heartbeat resumes
    disconnected --> suspended: owner suspends
    disconnected --> dead: extended absence
    suspended --> active: PATCH status=active
    suspended --> dead: extended absence
    dead --> [*]
                

Single-Agent Queuing

When only one agent is available for an endpoint's tier, the router queues incoming requests instead of immediately returning a 503 error. This matters for XIM deployments with a single backend agent.

The queue timeout is configurable via XEROTIER_SINGLE_AGENT_QUEUE_TIMEOUT_S. If the agent does not become available within the timeout, the request fails with a timeout error.