Configuration
All configuration is environment variables. There is no config file.
Server (serve and the admin commands)
| Variable | Default | Meaning |
|---|---|---|
BUS_HOST | 127.0.0.1 | Bind address. Must be loopback or this host's tailnet address (bind guard). |
BUS_PORT | 47910 | Listen port, 0 to 65535. |
BUS_DB | ${XDG_STATE_HOME:-$HOME/.local/state}/session-bus/bus.db | Database path. Used by every command that opens the DB. The directory is created. |
BUS_LOG_LEVEL | info | debug also logs successful inbox calls. |
Push shim (channel)
| Variable | Default | Meaning |
|---|---|---|
BUS_URL | none (required when named) | Base URL of the bus, for example https://<bus-host>.<tailnet>.ts.net:8443. The shim appends /mcp. A trailing / or /mcp, a query or a fragment is rejected (exit 2). |
SESSION_BUS_NAME | none | The session name. --session wins over it. Unset, empty or a literal unexpanded ${...} means idle. |
SESSION_BUS_TOKEN_CMD | none | Shell command run once with /bin/sh -c; its trimmed stdout is the token. The output is never logged. |
SESSION_BUS_TOKEN_CMD_TIMEOUT_MS | 15000 | Timeout for that command. |
SESSION_BUS_TOKEN | none | Literal token, used only when SESSION_BUS_TOKEN_CMD is unset. Avoid it in config files. |
BUS_POLL_MS | 5000 | Poll interval in ms. Also the starting backoff after an error. |
Headers helper (scripts/bus-headers.sh)
| Variable | Meaning |
|---|---|
SESSION_BUS_OP_REF | An op:// reference. The helper runs op read on it. |
SESSION_BUS_TOKEN | Used when SESSION_BUS_OP_REF is unset. |
OP_SERVICE_ACCOUNT_TOKEN | Read by op itself, if you use a 1Password service account. |
Set SESSION_BUS_OP_REF inside the headersHelper command string, not in your shell profile. With neither variable, the helper prints a message to stderr and exits 1.
State files
| Path | Written by |
|---|---|
${XDG_STATE_HOME:-$HOME/.local/state}/session-bus/bus.db (+ -wal, -shm) | serve and admin commands |
<BUS_DB>.lock | serve, restore |
${XDG_STATE_HOME:-$HOME/.local/state}/session-bus/shim-<name>.lock | push shim |
${XDG_STATE_HOME:-$HOME/.local/state}/session-bus/shim-<name>.json | push shim cursor (mode 0600) |
${XDG_STATE_HOME:-$HOME/.local/state}/session-bus/log/ | launchd unit stdout/stderr |
An unnamed shim writes nothing.
Client launch settings
These belong to Claude Code, not to session-bus, but affect push:
DISABLE_TELEMETRYandCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: on Claude Code 2.1.312, when both are set, the channels flag is ignored. See Push sessions.MCP_SDK_GENERATION=v1: try this client setting if a newer Claude Code does not register the channel.