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?
- Node.js 20 or newer. The package declares
engines.node >=20. - A git repo per seat. The suit writes files into the project root. Use a branch and a worktree for code changes so the main branch is never edited directly.
- An agent host. Any of the supported bridges: OpenCode, Grok, Hermes, OpenClaw, or Cursor project hooks. You can run more than one host on the same seat.
- A human owner. Money, credentials, deletes, and public posts stay with a person. The install does not change that, and nothing in it asks for a key.
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:
| Writes | What it is | Why it matters |
|---|---|---|
AGENTS.md | The operating manual every host reads first | Same rules on every host |
.xray/codex.json | The codex: the rule set checked before each tool call | Guardrails are enforced, not suggested |
.xray/features.json, .xray/config.json | Feature flags and token limits | Ceremony and context size per seat |
.mcp.json | Seven MCP servers, each run as npx -y 0xray mcp <name> | The tools agents call |
| Bridges | OpenCode, Grok, Hermes, OpenClaw configs, plus Cursor .cursor/hooks.json | Hosts load the same suit |
.gitignore | Seeded from a template only if you have none | Keeps runtime state out of git |
| Mill plant | The mill and inspect skills, then your own src/skills on top | Your 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:
| Host | Command |
|---|---|
| OpenCode | npx 0xray opencode install |
| Grok | npx 0xray grok install (writes project .grok/plugins/0xray) |
| Hermes | npx 0xray hermes install |
| OpenClaw | npx 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.
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.
How do you request a consult?
Want help standing up a fleet? Email consult@0xray.dev.
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.