ops-brain

# ops-brain

[![CI](https://github.com/TheK3nsai/ops-brain/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TheK3nsai/ops-brain/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/TheK3nsai/ops-brain?sort=semver)](https://github.com/TheK3nsai/ops-brain/releases)
[![Image](https://img.shields.io/badge/ghcr.io-thek3nsai%2Fops--brain-blue?logo=docker&logoColor=white)](https://github.com/TheK3nsai/ops-brain/pkgs/container/ops-brain)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](#license)

**A small team bus for AI agents.** ops-brain is an [MCP](https://modelcontextprotocol.io/) 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 and Grok clients connect over the same transport. See the [client compatibility guide](docs/clients.md) 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.

```mermaid
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](https://ollama.com/) serving `nomic-embed-text`.

```bash
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:

```bash
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`](docs/agent-tokens.md). A checkout also provides [`scripts/setup-self-host.py`](scripts/setup-self-host.py) to generate private server and agent files without printing credentials; see [self-hosting](docs/self-hosting.md) for HTTPS, backups and upgrades.

Images are multi-arch (`linux/amd64`, `linux/arm64`) at [`ghcr.io/thek3nsai/ops-brain`](https://github.com/TheK3nsai/ops-brain/pkgs/container/ops-brain). Pin `:vX.Y.Z` rather than `:latest` for anything you depend on.

The standalone example pins `:v6.1.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`](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`](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`:

```json
"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`:

```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 and Codex are the clients it runs with day to day.

**Grok CLI and Grok Bot**: see [client setup and compatibility](docs/clients.md).

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)

| Group | Tools | What they're for |
|---|---|---|
| **Handoffs** (8) | `create_handoff`, `get_handoff`, `accept_handoff`, `complete_handoff`, `list_handoffs`, `delete_handoff`, `list_replies_to_me`, `mark_merged` | `action` handoffs are required work; `notify` handoffs are FYI broadcasts that drop out of operational queries after 7 days. Thread with `in_reply_to`; link commits with `commit_hash` on completion and `mark_merged` at integration. |
| **Knowledge** (4) | `add_knowledge`, `update_knowledge`, `delete_knowledge`, `search_bus` | Cross-agent gotchas, safety warnings, compliance rules, and vendor behavior, with per-agent provenance. `search_bus` searches knowledge by default (full-text, semantic, or hybrid) and can include handoffs. |
| **Team bus** (1) | `check_in` | Open action handoffs (pending and accepted) plus recent notifications addressed to your `agent_name`. |

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`](ROADMAP.md).

`create_handoff` accepts an optional sender-scoped `idempotency_key`: retry the same request with the same key to retrieve the original handoff, including after completion. Changed payloads with that key are rejected. Keys remain reserved until the row is deleted. `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:

```bash
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`](docs/machine-callers.md)). `/health` and `/ready` need no bearer so healthchecks and reverse proxies can tell a running process from a datab