Deployment & config
How to run the CTXone Hub, and the configuration choices that matter — the shared daemon (the standard setup), running it as a service, giving an agent its own memory, securing the hub with a token when you expose it beyond localhost, and one hub for many users (below). If you followed the Quickstart and everything works, you already have the standard setup; this page is the reference for the rest.
The one rule that governs every setup
Section titled “The one rule that governs every setup”One hub owns one db file at a time. On startup a hub writes a PID lockfile
next to the db (<db>.lock). If a second hub tries to open the same --path
while the first is alive, it refuses to start:
database is already locked by ctxone-hub pid 12345 (lockfile: …/memory.db.lock);refusing to start a second hub against the same dbThis is deliberate — two hubs writing one SQLite file corrupts it (the 2026-04-28 incident). See DATA_SAFETY.md. Everything below is really about who holds that single lock.
How a hub can run
Section titled “How a hub can run”ctxone-hub has two transports for talking to agents, plus the HTTP surfaces:
| Mode | Command | Serves | Owns the db |
|---|---|---|---|
| MCP stdio | ctxone-hub --path DB | MCP tools to the spawning agent | yes, while the agent runs |
| HTTP (+Lens) | ctxone-hub --http --lens --path DB | REST API + web UI + MCP at /mcp | yes, while the daemon runs |
The standard setup is one shared HTTP daemon. An --http hub serves MCP (at
/mcp, Streamable HTTP) + REST + the Lens web UI from one process, and
ctx init (default --transport http) points every tool at it by URL — no
lockfile race, web UI always up, all tools share one graph. ctx init --transport stdio is the escape hatch: each tool spawns its own hub that holds
the lock, so you can’t also run a web UI on that db. Design notes:
the unified-hub design.
Choosing a topology
Section titled “Choosing a topology”Most setups want Topology B (the shared daemon) — it’s what ctx init writes
by default. Topology A is the no-daemon fallback; C and D cover isolation and
one-off inspection.
A. Agent-only stdio (no daemon, fallback)
Section titled “A. Agent-only stdio (no daemon, fallback)”ctx init --transport stdio — each tool spawns and owns its own stdio hub.
Nothing else touches the db.
- ✅ Zero extra processes, no port, no daemon to run.
- ❌ No Lens; can’t attach the CLI-over-HTTP to this db while the agent runs (the CLI reads the same graph, but only through a running HTTP hub). One tool per db — a second tool needs its own db (topology C).
B. Shared HTTP daemon — the default & standard
Section titled “B. Shared HTTP daemon — the default & standard”Run one long-lived hub that serves everything, and point agents, the CLI, and
Lens at it. Nothing spawns its own child; there is exactly one db owner. This is
what a plain ctx init configures.
# 1. Run the one daemon (ideally as a login service — see below — so it's up at boot).ctxone-hub --http --lens --path ~/.ctxone/memory.db
# 2. Point the CLI at it (defaults to http://localhost:3001, so usually optional).export CTX_SERVER=http://localhost:3001
# 3. Configure your tools to connect by URL. http is the default, so plain:ctx init # all detected toolsctx init --tool claude # or one toolctx init (default --transport http) writes an MCP entry like:
{ "mcpServers": { "ctxone": { "type": "http", "url": "http://localhost:3001/mcp?namespace=<detected>" } }}The ?namespace= is filled in from the project detected in the current directory
(same scoping a per-project stdio hub would use). Override the endpoint with
--mcp-url, e.g. --mcp-url http://mybox:3001/mcp.
- ✅ One process, one lock, startup order irrelevant — the reboot race is gone. Lens always up, independent of any agent; multiple agents share one graph.
- ✅ MCP sessions carry on across a hub restart and after five idle minutes: the hub keeps how each began in its db, so a client needn’t start a new one. A session unused for 7 days is forgotten.
- MCP clients reach the daemon two ways, and
ctx init --transport httpwrites the right one per client:- Native URL — Claude Code, Cursor, VS Code get
{"type":"http","url":…}. mcp-remotebridge — Claude Desktop has no native HTTP MCP support, soctx initwrites an stdio bridge (npx -y mcp-remote <url> --transport http-only) that proxies to the daemon. Requires Node/npx on PATH; a note is printed when this is used.- Codex — native HTTP via a
urlkey inconfig.toml([mcp_servers.ctxone]\nurl = "…/mcp?namespace=…").
- Native URL — Claude Code, Cursor, VS Code get
- ⚠️ A single daemon has no per-cwd project detection, so one agent config maps to one namespace (baked into the URL). An agent that roams many repos uses one fixed namespace or per-workspace configs. Need per-cwd auto-scoping? Use stdio (topology A) — it’s still fully supported.
C. Give an agent its own dedicated db (isolation)
Section titled “C. Give an agent its own dedicated db (isolation)”Point one agent at a different --path so it never contends with your shared
hub or another agent. Two separate files → two separate locks → no conflict, and
two independent memory graphs.
Edit that agent’s MCP config (or run ctx init --tool <name> after setting the
path). The stdio entry looks like:
// e.g. ~/Library/Application Support/Claude/claude_desktop_config.json{ "mcpServers": { "ctxone": { "command": "/opt/homebrew/bin/ctxone-hub", "args": ["--path", "/Users/you/.ctxone/claude.db", "--agent-id", "claude-desktop"] } }}Use this when:
- You want Claude’s memory kept separate from a shared/team graph.
- Two agents on one machine should not see each other’s memory.
- You’re experimenting and don’t want to touch your main graph.
Isolated dbs do not sync. A fact remembered in
claude.dbis invisible to the hub servingmemory.db. No two hubs sync yet: to share memory between machines, connect them to one hub (Connect to a Hub). To browse an isolated db in Lens, run a hub on it at a different port while the agent is stopped, or on a copy:ctxone-hub --http --lens --path /Users/you/.ctxone/claude.db --port 3002.
D. Browse a live agent’s memory without fighting the lock
Section titled “D. Browse a live agent’s memory without fighting the lock”You can’t open a second hub on a locked db. To look at the graph an agent is actively using, snapshot it and serve the copy:
cp ~/.ctxone/memory.db /tmp/lens.dbctxone-hub --http --lens --path /tmp/lens.db --port 3002Read-only snapshot; it won’t reflect writes after the copy. (The proper fix is the shared daemon in topology B — one owner, Lens live on the same graph the agents write.)
Configuration reference
Section titled “Configuration reference”Where the db lives
Section titled “Where the db lives”ctx init points agents at the canonical path:
- macOS / Linux:
~/.ctxone/memory.db - Windows:
%APPDATA%\ctxone\memory.db
Override per agent with --path (topology C). A bare ctxone-hub with no
--path defaults to ./target/ctxone.db (dev convenience) — always pass
--path in real setups.
Useful flags
Section titled “Useful flags”| Flag | Purpose |
|---|---|
--path <PATH> | SQLite db file (per-agent isolation lives here) |
--http | Enable the REST API |
--lens | Serve the web UI at / (requires --http) |
--port <N> | HTTP port (default 3001) — use distinct ports for parallel dbs |
--agent-id <NAME> | Attribution recorded on commits (ctx blame) |
--auth-token <TOK> | Bearer token guarding REST + /mcp (env CTXONE_AUTH_TOKEN); loopback exempt |
--allowed-origin <ORIGIN> | Extra browser origin allowed to call the API (repeatable; same-origin is always allowed) |
--init | Create the db file if missing (guards against path typos) |
--storage memory | Ephemeral, no file, no lock — good for tests/demos |
--storage postgres --database-url <URL> | Postgres instead of SQLite (or set DATABASE_URL) |
--pg-pool-size <N> | Most Postgres connections the hub holds (default 32); a multi-tenant hub’s tenants share them |
--tenants-file <PATH> | One hub for many users: each request’s token picks its tenant (below) |
--asd-path name=PATH | Register an ASD code-graph repo for the process pool |
Environment
Section titled “Environment”| Var | Effect |
|---|---|
CTX_SERVER | Hub URL the ctx CLI targets (default http://localhost:3001) |
CTX_NAMESPACE | Project namespace for CLI/MCP scoping |
CTX_BRANCH | Default memory branch/ref |
CTX_TOKEN | Bearer token the ctx CLI sends (for a remote authed hub) |
CTX_REMOTE_TURNS | 1 lets ctx send raw session turns to a hub that isn’t on this machine (overrides the remote_turns config key; see below) |
CTXONE_AUTH_TOKEN | Same as --auth-token (bearer guarding REST + /mcp) |
CTXONE_AUTH_TOKEN_FILE | Same as --auth-token-file (tokens one per line, re-read every second) |
CTXONE_REQUIRE_AUTH_ON_LOOPBACK | 1 = same as --require-auth-on-loopback (loopback peers need the token too) |
CTXONE_ALLOWED_ORIGINS | Comma/space-separated extra allowed browser origins |
CTXONE_STRICT_ORIGIN | 1 = same as --strict-origin (only the allowed origins, never same-origin by Host) |
DATABASE_URL | Postgres connection URL; setting it selects Postgres storage, unless --storage memory |
CTXONE_PG_POOL_SIZE | Same as --pg-pool-size |
CTXONE_TENANTS_FILE | Same as --tenants-file, for the hub and for ctxone-hub tenant |
CTXONE_BACKUP_KEEP | Startup snapshots to retain (default 5) |
CTXONE_BACKUP_INTERVAL_SECS | Background VACUUM-INTO snapshot interval (default 1800; 0 disables) |
RUST_LOG | Log level (info default) |
Authentication
Section titled “Authentication”The hub binds 0.0.0.0 (all interfaces). With no token set, REST and /mcp are
reachable from the network unauthenticated — the hub logs a loud warning at
startup. Before exposing it beyond localhost, set a bearer token:
ctxone-hub --http --lens --path ~/.ctxone/memory.db --auth-token "$(openssl rand -hex 32)"# or: CTXONE_AUTH_TOKEN=… ctxone-hub --http …Behaviour:
- Loopback peers (127.0.0.1/::1) are exempt — local CLI, Lens, and
same-host agents keep working with no token — unless
--require-auth-on-loopbackis set (see Hosted hub below). - Non-loopback requests must send
Authorization: Bearer <token>(else 401), exceptGET /api/health, so health checks need no token. - Setting a token also relaxes
/mcp’s loopback-only Host check so authenticated remote clients can connect (the bearer becomes the gate).
How each client gets the token:
ctxCLI — pass--token <TOK>or setCTX_TOKEN(only for a remote hub).- AI tools —
ctx init --transport httpwrites it into each tool’s config: ctx init --transport http --auth-token <TOK>— embeds a literal bearer: aheadersentry for native http (Claude Code/Cursor/VS Code) and a--headerarg for the mcp-remote bridge (Claude Desktop). The token is written in plaintext into those config files (a warning is printed).ctx init --transport http --auth-token-env <VAR>— keeps the secret out of config files: Codex getsbearer_token_env_var = "<VAR>", and native http entries referenceBearer ${VAR}(for clients that expand env vars). The mcp-remote bridge can’t expand env vars, so Claude Desktop needs the literal--auth-tokenform.
Raw session turns stay on the machine that recorded them. When ctx’s hub isn’t
on this machine (anything but localhost, a .localhost name, 127.x or ::1),
ctx ingest-session and ctx session import send each session’s title,
metadata, provenance, per-model token usage and extracted memories, and the
Stop-hook ctx capture-turn sends token counts and extracted memories, but none
of them sends the turns. The per-model usage is worked out from the turns on
this machine and sent as totals (PUT /api/sessions/{sid}/usage). To send turns
as well, run ctx config set remote_turns true, or set CTX_REMOTE_TURNS=1 for
one command.
Rotating tokens
Section titled “Rotating tokens”Keep tokens in a file instead of on the command line, one per line:
ctxone-hub --http --auth-token-file /etc/ctxone/tokensThe hub re-reads the file every second and accepts every token in it, so a
rotation needs no restart: add the new token as a line, switch clients to it,
then delete the old line. An empty file accepts no token. A Kubernetes secret
mounted as a volume works as is, since its updates swap the file atomically; one
mounted with subPath never updates.
Hosted hub
Section titled “Hosted hub”A hub reached over the internet, behind an ingress, should also stop trusting
loopback and Host:
ctxone-hub --http --storage postgres \ --auth-token-file /run/secrets/ctxone-tokens \ --require-auth-on-loopback \ --strict-origin --allowed-origin https://alice.ctxone.example--require-auth-on-loopback: an ingress or sidecar on 127.0.0.1 makes every request arrive from loopback, which would otherwise skip the token. The hub refuses this flag without a token, and hands its ownctxsubprocesses the token asCTX_TOKEN.--strict-origin: browsers may call the API only from the listed origins. Without it, anOriginmatching the request’sHostcounts as same-origin, and behind an ingress, or under DNS rebinding,Hostis whatever the caller sent.
A hub set up this way serves one tenant (--tenant): everyone with a token
shares one graph. For several users, each with their own memory, run one hub
with a tenants file instead: One hub for many users.
Postgres over TLS
Section titled “Postgres over TLS”The hub reaches Postgres over verified TLS, set in DATABASE_URL the way libpq
does it:
export DATABASE_URL='postgres://ctxone:secret@db.example.com:5432/ctxone?sslmode=verify-full'sslmode=verify-full(orrequire, orverify-ca): TLS, with the server’s certificate checked against Mozilla’s roots and its host name. There is no unverified TLS.- A provider that signs with its own CA (Amazon RDS, Google Cloud SQL, …):
download its CA bundle and add
&sslrootcert=/path/to/ca.pem, or setPGSSLROOTCERT=/path/to/ca.pem. - No
sslmode, orsslmode=disable, is plaintext: fine for a database on the same machine, and on a private network if you mean it, in which case saysslmode=disable. For a database on another machine with nosslmode, or withprefer, the hub logs a warning at startup.
The startup line says which mode the hub connected with
(Storage: postgres … tls=verify-full); it never logs the URL, which may
carry a password. scripts/test-postgres-tls.sh runs the hub’s TLS tests
against a throwaway Postgres that accepts only TLS.
Cross-origin (CSRF / DNS-rebinding)
Section titled “Cross-origin (CSRF / DNS-rebinding)”Independent of the token, the hub rejects browser requests whose Origin
isn’t same-origin or allow-listed — so a page you visit can’t drive the loopback
hub (loopback peers are auth-exempt, which is why this guard matters). CLI and
native MCP clients send no Origin and are unaffected; Lens is same-origin and
always allowed. CORS reflects only same-origin/allow-listed origins (never *).
To let a real cross-origin browser app (e.g. Lens hosted elsewhere) use the API:
ctxone-hub --http --allowed-origin https://lens.example.com # repeatable# or CTXONE_ALLOWED_ORIGINS="https://a.example, https://b.example"Lens over an authenticated hub
Section titled “Lens over an authenticated hub”When a token is set, a remote browser’s first call gets a 401 (loopback is
exempt, remote is not), and Lens asks for the token. Paste the hub’s token: Lens
checks it, keeps it in the browser’s storage for the hub’s origin, and sends it
as Authorization: Bearer on every call. A refused token (a rotated one, say)
brings the question back, and Forget token in the sidebar removes it. Reach a
remote hub over HTTPS, so the token isn’t sent in the clear. With
--strict-origin, list the hub’s own origin with --allowed-origin.
To keep the hub off the network instead, reach it over an SSH tunnel, which makes your browser a loopback client that needs no token:
ssh -L 3001:localhost:3001 you@hub-host # then open http://localhost:3001One hub for many users
Section titled “One hub for many users”One hub can serve many people (“tenants”) from one process and one Postgres database. Each tenant has its own memory, plans, workspaces, project registry, session statistics and MCP sessions, and two tenants can use the same workspace names without meeting. Each request’s token picks its tenant, and adding a tenant is one command, with no restart.
alice's agents, ctx, Lens ── token A ─┐ ├─ HTTPS ─▶ proxy ─▶ ctxone-hub --tenants-file ─▶ Postgres bob's agents, ctx, Lens ── token B ─┘How it’s built and how tenants are kept apart: the multi-tenant Hub design. The API’s side of it: HTTP API.
What it takes
Section titled “What it takes”- Postgres. One database holds every tenant. The hub creates its tables, and
a tenant’s rows on that tenant’s first request. Reach the database over TLS
(Postgres over TLS). To try multi-tenant mode out
without one,
--storage memorykeeps the tenants in memory until the hub stops. - One hostname with HTTPS in front of the hub, from a reverse proxy or an ingress (below). The hub itself speaks plain HTTP.
- One hub process, or several: replicas can share the database behind one load balancer (More than one replica).
Add tenants
Section titled “Add tenants”ctxone-hub tenant add alice --tenants-file /var/lib/ctxone/tenantsThis prints alice’s token on stdout, once: ctx_ and 64 hex digits. Give it to
alice. The tenants file keeps only its SHA-256, a line alice <hash> per token.
Set CTXONE_TENANTS_FILE instead of passing --tenants-file every time.
| Command | Effect |
|---|---|
add <name> | Create a tenant and print its token, once |
list | The tenants and how many tokens each has |
rotate <name> | Replace the tenant’s tokens with a new one, printed once. The old ones are refused within a second |
disable <name> | Refuse the tenant’s tokens. Its data stays, and the hub closes the tenant within a minute |
enable <name> | Accept a disabled tenant’s tokens again |
purge <name> | Delete a disabled tenant’s data from the database (--database-url, or DATABASE_URL), then its lines in the file. Asks for the tenant’s name unless given --yes, and waits about a minute first, so every hub has closed the tenant. Can’t be undone |
- The hub re-reads the file every second, so none of these needs a restart. A bad line stops the hub at startup; later it’s skipped with a warning, so a typo locks out only that line.
- Run
ctxone-hub tenantas the user the hub runs as. The firstaddcreates the file readable by its owner only (0600). Edits take<file>.lockand replace the file with a rename, so its directory must be writable, which a read-only mount (a Kubernetes secret, say) isn’t. - Several tokens for one tenant (one per device, say):
addandrotategive a tenant one, and more are lines you add yourself,alice <sha256 of the token>with the hash in lowercase hex.rotatereplaces them all. - Tenant names are 1 to 63 of
a-z,0-9and-.
Run the hub
Section titled “Run the hub”export DATABASE_URL='postgres://ctxone:…@db.internal:5432/ctxone?sslmode=verify-full'ctxone-hub --http --lens --port 3001 \ --tenants-file /var/lib/ctxone/tenants \ --strict-origin --allowed-origin https://hub.example.comWith DATABASE_URL set, the hub uses Postgres; --storage postgres --database-url <URL> says the same. At startup it logs that it’s in
multi-tenant mode, with the number of tenants and tokens, what’s off, and
Storage: postgres, every tenant on one pool with the TLS mode and pool size.
Request log lines carry the tenant as ctxone.tenant, never a token.
It refuses to start (exit 64), rather than ignore them, with settings that can’t
apply: --auth-token or --auth-token-file (the tenants file replaces them),
--tenant, SQLite, no --http, the ASD flags, --ctx-binary, and --lens
with --strict-origin but no --allowed-origin. A tenants file it can’t read,
or one with a bad line, stops it with exit 66.
As a systemd service, with DATABASE_URL=… in /etc/ctxone/hub.env and a
ctxone user that owns /var/lib/ctxone:
[Unit]Description=CTXone Hub (multi-tenant)After=network-online.targetWants=network-online.target
[Service]User=ctxoneEnvironmentFile=/etc/ctxone/hub.envExecStart=/usr/local/bin/ctxone-hub --http --lens --port 3001 --tenants-file /var/lib/ctxone/tenants --strict-origin --allowed-origin https://hub.example.comRestart=on-failure
[Install]WantedBy=multi-user.targetStopping the hub (SIGTERM) saves every open tenant’s session statistics first.
Size the connection pool
Section titled “Size the connection pool”Every tenant shares one pool of --pg-pool-size connections (default 32, or
CTXONE_PG_POOL_SIZE). A request holds a connection only while it reads or
writes, and a closed tenant holds none, so the pool tracks how many requests
run at once, not how many tenants there are. Connections open as they’re
needed, up to the limit.
The hub holds at most --pg-pool-size connections, plus one while a tenant
opens: tenants open one at a time, each under a lock on a connection of its
own. Keep that, plus a couple for ctxone-hub tenant purge and whatever else
uses the database, under the server’s max_connections (100 by default on
Postgres; managed plans often allow fewer). Lower the pool for a small plan.
More than one replica
Section titled “More than one replica”Several hubs can serve the same tenants from one database, so one can restart
or fail while the others answer. Start each the same way, with the same flags,
the same DATABASE_URL and the same tenants file. The load balancer in front
needs no affinity: any replica can answer any request.
- MCP sessions continue on any replica. A hub on Postgres keeps how each MCP
session began (the client’s
initialize) in the database. When a request names a session the replica doesn’t hold, because it began on another one or this one let it go (after five idle minutes, when the tenant closed, or in a restart), the replica takes it up and the client carries on. A session continues only for its tenant, in the workspace and session it began in. One unused for 7 days is forgotten, and its client is told to start a new one (a 404, which MCP clients answer by starting over). - Session statistics add up. Each replica saves what it counted since its last save (every 30 seconds, when a tenant closes and when it stops) on top of what the others saved, then takes in theirs, so the replicas agree within a save or two. A session deleted through one replica is gone from all of them.
- Rate limits are per replica. A tenant can make
--rate-limit-rpmrequests a minute to each replica, that many times the number of replicas in all. Lower it to match, or limit at the load balancer. - Connections add up too. Each replica holds up to
--pg-pool-size, plus one while a tenant opens. Keep the sum under the server’smax_connections. - The tenants file: run
ctxone-hub tenanton the file the replicas read, on a shared volume. Where each replica has a copy instead (a Kubernetes Secret or ConfigMap, say), a change reaches a replica when its copy does, which can take a minute or more.purgeallows a minute for every hub to stop serving the tenant, sodisablefirst, andpurgeonce every copy has the change. - Writes to a tenant’s graph from two replicas at once never lose a commit: a branch moves only from the commit a write was built on. Recall results are worked out again once the graph changes, whichever replica changed it, and the workspace summary is at most 15 seconds old.
- Row-level security is switched for the database:
ctxone-hub db row-security onruns once, from anywhere.
A single-tenant hub keeps its MCP sessions in its database too, on Postgres or in its SQLite file, so they carry on across a restart.
Row-level security
Section titled “Row-level security”Every query the hub runs is filtered by its tenant. Row-level security has the
database check that too: with it on, each table that holds tenants’ rows
(AgentStateGraph’s, and the hub’s ctxone_* tables) shows a statement only its
own tenant’s rows, and refuses to write another tenant’s. A query missing its
filter then sees nothing of anyone else’s. It’s off until you switch it on,
once for each database:
ctxone-hub db row-security on --database-url "$DATABASE_URL"It prints on. ctxone-hub db row-security status prints on, off or
partial and names any table it’s off for, and off switches it off. Hubs
already running needn’t restart: every connection a hub uses names its tenant
already.
-
Connect the hub as a role that row-level security binds: not a superuser, and without
BYPASSRLS, either of which skips it without a word. A new role has neither:CREATE ROLE ctxone LOGIN PASSWORD '…';CREATE DATABASE ctxone OWNER ctxone;At startup a hub on Postgres logs whether row-level security is on, and warns when it’s on but the hub’s role skips it, when it’s on for only some tables, or when a table with a
tenant_idcolumn has no policy. -
Run
ctxone-hub dbas the role that owns the tables, which is the hub’s role if the hub created them. Row-level security is forced, so it binds the owner too. Switching locks each table for a moment, and gives up if a busy one keeps it waiting 10 seconds; run it again. -
Back up as a role that skips it. With it on,
pg_dumpas the tables’ owner fails rather than dump only some rows. Dump as a superuser, or as a role made for backups (Postgres 14 or later):CREATE ROLE ctxone_backup LOGIN BYPASSRLS PASSWORD '…';GRANT pg_read_all_data TO ctxone_backup;Your provider’s snapshots aren’t affected.
-
ctxone-hub tenant purgeworks with it on: it deletes as the tenant it purges.
HTTPS in front
Section titled “HTTPS in front”The hub listens on 0.0.0.0:<port> over plain HTTP. Terminate TLS for your
hostname at a reverse proxy or ingress, and keep the hub’s port off the
internet. Then:
- Tokens never cross the network in the clear, and Lens keeps its token
for the
https://origin. - There’s no loopback exemption on a multi-tenant hub, so a proxy on
127.0.0.1 doesn’t let requests past the token check, and
--require-auth-on-loopbackisn’t needed. --strict-origin --allowed-origin https://<your hostname>lets browsers call the API only from the hub’s own pages. Behind a proxy,Hostis whatever the caller sent, so without--strict-origina matchingHostwould be enough.- Rate limits are per tenant (
--rate-limit-rpm, 600 a minute by default), so a proxy that hides client addresses changes nothing. With several replicas, they’re per replica too. - MCP responses can be long-lived event streams. Don’t buffer
/mcp, and allow long requests (nginx:proxy_buffering off;and a longproxy_read_timeout). /api/healthneeds no token, so a load balancer, a Kubernetes probe or the container image’s built-in health check can call it as it is. It answers only that the hub is up, opens no tenant, and isn’t rate limited. A token sent with it is still checked, so a wrong one is a 401.
Connect clients
Section titled “Connect clients”Connect to a Hub walks through it, with what each machine sends and what it keeps. Each person uses their own token, against the one hostname:
export CTX_SERVER=https://hub.example.comexport CTX_TOKEN=<your token>ctx init --mcp-url https://hub.example.com/mcp --auth-token-env CTX_TOKEN- The
ctxCLI readsCTX_SERVERandCTX_TOKEN. - AI tools:
ctx initpoints each one at/mcpwith the token, here read fromCTX_TOKENwhen the tool runs. Claude Desktop’s bridge can’t read a variable, so it needs--auth-token <token>instead, written into its config (Authentication). - Lens: open
https://hub.example.comand paste the token once. Lens keeps it in that browser, for that origin; Forget token in the sidebar removes it. - Project detection needs nothing more:
ctxsends what it finds in the directory, and the hub never reads its own disk for it. - Sessions:
ctx ingest-sessionand the Stop hook send a session’s metadata and extracted memories, but not its raw turns, to a hub that isn’t on the same machine, unlessremote_turnsis set (see Authentication).
What’s off
Section titled “What’s off”A multi-tenant hub’s own machine isn’t any tenant’s, so what acts on it is off:
- ASD code intelligence: the
/api/codeproxy and the MCP code tools; - discovering, importing, autosyncing and syncing session transcripts from the hub machine’s disk;
- SQLite backups and the lockfile (back up Postgres instead);
- project detection reading the hub machine’s disk;
helprunning other tools’ binaries.
Their routes answer 404 (HTTP API), and Lens leaves those views out. A single-tenant hub keeps all of them.
Running it
Section titled “Running it”- Backups: a Postgres backup (
pg_dump, or your provider’s snapshots) holds every tenant. There’s no export of one tenant yet. With row-level security on, runpg_dumpas a role that skips it (Row-level security). - A lost or leaked token:
ctxone-hub tenant rotate <name>. - Someone leaves:
disablethem, andpurgeonce their data can go. - Upgrades: stop the hub, which saves every open tenant’s statistics, and start the new one. Each tenant’s schema is brought up to date on its first request after that, and MCP clients carry on with their sessions.
- Idle tenants close after 30 minutes without a request, and open again on the next one, their MCP sessions with them. An open tenant’s session statistics are saved every 30 seconds.
Running as a service
Section titled “Running as a service”To make the HTTP/Lens hub survive reboots and start before any agent (so it,
not an agent’s stdio child, owns the db), run it as a login service. ctx service
generates and registers the unit for you — launchd on macOS, a systemd user
unit on Linux, and a Task Scheduler logon task on Windows (via schtasks):
ctx service install # lens on, port 3001, canonical dbctx service install --port 3001 --path ~/.ctxone/memory.dbctx service install --auth-token "$(openssl rand -hex 32)" # embeds token (chmod 600)ctx service install --dry-run # print the unit + commands, write nothingctx service status # is it registered/running?ctx service uninstall # stop + removeThe unit runs ctxone-hub --http --lens --path <db> --port <port> with
RunAtLoad/KeepAlive (macOS), Restart=on-failure (systemd), or a
LogonTrigger + RestartOnFailure (Windows), logging to ~/.ctxone/hub.log.
Preview it first with --dry-run. If another hub already holds the db (an
agent’s stdio hub, or a manual one), the service will fail on the lockfile —
stop it first. On Windows the auth token can’t be embedded in the task; set it
with setx CTXONE_AUTH_TOKEN <token> instead.
Equivalent hand-written launchd plist
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict> <key>Label</key><string>com.ctxone.hub</string> <key>ProgramArguments</key> <array> <string>/opt/homebrew/bin/ctxone-hub</string> <string>--http</string> <string>--lens</string> <string>--path</string> <string>/Users/you/.ctxone/memory.db</string> </array> <key>KeepAlive</key><true/> <key>RunAtLoad</key><true/> <key>StandardErrorPath</key><string>/Users/you/.ctxone/hub.log</string></dict></plist>launchctl load -w ~/Library/LaunchAgents/com.ctxone.hub.plistWith the daemon running, point agents at it with
ctx init --transport httpand they stop spawning their own hub — one process, one owner, no race.ctx inithandles every detected client (native URL, Codexurl, or the mcp-remote bridge for Claude Desktop), so they all connect to the daemon. Use a separate db (topology C) only for deliberate isolation, or for a client that supports neither native http nor the mcp-remote bridge. See the unified-hub design.
Troubleshooting
Section titled “Troubleshooting”database is already locked …— another hub owns that db. Find it (ps aux | grep ctxone-hub), or use a different--path/--port. Stale locks (owner gone) are reclaimed automatically.- Lens shows nothing / CLI can’t connect — check
CTX_SERVERand that a hub is running with--http.curl http://localhost:3001/api/health. - Agent and Lens show different memory — they’re on different db paths (topology C). That’s isolation working as configured.
- Every request to a multi-tenant hub is a 401 — there’s no loopback
exemption, so each request but
GET /api/healthneeds a tenant’s token.ctxone-hub tenant listshows whether the tenant is disabled;rotategives it a new token.
See also: ARCHITECTURE.md · DATA_SAFETY.md · TROUBLESHOOTING.md