Skip to main content

Limits

Claims record ownership. They do not lock the filesystem. The default edit mode is advisory; only a workspace set to enforce refuses conflicting supported edits.

Edit coverage​

  • Claude Code checks Edit, Write, MultiEdit and NotebookEdit. Codex checks apply_patch.
  • Shell commands, redirects and scripts that write files bypass these hooks.
  • Checks fail open after two seconds or on an error. A missing relay.write permission returns status 403 and the edit proceeds.
  • CTRLB_ENFORCE=off skips checks on one machine; CTRLB_OFF=1 turns all hooks off.
  • Codex does not run new or changed hooks until you trust them with /hooks.
  • OpenTelemetry export has no Relay hooks. A direct HTTP integration must implement checks itself.

One holder per key​

The first live hold wins. Other claims are refused until release, expiry or a valid transfer. Claims cover all users' agents in a run, even when your reads show only your own rows. A run id is therefore a coordination boundary, not an access control boundary.

Keys depend on normalized paths or names. Two different task names are two keys unless task registration rejects the unknown name. A finished task blocks later claims until reopen=true starts a new round. Files and slots are never finished. See Claims and edit checks.

Lease and time boundaries​

Normal leases last 10 minutes by default. The default allowed range is 60 to 86,400 seconds. Claim again to renew. Slots last two minutes. A crashed agent's hold ends when its lease expires; a valid takeover can transfer a stalled hold sooner.

After expiry, a task-name release with finished=true can still finish the current round if your hold remains open, the round is unfinished and nobody else holds the task. It writes the finish and returns released: 1, finished: true, finished_after_lease: true. done follows the same rule, returning done: true, finished_after_lease: true; its evidence requirements still apply.

With no live hold, a file path, slot or finished=false release returns released: 0 and writes nothing. A late task finish writes nothing if another agent holds the key; its message names the holder. No open hold in the current unfinished round also means no finish. Read the current task state before reclaiming work.

Relay state reads look back 30 days, so older holds and finishes no longer decide current claims. Resource history uses its own lookback, default 90 days. Runs listings accept windows of at most 366 days. These query windows do not replace your workspace's dataset retention policy.

Relay writes are visible to subsequent reads before the call answers. Session uploads arrive at turn end, before compaction and at session end, so transcript tool calls can lag claims by one turn. A run is live while an agent has written in the last 60 seconds.

Sizes​

ItemLimit or default
Run id and agent id256 bytes each. A run id must not contain /: it is a path segment, so such a run is listed but cannot be opened.
Resource and edit-check path1,024 bytes each.
Post, question, answer, brief and contract text2,000 bytes, cut on a character boundary.
Event text in peers300 characters.
Events returned by peersDefault 40, maximum 500.
Paths per edit check64.
Files or slots attached to a claim32.
Paths per task or contract1 to 32.
Task ask_about entries16.
Task test command500 bytes, one line.
Events in run detailNewest 5,000, with a truncation notice.
Runs per pageDefault 50, maximum 200.
Briefs per readDefault 40, maximum 200.

What is uploaded and limits covers transcript sizes and upload limits.

Who sees what​

A Model Context Protocol (MCP) key acts as its user with that user's roles and dataset grants. Reads need relay.read; writes and edit checks need relay.write and dataset write access. Session search, peers, runs and run details show your own user's rows unless you have relay.read_all.

A grant on the sessions dataset covers its paired Relay dataset. Writes use the configured sessions dataset. By default, Viewers read; Editors read and write; Admins also read across users and manage settings. A Viewer's claim or edit-check request is refused with status 403.

Hosted write tools are on by default. If an agent lists peers but not claim, write tools are off for your CtrlB deployment; ask your CtrlB administrator to turn them on. Changing settings requires a signed-in user with relay.manage; an MCP key cannot change them.

What the run view does not do​

Detectors are computed when the page reads a run. They do not send alerts. Shell edits lack keyed paths, so duplicate-edit detection cannot see them.

done evidence reports what the agent says it checked. A Claude Code witness means the local hook saw that command and exit code; it is only as trustworthy as that machine. CtrlB does not run the test. Codex carries no witness. Cost appears only when the harness supplies it; Codex records tokens without cost.

Local mode​

Local Relay is for one user on one machine. It requires CTRLB_RUN before the agent connects. The run and tool list stay fixed until restart; a run saved only in the config file does not turn Relay on.

There is no team search or continuous hosted sync. ctrlb push copies session records, not Relay rows. Local tasks, holds, contracts and handoffs remain in the local database. See Run Recall on your machine.