Limits

Sizes

What	Limit
Rows per records upload	500. More is refused with 400.
Bytes per records upload	4 MiB. More is refused with 413.
body of a session row	64 KiB
Post text	2,000 characters
Post text in peers	300 characters
peers events	40 by default, at most 500
Paths per edit check	64
Run id, agent id	256 bytes each
Resource, edit check path	1,024 bytes each
Events in one run's detail	The newest 5,000
Search hits	10 by default, at most 25, over the newest (or oldest) 500 candidate rows
fetch_records	50 rows, each body cut at 4,000 characters
Runs per page	50 by default, at most 200

Lease

• A claim lasts leaseSeconds from its hold unless it is released: 600 seconds (10 minutes) by default, 60 to 86,400 seconds.
• A claim's answer gives the end of its lease as lease_until.
• Claiming a key you already hold renews it. The answer is held: true, renewed: true with a new lease_until.
• When the lease runs out, the claim is gone and another agent can claim the key.
• A release after the lease ran out writes nothing. It answers released: 0, and the key is not done. Claim it again, then release it.
• A crashed or killed agent's claim lasts until its lease runs out.

One claim per key

• The first live hold on a key wins. Every other claim on it is refused with held_by until the holder releases it or its lease runs out.
• A key released as done is finished for the rest of the run. Every later claim is refused with finished_by. To redo the work, use a new run id.
• Claims are decided on the key, not on the text passed. See Resource keys.
• Claims in a run cover every user's agents in it, even when each user sees only their own rows.

Retention

• Session rows and relay rows are ordinary logs datasets in your workspace: agent_sessions and _ctrlb_relay_agent_sessions by default. They are kept for as long as your workspace keeps those datasets, like any other dataset.
• Relay reads look back 30 days. Claims and done keys older than that are forgotten, and the Runs list shows the last 30 days unless you choose another range.
• Nothing is updated or deleted by CtrlB Relay. A release is a new row.
• Session rows are uploaded at the end of each turn, before compaction and at session end. A tool call is in the session store after the turn that made it ends.

The edit check

Claims are advisory unless the workspace turns on enforce mode. A claim tells other agents, and the people watching, who is working on what. It does not stop a process from writing a file. Even in enforce mode:

• Only these tools are checked: Edit, Write, MultiEdit and NotebookEdit in Claude Code, and apply_patch in Codex. A shell command that writes a file, such as sed -i, a redirect, git checkout or a script, is not checked.
• The check fails open. If CtrlB does not answer within two seconds, or answers with an error, the edit goes ahead and the error is written to ~/.ctrlb/hooks.log.
• A key without the relay.write permission, such as a Viewer's, gets 403 from the check, and the edit goes ahead.
• CTRLB_ENFORCE=off skips the check on one machine. CTRLB_OFF=1 turns every hook off.
• Agents connected only through OpenTelemetry, or over HTTP without a hook, are not checked.
• Codex skips new or changed hooks until you trust them with /hooks.
• A file the agent holds itself is never a conflict.

The Runs page's detectors (duplicate edits, silent agents) are computed when the page reads a run. There are no alerts on them. Edits made from a shell have no paths, so the duplicate edit detector does not see them.

What a key can do

An MCP (Model Context Protocol) key acts as the user who generated it, with that user's roles and dataset grants.

• Session searches, peers, the Runs list and a run's detail show only that user's rows, unless the role has relay.read_all.
• post, claim, release, the edit check and records uploads need relay.write (Editors and Admins) and a grant on the sessions dataset. Reads need relay.read (every role except Visitor).
• A grant on the sessions dataset covers its relay dataset: a grant on agent_sessions covers _ctrlb_relay_agent_sessions.
• A records row naming another user is refused with 403, and nothing in that upload is written. user_name is always the key's user.
• A key can read the Relay settings but cannot change them, whatever its role. A person signed in to CtrlB with relay.manage (Admins) changes them.
• The key is accepted only in the Authorization header, and only while the workspace's MCP server is on. post, claim and release are available as MCP tools only when write tools are enabled on that server.
• When the user's permissions change, a key generated before the change stops working and answers MCP_KEY_STALE. A Visitor's key is refused. Generate a new key on the Connect screen.

Redaction

The plugin and the Codex hooks replace text that looks like a secret with [REDACTED] before upload. That covers private keys, cloud and API keys, tokens, JWTs (JSON Web Tokens), Authorization and Bearer values, assignments to names ending in SECRET, TOKEN, PASSWORD or KEY, and passwords in URLs. Pattern matching cannot catch every secret. Do not paste real credentials into a session. Rows you upload over HTTP, and OpenTelemetry records, are not redacted by CtrlB.