Hub / Guides / Configure

Configuration

Configure roles, gates, and limits

Yes. Each control is one file on disk. Roles live in seat folders, rules in .xray/codex.json, ceremony and memory in .xray/features.json, token ceilings in .xray/config.json. Edit your overlays, not managed copies, and postinstall layers them on top, so every fresh session reads the same answers the last one did.

Configuration in a multi-agent system answers four questions: who does what, what rules they follow, how much they can spend, and where the work is recorded. In 0xRay each answer lives in a file on disk, so a fresh session reads the same answers the last one did.

Which file controls what?

FileControlsOwner
AGENTS.mdThe manual hosts read firstManaged by the package
.xray/codex.jsonThe codex: 69 rule terms checked before tool callsPackage, overlaid by your xray/codex.json
.xray/features.jsonFeature flags, temperament, memory routingYou
.xray/config.jsonToken, cache, and memory limitsYou
.mcp.jsonWhich tool servers a host loadsPackage, editable
foundry.jsonPlant choice, extra skills, path remapsYou
.xray/state/STATION.mdThe station card: the live ticket for this seatThe agent, every session

Edit your own overlays (xray/codex.json, xray/features.json, src/skills, src/opencode/agents). Postinstall layers them over the managed defaults, and your file wins when names collide. Editing the managed copy works until the next upgrade, then it is gone.

How should you split seats?

A seat is one named role with its own working folder and its own station card. Typical seats:

The role is written in the seat's own skills and instructions. Do not let two seats own the same lane; that is the root of most ownership thrash.

How much ceremony should a seat enforce?

Temperament sets how strictly the engine enforces planning steps such as analyzing complexity before spawning a sub-agent. Set it in .xray/features.json under suit_temperament.

ProfileBehaviorGood for
guided (default)Ceremony enforcedSmaller or free models
auto on frontier hostsWarns on spawn-without-plan instead of blockingStrong models that plan well

An existing features.json without suit_temperament stays guided. The codex itself is always on in every profile; temperament changes ceremony, never the rules.

How do you cap tokens and memory?

.xray/config.json sets context and runtime ceilings. The values a working seat ships with:

"token_management": { "maxPromptTokens": 20000, "warningThreshold": 15000,
  "contextPruning": { "enabled": true, "aggressivePruning": true, "preserveCriticalContext": true } }

Lower maxPromptTokens to force shorter, cheaper prompts. Keep preserveCriticalContext on so pruning never drops the station card. Cache and heap settings live in the same file; the defaults are fine for most seats.

Where does memory go?

Repertoire is the preferred memory layer. In features.json:

"memory_routing": { "enabled": true, "provider": "repertoire",
  "config": { "signalsPath": ".xray/state/repertoire/curated_signals.json",
              "statePath": ".xray/state/repertoire/inference-state.json",
              "feedbackDir": ".xray/state/repertoire/feedback" } }

Paths sit under .xray/state/, so memory belongs to the seat. Opt out only with "enabled": false.

Where do tickets and messages live?

Every task is a ticket with an owner, a stage, and a state. 0xRay is queue-agnostic: the board can be a git issue tracker, a markdown board in the seat folder (house/WAVEBOARD.md in a reference seat), or both. What matters:

The reference board runs in two modes. With no LIVE_URL set, it is the hand-kept house/WAVEBOARD.md. With LIVE_URL set, seats read cards from a live board over GET /cards (plus /history endpoints), shown as a kanban with columns open, review, fix, merge, retest, and done. Seats check their inbox with live-inbox <seat>. There is no formal published schema for cards, so don't build against field names; treat the tracker as your choice and keep the card pattern: owner, stage, state, link.

Where do keys and credentials belong?

The suit config holds no secrets. Model keys, service tokens, and repo app keys belong to the host or a secret store, and the human owner issues them. Rules that hold across seats:

0xRay documents only the board and inbox variables a seat needs:

VariableWhat it isRequired
LIVE_URLLive board address; unset means the markdown boardYes, for the live board
SEAT_KEYS_DIRFolder holding seat keysYes, for the live board (a missing one exits 2 and names it)
LIVE_OWNEROwner label on cardsOptional
XRAY_MAINPath to your main checkoutOptional
LIVE_CURSORSCloud-run cursorsNot required

Everything secret stays in your host vault: per-seat repo app keys (gh-<seat>), npm one-time codes, and model keys. 0xRay does not define your host's own model-key variable names; check the host's docs.

How do you choose the plant and skills?

foundry.json chooses the mill plant. The built-in plant is mill plus inspect. "plant": "@0xray/blip" swaps in that package's declared skills. "shopPlant" adds extra shop skills. Your src/skills overlay on top.

How do you request a consult?

Need a second pair of eyes on your config? Email consult@0xray.dev.

Request a consult

What else do operators ask?

Where does the release gate live?

In the reviewer seat's PASS on the pull request plus npx @0xray/foundry gate, then npx @0xray/foundry gate --verify-only. Instruction files may shorten this to "foundry gate". With a global install the command is 0xray-foundry gate. A green build is the first check, not the ship. More in ship gates.

How do I stop runaway spend?

Token ceilings here, one deep-work run per ticket, and a weekly hold line set by the owner. See compute discipline.

Does the operating-kit config ever hold secrets?

No. .xray/config.json and features.json hold limits and flags only. Repo app keys, npm one-time codes, and model keys stay in your host vault.

What happens if SEAT_KEYS_DIR is missing?

With LIVE_URL set, the inbox command exits with code 2 and names the missing variable. Without LIVE_URL, seats use the markdown board and need neither.

Will an upgrade overwrite my rules?

Only if you edited managed files. Keep changes in xray/codex.json, xray/features.json, and src/skills; postinstall layers them on top and your file wins.