Hub / Guides / Install

Install

Install a multi-agent ops stack

Yes. One command installs it. Run npm install 0xray in each agent's project folder. Postinstall writes the shared rules, seven tool servers, host bridges, and a station card, so every agent follows the same codex and resumes its ticket after a reset. Then run npx 0xray validate to prove the operating kit is installed.

A multi-agent ops install puts the same operating rules, tool servers, and recovery notes into every repo an agent works in. In 0xRay that is one package install per seat. A seat is one named agent role (builder, reviewer, coordinator) with its own working folder. The install is the same for every seat; the role comes from config, not from a different package.

What do you need before you start?

How do you install the package?

From the seat's project root:

npm install 0xray

That is the whole required step. The package runs a postinstall script (install-bridges.cjs). Postinstall means the setup runs automatically right after npm finishes downloading.

What did postinstall write?

Read the diff before you commit. Postinstall does seven things:

WritesWhat it isWhy it matters
AGENTS.mdThe operating manual every host reads firstSame rules on every host
.xray/codex.jsonThe codex: the rule set checked before each tool callGuardrails are enforced, not suggested
.xray/features.json, .xray/config.jsonFeature flags and token limitsCeremony and context size per seat
.mcp.jsonSeven MCP servers, each run as npx -y 0xray mcp <name>The tools agents call
BridgesOpenCode, Grok, Hermes, OpenClaw configs, plus Cursor .cursor/hooks.jsonHosts load the same suit
.gitignoreSeeded from a template only if you have noneKeeps runtime state out of git
Mill plantThe mill and inspect skills, then your own src/skills on topYour skill wins when names match

MCP (Model Context Protocol) is the open standard hosts use to call tool servers. The seven servers are governance, skills, orchestrator, enforcer, researcher, code-review, and architect-tools. They all ship in the same package, so no extra install is needed.

Postinstall does not write a root SKILLS.md, and it does not unpack the large optional skill costume unless foundry.json sets "costume": true.

Which optional extras should you add?

npx 0xray setup

This adds symlinks, extra hooks, and Hermes skill sync. Run it if you use Hermes or want the hook extras. Skip it otherwise.

Install a single bridge again if a host was added after the first install:

HostCommand
OpenCodenpx 0xray opencode install
Groknpx 0xray grok install (writes project .grok/plugins/0xray)
Hermesnpx 0xray hermes install
OpenClawnpx 0xray openclaw install

How do you verify the install?

Three checks, in this order:

npx 0xray status     # is it installed
npx 0xray validate   # wear check: pack paths, Cursor hooks, mill, repertoire
npx 0xray health     # framework health

Then run npx @0xray/foundry inspect for the mill receipt. A receipt is a file or URL that proves a check ran. Chat output is not a receipt. If validate fails, fix that before you start agents (the house check in stand-up expects a PASS); a half-worn suit is the most common source of agents ignoring rules.

How do you add shared memory?

Repertoire is the memory layer. It ships on by default in the vendored config. For external hosts such as Hermes or Grok, add it next to the 0xRay servers in the host's MCP config:

"repertoire": { "command": "npx", "args": ["-y", "@0xray/repertoire", "mcp"] }

Turning it off is an explicit setting, never a silent default: { "enabled": false, "provider": "repertoire" }.

What should you commit?

Commit AGENTS.md, .xray/ config, .mcp.json, and the bridge files on a branch and open a pull request. Runtime state under .xray/state/ is per seat and stays out of git. The seeded .gitignore template ignores .xray/state/* but keeps .xray/state/LENS.md tracked. One catch: if you already had a .gitignore, postinstall appends a marked block (# --- 0xray suit (postinstall) ---) that ignores all of .xray/ with no LENS.md carve-out. Open your ignore file and check which one you got before you commit. The seeded template also blocks .env*, *.pem, *.key, credentials.json, and **/auth.json.

How do you upgrade?

Bump the version and reinstall. Postinstall runs again and overwrites managed files, marked ``. Keep your own rules in your skills and config overlays, not in managed files, or the upgrade will replace them.

Next, configure seats, gates, and limits.

How do you request a consult?

Want help standing up a fleet? Email consult@0xray.dev.

Request a consult

What else do operators ask?

Does install need an API key?

No. The install writes config only. Model and service keys belong to your host and your human owner.

Can two agents share one repo?

They can, but give each agent its own worktree and its own station card, or two agents will pick up the same ticket.

What if my host is not listed?

Any MCP-capable host can point at npx -y 0xray mcp <server>. Bridges just save the wiring.