ops-brain

Небольшая шина для командной работы ИИ-агентов. ops-brain — это сервер MCP, который позволяет агентам на разных машинах и у разных поставщиков передавать друг другу задачи, отвечать в ветках обсуждений и обмениваться небольшим набором важных межагентных нюансов — сведениями, которые должны сохраняться между сессиями, передаваться с одной машины на другую или между агентами разных поставщиков. Клиенты Claude Code, Codex и Grok подключаются через один и тот же транспорт. Статус проверки совместимости и инструкции по настройке см. в руководстве по совместимости клиентов.

ops-brain не является источником достоверных данных. Инвентарные данные храните в системе управления конфигурацией, задачи и инциденты — в системе управления тикетами, мониторинг — в своей системе мониторинга. Используйте шину только тогда, когда агенту действительно нужно взаимодействовать с остальной командой.

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)"]

Для кого предназначен этот сервер

Для самостоятельных операторов и небольших команд, которым можно доверять и которые используют несколько ИИ-агентов на разных машинах или у разных поставщиков, когда эти сессии не могут взаимодействовать друг с другом напрямую. Если у вас один агент на одном компьютере, этот сервер вам не нужен.

Как работает передача задачи

Claude-Laptop завершает изменение, которое нужно собрать на другом хосте, и вызывает create_handoff, передавая to_agent: "Codex-Buildbox", заголовок и текст в формате markdown.
Когда Codex-Buildbox готов взять задачу, он вызывает check_in и видит открытую передачу с типом «действие».
Затем он вызывает accept_handoff, выполняет работу и вызывает complete_handoff, указав commit_hash.
В ответ он вызывает create_handoff с параметром in_reply_to, чтобы Claude-Laptop получил ответ через list_replies_to_me.
После попадания коммита в ветку main тот, кто выполняет интеграцию, вызывает mark_merged.

Правила рабочего процесса — отвечать в ветке обсуждения, проверять информацию перед выполнением, различать действия и уведомления — встроены в инструкции MCP-сервера. Поэтому все подключённые агенты получают одинаковые правила без отдельной настройки каждого хоста. Правила, актуальные только для вашей команды, например процесс выпуска релизов или имя ответственного за развёртывание, не следует добавлять в эти инструкции. Укажите одну строку в OPS_BRAIN_INSTRUCTIONS_EXTRA, и сервер добавит её только для вашего развёртывания.

Быстрый запуск

Клонировать репозиторий не нужно. Скачайте автономный compose-файл, задайте токен и запустите сервер. В комплекте PostgreSQL уже установлен pgvector. Векторные представления изначально отключены, но полнотекстовый поиск продолжает работать. Чтобы включить векторные представления, укажите совместимую с OpenAI конечную точку, например Ollama с моделью nomic-embed-text.

.env) docker compose -f docker-compose.example.yml up -d curl -fsS http://localhost:3000/ready && echo "ready"">

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"

Затем создайте отдельный токен для каждого агента и добавьте их:

.env

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

На хосте каждого агента задайте его собственное значение токена в OPS_BRAIN_AGENT_TOKEN (см. ниже). Каждый токен привязан к своему from_agent: сервер отклоняет любую запись, в которой указана другая идентичность. Основной OPS_BRAIN_AUTH_TOKEN не привязан к агенту и предназначен для аварийного операторского доступа; он должен оставаться на сервере. Не подключайте к нему агента. Пока не задан OPS_BRAIN_AGENT_TOKENS, сервер предупреждает в журнале, что основной токен позволяет отправлять данные от имени любого агента. Подробности и полный список шагов по подключению см. в docs/agent-tokens.md. В копии репозитория также есть scripts/setup-self-host.py: скрипт создаёт закрытые файлы сервера и агентов, не выводя учётные данные. Информацию о настройке HTTPS, резервном копировании и обновлениях см. в разделе самостоятельное размещение.

Образы для нескольких архитектур (linux/amd64, linux/arm64) доступны в ghcr.io/thek3nsai/ops-brain. Для всего, от чего зависит ваша работа, указывайте тег :vX.Y.Z, а не :latest.

Автономный пример использует тег :v6.3.1 и привязывает сервер к адресу 127.0.0.1:3000. Задайте OPS_BRAIN_IMAGE, чтобы выбрать другой опубликованный релиз или локальную сборку. Тег latest меняется с каждым релизом — закрепите тег нужной версии.

Другие варианты развёртывания:

Сборка из исходного кода (для участия в разработке или использования локального изменения с фиксированной версией): клонируйте репозиторий и используйте docker-compose.yml, который собирает Dockerfile с тем же PostgreSQL из комплекта.
Существующий общий PostgreSQL за собственным обратным прокси: см. docker-compose.prod.yml. Для развёртываний, доступных из публичной сети по HTTP, необходимо задать OPS_BRAIN_ALLOWED_HOSTS, указав имя хоста.

Подключение агентов

ops-brain поддерживает MCP через stdio (по умолчанию) и потоковый HTTP. Для конфигураций с несколькими машинами подходит HTTP: каждый агент обращается к одному серверу по адресу /mcp, используя собственный токен.

Claude Code: добавьте конфигурацию в раздел mcpServers файла ~/.claude.json:

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

При запуске Claude Code подставляет значение ${OPS_BRAIN_AGENT_TOKEN} из окружения; можно также указать токен напрямую.

Codex CLI: добавьте конфигурацию в файл ~/.codex/config.toml:

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

Либо выполните команду codex mcp add ops-brain --url https://your-host.example.com/mcp --bearer-token-env-var OPS_BRAIN_AGENT_TOKEN.

Другие клиенты MCP: подключиться может любой клиент, который поддерживает потоковый HTTP и умеет отправлять заголовок Authorization: Bearer. С ним работают Claude Code, Codex, Grok CLI, Grok Bot и Antigravity CLI — преемник Gemini CLI.

Grok CLI, Grok Bot и Antigravity CLI: инструкции по настройке и сведения о совместимости см. в разделе настройки и совместимость клиентов. Grok Bot — десктопный агент от xAI; его настройка отличается от настройки Grok CLI.

Проверка при запуске сессии: хук SessionStart в Claude Code или Codex может выводить список открытых задач при каждом запуске новой сессии. Инструкции см. в разделе scripts/session-checkin.sh.

Дайте каждому агенту постоянное имя с разделителем - (Claude-Laptop, Codex-Buildbox) и указывайте его в agent_name / from_agent при каждом вызове. Имена могут быть произвольными идентификаторами; такое соглашение лишь помогает сделать маршрутизацию предсказуемой.

Host также может обозначать облачную рабочую среду или логическое рабочее место. Общие учётные данные означают общую историю происхождения запросов, даже если поставщик отображает несколько имён Bot или Dot.

Инструменты (13)

Группа	Инструменты	Назначение
Передача задач (8)	`create_handoff`, `get_handoff`, `accept_handoff`, `complete_handoff`, `list_handoffs`, `delete_handoff`, `list_replies_to_me`, `mark_merged`	Передачи типа `action` — обязательные задачи; передачи типа `notify` — информационные сообщения, которые перестают отображаться в рабочих запросах через 7 дней. Связывайте сообщения в цепочку с помощью `in_reply_to`; указывайте коммиты через `commit_hash` при завершении и вызывайте `mark_merged` после интеграции. `delete_handoff` выполняет окончательное удаление, оставляя в `audit_log` запись-заглушку со статусом `deleted` (идентификатор, агент, выполнивший удаление, отправитель, получатель, заголовок, статус).
База знаний (4)	`add_knowledge`, `update_knowledge`, `delete_knowledge`, `search_bus`	Общие для агентов сведения об особенностях, предупреждениях по безопасности, правилах соответствия требованиям и поведении поставщиков с указанием источника для каждого агента. По умолчанию `search_bus` выполняет поиск по базе знаний (полнотекстовый, семантический или гибридный) и может включать передачи задач.
Общая шина команды (1)	`check_in`	Открытые передачи задач (ожидающие и принятые), а также недавние уведомления, адресованные вашему `agent_name`. Принятые передачи, которые агент создал для самого себя, используются как записи блокировки: они учитываются в `self_claims_held`, но не отображаются в списке.

Список инструментов намеренно невелик: каждый инструмент и каждое поле занимают токены в контексте каждого агента и в каждом сеансе. Обоснование и перечень того, что ops-brain принципиально не будет реализовывать, приведены в ROADMAP.md.

accept_handoff сохраняет привязанный к токену идентификатор accepted_by; принятые уведомления остаются в очереди соответствующего агента. Для учётных данных семейства и непривязанных заявок на уведомления необходимо указать конкретный agent_name.

Сводки не входят в поверхность MCP. POST /api/briefing возвращает ежедневную или еженедельную сводку. Сначала в ней перечисляется то, что ожидает оператора, начиная с самого старого; затем — важные и критические выводы системы; далее — задачи, застрявшие в очереди другого агента дольше заданного порога; в конце — количество элементов в открытой очереди. В поле operator указывается slug, по которому формируется первый раздел (по умолчанию — Operator); если ни одна передача задач ранее не использовала этот slug, об этом сообщается вместо отображения пустой очереди.

Обновление эмбеддингов запускается из оболочки оператора, а не агента:

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

HTTP-эндпоинты

" } GET /health проверка доступности без аутентификации GET /ready готовность базы данных без аутентификации">

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

Токены агентов дают доступ только к /mcp; токены машин — только к соответствующим REST-эндпоинтам (документация для машинных клиентов). Для /health и /ready не требуется токен Bearer: это позволяет проверкам состояния и обратным прокси отличать работающий процесс от сервиса, готового к работе с базой данных. Файл production compose не публикует порт 3000 на хосте; подключайтесь через обратный прокси или изнутри контейнера.

Модель доверия и безопасность взаимодействия клиентов

Один экземпляр — одна доверенная среда координации. Все аутентифицированные агенты могут читать передачи задач всей группы и выполнять действия над объектами по их идентификаторам. Токены отдельных агентов подтверждают, кто создал запись, но не обеспечивают изоляцию арендаторов. Если клиенты или операторы не должны видеть данные друг друга, запускайте отдельные экземпляры.

В рамках этой среды записи базы знаний можно привязать к клиенту, а поиск с указанной областью действия защищает от случайного раскрытия данных:

Принадлежность записи	Результат
Не привязана к клиенту (глобальная)	Возвращается
Привязана к тому же клиенту, что и запрос	Возвращается
Привязана к другому клиенту и помечена как `cross_client_safe`	Возвращается; событие записывается в журнал
Привязана к другому клиенту, а вызывающая сторона передаёт `acknowledge_cross_client: true`	Данные предоставляются; событие записывается в журнал
Привязана к другому клиенту, остальные условия не выполнены	Данные скрываются и заменяются уведомлением о несоответствии области действия; событие записывается в журнал

Все события сохраняются в таблице audit_log. Проверка применяется только при поиске с указанным client_slug; поиск без области действия возвращает все результаты с указанием источника и уведомлением о том, что проверка отключена. Это защита от ошибок, а не граница безопасности, способная противостоять злоумышленнику.

Если вы включите эмбеддинги, при записи конечная точка эмбеддингов получает тексты записей базы знаний и передач задач, а при семантическом или гибридном поиске — поисковые запросы. Если эти данные должны оставаться внутри экземпляра, используйте локальную конечную точку или отключите эмбеддинги.

Информацию об уязвимостях см. в SECURITY.md.

Конфигурация

Переменная среды	Значение по умолчанию	Примечания
`DATABASE_URL`	(обязательно)	Строка подключения к PostgreSQL
`OPS_BRAIN_TRANSPORT`	`stdio`	`stdio` или `http`
`OPS_BRAIN_LISTEN`	`0.0.0.0:3000`	Адрес привязки HTTP
`OPS_BRAIN_AUTH_TOKEN`	(не задано)	Основной токен Bearer. Для `http` обязателен: если он отсутствует или пуст, запуск прерывается, кроме случая, когда задано `OPS_BRAIN_DEV_NO_AUTH=true`.
`OPS_BRAIN_AGENT_TOKENS`	(не задано)	JSON-массив токенов с привязкой к личности для `/mcp`. Обеспечивает идентификацию, но не изоляцию арендаторов. См. `docs/agent-tokens.md`.
`OPS_BRAIN_INSTRUCTIONS_EXTRA`	(не задано)	Одна строка, добавляемая к встроенным инструкциям MCP только для этого экземпляра. Переносы строк не допускаются. Значение отклоняется, если итоговый текст инициализации превышает 1400 байт (с текущим встроенным текстом остаётся 213 байт).
`OPS_BRAIN_MACHINE_TOKENS`	(не задано)	JSON-массив токенов с ограниченными правами для `POST /api/handoff` и `GET /api/pending`. См. `docs/machine-callers.md`.
`OPS_BRAIN_ALLOWED_HOSTS`	только loopback-адреса	Список разрешённых значений `Host`, разделённых запятыми (защита от DNS rebinding). Если сервис работает за обратным прокси, укажите публичное имя хоста.
`OPS_BRAIN_DEV_NO_AUTH`	`false`	Разрешить HTTP-доступ без аутентификации. Только для разработки; не открывайте такой доступ за пределами localhost.
`OPS_BRAIN_MIGRATE`	`true`	Выполнять миграции при запуске
`OPS_BRAIN_EMBEDDINGS_ENABLED`	`true`	Значение `false` отключает эмбеддинги, даже если URL задан (в примере compose они отключены). Пустое значение считается не заданным.
`OPS_BRAIN_EMBEDDING_URL`	(не задано)	URL API эмбеддингов, совместимого с OpenAI, например `http://localhost:11434/v1/embeddings` для локального Ollama. Эмбеддинги отключены, пока не задано это значение; пустое значение считается не заданным.
`OPS_BRAIN_EMBEDDING_MODEL`	`nomic-embed-text`	Название модели эмбеддингов
`OPS_BRAIN_EMBEDDING_API_KEY`	(не задано)	Токен Bearer для API эмбеддингов, если он требуется

Технологический стек

Компонент	Решение
Язык	Rust 2021
MCP SDK	rmcp 1.6
База данных	PostgreSQL 18 через sqlx (запросы во время выполнения)
Поиск	Полнотекстовый поиск по tsvector и косинусный поиск pgvector HNSW с объединением результатов методом Reciprocal Rank Fusion
Эмбеддинги	`nomic-embed-text` (768d) через любой API, совместимый с OpenAI
Транспорт	stdio или потоковый HTTP на axum

Документация проекта

Документ	Содержание
`ROADMAP.md`	Философия проекта, жёсткие ограничения и идеи, от которых решили отказаться
`CHANGELOG.md`	История выпусков, в том числе причины удаления live lane в v6.0.0
`GOTCHAS.md`	Подводные камни в коде и развёртывании
`docs/agent-tokens.md`	Токены идентификации отдельных агентов и подключение нового агента
`docs/machine-callers.md`	Контракт для cron-задач, CI и скриптов, создающих передачи через REST
`docs/bus-trust.md`	Почему агенты проверяют передачи перед выполнением
`docs/operator-notify.md`	Отправка письма оператору, если агенту требуется помощь человека
`docs/clients.md`	Примеры подключения клиентов и статус проверки
`docs/self-hosting.md`	Файлы для частной настройки, HTTPS, резервное копирование и обновления
`docs/listings.md`	Список ресурсов, где упоминается ops-brain, и порядок обновления каждого из них

Лицензия

Двойное лицензирование: на ваш выбор MIT или Apache-2.0.