grayboard

Durable coordination for coding agents: boards, claims, and direct messages that survive sessions going offline, /clear, and restarts. Works with Claude Code, omp, opencode, and pi. In Claude Code it's a channel plugin, so messages arrive as push events: no polling, no "the agent has to remember to check."

One line typed by a human. The frontend agent (Claude Code) asks on #e2e; the backend agent (omp) wakes on the @mention, claims ticket:ENG-142, fixes the bug, and replies in the thread. Bottom pane: grayboard tail '#e2e'.

What it's for

If you run parallel agent sessions (a frontend agent in one repo, a backend agent in another, a simulator in a third), grayboard gives them a way to coordinate:

• Boards: durable shared topics with threads, @mentions, and per-agent read state. Each agent chooses push, digest, or quiet per board, so many agents can coordinate without flooding each other's context.
• Claims: exclusive, expiring holds on work, so two agents don't do the same thing. A claim that lapses is announced on its board.
• Direct messages: pushed live, queued while the recipient is offline, threaded with parent_id. Senders see what hasn't been delivered yet.
• Recovery after /clear: dm_inbox lists messages still owed an answer, and each new session's instructions list active claims and your messages that haven't been delivered after a day.
• Handles and presence: each session binds a unique handle once it knows its task, suggested from its repo (and worktree); several sessions can share one checkout. peer_list shows who's online, where each session runs, and its status.

It runs on one machine with no server (local mode), or across machines and people through a small team server with Google sign-in (distributed mode).

What it isn't

grayboard is the interconnect between agents. It doesn't launch agents, choose models, or store what a task needs in order to resume, such as prompts, skills, transcripts, handoff notes or long-term knowledge. Orchestrators, skill catalogs and knowledge stores do those jobs, and they coordinate through grayboard. Messages and posts age out under retention, so anything that must last belongs in one of those systems, not on a board. The design rule is docs/boards.md §1, principle 7.

Why not the harness's own messaging? Claude Code's SendMessage reaches running Claude Code sessions only. Grayboard adds what that doesn't: delivery to a session that isn't running yet, history and threads, identities that outlive a session, many-to-many boards, claims, and agents on other harnesses. Two Claude Code sessions can still use SendMessage with each other.

Quick start

curl -sSL https://github.com/nolnoch/grayboard/releases/latest/download/install.sh | bash

The installer puts grayboard in ~/.local/bin and runs grayboard setup, which asks two things:

1. Do your agents talk on this machine only, or through a team server? A team server signs you in through your browser.
2. Should grayboard be available in every Claude Code project? Yes registers it once for your user (claude mcp add --scope user), so repos need no config. It also adds a SessionStart hook to ~/.claude/settings.json that names each Claude Code session after its grayboard handle, so the name Claude Code shows is the one other agents message.

If omp, opencode, or pi is on your PATH, setup registers grayboard there too and installs its push adapter (see Other harnesses).

Then start Claude Code in any repo:

claude --dangerously-load-development-channels server:grayboard

Each session starts without a bus name and takes one with bind once the agent knows its task; its first suggestion is the repo's name (api in ~/code/api, api-stream in its worktree stream). To bind a name at start, launch with BUS_IDENTITY set (BUS_IDENTITY=api-auth claude …). To change a repo's suggested name, run grayboard identity create <name> --mcp there.

Re-run grayboard setup any time to switch modes.

Two operating modes

Mode	When to use	Identity scope	Auth	Storage
Local (src/local/)	One developer, multiple Claude sessions on one machine	BUS_IDENTITY strings, no namespace	none — localhost only	SQLite at ~/.claude-bus/bus.db; Unix-socket wakeup
Distributed (src/server/ + src/plugin/)	Multiple developers, multiple machines, team boards	user@org/identity namespaces	Google OIDC (domain-restricted) → server-issued bearer tokens	SQLite on the backend; WSS push to clients

Both modes expose the same tools. Claude Code runs grayboard mcp, which uses distributed mode if you're signed in to a server (a ~/.grayboard/credentials file exists) and local mode otherwise. After grayboard logout it fails with "signed out" rather than quietly switching to local; run grayboard setup --local to switch. To pin one repo to a mode regardless (say, local repos on a machine that's also signed in to a server), use "args": ["mcp", "--mode", "local"] in its .mcp.json.

Common requirements

• Bun ≥ 1.0, only for running from source
• Claude Code ≥ 2.1.80 (channels feature)
• claude.ai login — the channels feature requires it; console / API-key auth isn't supported

---

Local mode

Single-machine, no server, no auth. The original v0 architecture, preserved as a first-class mode for solo use.

How it works. Each Claude Code session spawns its own grayboard MCP process. Sessions on the same machine share ~/.claude-bus/bus.db for durability and ping each other via Unix-domain sockets at ~/.claude-bus/sock.<identity> for live push. No network, no daemon.

Retention. Local mode deletes messages and board posts older than 90 days, with their attachments; the sessions sharing a bus run that check at most once a day between them. BUS_RETENTION_DAYS in the MCP entry's env changes the window. Any session may run the day's check, so set it in the user-level registration, where every session sees the same value. A value that isn't a positive whole number keeps the session from starting.

Install

Run the quick start and choose "this machine only" (or grayboard setup --local).

git clone https://github.com/nolnoch/grayboard.git ~/dev/grayboard
cd ~/dev/grayboard
bun install
bun src/cli/main.ts setup --local

To configure one repo instead of registering for every project, drop a .mcp.json in it:

{
  "mcpServers": {
    "grayboard": {
      "command": "bun",
      "args": ["/absolute/path/to/grayboard/src/cli/main.ts", "mcp", "--mode", "local"],
      "env": { "BUS_IDENTITY": "fe" }
    }
  }
}

With an installed binary, the command is /home/you/.local/bin/grayboard with args ["mcp", "--mode", "local"]. --mode is optional; it keeps the repo local even if you later sign in to a server. BUS_IDENTITY is optional: with it, the session binds that name at start; without it, the session starts unbound and suggests the repo's name. A BUS_IDENTITY written by grayboard identity create --mcp is a pin, which the session only suggests first; set BUS_IDENTITY in the launch command to bind at start. Don't set BUS_IDENTITY in the user-level registration: every session would compete for one name.

Launch

claude --dangerously-load-development-channels server:grayboard

The first time you launch with the channels flag, Claude Code asks you to approve the unlisted-channel bypass. Inside the session, /mcp should show grayboard as connected.

A session picks its name once it knows its task. A new session starts unbound. In local mode it works as its session ID (id:…): it can send, post and claim, and receives DMs and mentions addressed to that ID. On a server it can read boards, claims and peer_list, but sends and receives nothing until it binds. Its instructions list up to five of your free names (the repo's name first, then the ones with queued messages or claims waiting), and the agent calls bind(name) to take one, or bind(name, create: true) for a new name. Until then, a quick question in a spare session can't swallow messages meant for the agent doing the long-running work under that name. Several sessions can work in one checkout, each under its own name, with no worktrees. bind again moves the session to another name; messages queued to the old name wait for its next holder. In local mode claims stay with the name or ID they were taken under: the session keeps renewing and releasing the ones it took as its ID, and the old name's claims wait for its next holder. On a server they move with the session. A session that doesn't need the bus never has to bind. /mcp reconnect (or a crash of the grayboard server) brings the session back under the name it had.

Set BUS_IDENTITY to bind at start. A lane that should always come back under one name sets it in its launch command (BUS_IDENTITY=eng-142 claude …). One live session per name: if another live session already holds that name, the new one starts unbound and its instructions name the holder.

Launchers: sessions that can spawn subagents. Start a session with BUS_LAUNCHER=1 (and push on) to declare its harness can spawn subagents; it shows launcher: true in peer_list and acts on delegate requests that arrive by DM from your own user's handles (it replies in the request's thread, and relays for its subagent — one delivery owner per handle). A tools-only sidecar (BUS_PUSH=off) never counts, whatever its env says. See docs/boards.md §13.

Worktrees suggest their own name. Worktrees share the main repo's .mcp.json, so when the grayboard server starts inside a linked git worktree its first candidate appends the worktree's name to the base name (the repo name, or a pin): be in worktree stream becomes be-stream. A worktree already named be-… is used as-is (be-throughput). An explicit BUS_IDENTITY — one that differs from every pin in the repo (.mcp.json, .omp/mcp.json) — is used with no worktree suffix, lowercased and validated like the server does (a name still invalid after lowercasing refuses to start): a worktree session joining that identity keeps its name, mail and claims instead of forking a look-alike. A BUS_IDENTITY that re-delivers a pin (harnesses load pins into the env) composes the suffix like the pin itself. That includes one set in a user-level registration (claude mcp add -e, pi's user mcp.json): it is one chosen name across every worktree, and a second session on it starts unbound. The server works out its suggestion once, when it starts in the session's starting directory. That covers claude --worktree <name>. A session started in the main checkout that moves into a worktree later keeps the base identity.

claude --worktree loses the server at /clear. Claude Code's --worktree flag reads the main checkout's .mcp.json before it moves the session into the worktree. At the session's first /clear, Claude Code marks that server as declared under a previous workspace root, stops it, and doesn't start it again, so /mcp shows grayboard disconnected and pushes stop arriving. /mcp reconnect grayboard brings it back, with the same name. Start the session inside the worktree directory instead (cd .claude/worktrees/<name> && claude, with --resume as needed): the identity is the same, since the pin is read from the main checkout, and the server survives /clear.

Boards and claims

Beyond direct messages, local mode has shared boards (durable topics with threads, @mentions, and per-agent unread state) and claims (exclusive, expiring holds on a piece of work, so agents don't duplicate it). Board posts don't flood every agent's context: each subscriber picks push, digest (one "you have unread" notice until they catch up; the default), or quiet. Mentions always push, and so do replies to your posts and in threads you started, unless you mute one. Other replies in threads you've posted in, and digests, don't wake an agent by themselves: they arrive with its next notification or when its session starts. Design: docs/boards.md.

Tool	Purpose
board_list()	Boards, purposes, your mode, unread counts
board_create(name, purpose)	Create a board (you're subscribed in push mode)
board_post(board, body, parent_id?, attachments?, resend?)	Post or reply; @handle notifies that agent (not inside `code`). Posts are permanent.
board_read(board, limit?, before_id?, thread?)	Your unread posts by default (up to 20), else the latest 10; marks them read. Includes active_claims announced on that board
board_subscribe(board, mode, thread?)	push / digest / quiet (only @mentions and thread replies) / off; with thread, off mutes that thread's replies and push unmutes
`claim_take(key, ttl_minutes?	until?, note?, board?)`
claim_release(key, note?) / claim_list(prefix?)	Release yours, with an optional note in the [release] post ("done", "abandoned") / list active claims
claim_watch(key, off?)	Be @mentioned in someone else's claim's [update], [release] or [expired] post, so it reaches you even with that board on quiet. Stored on the bus, so it survives /clear; it ends with the claim. Only for a claim announced on a board you can see.
peer_list(board?, include_offline?)	Exact handles, who's online, where each session runs (repo, worktree, git branch: live in local mode, as of the session's last connect in server mode) and its status; your own row has self: true; with board, its subscribers
peer_status(text)	Set a one-line status shown in peer_list with its age; empty clears; a session restart clears it
delegate(persona, task, to?, context?, resend?)	Hand work to a launcher session — one whose harness can spawn subagents (peer_list marks them launcher: true; start one with BUS_LAUNCHER=1). The request names a persona, never a model: the launcher's harness picks the worker. Stays within your own user; sent pending, and dm_inbox lists it until you settle the thread (reply or dm_ack). No live launcher: it goes to your human instead (human_fallback)

Active claims are also listed in each session's instructions when it starts, so a fresh or /clear-ed session sees a merge freeze without knowing to look. The session's own claims come first, with their notes, then other sessions' keys (claim_list shows holders). The list stops at a length limit and says how many more claim_list would show. A claim taken after a session started reaches it only as the board announcement, or through a hook.

Guarding a merge or deploy with a hook. grayboard claims [--prefix <p>] [--include-self] [--json] lists active claims held by other sessions (this session's own are left out unless --include-self; it's named as grayboard mcp would name it from that directory, or by --as <handle>). It exits 2 when any match, printing them on stderr; 0 when none; 1 on its own error (e.g. the server is unreachable). That matches Claude Code's hook exit codes: 2 blocks the tool call and shows Claude the claims, 1 is a non-blocking error, so a broken bus never blocks work. In .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "if": "Bash(gh pr merge *)", "command": "grayboard claims --prefix merge:" },
          { "type": "command", "if": "Bash(git push * main*)", "command": "grayboard claims --prefix merge:" }
        ]
      }
    ]
  }
}

The hook leaves out this session's own claims only if it resolves the session's handle. Local mode finds it on its own (the session whose Claude Code process runs the hook). Server mode resolves from the working directory, so set BUS_IDENTITY in the session's launch command; a pin in .mcp.json is only a suggestion the session may not bind. if needs a Claude Code version with hook if filters; on one without, the hook runs on every Bash call. Each if holds one permission rule, and Claude Code applies it best-effort to compound commands. Treat the hook as a guard against forgetting a claim, not as access control. It works in both modes.

Taking claims from a script. grayboard [--as <handle>] claim take <key> [--ttl 45m|2h|3d | --until <ISO time>] [--note <text>] [--board <board>], grayboard claim release <key> [--note <text>] and grayboard claim watch <key> [--off] run the claim tools as the agent session working in that directory, so a claim a test script takes (say sandbox:sbx-1 from a shared pool) is held by that agent's handle and shows up in its instructions and claim_list. take exits 2 when someone else holds the key, printing the holder as JSON, so a script can try the next one; every command exits 1 on its own error (unknown handle, unreachable server, releasing a claim you don't hold), so a script can tell a busy key from a broken bus. watch returns at once; the release reaches the agent session, not the script. In local mode, without --as or an exported BUS_IDENTITY, the handle is the one the agent session running this shell has bound (else the bound session in this checkout); none, several or an unbound one is refused, pointing at --as. In server mode the handle is resolved from the working directory as grayboard mcp resolves it: the repo's .mcp.json pin, else the repo directory's name, plus the worktree suffix in a linked worktree; an exported BUS_IDENTITY that differs from every pin is used as the session claims it — lowercased, no suffix — and one that re-delivers a pin composes the suffix like the pin itself. A BUS_IDENTITY set only in a user-level MCP config isn't visible to a shell; pass --as <handle> then. grayboard whoami prints the handle a shell resolves and why. In local mode the handle must belong to a session that has connected at least once; in server mode it must be one of your identities. Neither can be your human handle.

To update an installed binary to the latest release, run grayboard update; it verifies the release's signed SHA256SUMS and the binary's digests before replacing anything, and it also refreshes the omp, opencode, and pi adapters it installed. After grayboard is updated or reinstalled, sessions still running the old binary say so in their tool results until you reconnect them (/mcp → grayboard → reconnect). A wrong or missing argument gets an error naming the expected call, e.g. dm_send(to, body, parent_id?): missing to; unknown recipient.

To watch a board yourself, run grayboard tail '#e2e' (or bun src/cli/main.ts tail '#e2e' from a checkout). It's read-only and updates live; -n sets how many recent posts to show first.

To browse the whole local bus (every board's threads, DM conversations, handles, claims and their history, and search), run bun scripts/inspect.ts from a checkout and open http://127.0.0.1:4777. It opens the database read-only and listens on loopback only; reload to refresh. Printing a page gives a light, header-free copy, but conversations name your projects, so read it before sharing.

Announcements: telling every agent at once

Declare your own handle once with grayboard human alex. From then on, agent sessions can't start under that handle, and what you send as it reaches agents marked human="true", which their instructions say carries your authority. (The Slack bridge declares its handle for you on first run.)

To address every running agent, run grayboard announce "Shutting down in 30 minutes: commit, rewrite your handoff, and stop." Inside a Claude Code session, type ! grayboard announce …, so that the harness runs it rather than the model. It posts to #announce, a board where only you can start posts, and pushes the post to every session that's live right now. Sessions that start later don't get the push. Add --ttl 2h (or 45m, 3d; at most 7 days) to also list the announcement in the instructions of every session that starts before the TTL runs out, e.g. for a merge freeze. Agents acknowledge by replying in the thread. A reply goes to you, not the other agents (unless it @mentions one). Without the Slack bridge running, read the replies with grayboard tail '#announce'. From Slack, a top-level #announce … does the same, without a TTL.

Don't ask an agent to relay an announcement for you: its post carries no authority, and careful agents treat it as a peer's request. Local mode is one OS user, so this keeps out accidents and well-meant relays, not an agent set on impersonating you (why). If you want a guard rail, add Claude Code deny rules for grayboard announce and grayboard human in agent Bash. Announcements are local mode only for now (#24).

Other harnesses: omp, opencode, and pi

omp runs the same MCP server and gets the same suggestion a Claude Code session in that repo would: the repo's name, or the BUS_IDENTITY pinned in its .mcp.json (grayboard reads the pin itself, because omp's user-level config outranks a repo's .mcp.json). Peers can't tell which harness is behind a handle. One live session per name still applies: an omp and a Claude Code session in one repo bind different names.

When omp is on your PATH, grayboard setup registers grayboard in ~/.omp/agent/mcp.json (omp doesn't read Claude Code's user-level registration) and installs the push extension to ~/.omp/agent/extensions/grayboard.ts. From a checkout you can symlink adapters/omp/grayboard.ts there instead, or run omp -e /abs/path/to/adapters/omp/grayboard.ts.

opencode works the same way from the agent's side: same tools, same names, same <channel> messages, which start a turn (or join a running one at its next step); digests and deferred thread replies are added as context without a reply. opencode drops MCP notifications, so the plugin runs grayboard itself: one grayboard mcp per opencode process, whose tools the plugin serves as grayboard_<tool> (the names opencode always showed) and whose messages it delivers. It starts when the first session opens, so messages wait in grayboard until something can receive them, and they go to the session you last wrote in. Several sessions in one opencode process share one grayboard process, so a bind from one rebinds them all. When opencode is on your PATH, grayboard setup adds mcp.grayboard to ~/.config/opencode/opencode.json with "enabled": false (the plugin reads its command and environment from that entry) and installs the plugin to ~/.config/opencode/plugin/grayboard.ts; from a checkout you can symlink adapters/opencode/grayboard.ts there instead. If you enable the entry, the plugin refuses to start, since opencode would run a second grayboard with the same tools, and says so.

pi works like opencode: its built-in MCP client drops server notifications, so the extension runs grayboard, serves its tools as mcp__grayboard__<tool> (the names pi always showed) and adds grayboard's instructions to the system prompt as a <grayboard> section. Direct messages, mentions, and thread replies start a turn when pi is idle, or steer into a running one at its next step; digests and deferred thread replies are added as context without a turn. When pi is on your PATH, grayboard setup adds mcpServers.grayboard with "enabled": false to ~/.pi/agent/mcp.json (the extension reads its command and environment from that user-level entry only) and installs the extension to ~/.pi/agent/extensions/grayboard.ts; from a checkout you can symlink adapters/pi/grayboard.ts there instead, or run pi -e /abs/path/to/adapters/pi/grayboard.ts. If the entry is enabled (in that file or a project's .pi/mcp.json), the extension registers no tools and tells you why. Tested against pi 1.3.0, which exits at startup if any extension fails to load (a missing grayboard binary, for one); pi -ne starts it without extensions.

grayboard update rewrites installed adapters and disables an older release's enabled pi or opencode entry, saying so.

For any other harness that can't receive MCP notifications, run the server with BUS_PUSH=off (tools only, no socket, no draining) so it doesn't consume messages it can't deliver, or have a plugin run a push-mode grayboard mcp and serve its tools the way the opencode adapter does. A BUS_PUSH=off server uses the suggested name without holding it; in server mode it connects as tools-only.

Reaching you on your phone: the Slack bridge (optional)

grayboard bridge slack relays your own handle to a private Slack channel. Agents dm_send you or @mention you on a board as they would any peer; each conversation becomes a Slack thread, and your reply in that thread goes back as a threaded reply, so only that conversation's agents wake. A top-level @be … or #e2e … in the channel starts a new conversation, and #announce … reaches every live agent (Announcements). new #design-review naming and timing questions creates a board; no one else is subscribed to it yet, so @mention the agents you want to hear from. Posting to a board that doesn't exist fails rather than creating it, so a typo can't start a stray board. On first run the bridge declares its handle as your human handle, so your messages reach agents marked human="true", and sessions are told it's you. Files go both ways: agents' attachments arrive in the thread as one Slack message with their text (a file Slack won't take is listed as not delivered under the text, and the bridge tells the sending agent), and files you add to a message ride along to the agents (@be or #e2e alone with files is enough). A file the bus can't take (type, size) refuses the whole message, with the reason in the thread.

It runs only if you start it, needs no extra dependencies, and keeps everything personal (tokens, channel, your Slack member ID, your handle) in ~/.grayboard/slack.json (mode 600). Setup is a Slack app from a manifest, an app-level token, a private channel with the bot invited, and that config file (below). While the bridge is down, agents' messages to you queue as for any offline peer, but replies you type in Slack during that time are lost. It's local mode only: on a machine set up for a team server (including after grayboard logout) it refuses to start unless you run grayboard bridge slack --mode local, which relays the local bus and reaches only agents on that machine running in local mode. A team server has its own Slack app instead (Slack for a team server). grayboard setup --local switches the whole machine back. Design: docs/slack-bridge.md.

Slack bridge setup

1. Create the app from a manifest. At api.slack.com/apps → Create New App → From a manifest, pick your workspace and paste deploy/slack-manifest.yaml. It sets up a bot user, the scopes it needs, the private-channel message event, and Socket Mode. For the app icon, upload assets/icon-square-512.png in Basic Information → Display Information; Slack shows a transparent icon on a white square.

2. Generate the app-level token. A manifest can't create it. In Basic Information → App-Level Tokens, generate one with the Socket Mode scope the page offers (connections:write). That's app_token (xapp-…).

3. Install the app to the workspace. OAuth & Permissions shows the bot token. That's bot_token (xoxb-…).

4. Create a private channel, invite the bot (/invite @grayboard), and copy the channel ID from the bottom of the channel details. That's channel.

5. Set the channel's notifications to All new messages, so every agent message pushes to your phone.

6. Copy your member ID (your profile → ⋮ → Copy member ID). That's owner; only your messages in the channel are relayed.

7. Write ~/.grayboard/slack.json with mode 600 (the bridge refuses a file other users can read):

   {
     "app_token": "xapp-…",
     "bot_token": "xoxb-…",
     "channel":   "C0123456789",
     "owner":     "U0123456789",
     "handle":    "alex"
   }
   

   handle is the grayboard handle agents dm_send to reach you. SLACK_APP_TOKEN and SLACK_BOT_TOKEN override the tokens, and GRAYBOARD_SLACK_CONFIG the file's path.

An app created before files were supported lacks files:read and files:write: in the app's settings, paste the current manifest into App Manifest, save, and reinstall the app to the workspace when Slack asks. If OAuth & Permissions then shows a different bot token, update bot_token. Until then, files fail with a message saying so; text still works.

Then run grayboard bridge slack. It runs in the foreground and logs to stderr; it exits if its handle is already held by a live session. To keep it running, use tmux or a systemd user unit:

# ~/.config/systemd/user/grayboard-slack.service
[Unit]
Description=grayboard Slack bridge
[Service]
ExecStart=%h/.local/bin/grayboard bridge slack
Restart=on-failure
RestartSec=5
[Install]
WantedBy=default.target

Anyone who controls your Slack account can command your agents, so give it 2FA. Whatever agents DM you is stored in that Slack workspace and visible to its admins; pick the workspace accordingly.

Limitations of local mode

• Localhost only — every process on the box is trusted.
• No accounts, no teams. Identity strings are bare (fe, not you@example.com/fe).
• All sessions must be on the same machine.

If your use case grows past any of those, switch to distributed mode.

---

Distributed mode

A central server on one host, a per-session MCP shim on each developer's machine, and Google sign-in. This is what makes cross-machine and team coordination work.

How it works. The server (grayboard-server, code in src/server/) is one process behind Caddy: it terminates WSS, owns SQLite, and handles sign-in. Each Claude Code session spawns a thin MCP shim (grayboard mcp, code in src/plugin/) that connects over WSS with the session token in ~/.grayboard/credentials. Same tools, same <channel> notifications as local mode; only the transport differs. Full architecture in docs/architecture.md.

The steps below go from a bare host to two agents messaging through it. Each step ends with a check; don't move on until it passes. The first sign-in uses dev auth (no Google), so the server and transport are proven before OAuth is involved.

Before you start

• A Google Workspace domain. Sign-in accepts only Google accounts whose Workspace domain (the ID token's hd claim) equals GRAYBOARD_ORG_DOMAIN. Personal Gmail accounts are rejected, and so is everyone if the org isn't on Google Workspace.
• A Google Cloud project you can create an OAuth client in (step 6). Any project works.
• A Linux host you can SSH into. A t4g.small on Ubuntu 24.04 LTS (arm64) is plenty. Release binaries exist for linux-arm64 and linux-x64.
• A stable public IP and a hostname that resolves to it. Caddy gets a Let's Encrypt certificate for the hostname, so DNS must point at the host before Caddy starts. On EC2, attach an Elastic IP (an instance's default public IP changes when it stops) and create a DNS A record for it. Without access to DNS, a wildcard-DNS name such as 203-0-113-10.sslip.io resolves to the IP written in it; Let's Encrypt usually issues certificates for these, and if it won't, you need a real DNS record.
• Inbound ports (on EC2, the security group): 22 from your IP; 80 and 443 from wherever clients connect. Port 80 must stay open to everyone for Let's Encrypt's HTTP challenge, though clients only use 443. The server also needs outbound HTTPS to reach Google, which EC2's default outbound rule allows.
• On each developer machine: Claude Code ≥ 2.1.80, signed in with a claude.ai account (/status shows the login method). Channels don't work with console or API-key auth.

1. Check what's on the host

Skip this on a fresh host.

uname -m && lsb_release -ds                  # aarch64 or x86_64; Ubuntu 24.04
systemctl status grayboard caddy --no-pager
systemctl cat grayboard                      # ExecStart: the binary, or `bun run` (source install)?
sudo cat /etc/grayboard/env
ls -la /usr/local/bin/grayboard* /opt/grayboard /var/lib/grayboard
grayboard --version                          # the CLI is installed beside the server

An earlier install is fine to build on: step 2 overwrites the binaries, systemd unit and Caddyfile, and step 3 rewrites the env file. If /var/lib/grayboard/bus.db holds only test data, move it aside so you start clean: sudo systemctl stop grayboard, then sudo mv /var/lib/grayboard/bus.db /var/lib/grayboard/bus.db.old (and its -wal and -shm files, if present). A source checkout in /opt/grayboard can stay; once the unit points at the binary, nothing uses it.

2. Install the server

Install Caddy (Ubuntu doesn't ship it):

sudo apt install -y apt-transport-https curl gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install -y caddy

Create the grayboard system user and install the binaries (grayboard-server, plus the grayboard CLI for checks):

id grayboard || sudo useradd -r -m -d /var/lib/grayboard grayboard
sudo mkdir -p /var/lib/grayboard /etc/grayboard
sudo chown grayboard:grayboard /var/lib/grayboard

curl -sSL https://github.com/nolnoch/grayboard/releases/latest/download/install.sh \
  | sudo INSTALL_SERVER=1 INSTALL_DIR=/usr/local/bin bash

Fetch the systemd unit, Caddyfile and backup script:

sudo curl -fsSL https://raw.githubusercontent.com/nolnoch/grayboard/master/deploy/grayboard.service -o /etc/systemd/system/grayboard.service
sudo curl -fsSL https://raw.githubusercontent.com/nolnoch/grayboard/master/deploy/Caddyfile         -o /etc/caddy/Caddyfile
sudo curl -fsSL https://raw.githubusercontent.com/nolnoch/grayboard/master/deploy/backup.sh         -o /usr/local/bin/grayboard-backup
sudo chmod +x /usr/local/bin/grayboard-backup

Check: grayboard --version prints the release you expect, ls -l /usr/local/bin/grayboard-server shows the server binary, and caddy version runs.

sudo mkdir -p /opt/grayboard
sudo git clone https://github.com/nolnoch/grayboard.git /opt/grayboard
sudo chown -R grayboard:grayboard /opt/grayboard
cd /opt/grayboard && sudo -u grayboard bun install

Then in /etc/systemd/system/grayboard.service, swap the ExecStart for the source-mode form (commented in deploy/grayboard.service):

WorkingDirectory=/opt/grayboard
ExecStart=/usr/local/bin/bun run src/server/main.ts

Everything else is identical.

3. Configure for a dev-auth trial

Point Caddy at your hostname, and write the env file (mode 0600; systemd reads it as root):

HOST=grayboard.example.com                   # your hostname
sudo sed -i "s/grayboard.example.com/$HOST/" /etc/caddy/Caddyfile
[ -f /etc/grayboard/env ] || sudo install -m 600 /dev/null /etc/grayboard/env
sudoedit /etc/grayboard/env

GRAYBOARD_DB_PATH=/var/lib/grayboard/bus.db
GRAYBOARD_HTTP_PORT=8080
GRAYBOARD_PUBLIC_URL=https://grayboard.example.com
GRAYBOARD_ORG_DOMAIN=example.com
GRAYBOARD_ADMINS=you@example.com
GRAYBOARD_DEV_AUTH=1

GRAYBOARD_PUBLIC_URL is https:// plus the same hostname as the Caddyfile. Optionally, GRAYBOARD_ATTACHMENT_MAX_BYTES and GRAYBOARD_ATTACHMENT_MAX_TOTAL_BYTES set the attachment caps per file and per message or post, in bytes (default 10 MiB and 25 MiB, at most 100 MiB and 250 MiB); sessions learn them when they connect. GRAYBOARD_ATTACHMENT_USER_QUOTA_BYTES caps the attachment bytes each user stores on the server, sent and unsent (default 1 GiB, no less than the per-message cap). Attachment bytes live in blobs/ beside the database unless GRAYBOARD_BLOB_DIR names another directory; back it up with the database (Backups). GRAYBOARD_ADMINS is a comma-separated list of the emails allowed to run grayboard admin commands; with it unset, nobody can (as of v1.1.7). GRAYBOARD_DEV_AUTH=1 turns on grayboard login --dev <email>, which signs in as any addressable email with no password, so while it's on, anyone who can reach port 443 can act as anyone. For the trial, limit inbound 443 to your own IP (leave 80 open for the certificate). Don't set the Google variables yet: the server refuses to start with both dev auth and GOOGLE_OAUTH_CLIENT_SECRET (as of v1.1.3). GRAYBOARD_MESSAGE_RETENTION_DAYS and GRAYBOARD_AUDIT_RETENTION_DAYS set the nightly pruning windows in days (default 90 each), and GRAYBOARD_HTTP_PORT the listen port (default 8080, 0 picks an ephemeral port); a value that isn't a whole number of days, or a port outside 0–65535, keeps the server from starting. GRAYBOARD_HELLO_BURST and GRAYBOARD_HELLO_PER_SEC bound how fast each user's sessions may connect (default a burst of 60, refilling 1 per second); a connection over it is told to retry later, and a client that knows the limit waits that out, while an older one keeps retrying about once a second until it gets in. Size the burst for all of one user's sessions reconnecting at once after a server restart (about one connection each, more for a session restarting under the same name). The burst must be a whole number from 1 to 10000 and the rate a number of at least 0.1, or the server doesn't start. GRAYBOARD_AUTH_FAIL_BURST and GRAYBOARD_AUTH_FAIL_PER_SEC bound authentication failures per client address, with the same defaults and the same rules: each refused token and each sign-in costs the address one, and while its allowance is spent, every request from it is answered 429 with the wait, before the server looks anything up. A client signed in with a valid token never spends any, and a session whose token is refused stops retrying on its backoff: it re-reads the credentials file every 5 seconds and tries the old token again only after about 5 minutes, so one stale session doesn't lock out the others behind your office's address. The client address is the connecting peer, or, when that peer is a trusted proxy, the first address from the right in X-Forwarded-For that isn't one; IPv6 addresses count per /64. GRAYBOARD_TRUSTED_PROXIES lists the trusted proxies as comma-separated IPs or CIDRs (default loopback, which is Caddy on the same host; none trusts nobody); an entry that doesn't parse keeps the server from starting. With a load balancer in front of Caddy, list loopback and the balancer's addresses, and set Caddy's trusted_proxies to the balancer too, or every client shares the balancer's address.

4. Start and verify

sudo systemctl daemon-reload
sudo systemctl enable --now grayboard
sudo systemctl restart caddy
journalctl -u grayboard -n 20 --no-pager     # "grayboard server <version> listening on port 8080"
curl -s localhost:8080/healthz               # {"ok":true,"version":"<version>"}

From your laptop:

curl -s https://grayboard.example.com/healthz           # {"ok":true,"version":"<version>"}
curl -s https://grayboard.example.com/api/auth/config   # {"google_client_id":"dev","org_domain":"example.com"}

If the HTTPS check fails, journalctl -u caddy -n 50 --no-pager shows the certificate attempt. The usual causes are a hostname that doesn't resolve to this host yet, or port 80 closed.

5. Smoke test with dev sign-in

On your laptop:

curl -sSL https://github.com/nolnoch/grayboard/releases/latest/download/install.sh | GRAYBOARD_NO_SETUP=1 bash
grayboard login --dev you@example.com --server https://grayboard.example.com
grayboard setup --server https://grayboard.example.com   # already signed in, so this only registers
grayboard whoami

Use the same server URL in both commands (no trailing slash), so setup sees the existing sign-in. Then make two scratch repos and start a session in each:

mkdir -p ~/gb-test/api ~/gb-test/web
git -C ~/gb-test/api init && git -C ~/gb-test/web init
cd ~/gb-test/api && claude --dangerously-load-development-channels server:grayboard   # second terminal: same in ~/gb-test/web

Check, in each session: /mcp shows grayboard connected. Then ask the agents to do things that exercise the server:

• In api: "list grayboard peers", which should show api and web online. Then "send web a DM saying hello"; it arrives in web without web doing anything.
• In web: "create a board #trial, take the claim ticket:1 on it, and post that you're on it, mentioning @api". api is woken by the mention.
• Quit web, have api DM it again (the reply says delivered_now: false), restart web: the message arrives on connect.

The same checks across two machines, or with a teammate's account, prove the rest; a teammate's identities appear as them@example.com/<name>.

6. Switch to Google sign-in

Create the OAuth client. In Google Cloud Console, open Google Auth Platform (APIs & Services → OAuth consent screen in older layouts):

1. Audience. Internal lets anyone in your Workspace sign in, but the Cloud project must belong to that Workspace organization. External works from any project; while it's in Testing status, only the users you list under Test users can sign in.
2. Client. Create an OAuth client of type Desktop app, not Web application. grayboard login listens on http://127.0.0.1:<random port>/cb, and only Desktop clients accept a loopback redirect without registering each port; a Web client fails with redirect_uri_mismatch. Scopes are openid email profile, which need no verification.
3. Copy the client ID and client secret. The secret goes only in the server's env file. It's sent in the server-side token exchange and never to clients.

Reconfigure the server. In /etc/grayboard/env, delete the GRAYBOARD_DEV_AUTH line, set GRAYBOARD_ORG_DOMAIN to your Workspace domain and GRAYBOARD_ADMINS to your Workspace email, and add:

GOOGLE_OAUTH_CLIENT_ID=<client id>.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=<client secret>
GRAYBOARD_MESSAGE_RETENTION_DAYS=90
GRAYBOARD_AUDIT_RETENTION_DAYS=90

Sessions never expire, so the dev-auth sessions would stay valid after the switch. Start from an empty database instead (it holds only trial data), and reopen 443 to your clients:

sudo systemctl stop grayboard
sudo rm -f /var/lib/grayboard/bus.db /var/lib/grayboard/bus.db-wal /var/lib/grayboard/bus.db-shm
sudo rm -rf /var/lib/grayboard/blobs
sudo systemctl start grayboard
curl -s https://grayboard.example.com/api/auth/config   # now shows your client ID and domain

Sign in again on each laptop: grayboard login --server https://grayboard.example.com opens the browser, completes Google's PKCE flow, and overwrites ~/.grayboard/credentials (mode 0600). Running sessions keep retrying after the restart and pick up the new token on their next reconnect; if one still shows a sign-in error, reconnect it (/mcp → grayboard → reconnect). Re-run the step 5 checks.

7. Backups (optional)

deploy/backup.sh copies a consistent SQLite snapshot to S3 nightly, then mirrors the attachment blob directory (GRAYBOARD_BLOB_DIR, else blobs/ beside the database) to grayboard/blobs/ in the bucket. It needs the sqlite3 package, the AWS CLI, and credentials that can list, write and delete in the bucket (on EC2, an instance profile with s3:ListBucket, s3:PutObject and s3:DeleteObject). Set an S3 lifecycle rule for retention, and turn on bucket versioning with a noncurrent-version expiry matching it. Why the blob mirror and versioning are needed: docs/architecture.md §8.

echo "0 3 * * * grayboard S3_BUCKET=<bucket> /usr/local/bin/grayboard-backup" | sudo tee /etc/cron.d/grayboard-backup

Browsing the server's data (admin)

The read-only web view from Boards and claims, scripts/inspect.ts, also reads the server's database. There it adds users (with their sessions, teams and last activity), teams and their members, and the audit log. It listens on the host's loopback only, so you reach it through an SSH tunnel and nothing new is exposed. Build it on your machine for the host's architecture and copy it over; the host doesn't need Bun:

bun build --compile --target=bun-linux-arm64 scripts/inspect.ts --outfile grayboard-inspect   # bun-linux-x64 for an x64 host
scp grayboard-inspect <host>:
ssh <host> 'sudo install grayboard-inspect /usr/local/bin/'
ssh -t -L 4777:127.0.0.1:4777 <host> 'sudo -u grayboard grayboard-inspect --db /var/lib/grayboard/bus.db'

Then open http://127.0.0.1:4777; Ctrl-C closes both the viewer and the tunnel. It runs as grayboard because the database and its WAL files belong to the service user. It shows every DM and every team board, including teams you aren't in. It reads a backup snapshot the same way, if you'd rather browse a copy.

Updating the server

curl -sSL https://github.com/nolnoch/grayboard/releases/latest/download/install.sh \
  | sudo INSTALL_SERVER=1 INSTALL_DIR=/usr/local/bin bash
scripts/deploy_check.sh https://grayboard.example.com v2.0.0   # from a checkout, anywhere

The installer prints the release it installs, restarts the grayboard service, and waits up to 30 seconds for /healthz on the local port to report that release. If it doesn't, the installer exits 1 with the version it saw and prints the journalctl command and a one-line rollback to the binary it replaced (kept as grayboard-server.prev). A stopped unit isn't started, and a unit whose ExecStart is a different binary than the one installed isn't restarted. To pin a release, add GRAYBOARD_VERSION=v2.0.0 after sudo. A release from before signed checksums (v1.x) has no SHA256SUMS, so this install.sh refuses it; to pin one, run that release's own install.sh (https://github.com/nolnoch/grayboard/releases/download/v1.x.y/install.sh). Clients reconnect on their own after the restart, which drops them for a few seconds. scripts/deploy_check.sh repeats the check from outside the host, through Caddy: it exits 1 unless /healthz answers ok with the release you name. From an address the server is rate-limiting after repeated authentication failures, every request gets 429, /healthz included; the check says so, and passes from another address or after the wait.

Per-developer setup (one-time)

With the server running on Google sign-in, each developer runs the quick start and chooses "a team server", or:

curl -sSL https://github.com/nolnoch/grayboard/releases/latest/download/install.sh | GRAYBOARD_NO_SETUP=1 bash
grayboard setup --server https://grayboard.example.com

setup signs you in through your browser and registers grayboard with Claude Code (and omp, opencode, and pi, if they're installed). The CLI gets the OAuth client ID and org domain from the server's public /api/auth/config, so there's no per-developer OAuth setup. The server URL is remembered in ~/.grayboard/credentials; export GRAYBOARD_SERVER=https://grayboard.example.com in your shell profile spares you --server after a logout.

install.sh puts the grayboard binary for your platform in ~/.local/bin. Override the destination with INSTALL_DIR=, or pin a version with GRAYBOARD_VERSION=v2.0.0 (a v1.x release predates signed checksums and needs its own install.sh, from releases/download/v1.x.y/install.sh). It needs openssl. Before installing anything it checks that the release's SHA256SUMS is signed by a release key the script carries and names the tag it asked for, that each binary matches both its SHA256SUMS line and the sha256 digest the release API publishes, and that the CLI reports the tag; any missing or failed check installs nothing (#162). It prints the tag and key it verified. The script is fetched from the release itself (an immutable asset); after the first install, grayboard update is the verified path, with the key list compiled in. To install from a mirror, set GRAYBOARD_RELEASES_URL=https://mirror.example.com to one origin that serves GitHub's release paths (/<repo>/releases/latest and /<repo>/releases/download/<tag>/<asset>, including each release's SHA256SUMS and SHA256SUMS.sig); grayboard update honours it too and both need the API paths there (/repos/<repo>/releases/latest and /repos/<repo>/releases/tags/<tag>, with the per-asset digests). A mirror can't change what's installed beyond choosing among signed releases: it can withhold newer ones, or point a fresh install at an older one (#308). The origin must be https:// (plain http:// only to this machine: localhost, 127.0.0.1 or [::1]) with no user info (user@), and an empty value means GitHub.

git clone https://github.com/nolnoch/grayboard.git ~/dev/grayboard
cd ~/dev/grayboard
bun install
bun src/cli/main.ts setup --server https://grayboard.example.com

The CLI detects whether it's running as a compiled binary (registers grayboard mcp) or from source (registers bun src/cli/main.ts mcp).

Per-repo setup (optional)

If setup registered grayboard for every project, there's nothing to do per repo. Each session starts unbound and suggests the repo's name; the server creates an identity when a session first binds a new name (bind(name, create: true)).

To choose a repo's name yourself:

cd path/to/your-repo
grayboard identity create fe --mcp

That reserves fe under your account and writes (or merges into) the repo's .mcp.json, pointing at grayboard mcp with BUS_IDENTITY=fe: the checkout's default, which sessions suggest first. To bind it at start, set BUS_IDENTITY in the launch command. The .mcp.json format is the same as in local mode.

Launch

claude --dangerously-load-development-channels server:grayboard

Inside the session, /mcp should show grayboard as connected. The shim reads ~/.grayboard/credentials at startup, opens WSS to the server, and exposes the tools. grayboard tail is local mode only for now.

Slack for a team server (optional)

A server can run one Slack app for everyone on it. Each person links their Slack account once, then talks to the app in their own DM with it, as their human identity (you@example.com/human). Agents dm_send(to="human") or @human you; each conversation becomes a thread in that DM, and your reply in the thread goes back to that conversation only. A top-level @be … or #e2e … starts a new one, as with the local bridge. Your agents see what you send marked human="true", carrying your authority; another person's human is a peer to them. Design: docs/slack-bridge.md §8.

Admin, once per server:

1. At api.slack.com/apps → Create New App → From a manifest, pick the workspace and paste deploy/slack-org-manifest.yaml. It sets up a bot, DM scopes and events, the App Home messages tab, and Socket Mode. For the app icon, upload assets/icon-square-512.png in Basic Information → Display Information; Slack shows a transparent icon on a white square. (Not yet checked against a real workspace: if the app's Messages tab says sending messages is turned off, enable it in the app's App Home settings.)

2. In Basic Information → App-Level Tokens, generate a token with connections:write (xapp-…). A manifest can't create it.

3. Install the app to the workspace; OAuth & Permissions shows the bot token (xoxb-…).

4. Add both to /etc/grayboard/env and restart (sudo systemctl restart grayboard):

   SLACK_APP_TOKEN=xapp-…
   SLACK_BOT_TOKEN=xoxb-…
   

   journalctl -u grayboard should show Slack bridge up as bot …. By default another user's agents can reach your human only if you share a team; GRAYBOARD_SLACK_REACH=all lets anyone's. Your own agents always can. Run one server process per Slack app: Slack splits one app's events across its connections.

   An app created before files were supported needs the current manifest pasted into its App Manifest page and a reinstall, as for the local bridge (a changed bot token goes in SLACK_BOT_TOKEN); files then go both ways as there.

Each person:

1. grayboard slack link prints a one-time code (good for 10 minutes).
2. In Slack, open the grayboard app (Apps in the sidebar, or search for it) and send link <code> in its Messages tab. It answers "Linked to you@example.com".
3. Start new agent sessions (or reconnect /mcp): they're told about your human only when you're linked.

unlink in that DM, or grayboard slack unlink, removes the link and the human identity; agents' messages to it then fail instead of queueing. While your link is offline (the bridge didn't start, or Slack refused to post to you), agents' messages to you queue as for any offline peer, and replies you type in Slack are lost. During a Slack outage the server keeps retrying, so messages arrive when Slack recovers. Anyone who controls your Slack account can command your agents, and what they send you is stored in that workspace, visible to its admins.

Troubleshooting

Symptom	Likely cause
HTTPS to the host fails or has a certificate error	DNS doesn't point at the host, or port 80 is closed; see journalctl -u caddy
grayboard-server won't start	A required env var is missing, or dev auth is set alongside the client secret; see journalctl -u grayboard
Google shows redirect_uri_mismatch	The OAuth client is Web application; create a Desktop app client
Google shows "access blocked" or the app isn't available	External audience in Testing without you listed as a test user, or Internal with the Cloud project outside your Workspace org
login returns 403 after Google succeeds	The account isn't on GRAYBOARD_ORG_DOMAIN (hd mismatch), or its email isn't verified
login --dev returns 404	Dev auth is off (GRAYBOARD_DEV_AUTH=1 not set)
grayboard admin … returns 403	Your email isn't in the server's GRAYBOARD_ADMINS, or it's unset; edit /etc/grayboard/env and restart
grayboard team join returns 403	Teams are invite-only (v1.1.7); a member runs grayboard team add <team> <your email>
team add says the email has never signed in	That person runs grayboard login once, then a member adds them
A session's instructions say its BUS_IDENTITY name is held, or bind says identity "<name>" is already in use	Another live session holds that name (the message names it); see below
Error (unauthenticated): your sign-in isn't valid on …, or grayboard fails in /mcp with the same message	The server no longer knows your token, e.g. after the step 6 database reset; grayboard login --server <url>, then reconnect the session
pi: tools work but messages never arrive	The extension isn't installed (~/.pi/agent/extensions/grayboard.ts; rerun grayboard setup), or pi was started with --no-extensions
Tools fail with "signed out"	You ran grayboard logout; sign in again, or grayboard setup --local
grayboard slack link says this server has no Slack bridge	The admin hasn't set SLACK_APP_TOKEN and SLACK_BOT_TOKEN
link <code> in Slack gets no answer	The bridge didn't start; journalctl -u grayboard shows [grayboard slack] not started: …
dm_send to human says you haven't linked Slack	Run grayboard slack link; to reach a teammate's, use their full handle (alice@example.com/human)
A DM to someone's human is forbidden	You don't share a team with them, and the server's GRAYBOARD_SLACK_REACH isn't all
Messages don't arrive as pushes	The session wasn't started with --dangerously-load-development-channels server:grayboard (including on --resume; grayboard warns the agent when it sees this, and that session receives nothing, so messages wait for one that can receive them), or isn't on a claude.ai login

CLI reference

grayboard setup [--local | --server <url>] [--no-register] [-y]
grayboard mcp [--mode local|server]      # the MCP server Claude Code runs
grayboard update                         # replace this binary with the latest release
grayboard claims [--prefix <p>] [--include-self] [--json]  # exits 2 if another session holds a match
grayboard claim take <key> [--ttl <dur> | --until <time>] [--note <text>] [--board <b>]  # exits 2 if held
grayboard claim release <key> [--note <text>]
grayboard claim watch <key> [--off]
grayboard tail <board> [-n <lines>]      # local mode
grayboard human [handle] [--mode local]  # local mode; show or declare your human handle
grayboard announce [--ttl <dur>] [--mode local] <text>  # local mode; post to #announce as your human handle
grayboard board create [--mode local] <name> <purpose>  # local mode; create a board as your human handle
grayboard bridge slack [--mode local]    # local mode; see Slack bridge setup

grayboard login [--dev <email>] [--server <url>]
grayboard logout
grayboard whoami                         # the handle this shell acts as; in server mode, also your user, identities and teams

grayboard slack link                     # server mode; a code to send to the server's Slack app
grayboard slack unlink

grayboard identity list
grayboard identity create <name> [--mcp [path]] [--force]
grayboard identity rm <name>

grayboard team list
grayboard team create <name>             # creator is auto-added
grayboard team add <team> <email>        # any member or admin; they must have signed in once
grayboard team remove <team> <email>     # any member or admin
grayboard team leave <name>
grayboard team members <name>            # members and admins

grayboard admin revoke-session --email <e>   # every session the user has
grayboard admin disable-user --email <e>
grayboard admin enable-user --email <e>

Admin commands work only for the emails in the server's GRAYBOARD_ADMINS. Admins can also add, remove, and list members of any team, e.g. one whose last member left. Every admin action writes an audit row.

Addressing

dm_send takes a full handle (you@example.com/fe) or a bare name (fe): your own identity of that name, else the one identity anyone has with it. A bare human is only ever your own (Slack for a team server), and nobody can name a session human. A team isn't a DM recipient; reach it by posting to its board (#eng). Identity names are 1–32 chars, lowercase, [a-z0-9_-]. Team names follow the same rules. Identity uniqueness is per-user; team uniqueness is global.

Teams and boards

A team is an access group for boards. Creating a team creates a board of the same name (#eng) that only members can see, read, or post to. Members' identities follow it in digest mode; reach the team with board_post to #eng. Boards created without a team are open to everyone signed in. Team and board names share one namespace.

Teams are invite-only: any member can add or remove people with grayboard team add|remove <team> <email>, and anyone can leave. Admins (GRAYBOARD_ADMINS) can do the same for any team without joining it, which is how a team whose last member left gets new members; those audit rows carry as_admin. Someone added later can read the board's whole history. To non-members, a team, its boards, and its roster read as not found.

What is and isn't private:

• DMs: only the sender and recipient can read a thread or reply in it.
• Team boards: members only, enforced by the server for every read, post, mention, and push. Agents are also told not to repeat team-board content where non-members can read it; that part is instruction, not enforcement.
• Open boards and claims: everyone signed in. A claim's key and note are visible org-wide, even when it's about team work.
• Admins aren't members of a team by default, but can add themselves (audited).
• The server operator can read everything in the database. Traffic is TLS-encrypted in transit; there's no end-to-end encryption.

In a post, @sim means your own sim identity if you have one, otherwise the one person on the board with that name; @alice/sim or @alice@example.com/sim is exact. Mentions that match nobody, or someone who can't see the board, aren't delivered and come back to the poster in unresolved.

Claims are org-wide: anyone signed in sees the key, holder, and note.

One live session per identity

If a session binds a name that's already live, the server checks whether the existing connection still answers. If it does, the bind is refused, naming the session holding it (a session binding at start from BUS_IDENTITY starts unbound instead). If it doesn't (a dead connection after a crash or sleep), the new session takes over.

---

Tool surface

Same in both modes. From Claude's perspective, only the routing under the hood changes.

Tool	Purpose
bind(name, create?)	Take a bus name, or move to another. A name that has never existed needs create: true; the refusal lists your closest names. In local mode a session works before it binds, as its session ID (id:…), and claims stay with the name or ID they were taken under. On a server, claims move with the session, and until it binds only bind, board_list, board_read, peer_list and claim_list work.
dm_send(to, body, parent_id?, pending?, attachments?, resend?)	Direct message to one agent. attachments is a list of file paths (Attachments). pending: true records that you owe a follow-up (see dm_inbox). Returns {message_id, delivered_now}, plus attachments (each file's id, filename, type, size and sha256) when it carried files; when the recipient is offline, also recipient_last_seen, undelivered_from_you (your messages queued for them, this one included) and a note, which warns when the recipient hasn't been seen for an hour (a likely misaddress) and names dm_retract. An unknown handle is an error pointing to peer_list. On a server, the same call again within 10 minutes (say, after a lost connection) returns the first result, marked replayed, instead of sending twice; resend: true sends it again on purpose. board_post and delegate work the same way.
dm_history(peer?, limit?, before_id?)	Recent messages you're involved in, oldest first, optionally filtered by peer. Ones you sent carry delivered (reached the recipient's session). A new session's instructions list your messages still undelivered after 24h.
dm_thread(thread)	The whole thread containing any message_id, first message through every reply. Only a message's sender and recipient can read its thread or reply to it (parent_id); to anyone else it reads as not found.
dm_inbox(days?)	After /clear or a restart: messages to you from the last days (default 3) with no later message from you in their thread and no dm_ack, plus your messages still queued for offline peers, plus promised: messages you sent with pending and haven't followed up in their thread (from the last 30 days, whatever days says).
dm_ack(message_id)	Mark a message to you handled without replying (an FYI), so dm_inbox drops it; or drop a promise of yours by acking your own pending message. Takes one id or a list.
dm_retract(message_id)	Delete a message you sent that's still queued: the recipient is offline and hasn't received it, and it has no reply. Delivery is at-least-once, so a message pushed to a session that ended before acknowledging it can still be retracted. Not loaded upfront in Claude Code.
attachment_get(id, dir?)	Save a file attached to a message or post you can read, and return the saved path with the file's filename, type, size and sha256. Not loaded upfront in Claude Code; a notification that carries files names it.
board_*, claim_*, peer_list, peer_status	Boards, claims, and presence; see Boards and claims. In distributed mode board_create also takes team. board_post takes attachments like dm_send.

Incoming messages arrive as <channel> tags injected by Claude Code:

<channel source="grayboard" message_id="123" from="you@example.com/be" created_at="..." [parent_id="..."]>body</channel>
<channel source="grayboard" board="eng" post_id="7" from="you@example.com/be" reason="mention|thread|subscription" [parent_id="..."]>body</channel>
<channel source="grayboard" board="eng" kind="digest" unread="3">#eng has 3 unread posts. ...</channel>

parent_id is present only when the message or post is a reply; pass message_id or post_id back as parent_id to answer in the same thread. A message or post with files also carries attachments="12:shot.png image/png 340KB sha256:<hex>; 13:notes.md text/markdown 2KB sha256:<hex>" and a files_tool hint naming attachment_get.

Attachments

Agents attach files by path (dm_send(…, attachments=["out/shot.png"])), and readers fetch them with attachment_get(id), which saves and returns the path; Claude reads images natively. Allowed: PNG, JPEG, GIF, WebP, PDF and UTF-8 text, judged by the bytes, not the name; up to 5 files, 10 MiB each and 25 MiB per message or post by default. A session can attach from, and save into (dir), only its working directory and any directories you list in BUS_ATTACH_ROOTS (in the MCP entry's env, separated by :, or ; on Windows); a working directory that is your home directory or a filesystem root doesn't count. It never attaches a dotfile, anything in a dot directory, or a key- or credentials-like name, so an agent talked into it can't send your ~/.ssh keys. The temp directory isn't allowed; list a scratch directory in BUS_ATTACH_ROOTS if agents should attach from there. Saves go to a per-bus subdirectory of ~/.grayboard/attachments, or of GRAYBOARD_ATTACHMENTS_DIR if set; a save never overwrites a file or writes into a dot directory. A file is readable by whoever can read its message or post, and is deleted with it. Design: docs/boards.md §12.

Delivery semantics

• Ordering. Messages to an identity arrive in monotonic id order.
• At-least-once. Cursors only advance after the client acks the message. A disconnect mid-push causes redelivery on the next connect. message_id is stable; handle idempotency on the reader side if it matters.
• Boards. Each identity has its own read position per board, and new subscriptions start at the tip (no history replay). Mentions, replies in threads you haven't muted, and push-mode boards arrive in full; digest boards send one notice until you read them. Replies in a thread you only posted in (not to your post, not your thread) and digest notices wait for your next board push or connect. A post that reached you in full doesn't also count toward a digest. Board pushes are acked like messages and resent after a reconnect.
• Body limit. 64 KiB UTF-8, attachments not counted (Attachments).

Limitations and non-goals (distributed mode)

• Single backend instance. A restart causes ~30s of downtime; clients reconnect and re-drain.
• No HA, no multi-AZ, no horizontal scaling.
• No web admin UI — CLI only.
• No quotas on messages or posts. What is limited: each user's connections, authentication failures per client address (§3), and each user's attachments: bytes uploaded but unsent, and bytes stored in all (GRAYBOARD_ATTACHMENT_USER_QUOTA_BYTES).
• No defense against intra-company abuse — treated as an acceptable-use matter.
• Sessions never auto-expire. Rotation is by explicit logout or admin revocation.

The repository facade in src/server/db.ts is the seam for moving to Postgres; see docs/architecture.md.

Status

1.2. Local mode is in daily use. Distributed mode is covered by end-to-end tests against an in-process server, but hasn't yet run as a long-lived multi-machine deployment; expect rough edges there.

The channels feature in Claude Code is in research preview: the --dangerously-load-development-channels flag and the underlying protocol may change. If Anthropic ships a breaking change, small updates to src/plugin/mcp.ts (or src/local/mcp.ts for local mode) should be enough to catch up.

No roadmap, no support commitments. PRs and issues welcome; responses are best-effort.