OPERATIONS · WHERE XMESH RUNS

Where XMesh runs

XMesh runs where your agent already runs: a process beside your session, not a service you rent. A team can run the same software as one container on an always-on host. Three questions decide whether a deployment really works, and a container makes you answer them: where does its state live, which mind does it think with, and who chose what it may spend?

1. On your own machine (start here)

npm i -g @sym-bot/xmesh@0.10.10
xmesh mcp install --user   # add XMesh to Claude Code once, for every project
xmesh                      # starts XMesh in the background; its passcode is in ~/.xmesh/passcode

That is the whole deployment for one person, or a team on one machine. State lives in ~/.xmesh, and Claude Code reaches it through the bridge you added once. You do not even need to start it: the bridge starts it on first use (Codex needs one codex mcp add line; see the quick start). Your provider login stays with the CLI that XMesh starts; XMesh never sees it. No proxy, volume or licence: evaluation is free for non-production use.

WHAT A SANDBOX MUST KEEP
XMesh needs its own process that stays up when your agent session does not: missions, critics and recall live there. A sandbox deleted with each task loses its state every time. Give it a volume at the container’s /state path.

2. A team’s own host — one container, one volume

To keep XMesh up when no session is open, run one container with one volume on any host: a spare machine, a VPS or a cluster. Nothing in the image is tied to a platform.

THE RELEASE THESE COMMANDS RAN ON
The container commands and output below were run on the published symbotdocker/xmesh:0.9.40 image (the team-root step on 0.9.41), and the page keeps that tag so the record stays exact. For a new deployment, pin 0.10.10. The docker commands should carry over but have not been re-run on it, and the HTTP routes moved under /api/v1/_/ (health, readiness, session, spend/choice).
01
Pull a version you can name
docker pull symbotdocker/xmesh:0.9.40

The image is public on Docker Hub: no login, no build step. Pin the tag so you can always say what you ran. Each tag covers amd64 and arm64 and is built from the same release-gated artifact as the npm package of that version.

02
One volume per team
docker volume create xmesh-acme

docker run -d --name xmesh -p 8787:8787 \
  -v xmesh-acme:/state \
  symbotdocker/xmesh:0.9.40

Everything the deployment owns lives on that volume: /state/xmesh for the server, /state/sym for the mesh nodes. Back it up and you have backed up the team; delete it and the team is gone.

MEASURED
Never run two containers on one volume: nothing coordinates two processes writing the same state. In Kubernetes, use a StatefulSet with replicas: 1, not a Deployment, whose rolling update runs the new pod beside the old one.
03
Check that it is listening
curl -s localhost:8787/api/health
# {"verification":"on — … (opt out: XMESH_MISSION_CRITIC=0)",
#  "spend":{"protection":"workload-cap","chosen":false},
#  "ok":true,"ready":false,"grounded":false}

ok means a process is listening; ready, that it has a mind (the model that does its thinking); grounded, that it is on a live mesh with cognition to reason from. They are separate because the likeliest failure looks healthy: a container that answers and accepts missions but thinks nothing. Here ready:false is correct, since no provider is set; the authenticated /api/readiness says what to set.

verification on means a critic that did not write the work reviews it. Left alone, it runs on the doer’s own mind and model; a second model is configuration (a room’s criticMind and criticModel).

THE PASSCODE
XMesh prints the API passcode once, at first start:
docker logs xmesh | grep passcode
# [xmesh] passcode: ········   (generated on first run — stored in /state/xmesh/passcode)
Send it to POST /api/session (the field is credential; passcode works too) and use the token it returns. On a public URL, do not rely on the generated passcode; see below.

Give it a mind

The image includes its worker mind, a pinned codex CLI (since 0.9.39). Set the provider and a key, and ready becomes true:

docker run -d --name xmesh -p 8787:8787 \
  -v xmesh-acme:/state \
  -e XMESH_LLM_PROVIDER=api:openai \
  -e OPENAI_API_KEY=<your key> \
  -e XMESH_PASSCODE=<credential> -e XMESH_REQUIRE_CREDENTIAL=1 \
  symbotdocker/xmesh:0.9.40

curl -s localhost:8787/api/health
# {…,"ok":true,"ready":true,"grounded":false}

The entrypoint signs the CLI in, checks the login, and removes the key before the server starts, so the key is never on a command line or in the server’s environment. ready:true with grounded:false is normal for a fresh deployment: it can work, but has no peers yet.

WHY A PERSONAL SUBSCRIPTION CANNOT GO IN THE CONTAINER
A personal Claude subscription signs in through the claude CLI from your home directory. No API key stands for it, the container does not include that CLI, and mounting a personal login would tie a shared service to one person. Use your subscription with XMesh on your own machine (section 1); give a team deployment a key.

The spending limit you did not choose

A fresh deployment runs under a default cap of 40 commissioned work units per UTC day, generous against measured use of about six missions a day. /api/health reports chosen:false until someone chooses. When the cap is reached, the refusal says what a day of your work actually costs. XMesh never bills you; the cap limits spend from your own provider account. To set your own, as the deployment’s owner:

curl -s -X POST localhost:8787/api/spend/choice \
  -H "x-mesh-token: $TOKEN" -H 'content-type: application/json' \
  -d '{"mode":"workload","dailyUnits":40}'
# {"ok":true,"spend":{"protection":"workload-cap",
#   "detail":"0/40 work units today (UTC)","remaining":40}}

Choose a daily workload cap, a daily USD limit, or explicitly unbounded spend; each choice is recorded with a name. XMesh never picks unbounded spend on its own, and no MCP tool can set a budget. chosen then reads true on an endpoint that needs no login, so one request per host audits a fleet.

When the host is public

Behind an HTTPS proxy, three settings switch the container to public mode. It then refuses to start without an explicit credential, with one shorter than 16 characters, or with a hop count that is not a number:

-e XMESH_REQUIRE_CREDENTIAL=1        # refuse to start without an explicit credential
-e XMESH_PASSCODE=$(openssl rand -base64 24)   # ≥16 chars, GENERATED — never a typed phrase
-e XMESH_TRUST_PROXY=1               # a HOP COUNT: exactly the edges in front of you

Logins are rate-limited per client address and overall. XMESH_TRUST_PROXY is a hop count, not a switch: trusting every proxy would let a guesser pick its own rate-limit key. Never expose raw :8787 publicly: a bearer token over plain HTTP is a credential in the clear.

YOUR OUTBOUND BOUNDARY
Set XMESH_LLM_BASE_URL to an in-house gateway and every API request is pinned to it. A redirect to a vendor host is refused before any connection opens, on retry and failover too. The product’s own tests check this in both directions.

On a persistent host, name the team root

On a platform that mounts a network volume, put the team root (where XMesh keeps its state) inside the mount:

-e XMESH_VOLUME_MOUNT=/workspace
-e XMESH_TEAM_ROOT=/workspace/xmesh-teams/acme-prod
ON 0.9.40, ADD A THIRD LINE
-e SYM_STATE_DIR=/workspace/xmesh-teams/acme-prod/sym. Without it, 0.9.40 writes the node stores (the cognition later missions are briefed from) to the container user’s home, off the volume: the second mission’s brief carried none of the first’s cognition. 0.9.41 derives the path from the team root, so there the line is redundant but harmless.

The volume then carries a marker of its deployment: a container naming a different team root on it refuses to start. The image starts as root only to take ownership of those paths, refuses a bad layout by name (a mount of /, a root outside the mount, a mount without a root), then switches to an unprivileged user. A production-team licence is tied to the team root’s full path: the same path is the same team, on any host.

Removing it

docker rm -f xmesh && docker volume rm xmesh-acme

The second command is the one that matters: the volume holds the team. Check that it is gone; from outside, an empty deployment and a healthy one look alike.

Kubernetes

Four decisions matter:
1. A StatefulSet with replicas: 1.
2. Run as uid 1000 with fsGroup: 1000, so the volume claim is writable and the image never starts as root.
3. readOnlyRootFilesystem, with writable emptyDirs at /tmp and /home/node (the login home).
4. No PodDisruptionBudget: with one replica, minAvailable: 1 blocks every node drain.

This setup answered ready:true on the published 0.9.40 image. A reference manifest is part of the evaluation pilot; ask through contact@sym.bot.