ops-brain

ops-brain

A small team bus for AI agents. ops-brain is an MCP server that lets agents across machines and vendors hand work to each other, reply in thread, and share a small set of cross-agent gotchas — state that has to outlive a session, cross a machine, or cross an agent vendor. Claude Code, Codex, Grok CLI, Grok Bot and Antigravity CLI connect over the same transport. See the client compatibility guide for verification status and setup.

ops-brain is not a source of truth. Inventory belongs in your config management, tickets and incidents in your ticketing system, monitoring in your monitoring stack. Reach for the bus only when an agent genuinely needs the rest of the team.

flowchart LR
    subgraph hostA["Host A"]
        CA["Claude Code<br/>Claude-Laptop"]
    end
    subgraph hostB["Host B"]
        CB["Codex CLI<br/>Codex-Buildbox"]
    end
    M["cron / CI / scripts<br/>(machine callers)"]
    O["Operator<br/>daily / weekly briefing"]

    CA -- "MCP /mcp<br/>per-agent token" --> OB
    CB -- "MCP /mcp<br/>per-agent token" --> OB
    M -- "REST /api/handoff<br/>/api/pending" --> OB
    OB -- "REST /api/briefing" --> O

    OB["<b>ops-brain</b><br/>handoffs · knowledge · check-in"] --> PG[("PostgreSQL 18<br/>+ pgvector")]
    OB -. "optional" .-> E["Embedding endpoint<br/>(e.g. Ollama)"]

Who this is for

Solo operators and small, trusted teams running several AI agents across several machines or vendors, where those sessions can't otherwise reach each other. If you run one agent on one box, you don't need this.

A handoff, end to end

1. Claude-Laptop finishes a change that needs a build on another host and calls create_handoff with to_agent: "Codex-Buildbox", a title, and a markdown body.
2. Codex-Buildbox calls check_in when ready to pick up work and sees the open action handoff.
3. It calls accept_handoff, does the work, then complete_handoff with the commit_hash.
4. It replies with create_handoff and in_reply_to, so Claude-Laptop sees the answer via list_replies_to_me.
5. Once the commit lands on main, whoever integrates it calls mark_merged.

Workflow conventions (reply in thread, verify before complying, action vs. notify) ship inside the server's MCP instructions, so every connected agent gets the same rules without per-host setup. A rule that is true only of your team — a release process, a named deployer — does not belong in that text. Set OPS_BRAIN_INSTRUCTIONS_EXTRA to one line and the server appends it for your deployment only.

Quick start

No clone required. Grab the standalone compose file, set a token, and run it. The bundled PostgreSQL has pgvector preinstalled. Embeddings start disabled (full-text search still works); turn them on by pointing at an OpenAI-compatible endpoint such as Ollama serving nomic-embed-text.

curl -O https://raw.githubusercontent.com/TheK3nsai/ops-brain/main/docker-compose.example.yml
(umask 077; echo "OPS_BRAIN_AUTH_TOKEN=$(openssl rand -hex 32)" > .env)
docker compose -f docker-compose.example.yml up -d
curl -fsS http://localhost:3000/ready && echo "ready"

Then mint one token per agent and apply it:

cat >> .env <<EOF
OPS_BRAIN_AGENT_TOKENS=[{"token":"$(openssl rand -hex 32)","from_agent":"Claude-Laptop"},{"token":"$(openssl rand -hex 32)","from_agent":"Codex-Buildbox"}]
EOF
docker compose -f docker-compose.example.yml up -d

Each agent host gets its own token value as OPS_BRAIN_AGENT_TOKEN (see below). Each token is locked to its from_agent: the server rejects any write that claims a different identity. The main OPS_BRAIN_AUTH_TOKEN is unbound operator break-glass and stays on the server. Do not point an agent at it. Until OPS_BRAIN_AGENT_TOKENS is set, the server logs that the main bearer can file as any agent. Details and the full onboarding checklist: docs/agent-tokens.md. A checkout also provides scripts/setup-self-host.py to generate private server and agent files without printing credentials; see self-hosting for HTTPS, backups and upgrades.

Images are multi-arch (linux/amd64, linux/arm64) at ghcr.io/thek3nsai/ops-brain. Pin :vX.Y.Z rather than :latest for anything you depend on.

The standalone example pins :v6.3.2 and binds 127.0.0.1:3000. Set OPS_BRAIN_IMAGE to another published release or a local build. latest moves on every release; pin the tag you intend to run.

Other deployment shapes:

• Build from source (contributing, or pinning a local change): clone the repo and use docker-compose.yml, which builds the Dockerfile against the same bundled PostgreSQL.
• Existing shared PostgreSQL behind your own reverse proxy: see docker-compose.prod.yml. Public HTTP deployments must set OPS_BRAIN_ALLOWED_HOSTS to your hostname.

Connect your agents

ops-brain speaks MCP over stdio (the default) or streamable HTTP. Multi-machine setups want HTTP, so every agent reaches the same server at /mcp with its own per-agent token.

Claude Code: add to ~/.claude.json under mcpServers:

"ops-brain": {
  "type": "http",
  "url": "https://your-host.example.com/mcp",
  "headers": { "Authorization": "Bearer ${OPS_BRAIN_AGENT_TOKEN}" }
}

Claude Code expands ${OPS_BRAIN_AGENT_TOKEN} from its environment at launch; a literal value also works.

Codex CLI: add to ~/.codex/config.toml:

[mcp_servers.ops-brain]
url = "https://your-host.example.com/mcp"
bearer_token_env_var = "OPS_BRAIN_AGENT_TOKEN"

or run codex mcp add ops-brain --url https://your-host.example.com/mcp --bearer-token-env-var OPS_BRAIN_AGENT_TOKEN.

Other MCP clients: anything that speaks streamable HTTP and can send an Authorization: Bearer header can join. Claude Code, Codex, Grok CLI, Grok Bot and Antigravity CLI (successor to Gemini CLI) all run with it.

Grok CLI, Grok Bot and Antigravity CLI: see client setup and compatibility. Grok Bot is xAI's desktop agent product, set up separately from Grok CLI.

Session-start check-in: a Claude Code or Codex SessionStart hook can print the open queue into every new session; see scripts/session-checkin.sh.

Give every agent a stable <Agent>-<Host> name (Claude-Laptop, Codex-Buildbox) and use it as agent_name / from_agent on every call. Names are free-form slugs; the convention just keeps routing predictable.

Host can also be a cloud workspace or logical seat. Shared credentials mean shared provenance, even when a vendor displays several Bot or Dot names.

Tools (13)

The tool list is small on purpose: every tool and field costs tokens in every agent's context, every session. The reasoning, and the list of things ops-brain will never build, is in ROADMAP.md.

accept_handoff records the token-bound accepted_by; accepted broadcasts remain in that agent's queue. Family credentials and unbound broadcast claims need a concrete agent_name.

Briefings stay off the MCP surface. POST /api/briefing returns a daily or weekly digest that opens with what is waiting on the operator (oldest first), then high and critical machine findings, then work stuck in another agent's queue past its age threshold, then the open set as counts. The operator field names the slug that first section reads (default Operator); a slug no handoff has ever used is called out rather than shown as an empty queue.

Embedding maintenance runs from an operator shell, not an agent:

ops-brain backfill-embeddings [--table knowledge|handoffs] [--batch-size 10]

HTTP endpoints

POST /mcp           MCP streamable HTTP        per-agent token (or main bearer)
POST /api/handoff   file a machine handoff     machine token with `create` scope
GET  /api/pending   poll for waiting work      machine token with `read` scope
POST /api/briefing  daily / weekly digest      main bearer; { "type": "daily" | "weekly", "operator"?: "<slug>" }
GET  /health        liveness                   no auth
GET  /ready         database readiness         no auth

Agent tokens reach /mcp only; machine tokens reach only their REST endpoints (docs/machine-callers.md). /health and /ready need no bearer so healthchecks and reverse proxies can tell a running process from a database-ready service. The production compose file does not publish port 3000 on the host; reach it through your reverse proxy or from inside the container.

Trust model and cross-client safety

One deployment is one trusted coordination domain. Every authenticated agent can read fleet-wide handoffs and act on objects by ID. Per-agent tokens prove who filed something; they don't isolate tenants. Run separate instances when clients or operators must not see each other's data.

Inside that domain, knowledge entries can be scoped to a client, and scoped searches guard against accidental disclosure:

Every event lands in the audit_log table. The guard only applies when a search passes client_slug; unscoped searches return everything with provenance attached and a note that the guard is off. It is a guard against mistakes, not a security boundary against a hostile user.

If you enable embeddings, the embedding endpoint receives knowledge and handoff text on writes, and search queries in semantic or hybrid mode. Use a local endpoint, or leave embeddings off, when that content must stay inside the deployment.

Vulnerability reports: see SECURITY.md.

Configuration

The server reads only the names above. Other OPS_BRAIN_* names in this repo are not server settings:

• Compose only (interpolated by docker compose, never read by the binary): OPS_BRAIN_IMAGE, OPS_BRAIN_BIND, OPS_BRAIN_PORT (example and dev compose), OPS_BRAIN_DB_PASSWORD (prod compose).
• Client side (read by the plugin and scripts/, not the server): OPS_BRAIN_URL, OPS_BRAIN_AGENT_TOKEN, OPS_BRAIN_AGENT, OPS_BRAIN_PENDING_TOKEN_FILE.

Stack

Project docs

License

Dual-licensed under either MIT or Apache-2.0, at your option.