XEM overview - Xerotier

Overview

Reasoning and execution belong on separate agents. A language model running on an existing XIM node produces the plan and the tool calls. The XEM node, deployed on or adjacent to the target infrastructure, runs them. The router brokers every message between the two; neither side talks to the other directly.

Ownership model: XEM is always project-owned. The platform provides routing, credential encryption (via the router-mandatory XEROTIER_COMPLETION_ENCRYPTION_KEY), and audit logging. The platform does not provide sandboxing, safe execution guarantees, or remediation for XEM actions. If a user deploys a XEM, they accept full ownership of what the model runs.

XIM vs XEM

XIM and XEM are the two agent roles in the Xerotier mesh. They share an enrollment mechanism, transport (CurveZMQ + MessagePack), and audit path, but they own different halves of an agentic loop.

Concern	XIM (Inference)	XEM (Execution)
Output	Tokens, embeddings, tool-call plans.	Side effects on infrastructure.
Runtime	vLLM with model weights; GPU required.	Static Swift binary; no GPU, no model weights.
API key scope	`inference`	`execution`
Workspace binding	Per-project endpoint manifest.	`workspace_agent_bindings` per operational workspace.
Ownership	Platform-managed; router brokers placement.	Project-owned; operator accepts what the model runs.

Architecture

The XEM architecture follows the same mesh pattern as XIM. The router sits at the center, coordinating between the inference agent (XIM) and the execution agent (XEM) via CurveZMQ with MessagePack serialization.

flowchart LR
    Frontend --> Router
    Router --> Scope["Scope / Manifest / Rate-Limit Middleware"]
    Scope --> Approval["Approval Gate"]
    Approval --> XIM["XIM (Inference)"]
    Approval --> XEM["XEM (Execution)"]
    XIM --> Audit["Audit Log (PostgreSQL)"]
    XEM --> Audit
    XEM -. SSE .-> Frontend
    Approval -. SSE .-> Frontend

Request flow: scope check, approval gate, dispatch to XIM or XEM, audit log, SSE back to the frontend.

The flow for a tool execution request is:

The inference model (on XIM) emits a tool_calls response with x_exec: true.
The router validates scope, rate limits, and approval policy.
If the tool is destructive or irreversible, the router triggers a human-in-the-loop approval gate.
The router dispatches the tool call to the appropriate XEM agent.
The XEM executes the tool and returns results.
The router forwards results to the inference model for synthesis.
The final response streams to the frontend via SSE.

XEM requires no GPU, no model weights, and no vLLM. It is a single static Swift binary in a minimal container image, enrolling over HTTPS via the join-key JWT mechanism and establishing a CurveZMQ data plane with the router.

Agents vs Workspaces

A single XEM agent serves many workspaces. Each workspace is a named operational-scope binding (e.g. kubernetes-prod, openstack-platform, docker-fleet). Workspaces come in two kinds:

Kind	Description	XEM binding
`chat`	Knowledge workspaces for conversations, documents, and research.	None, no tool execution.
`operational`	Infrastructure workspaces with scoped credentials and tool access.	Bound to one or more XEM agents via `workspace_agent_bindings`.

Chats live under workspaces. Memories, artifacts, and learnings are workspace-scoped. Promotion from chat to operational is supported (via PUT /:project_id/v1/workspaces/:id with kind=operational); demotion is not.

Capabilities

The router-side surface that XEM agents consume includes:

Exec API, tool catalog, invocation lifecycle, execution records, and raw output retrieval under /:project_id/v1/exec/*.
Approval engine, human-in-the-loop approval gates with SLA and escalation chains.
Internal deep-think, planning hop available to XEM-routed invocations under POST /:project_id/v1/internal/deep-think.
Chat templates, prompt template management under /:project_id/v1/chat-templates/* with platform, project, and workspace scope layers.
User preferences, picker history and pinned items under /:project_id/v1/user/preferences.
Rate limiting, four-layer rate limiter (agent, workspace, tool, user) backed by the configured cache (Redis in production, in-memory by default via XEROTIER_CACHE_BACKEND).
Webhook events, 14 exec.* event types for external integrations (see webhooks).
xeroctl commands, see the xeroctl exec CLI reference for the registered subcommand surface.

API Surface

All XEM-specific endpoints require the execution API-key scope. A key with only inference scope cannot enable x_exec: true in requests, the router returns 403 scope_insufficient.

Family	Path prefix	Scope
Exec (tools, invocations, executions, approvals)	`/:project_id/v1/exec/*`	`execution`
Chat templates	`/:project_id/v1/chat-templates/*`	`inference` (read) / `management` (write)
User preferences	`/:project_id/v1/user/preferences`	`inference`
Learnings	`/:project_id/v1/exec/learnings`	`execution`
Context	`/:project_id/v1/exec/context`	`execution`
Internal deep-think	`POST /:project_id/v1/internal/deep-think`	`execution`

Security Model

CurveZMQ encryption, every ZMQ frame between router and XEM is encrypted with Curve25519.
Manifest-as-allowlist, the router rejects tool names the XEM did not declare in its capability manifest (see error codes for the rejection codes emitted by the exec dispatch path).
Approval gates, destructive and irreversible operations require human approval by default.
Four-layer rate limiting, per-agent, per-workspace, per-tool, and per-user caps prevent runaway execution.
Audit logging, invocation rows are written to execution_audit_log, with foreign keys linking the associated approval and execution records.
Scope enforcement, API key scopes are checked at the middleware level before any handler code runs. The exec dispatch path applies a two-tier check: an umbrella execution scope at the middleware mount, then a per-tool scope evaluated by the exec scope validator before the call reaches the XEM.
Enrollment refresh, /v1/enroll/refresh verifies the XEM token signature inline (no middleware) using a grace-window check; all other XEM-facing routes sit behind the scope middleware stack.

Getting Started

To begin working with XEM execution management:

Ensure your API key has the execution scope enabled.
Browse available tools with xeroctl exec tools or GET /:project_id/v1/exec/tools.
Invoke a tool with xeroctl exec invoke --workspace <wid> --tool kubectl.get --args '{"resource":"pods","namespace":"default"}' or POST /:project_id/v1/exec/invocations.
Monitor execution with xeroctl exec watch <invocation-id> or poll GET /:project_id/v1/exec/invocations/:id.
Configure approval policies per workspace to gate destructive operations.