Run Recall on your machine
Local mode runs CtrlB Recall and CtrlB Relay with one free ctrlb binary and SQLite under ~/.ctrlb. You need no account. After installation, recording sessions, searching records and coordinating agents work without a network connection. Your coding agent may still need a connection to its model provider.
Requirements
Use macOS or Linux on an arm64 or amd64 processor. You need Python 3.9 or newer for the agent hooks and config-reading exports. The script needs curl and either sha256sum or shasum. The clone route also needs Git. For Codex, use CLI version 0.166 or newer.
Install the binary
Run the release script:
curl --proto '=https' --tlsv1.2 -fsSL https://github.com/ctrlb-hq/ctrlb-agent/releases/latest/download/install.sh | sh
Add ~/.local/bin to your shell's PATH if it is not there. Open a new terminal, then initialize:
ctrlb init
Initialization creates ~/.ctrlb/config.json with mode 0600 and the database. It shows a new local key once. The exports below read it from the config; do not paste the key into an agent session. Repeating initialization always preserves the existing local key. It also keeps the port and dataset unless you pass --port or --dataset. An existing config is backed up before replacement.
Choose a release or folder
To install binary release v0.1.0, put CTRLB_VERSION on sh, not on curl:
curl --proto '=https' --tlsv1.2 -fsSL https://github.com/ctrlb-hq/ctrlb-agent/releases/latest/download/install.sh | CTRLB_VERSION=v0.1.0 sh
Set CTRLB_INSTALL_DIR on sh in the same way to change the install folder. Its default is ~/.local/bin. The binary release version is separate from plugin version 0.2.0.
Use a clone instead
Clone the public repository:
git clone https://github.com/ctrlb-hq/ctrlb-agent.git ~/ctrlb-agent
cd ~/ctrlb-agent
Run the local installer:
python3 -I install.py --local
This route installs ~/.ctrlb/bin/ctrlb and runs initialization for you. Add ~/.ctrlb/bin to PATH. Add --version v0.1.0 to select a release, or --port N to choose a port. CTRLB_HOME changes the home used for the binary, config and database.
The script and clone routes use different folders. Choose one route and use it again for upgrades. Hooks look in <CTRLB_HOME>/bin before PATH, so an older clone-installed binary can take precedence over a newer script-installed copy. CTRLB_BIN overrides discovery.
Check the download yourself
Open the ctrlb-agent releases and download SHA256SUMS for your release. Compare the SHA-256 checksum of ctrlb-<os>-<arch> with its entry. The operating system is darwin or linux; the architecture is arm64 or amd64. Both installers verify the checksum before replacing the binary and refuse a missing or mismatched checksum.
Connect Claude Code
Remove old hosted CTRLB_URL, CTRLB_MCP_URL, CTRLB_KEY and CTRLB_MODE settings from your profile and active shell before loading local values. Environment variables override the config file.
Install the plugin:
claude plugin marketplace add ctrlb-hq/ctrlb-agent
claude plugin install ctrlb-agent@ctrlb-agent
Add these two lines to your shell profile. If you use CTRLB_HOME, set it before them. Open a new terminal to load the values before starting your agent.
export CTRLB_MCP_URL="$(python3 -I -c 'import json, os; print(json.load(open(os.path.join(os.environ.get("CTRLB_HOME") or os.path.expanduser("~/.ctrlb"), "config.json")))["mcp_url"])')"
export CTRLB_KEY="$(python3 -I -c 'import json, os; print(json.load(open(os.path.join(os.environ.get("CTRLB_HOME") or os.path.expanduser("~/.ctrlb"), "config.json")))["key"])')"
Connect Codex
Use the same two exports above and remove old hosted settings first. From the public repository clone, run:
python3 -I install.py --codex
Keep the clone where it is because the hooks call scripts in it. Start Codex and run /hooks once to trust the new hooks. Repeat that step when hooks change. Connect Codex explains the optional project instruction block and installer backups.
Start and check
Start a new Claude Code or Codex session. Its session-start hook starts ctrlb serve if the local server is down. New transcript records go to ~/.ctrlb/ctrlb.db, or ctrlb.db under CTRLB_HOME.
ctrlb status
Status shows the version, database size, datasets, row and session counts, and newest record time. Give the agent a task, then check status after its turn ends.
You can start the server yourself with ctrlb serve. It listens on 127.0.0.1, port 7531 by default. Choose a different port with ctrlb init --port N before starting the server. Hook errors go to ~/.ctrlb/hooks.log; server lifecycle messages go to ~/.ctrlb/ctrlb.log.
Tools and several agents
The Model Context Protocol (MCP) connection always lists five Recall tools: search_sessions, find_command, next_actions, fetch_records and session_index. They read stored records and make no model call.
With no CTRLB_RUN, only those five tools are listed and Relay hooks stay off. For several agents, set the same CTRLB_RUN and a different CTRLB_AGENT in each terminal before starting them. Start a run has commands for Claude Code and Codex. The agents share tasks, claims, notes, questions, contracts and handoffs in the local database. Restart every agent to join or change a local run; a run stored only in the config file does not turn on Relay.
Limits
Local mode is for one machine and one user. It has no team search and no continuous sync with hosted CtrlB. Relay limits also apply to local coordination.
Move to hosted CtrlB
When you have a hosted workspace, go to the sidebar and, under AI operations, choose Connect for its URL, sessions dataset and key. Run this yourself in a terminal. Replace <hosted> with <your CtrlB URL> and <name> with that dataset.
export CTRLB_HOSTED_KEY="$(python3 -I -c 'import getpass; print(getpass.getpass("Hosted CtrlB key: "))')"
ctrlb push --url "<hosted>" --dataset "<name>"
unset CTRLB_HOSTED_KEY
The hidden prompt keeps the key out of command arguments and shell history. Alternatively, pass --key-file PATH for a file readable only by its owner, mode 0600. Add --dry-run to show tables and remaining counts without uploading. A dry run still requires the hosted key.
ctrlb push copies stored session rows with their timestamps, backs up the local config and switches it to hosted CtrlB. It stops the local server and keeps the SQLite file. Local Relay rows stay in that file; they are not pushed. Run the same command again to resume an interrupted upload.
Reload the two config-reading exports and restart the agent. For Codex, run python3 -I install.py --codex again from the clone so its saved server URL points to hosted CtrlB, then trust changed hooks with /hooks. Remove any CTRLB_MODE=local override. Upload state is kept, so new sessions continue from their new transcript lines.
Upgrade
Run the same installation route again: the release script or python3 -I install.py --local from your clone. Keep the same install folder. Before the clone route initializes again, stop the running local server; initialization refuses a busy local home.
To stop the server on macOS or Linux, read the process id in ctrlb.pid and check which process has it. If there is no ctrlb.pid file, no local server is running and there is nothing to stop.
pid="$(cat ~/.ctrlb/ctrlb.pid)"
ps -p "$pid" -o command=
If the printed line is a ctrlb command with serve, stop that process:
kill "$pid"
If the line shows another program or nothing, do not run kill. The file can be left behind after a crash or a restart of your machine, and the id can then belong to another process. In that case no local server is running; delete ctrlb.pid.
If you set CTRLB_HOME, use ctrlb.pid in that directory instead. The server handles this signal by closing its HTTP listener and database, then removing the process-id file. Wait for that file to disappear before initializing again.
After the install script replaces the binary, a server that is still running keeps serving the old version until you stop it. The next agent session starts the new version.
Settings reference
| Setting | Purpose and default |
|---|---|
CTRLB_HOME | Config, database, logs and upload state; default ~/.ctrlb. The clone route also puts its binary here under bin. |
CTRLB_INSTALL_DIR | Script install folder; default ~/.local/bin. Set on sh. |
CTRLB_VERSION | Script release tag; default latest release. Set on sh. Clone route uses --version. |
CTRLB_DOWNLOAD_URL | Alternative release base URL. The script uses the value as given. Only the clone route replaces literal <version> with the selected version; its --download-url takes precedence over this variable. |
CTRLB_BIN | Explicit binary path for hooks, configuration and status scripts. |
CTRLB_MCP_URL, CTRLB_KEY | Read the local connection and key with the exports above. |
CTRLB_URL, CTRLB_MODE | Override saved URL or mode; remove hosted overrides for local setup. |
CTRLB_DATASET | Sessions dataset; default agent_sessions. Keep it consistent with initialization. |
CTRLB_RUN | Shared run id; must be set before the local connection starts. |
CTRLB_AGENT | Agent label; falls back to CTRLB_USER, then the session id. |
CTRLB_ENFORCE | off skips this machine's edit checks. |
CTRLB_OFF | 1 turns every hook off. |
CTRLB_SCRATCH_DIR | Run scratch directory; default <CTRLB_HOME>/relay/<run id>/scratch. {run} expands to the run id. |
CTRLB_AUTO_SLOTS | Claude Code shared-file paths, comma-separated; default REGISTRY.md. Empty turns automatic slots off. |
CTRLB_HOSTED_KEY | Hosted key used by ctrlb push; --key-file is an alternative. |
ctrlb init --port N | Saved local port; default 7531. |
ctrlb init --dataset NAME | Saved sessions dataset; default agent_sessions. |
ctrlb serve --port N | Overrides the listening port for this server process. Keep agent connection settings consistent. |
Remove local mode
- Stop your agent sessions. Stop the local server with the steps in Upgrade.
- Run
claude plugin uninstall ctrlb-agent@ctrlb-agent, or runpython3 -I install.py --codex --uninstallfrom the clone for Codex. - From each project where you added instructions, run
python3 -I ~/ctrlb-agent/install.py init --claude --removeorpython3 -I ~/ctrlb-agent/install.py init --codex --removeto remove its project block. - Delete the binary. The script writes one file,
ctrlb, inCTRLB_INSTALL_DIRor~/.local/bin. The clone route writes~/.ctrlb/bin/ctrlb, or the equivalent underCTRLB_HOME. - Remove the two config-reading export lines from your profile and open a new terminal. Delete the clone at
~/ctrlb-agentif you made one. - Delete
~/.ctrlb, or your chosenCTRLB_HOME. This deletesctrlb.db, which holds your records, plus the config, logs and upload state. Keep a copy first if you need the records.