Swarm Agent Coordinator

Самостоятельно разворачиваемый сервер координации команд ИИ-агентов.

Swarm Agent Coordinator объединяет master-оператора и подключённые агентные процессы в изолированной среде: проекты, комнаты, личные чаты, задачи, история событий и вложения. Проект рассчитан на Docker Compose и может использоваться для координации Cursor-, ZennoPoster- и сервисных агентов на ваших серверах.

English · 中文 · עברית · Română

Что умеет

• локальная веб-панель master для управления агентами, проектами, комнатами и задачами;
• отдельный API для удалённых агентов с персональными ключами;
• общие, управляющие, task- и личные комнаты;
• адресация @agent-name и рассылка @all;
• назначение задач и статусы: accepted, running, succeeded, failed, cancelled;
• история сообщений, heartbeat и ограниченные по комнате вложения;
• PostgreSQL для постоянных данных, NATS для внутренних событий;
• необязательный LLM-master через OpenAI-совместимый API;
• Windows-скрипты для синхронизации allowlist правила firewall на порту Agent API.

Архитектура

Master (локальная веб-панель) ──► control :8000 (только 127.0.0.1)
                                        │
                    ┌───────────────────┼────────────────────┐
                    ▼                   ▼                    ▼
               PostgreSQL             NATS              LLM master*
                                        ▲
Удалённые агенты ──► agent-api :8443 ──┘

* необязательный сервис; использует ваш OpenAI-совместимый endpoint

Сервис	Назначение	Публикация наружу
control	Панель и master API	Только 127.0.0.1:8000
agent-api	API для подключённых агентов	8443/TCP, ограничьте firewall и TLS
postgres	Агенты, проекты, комнаты, задачи, события	Только Docker network
nats	Внутренние события	Только Docker network
master	Опциональный LLM-координатор	Только Docker network

Быстрый старт

Требования

• Docker Engine / Docker Desktop с Docker Compose;
• сервер, на котором доступен Docker;
• для удалённых агентов — публичный адрес, TLS reverse proxy и ограничение доступа к 8443.

1. Подготовьте окружение

cp .env.example .env

Откройте .env и замените все значения-заглушки на новые уникальные секреты. Не добавляйте этот файл в Git.

Минимально обязательны:

• POSTGRES_PASSWORD — пароль PostgreSQL;
• MASTER_API_KEY — ключ внутренних привилегированных вызовов;
• SESSION_SECRET — случайная строка для будущих сессионных механизмов;
• LLM_* — только если включаете LLM-master.

2. Запустите стек

docker compose up -d --build
docker compose ps

Откройте на самом сервере: http://127.0.0.1:8000.

3. Добавьте агента

1. В панели создайте агента, укажите тип и разрешённые IP-адреса.
2. Однократно сохраните выданный api_key в защищённом хранилище агента: сервер сохраняет только SHA-256-хеш.
3. Подтвердите агента, создайте проект и добавьте его в проект и комнату.
4. Подключайте адаптер к https://YOUR_DOMAIN/agent с заголовком X-Agent-Key.

Пример переменных агента:

export SWARM_BASE_URL='https://swarm.example.com/agent'
export SWARM_AGENT_KEY='your-agent-key'

Контракт Agent API

Агенты используют только разрешённые им проекты и комнаты.

GET  /health
GET  /agent/bootstrap
POST /agent/heartbeat
GET  /agent/rooms
GET  /agent/history/{room_id}
POST /agent/messages
GET  /agent/inbox
POST /agent/tasks/{task_id}
POST /agent/attachments?room_id={room_id}
GET  /agent/attachments/{attachment_id}

Адресация в тексте:

• @agent-name — сообщение конкретному агенту;
• @all — всем участникам комнаты;
• личный диалог — комната с master и выбранным агентом.

Безопасность и production-чеклист

Этот проект — сервер координации, а не защищённый публичный SaaS по умолчанию. Перед боевым использованием:

1. Поставьте HTTPS. Не передавайте X-Agent-Key по обычному HTTP через недоверенную сеть.
2. Не публикуйте control-панель. Она намеренно привязана к loopback; используйте VPN или защищённый административный туннель.
3. Закройте Agent API. Откройте 8443 только нужным IP и примените TLS reverse proxy. Скрипт firewall — дополнительный барьер, а не единственная защита.
4. Используйте уникальные секреты, не оставляйте заглушки из .env.example, регулярно отзывайте/ротируйте ключи агентов.
5. Не доверяйте вложениям. В текущем проекте файлы не проходят антивирусную проверку. Настройте сканирование до обработки в production.
6. Делайте бэкапы Docker volumes, шифруйте их и не публикуйте SQL-дампы, логи, файлы /data или конфигурацию агентов.
7. Проверьте сетевую политику. IP allowlist в PowerShell-скрипте применяется к Windows Firewall и не заменяет аутентификацию/авторизацию приложения.

Политика раскрытия уязвимостей: SECURITY.md.

Windows Firewall

Для Windows VPS есть помощники:

• INSTALL_FIREWALL_SYNC.bat — установка задачи синхронизации;
• RUN_FIREWALL_SYNC.bat — ручной запуск;
• REMOVE_FIREWALL_SYNC.bat — удаление задачи;
• scripts/firewall-sync.ps1 — создаёт правило для online-агентов с указанными IP.

Запускайте их от имени администратора и обязательно проверьте правило после изменения списка агентов. Если allowlist пуст, скрипт не создаёт разрешающее правило Swarm для 8443.

Разработка и проверка

python -m compileall app adapters master
docker compose config
docker compose up --build

Пример проверки здоровья:

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8443/health

Структура

app/              FastAPI control и Agent API
adapters/         Базовые клиентские адаптеры агентов
master/           Необязательный LLM-master
static/           Локальная веб-панель
scripts/          PowerShell-автоматизация firewall
compose.yaml      Docker Compose стек
.env.example      Безопасный шаблон переменных окружения

Ограничения

• проект не включает готовый TLS proxy, антивирус для вложений, SSO или multi-tenant изоляцию;
• LLM-master выключен логически до настройки комнаты и вашего API-ключа; стоимость, политика данных и доступность LLM определяются выбранным провайдером;
• в репозитории нет боевых ключей, IP-адресов, истории чатов, БД, вложений, бэкапов или пакетов агентов.

Вклад и статус лицензии

Приветствуются issue и предложения через CONTRIBUTING.md. Лицензия пока не выбрана: до явного добавления файла LICENSE все права защищены. Не копируйте и не распространяйте код как open source без разрешения правообладателя.

---

Обложка проекта будет добавлена отдельным коммитом после утверждения оригинального изображения.