Run your first xMesh mission

One package installs both commands: xmesh runs the local runtime and xmesh-mcp lets a coding agent call it.

npm install -g @sym-bot/xmesh
# added 182 packages in 7s

From the project you are working in, start xMesh in a terminal and leave it running. Nothing to declare: the mind a mission runs inside is detected — the claude CLI on your PATH, on your own login — and the independent review of every mission runs on it too.

cd demo && xmesh
# [xmesh] API on http://localhost:8787
# [xmesh] passcode: ········   (generated on first run — stored in ~/.xmesh/passcode)
# [xmesh] MCP bridge wired: demo/.mcp.json → …/@sym-bot/xmesh/mcp/xmesh-mcp-server.mjs (XMESH_URL=http://localhost:8787)
#         Restart or reconnect your coding agent (Claude Code: /mcp) to load the tools.

Started from a project directory, it wrote that directory’s .mcp.json itself. A fresh runtime commonly reports ready:true, grounded:false: it can run work but has no mesh peers yet. That is an isolated deployment, not a broken one. On Codex instead: XMESH_LLM_PROVIDER=cli:codex xmesh.

Independent mission review is on by default: every mission starts a critic that reviews a completion it did not author, under a skeptical membrane that weights the acceptance criteria and the reviewer’s stance above the doer’s own framing. Its verdict is recorded on the mission row separately from the completion — approved, objected, or absent when no verdict arrived within the window a completed mission is held open — and /api/health reports the verification state. Opt out with XMESH_MISSION_CRITIC=0 only when you deliberately prefer lower usage to independent review.

Which model that critic runs on is yours to set, and it is the lever worth pulling. Left alone, the critic resolves to the same mind as the doer: the review is independent in authorship and stance, on one vendor’s model. The lever is the room’s policy, not an environment variable: the same PUT /api/rooms/<room>/policy call shown in step 4 takes criticMind and criticModel beside doerMind and doerModel, so a room can put its critic on a different vendor’s CLI or on a lane behind an API key. Our own published measurement of this ran single-vendor, so treat cross-vendor review as the configuration we recommend rather than one we have published numbers for.

Restart Claude Code in that directory (or run /mcp) and approve the xmesh server when it asks. The mesh_* tools are then available. Nothing else is required.

Your connection’s seat — who missions are recorded as asked-by and where completion confirmations go — is derived from the Claude Code session (claude-<project>-<session>, the same name the SYM mesh plugin uses there, so confirmations reach that plugin when it is installed). The run below printed seat: claude-demo-70f4ba (derived from this Claude Code session) on the bridge’s first line. Set XMESH_SEAT to pin another name; the runtime matches the seat exactly. An identified requester receives mission status and completion confirmations. A connection wired by hand with no seat still runs its missions, but the requester is recorded as anonymous and receives no pushed confirmation; the mission reply says so immediately and gives the pull path.

Another project later? Run xmesh there too: it finds the runtime already running, wires that project to it, says so, and exits. One runtime serves every project and every Claude Code session on the machine, each under its own seat. For Codex, or to wire a directory by hand:

codex mcp add xmesh --env XMESH_URL=http://localhost:8787 --env XMESH_SEAT=my-coding-agent -- xmesh-mcp
# or, from any project directory:
xmesh mcp install --url http://localhost:8787

Fully restart the coding agent after adding or changing the server. MCP tool schemas are cached when the connection opens; restarting xMesh alone does not refresh them.

The provider you started with is the mind missions run inside, on your own login. To run them on a model behind an API key instead — OpenAI here, or any endpoint that speaks the OpenAI or Anthropic API — save a lane and point a room at it. Everything below was run as written on 5 September 2026 against xMesh 0.9.45; what it printed is quoted.

Put the key in a file the runtime can read. It is read from that file when a mind is spawned and is never placed in an environment variable.

umask 077; mkdir -p ~/.xmesh-teams/core-team/secrets
printf '%s' 'sk-…' > ~/.xmesh-teams/core-team/secrets/openai.key

Exchange the passcode for a session token, then save the lane. protocol is the API the endpoint speaks. The runtime immediately asks the provider whether it serves the model you named and records the answer beside the lane; Station’s Models panel shows the same table.

TOKEN=$(curl -s -X POST localhost:8787/api/session -H 'content-type: application/json' \
  -d '{"credential":"<passcode>","seat":"me"}' | jq -r .token)

curl -s -X PUT localhost:8787/api/lanes/openai -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"protocol":"openai","transport":"api","baseUrl":"https://api.openai.com/v1",
       "keyFile":"/Users/you/.xmesh-teams/core-team/secrets/openai.key",
       "model":"gpt-4o-mini","pool":"openai","capabilities":["text","code"]}'

curl -s -X POST localhost:8787/api/lanes/openai/probe -H "Authorization: Bearer $TOKEN"
# → "provider confirms 'gpt-4o-mini' (one of 127 it lists)"

Point a room at the lane, and file a mission with that room as its origin.

curl -s -X PUT localhost:8787/api/rooms/my-room/policy -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"doerMind":"openai","doerModel":"gpt-4o-mini"}'

curl -s -X POST localhost:8787/api/missions -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{
    "originRoom": "my-room",
    "intent": "In your current working directory, write the file openai-proof.md with exactly two lines: line 1 "lane: openai"; line 2 "sum: " followed by the sum of the integers from 1 to 100. Do nothing else.",
    "criteria": "CHECK: file openai-proof.md\nCHECK: contains openai-proof.md sum: 5050\nCHECK: contains openai-proof.md lane: openai"
  }'

The mission was accepted in 5 seconds and completed in 24, three of three checks passed, the critic raised no objection, and the file held its two lines. The evidence that it ran on the lane is the runtime’s own record, not anything the model says about itself — a model asked which model it is can only echo its context. The daemon log (/tmp/meshlog/server.log on macOS) recorded, at spawn:

[mission-dbafd5-doer-1] on mesh room 'mission-dbafd5' · mind=codex · lane=openai · model=gpt-4o-mini · workspace=…
[mission-dbafd5-doer-1] run lane — openai · transport=api · mind=codex · model=gpt-4o-mini · api.openai.com

and the mission row shows mind: codex/gpt-4o-mini. Your provider’s usage page is the independent check: the calls appear there, on the key in the file. Two things to know from the run: a Codex doer writes only inside its mission workspace, so name files relative to the working directory rather than absolute paths elsewhere; and the MCP bridge must match the daemon’s version, because an older bridge drops the origin room and the mission runs on the default mind.

A fresh install runs under a default cap of 40 work units per UTC day — generous against measured normal use, and one work unit is one commissioned admission, not one model call. It is a default, not a decision: /api/health reports chosen: false while it is in effect, and when the cap binds, the structured 402 that refuses the mission says nobody chose the limit and reports what a day of your own work actually cost — the fact you lacked at first contact. The choice is deliberately not a tool an agent can call: the mesh never sets its own budget, and unbounded spend is never a default — it takes an explicit call with a name recorded against it. To replace the default (a daily workload cap, a daily USD line, or explicitly unbounded), read the passcode printed by xMesh, create a validator session, then record the choice once:

If you meet a 402 elsewhere: there are two, and they are unrelated. The spend cap above refuses a mission until the default (or your choice) allows it; the licence 402 on Enterprise Federation endpoints refuses cross-organization reads without a production Team Mesh licence. Neither is an error in your setup.

curl -s http://localhost:8787/api/session \
  -H 'content-type: application/json' \
  -d '{"credential":"YOUR_PASSCODE","seat":"developer"}'

# Copy the token from that response:
curl -s http://localhost:8787/api/spend/choice \
  -H 'content-type: application/json' \
  -H 'x-mesh-token: YOUR_TOKEN' \
  -d '{"mode":"workload","dailyUnits":40}'

In the restarted Claude Code, ask it to run any useful task in xMesh. You do not need to name an MCP tool or write tool syntax; the ask carries your project directory, so “this repository” means the one you are in and the deliverable lands there.

Run this task in xMesh: review this repository and identify the top three release risks.

Claude Code invokes mesh_mission and returns the mission id. This is what the run above recorded for exactly that ask, on a two-file demo repository:

mission: mission-88cb61   seat: claude-demo-70f4ba   project: …/demo
requested → accepted 1.3 s · accepted → completed 203 s · checks 2/2
risks.md written into the repository: 119 lines, first finding
  "1. The package has no entry point, so src/math.js is unreachable to any consumer — src/math.js:1-2, package.json:1"

The doer read the repository, wrote the file into it, and said in the file what it had not verified by running code. The critic’s verdict lands on the mission row separately; when this row was read a minute after completion none had landed yet. Keep the mission id: mesh_missions with that id returns the full record — transitions, review, artifact — even after the temporary crew dissolves.