xeroctl agents - Xerotier

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 exposes the following subcommands:

agents (default), CRUD and event history for registered agents (list, get, create, update, delete, events).
agents join-keys, Manage one-time enrollment tokens used by new agent workers to register themselves (list, create, revoke).
agents pause-exec, Pause tool execution for an agent (optionally workspace-scoped).
agents resume-exec, Resume tool execution for an agent (optionally workspace-scoped).
agents revoke-credentials, Revoke an agent's credentials, forcing re-enrollment.
agents candidates, List, approve, and reject pending candidate workers for an agent.
agents curve-rotate, Initiate a CURVE (Curve25519) control-plane key rotation for an enrolled XEM agent.

The agents and agents join-keys groups use a unified flag-based interface: the action is determined by which flag is present, and only one action flag may be specified at a time. The remaining subcommands are positional verbs.

Deployment-aware: agents resolves the base URL and API key from the active xeroctl deployment (the project id is derived from base_url). Requests hit /v1/management/agents/* on the router. Use xeroctl config use <name> to switch deployments; override a single invocation with --context, --base-url, or --api-key.

Pagination flags: --limit <n> and --after <cursor> apply to every listing subcommand (agents, agents --events, join-keys). Per-command tables below list only command-specific flags.

Global flag: --dry-run is a global xeroctl flag (not specific to delete or revoke). When present on a mutating subcommand it prints the intended action without contacting the router.

Destructive subcommands write router state. Reach for --dry-run first, --force only after.

agents --delete, removes the agent record.
agents revoke-credentials, ends the agent's authenticated session; re-enrollment required.
agents curve-rotate, rotates the control-plane key (owner-only, one-way after acknowledgement).
agents join-keys --revoke, kills future enrollments through the key.

Agents Usage Pattern

Positional arguments documented below as <agent-id> are required unless flagged otherwise.

bash

                    xeroctl agents                                       # List agents
xeroctl agents <id>                                   # Show agent details
xeroctl agents --create --name <name> \
  --worker-id <wid> --public-key <b64> --region <r>   # 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
                

Accepts the shared pagination flags --limit and --after (see Overview).

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. --name, --worker-id, --public-key, and --region are all required. A join key is typically used when the actual worker process needs to self-register, but administrators can also pre-create agent records by supplying the worker identifier and the agent's base64-encoded Curve25519 public key directly.

bash

                    # Minimal creation (all four flags are required)
xeroctl agents --create \
  --name "gpu-worker-1" \
  --worker-id w-001 \
  --public-key <base64-curve25519-public-key> \
  --region us-east

# With capacity and description
xeroctl agents --create \
  --name "gpu-worker-2" \
  --worker-id w-002 \
  --public-key <base64-curve25519-public-key> \
  --region us-east \
  --max-concurrent 8 \
  --description "H100 worker for production" \
  --supported-tiers priority,default
                

Options

Option	Description
`--name <name>`	Agent name (required)
`--worker-id <id>`	Mesh worker identifier (required)
`--public-key <b64>`	Base64-encoded Curve25519 public key for the agent (required)
`--region <region>`	Deployment region, e.g. `us-east`, `eu-west` (required)
`--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`)

agents update

Update an existing agent. At least one of the supported fields 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"
xeroctl agents agt_abc123 --update --status suspended
xeroctl agents agt_abc123 --update --region us-west
xeroctl agents agt_abc123 --update --supported-tiers priority,default
                

Options

Option	Description
`--name <name>`	New agent name
`--description <text>`	New description
`--max-concurrent <n>`	New maximum concurrent request count
`--region <region>`	New deployment region
`--status <value>`	New status value (e.g. `active`, `suspended`)
`--supported-tiers <tiers>`	Comma-separated supported service tiers
`--worker-id <id>`	Replace the mesh worker identifier
`--public-key <b64>`	Replace the agent's Curve25519 public key

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 (--dry-run is a global xeroctl flag)
xeroctl agents agt_abc123 --delete --dry-run
                

--force skips the confirmation prompt. --dry-run is a global xeroctl flag (see Overview).

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
                

Accepts the shared pagination flags --limit and --after (see Overview); the cursor is an event ID.

Output columns: ID, EVENT_TYPE, DETAILS, CREATED.

agents pause-exec

Pause tool execution for an enrolled agent. The agent stays connected and continues to heartbeat, but the router stops dispatching tool-execution work to it. Pausing is optionally scoped to a single workspace; with no --workspace the pause applies to all workspaces the agent serves.

bash

                    xeroctl agents pause-exec agt_abc123
xeroctl agents pause-exec agt_abc123 --workspace ws_team_a
                

Arguments and Options

Name	Description
`<agent-id>`	Agent external id.
`--workspace <name>`	Workspace to scope the pause to

agents resume-exec

Resume tool execution for an agent previously paused with pause-exec. Like the pause variant, the resume may be scoped to a single workspace.

bash

                    xeroctl agents resume-exec agt_abc123
xeroctl agents resume-exec agt_abc123 --workspace ws_team_a
                

Arguments and Options

Name	Description
`<agent-id>`	Agent external id.
`--workspace <name>`	Workspace to scope the resume to

agents revoke-credentials

Revoke the agent's enrolled credentials. The agent loses its authenticated session and must re-enroll using a fresh join key before it can serve traffic again. A confirmation prompt is shown by default.

bash

                    xeroctl agents revoke-credentials agt_abc123
xeroctl agents revoke-credentials agt_abc123 --workspace ws_team_a --force
                

Arguments and Options

Name	Description
`<agent-id>`	Agent external id.
`--workspace <name>`	Workspace to scope the revocation to
`--force`	Skip the confirmation prompt

agents candidates

List, approve, or reject pending candidate workers attached to a specific agent. Candidates appear when a worker has connected but not yet been admitted to the agent's serving pool. The verbs are positional; the agent id is required, and approve/reject also take a candidate id.

bash

                    # List candidates for an agent
xeroctl agents candidates list agt_abc123

# Approve a candidate
xeroctl agents candidates approve agt_abc123 cand_xyz789

# Reject a candidate
xeroctl agents candidates reject agt_abc123 cand_xyz789
                

Subcommands

Subcommand	Description
`list <agent-id>`	List candidates for the agent. Output columns: ID, Status, Agent, Created.
`approve <agent-id> <candidate-id>`	Approve the candidate and admit it to the agent's serving pool.
`reject <agent-id> <candidate-id>`	Reject the candidate; it will not be admitted.

A separate project-scoped surface for candidate approval lives under xeroctl discovery. Use the agents candidates form when you already know the agent the candidate belongs to.

agents curve-rotate

Initiate a CURVE (Curve25519) control-plane key rotation for an enrolled XEM agent. The router instructs the agent to generate a fresh key pair and waits for a signed acknowledgement over the existing authenticated channel before promoting the new key. Owner-only.

bash

                    xeroctl agents curve-rotate agt_abc123
xeroctl agents curve-rotate agt_abc123 --reason "post-incident"
                

Arguments and Options

Name	Description
`<agent-id>`	Agent external id.
`--reason <text>`	Free-text reason recorded in the audit log. Defaults to `scheduled`.

On success the command prints the rotation request id, the dispatch status, and a monitor URL. Track progress with xeroctl agents <agent-id> --events.

Join Keys Subcommand

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

The router management API does not expose a standalone GET-by-id endpoint for join keys. Running xeroctl agents join-keys <id> without an action flag prints a notice and falls back to the list view; query the listing (optionally with --include-terminal) or the agent audit trail for per-key state.

bash

                    xeroctl agents join-keys                             # List join keys
xeroctl agents join-keys --create \
  --name <name> --region <r> \
  --router-addr tcp://router:5555                    # Create a join key
xeroctl agents join-keys <id> --revoke               # Revoke a join key
                

join-keys list

List join keys for the project. By default only live keys are returned; pass --include-terminal to also surface revoked, fully-enrolled, or expired keys.

bash

                    xeroctl agents join-keys
xeroctl agents join-keys --limit 50
xeroctl agents join-keys --include-terminal
                

Options

Option	Description
`--include-terminal`	Include revoked, fully-enrolled, and expired join keys in the output

Also accepts the shared pagination flags --limit and --after (see Overview).

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

join-keys create

Create a new join key. --name, --region, and at least one --router-addr are required. The token value is shown once at creation, save it immediately as it will not be shown again.

bash

                    # Minimal join key (all three flags are required)
xeroctl agents join-keys --create \
  --name gpu-pool \
  --region us-east \
  --router-addr tcp://router:5555

# Multiple router addresses, enrollment cap, and TTL
xeroctl agents join-keys --create \
  --name gpu-pool-eu \
  --region eu-west \
  --router-addr tcp://router-a:5555 \
  --router-addr tcp://router-b:5555 \
  --max-enrollments 5 \
  --ttl-seconds 86400 \
  --supported-tiers priority,default
                

Options

Option	Description
`--name <name>`	Join key display name (required)
`--region <region>`	Region to scope the join key to (required)
`--router-addr <addr>`	Router address the enrolled agent should connect to. Repeatable; at least one is required.
`--max-enrollments <n>`	Maximum number of agents that can enroll with this key
`--ttl-seconds <n>`	Join key time-to-live in seconds
`--supported-tiers <tiers>`	Comma-separated supported service tiers for enrolling agents

Note on --agent-role: The router management API also accepts an agent_role body field constrained to inference or execution. The current xeroctl join-keys create command does not expose this flag; created keys default to inference. To pin execution, use the management REST API directly.

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 (--dry-run is a global xeroctl flag)
xeroctl agents join-keys jk_abc123 --revoke --dry-run
                

--force skips the confirmation prompt. --dry-run is a global xeroctl flag (see Overview).

Examples

Enroll a New Agent Worker

bash

                    # Create a join key for the new worker
xeroctl agents join-keys --create \
  --name new-worker \
  --region us-east \
  --router-addr tcp://router:5555 \
  --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
                

Temporarily Park an Agent

bash

                    # Pause tool execution while leaving the agent connected
xeroctl agents pause-exec agt_abc123

# Resume when ready
xeroctl agents resume-exec agt_abc123
                

Rotate an Agent's CURVE Key

bash

                    xeroctl agents curve-rotate agt_abc123 --reason "scheduled-rotation"
xeroctl agents agt_abc123 --events --limit 20
                

Clean Up Unused Join Keys

Live listings hide revoked, expired, and fully-enrolled keys by default; --include-terminal surfaces them.

bash

                    # List join keys, including terminal states
xeroctl agents join-keys --include-terminal

# Revoke any keys that are no longer needed
xeroctl agents join-keys jk_abc123 --revoke --force
                