Connect over HTTP or OpenTelemetry
Scripts and other agents can send Recall records over HTTP. In the sidebar, under AI operations, choose Connect to generate a Model Context Protocol (MCP) key. Replace <your CtrlB URL> and <your key> in these commands.
Send the key as Authorization: Bearer <your key>, not as a query parameter. Calls act as your user with your roles and dataset grants. Bodies and answers use JSON. Times are microseconds since the Unix epoch.
The paths below use agent_sessions, the default sessions dataset. Change it to your workspace's configured dataset. Uploads require relay.write and write access to that dataset; reads require relay.read and read access. An unknown column returns status 400.
For tasks, claims, questions and edit checks, use Relay over HTTP.
Connect another MCP client
Connect an MCP client to <your CtrlB URL>/mcp with Authorization: Bearer <your key>. For example, add the connection by hand in Claude Code:
claude mcp add --transport http ctrlb "<your CtrlB URL>/mcp" --header "Authorization: Bearer <your key>"
On this route, Claude Code exposes tools as mcp__ctrlb__<tool>. This connection has no hooks: no session upload and no edit checks. Use the plugin or Codex installer when you need those hooks.
Upload rows
curl -sS -X POST "<your CtrlB URL>/ai/sessions/agent_sessions/records" \
-H "Authorization: Bearer <your key>" \
-H "Content-Type: application/json" \
-d '[{"_timestamp": 1793000000000000, "host": "build-01", "harness": "script",
"session_id": "sess-1", "parent_session": "", "agent_id": "", "run_id": "demo-run-1", "agent": "agent-a",
"seq": 1, "block_idx": 0, "role": "assistant", "block_type": "tool_use", "tool_name": "Edit",
"tool_use_id": "call-1", "command": "", "paths": "[\"src/app.py\"]", "body": "{\"file_path\": \"src/app.py\"}",
"is_error": false, "is_summary": false, "cwd": "/work/app", "git_branch": "main",
"cost_usd": 0.0, "input_tokens": 0.0, "output_tokens": 0.0}]'
Answer: 202 {"accepted": 1}.
A partly written upload returns status 500 with {error, accepted}. accepted counts the leading rows already written; resend only the remaining rows. Resending accepted rows writes them again.
- One row per content block:
block_typeistext,thinking,tool_use,tool_resultorresult.session_idandseqare required. The columns are the ones above plususer_name,body_lenandtruncated; an unknown column is refused with400. harnessnames the client. The plugin writesclaudeand the Codex hooks writecodex; another client may name its own.- At most 500 rows (more is
400) and 4 MiB (more is413) per call. pathsis a JSON array, as text, of the files an edit touched. Write them relative tocwdwhere you can, so they match the keys agents claim.- Write numbers as floats with a decimal point (
0.0) and flags as booleans from the first row. The dataset fixes a column's type from the first value it sees. - Leave
user_nameout: CtrlB fills it from the key. A row naming another user is refused with403. - The plugin replaces text that matches secret patterns before upload. For direct HTTP uploads, apply your own secret replacement first.
Search
curl -sS -G "<your CtrlB URL>/ai/sessions/agent_sessions/search" \
-H "Authorization: Bearer <your key>" \
--data-urlencode "term=src/app.py" \
--data-urlencode "order=newest" \
--data-urlencode "limit=20"
Matches term in the text and the shell command of your rows, with 300 characters around each hit. Optional: session_id, tool, order (newest or oldest), one_per_session, limit, offset. You see your own rows unless your role has relay.read_all.
Records of one session
curl -sS -G "<your CtrlB URL>/ai/sessions/agent_sessions/sess-1/records" \
-H "Authorization: Bearer <your key>" \
--data-urlencode "seq_from=1" \
--data-urlencode "seq_to=40"
Rows are in seq order: 50 by default, at most 1,000 when you pass limit. Each body is cut at 4,000 characters unless you pass body_max.
Commands
curl -sS -G "<your CtrlB URL>/ai/sessions/agent_sessions/commands" \
-H "Authorization: Bearer <your key>" \
--data-urlencode "command=pytest" \
--data-urlencode "limit=20"
Every past tool call whose command contains command, newest first, each with its session_id and seq. Pass those to the next call to see what happened.
What came next
curl -sS -G "<your CtrlB URL>/ai/sessions/agent_sessions/sess-1/next" \
-H "Authorization: Bearer <your key>" \
--data-urlencode "seq=12" \
--data-urlencode "k=5"
The result of the tool call at row seq, then the next k tool calls and their results, skipping text and thinking. tool keeps only that tool's calls.
List and index sessions
Route after /ai/sessions/<dataset> | Query and answer |
|---|---|
GET /list | Filters user, harness, run_id, top_level, from, to, limit, offset. Returns {sessions, next_offset} with counts and session details. Default 50, maximum 100 sessions per page; a time window spans at most 366 days. With from and to omitted, it covers the last 30 days. |
GET /index | Filters cwd, branch, limit, since, until. Returns the compact session index described in Recall tools. |
OpenTelemetry only
OpenTelemetry (OTEL) exports the harness's own event log over the OpenTelemetry Protocol (OTLP). It is a separate route from Recall records. Use your workspace's ingest credentials, not your MCP key. Get the dataset's OTLP logs endpoint and Authorization header value from your workspace's connection settings; see Prerequisites.
Replace <your OTLP logs endpoint> and <your ingest credentials> below. The endpoint ends in /api/<org>/<dataset>/_otel/v1/logs.
Claude Code
Add these lines to your shell profile, or put them in front of one claude command:
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="<your OTLP logs endpoint>"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=<your ingest credentials>"
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_ASSISTANT_RESPONSES=1
export OTEL_LOG_TOOL_DETAILS=1
export OTEL_LOGS_EXPORT_INTERVAL=5000
- The three
OTEL_LOG_*lines add the prompt text, the response text and the tool arguments to the records. Without them, the records carry event names, tool names, timings, token counts and cost, but no text. OTEL_LOGS_EXPORT_INTERVALis how often, in milliseconds, the batch is sent. This is the configured interval, not a delivery guarantee.
To tag every record of a run, add a resource attribute. Every record carries it as a column:
OTEL_RESOURCE_ATTRIBUTES=ctrlb.run=nightly-refactor-1 claude -p "Fix the failing tests in src/parser"
Codex
Codex reads its OTEL settings from config.toml. The installer writes them for you, inside the same marked block as the MCP server and the hooks:
cd ~/ctrlb-agent
python3 -I install.py --codex --otel \
--otel-endpoint "<your OTLP logs endpoint>" \
--otel-header "Authorization=<your ingest credentials>" \
--dry-run
The dry run shows header values as "<hidden>". Drop --dry-run to write it. The installer refuses to write your CtrlB MCP key into an OTEL header. The header value is stored in config.toml as given, so the file holds your ingest credentials; keep its mode at 0600.
If you want the export without the hooks or the MCP server, add the tables yourself. This is the layout Codex 0.166 accepts:
[otel]
log_user_prompt = true
log_agent_responses = true
[otel.exporter.otlp-http]
endpoint = "<your OTLP logs endpoint>"
protocol = "json"
headers = { "Authorization" = "<your ingest credentials>" }
exporteris a table here, not a string.exporter = "otlp-http"is rejected when Codex loads the file.endpointandprotocolare required.protocolis"json"or"binary".headersis a map, not a string.tool_result = { max_bytes = 65536 }under[otel]caps the tool output in each record.
Run codex mcp list after editing. Codex loads the whole file for every command and names the key it rejects.
What this export leaves out
OTEL events do not create Recall rows. The five Recall tools, run view and transcript drawer read the records written by the plugin or Codex hooks, not these events.
The export has no thinking blocks, keyed paths, or Recall run_id and agent columns. It does not provide Relay tools, edit checks, secret replacement or past-session uploads. Claude Code can tag events with OTEL_RESOURCE_ATTRIBUTES, but that does not create Relay coordination. Prompt and response text is exported as written.
Use Connect Claude Code or Connect Codex for Recall and Relay, or Run Recall on your machine for local setup.