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.
/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.
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).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.
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.
replicas: 1, not a Deployment, whose rolling update runs the new pod beside the old one.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).
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.
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.
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
-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.