xeroctl agents

Manage inference agents and the join keys used to enroll them. Part of the xeroctl CLI.

Overview

Agents are the compute workers that run model inference workloads in your project. Each agent registers with the platform, receives model assignments via the sync system, and reports health via heartbeats.

The agents command group has two sections:

  • agents -- CRUD and event history for registered agents.
  • agents join-keys -- Manage one-time enrollment tokens used by new agent workers to register themselves.

Both sections use a unified flag-based interface. The action is determined by which flag is present. Only one action flag may be specified at a time.

Agents Usage Pattern

bash
xeroctl agents # List agents xeroctl agents <id> # Show agent details xeroctl agents --create --name <name> # Create an agent xeroctl agents <id> --update --name <name> # Update an agent xeroctl agents <id> --delete # Delete an agent xeroctl agents <id> --events # List agent events

agents list

List all agents for the project. This is the default action when no ID or action flag is given.

bash
xeroctl agents xeroctl agents --limit 50 xeroctl agents --after agt_abc123

Options

Option Description
--limit <n> Maximum number of results
--after <cursor> Pagination cursor: ID to start after

Output columns: ID, NAME, WORKER_ID, STATUS, REGION, LAST_HEARTBEAT. The STATUS column is color-coded.

agents get

Show details of a specific agent including worker ID, status, region, last heartbeat, max concurrent requests, and description.

bash
xeroctl agents agt_abc123 xeroctl agents agt_abc123 -o json

agents create

Create a new agent record. The --name option is required. A join key is typically used when the actual worker process needs to self-register, but administrators can also pre-create agent records.

bash
# Minimal creation xeroctl agents --create --name "gpu-worker-1" # With region and capacity xeroctl agents --create \ --name "gpu-worker-2" \ --region us-east \ --max-concurrent 8 # Full options xeroctl agents --create \ --name "gpu-worker-3" \ --region eu-west \ --max-concurrent 4 \ --description "H100 worker for production" \ --supported-tiers priority,default \ --storage-limit 500

Options

Option Description
--name <name> Agent name (required)
--region <region> Deployment region (e.g., us-east, eu-west)
--max-concurrent <n> Maximum number of concurrent inference requests
--description <text> Human-readable description of the agent
--supported-tiers <tiers> Comma-separated service tiers this agent handles (e.g., priority,default)
--storage-limit <gb> Storage limit in gigabytes for model files

agents update

Update an existing agent. Supported fields for update are name, description, and max-concurrent. At least one must be provided.

bash
xeroctl agents agt_abc123 --update --name "gpu-worker-1-renamed" xeroctl agents agt_abc123 --update --max-concurrent 16 xeroctl agents agt_abc123 --update --description "Updated H100 worker"

Options

Option Description
--name <name> New agent name
--description <text> New description
--max-concurrent <n> New maximum concurrent request count

agents delete

Delete an agent from the project. A confirmation prompt is shown by default.

bash
# With confirmation prompt xeroctl agents agt_abc123 --delete # Skip confirmation xeroctl agents agt_abc123 --delete --force # Dry run xeroctl agents agt_abc123 --delete --dry-run

Options

Option Description
--force Skip the confirmation prompt
--dry-run Show what would be deleted without making changes

agents events

List event history for a specific agent. Events include lifecycle changes, errors, and operational events.

bash
xeroctl agents agt_abc123 --events xeroctl agents agt_abc123 --events --limit 50 xeroctl agents agt_abc123 --events --after evt_xyz

Options

Option Description
--limit <n> Maximum number of events to return
--after <cursor> Pagination cursor: event ID to start after

Output columns: ID, EVENT_TYPE, DETAILS, CREATED.

Join Keys Subcommand

Join keys are single-use (or limited-use) enrollment tokens that allow new agent worker processes to register themselves with the platform. After the token is consumed by the maximum number of agents, it can no longer be used for enrollment.

bash
xeroctl agents join-keys # List join keys xeroctl agents join-keys <id> # Show join key details xeroctl agents join-keys --create # Create a join key xeroctl agents join-keys <id> --revoke # Revoke a join key

join-keys list

List all join keys for the project. Shows ID, status, region, current and max enrollment counts, and expiration.

bash
xeroctl agents join-keys xeroctl agents join-keys --limit 50

Options

Option Description
--limit <n> Maximum number of results
--after <cursor> Pagination cursor: ID to start after

Output columns: ID, STATUS, REGION, ENROLLMENTS (current), MAX, EXPIRES.

join-keys get

Show details of a specific join key including enrollment counts and expiration.

bash
xeroctl agents join-keys jk_abc123 xeroctl agents join-keys jk_abc123 -o json

join-keys create

Create a new join key. The token value is shown once at creation -- save it immediately as it will not be shown again.

bash
# Basic join key xeroctl agents join-keys --create # Scoped to a region with enrollment limit xeroctl agents join-keys --create \ --region us-east \ --max-enrollments 10 # With tier and storage restrictions xeroctl agents join-keys --create \ --region eu-west \ --max-enrollments 5 \ --supported-tiers priority,default \ --storage-limit 1000

Options

Option Description
--region <region> Region to scope the join key to
--max-enrollments <n> Maximum number of agents that can enroll with this key
--supported-tiers <tiers> Comma-separated supported service tiers for enrolling agents
--storage-limit <gb> Storage limit in gigabytes applied to agents enrolled via this key

Security: The join token is shown only once at creation. Store it securely and distribute only to trusted agent worker processes.

join-keys revoke

Revoke a join key, immediately preventing any further enrollments using it. A confirmation prompt is shown by default.

bash
# With confirmation prompt xeroctl agents join-keys jk_abc123 --revoke # Skip confirmation xeroctl agents join-keys jk_abc123 --revoke --force # Dry run xeroctl agents join-keys jk_abc123 --revoke --dry-run

Options

Option Description
--force Skip the confirmation prompt
--dry-run Show what would be revoked without making changes

Examples

Enroll a New Agent Worker

bash
# Create a join key for the new worker xeroctl agents join-keys --create \ --region us-east \ --max-enrollments 1 # Use the printed token when starting the agent worker process # (the worker uses the token to self-register) # Verify the agent appeared xeroctl agents

Inspect and Monitor an Agent

bash
# List all agents xeroctl agents # Get full details xeroctl agents agt_abc123 # View recent events xeroctl agents agt_abc123 --events --limit 20

Clean Up Unused Join Keys

bash
# List join keys and review status xeroctl agents join-keys # Revoke any keys that are no longer needed xeroctl agents join-keys jk_abc123 --revoke --force

xeroctl CLI

Back to the main xeroctl reference.

Agent Types

Learn about agent roles and capabilities.