XEM environment variables

Overview

See Config Files for the YAML companion to this reference.

Prefix Split: XEM_* vs XEROTIER_*

The XEM agent uses the XEM_* prefix for every variable it reads through XEMAgentConfig.load. The only exception is XEROTIER_XEM_METRICS_PORT, which is read directly in XEMAgentCLI before the config layer is materialised.

Do not set XEROTIER_XEM_* for any other knob: those names are not read by the agent. The XIM inference agent uses a different prefix (XEROTIER_AGENT_*); see XIM Agent Variables below.

Connection

Where the agent dials the router.

Name	Default	Purpose
`XEM_ROUTER_URL` required #	unset	HTTPS endpoint of the router used for enrollment and the data plane.
`XEM_JOIN_KEY` required #	unset	One-shot enrollment token issued by the router. Consumed on first boot.

Identity

How the agent advertises itself to the router.

Name	Default	Purpose
`XEM_REGISTRATION_NAME` required #	unset	Stable display name the router uses to track this agent across restarts.

Runtime

Concurrency, lease, and lifecycle tuning.

Name	Default	Purpose
`XEM_LEASE_RENEWAL_INTERVAL_MS` #	`10000`	Cadence (milliseconds) for lease renewal messages to the router.
`XEM_SHUTDOWN_GRACE_SECONDS` #	`30`	Time the agent waits for in-flight executions to finish on SIGTERM before forcing exit.
`XEM_MAX_CONCURRENT_EXECUTIONS` #	`20`	Ceiling on simultaneous tool executions handled by the agent.
`XEM_LOG_LEVEL` #	`info`	Log verbosity. One of `trace`, `debug`, `info`, `notice`, `warning`, `error`.

Filesystem Paths

Where the agent stores keys, queue state, and tool bundles.

Name	Default	Purpose
`XEM_TOOLS_DIR` #	`/var/lib/xerotier/tools`	Directory of tool bundles the agent loads at startup.
`XEM_CREDENTIALS_DIR` #	`/var/lib/xerotier/credentials`	Directory of per-workspace credential files referenced by `credentials_ref` in tool manifests.
`XEM_SIGNING_KEY_PATH` #	`/var/lib/xerotier/agent-signing-key.hex`	Persisted Ed25519 signing-key file used to sign messages to the router.
`XEM_CURVE_KEY_PATH` #	`/var/lib/xerotier/agent-curve-key.hex`	Persisted CURVE key-agreement private-key file.
`XEM_QUEUE_DB_PATH` #	`/var/lib/xerotier/state/queue.sqlite`	SQLite file backing the outbound dispatch queue.

Router Callback

Credentials that let callback-dependent tools (for example, DeepThinkXemTool) dial back into the router. When the auth token is absent the agent leaves the callback nil and affected tools surface router_callback_missing rather than dispatching unauthenticated.

Name	Default	Purpose
`XEM_ROUTER_AUTH_TOKEN` optional #	unset	Bearer token used on router-callback requests.
`XEM_PROJECT_EXTERNAL_ID` optional #	unset	External project id (`ws_<hex>`) attached to callbacks for project-scoped routing.

Observability

Name	Default	Purpose
`XEROTIER_XEM_METRICS_PORT` #	`9095`	TCP port for the Prometheus metrics HTTP server.
`XEROTIER_OTEL_ENABLED` #	`false`	Enables distributed tracing emission. Set to `true` or `1`.
`XEROTIER_OTEL_ENDPOINT` #	unset	OTLP collector endpoint URL for trace export.
`XEROTIER_OTEL_SERVICE_NAME` #	service-supplied	Service name attribute attached to emitted spans.
`XEROTIER_OTEL_SAMPLE_RATE` #	`1.0`	Trace sample rate between `0.0` and `1.0`.

XIM Agent Variables (Cross-Reference)

The XIM inference agent (xerotier-xim-agent) is a separate binary that hosts vLLM and uses the XEROTIER_AGENT_* prefix. Subset listed here; the full set lives in the inventory linked under Further Reading.

Name	Default	Purpose
`XEROTIER_AGENT_JOIN_KEY` #	unset	Enrollment join key for the XIM agent. Alternative to `--join-key`.
`XEROTIER_AGENT_ALLOW_INSECURE` #	unset	Set to `1` or `true` to allow non-HTTPS enrollment URLs (development only).
`XEROTIER_AGENT_LOG_LEVEL` #	`info`	Log verbosity for the XIM agent process.
`XEROTIER_AGENT_MAX_CONCURRENT` #	auto	Optional ceiling on concurrent inference requests.
`XEROTIER_AGENT_METRICS_PORT` #	`9094`	Prometheus metrics port for the XIM agent.
`XEROTIER_AGENT_VLLM_PATH` #	PATH lookup	Absolute path to the vLLM binary.
`XEROTIER_AGENT_VLLM_SOCKET_PATH` #	`/tmp/xerotier-engine.sock`	Unix socket path used to dial vLLM.
`XEROTIER_AGENT_VLLM_SALT_SECRET` #	unset	Server secret for tenant-isolated cache keys.

Precedence

Configuration layers for the XEM agent resolve in this order (later wins):

// 1 defaults Built-in constants compiled into the agent.
// 2 xem.yaml File values from /etc/xerotier/xem.yaml.
// 3 XEM_* env Process environment variables.
// 4 CLI flags xerotier-xem-agent command-line flags.

Secrets such as XEM_JOIN_KEY and XEM_ROUTER_AUTH_TOKEN should flow through environment variables or a secrets manager, not committed YAML.