Конфигурация сервера

🔵 Платформу настраивают два файла: config/server.yaml (ядро, провайдер, логирование, auth, виджет) и config/budgets.yaml (бюджетные группы и привязка шаблонов). Расписания — в config/cron.yaml, слежение за изменениями — в config/monitors.yaml, воркфлоу — в config/workflows/. Секреты — в .env (машинно-локальные) либо зашифрованными в config/secrets.yaml (см. Версионирование конфигов).

3.1 Источник конфига — локальная папка или git-репозиторий

Всё дерево конфига (server.yaml, agents/, web/, workflows/, budgets.yaml, cron.yaml, monitors.yaml) грузится из одного корня. По умолчанию это локальная ./config; вместо неё можно клонировать git-репозиторий, чтобы конфиг версионировался и ревьюировался отдельно от бинарника.

Приоритет: CLI-флаг → переменная окружения → локальный ./config.

AGENT_OS_CONFIG_REPO=https://github.com/org/agent-config \
AGENT_OS_CONFIG_REF=v1.2.0 \
./agent-os serve

Репозиторий клонируется в ~/.agent-os/configs/<repo>-<ref> на локальную ветку (--config-ref), а не в detached HEAD, чтобы хост мог коммитить и пушить; SHA коммита пишется в лог при старте и виден на /health в поле config. Поллер конфига делает merge --ff-only/rebase — локальные коммиты (версии конфига) не затираются. Секреты можно хранить в конфиг-репозитории зашифрованными (config/secrets.yaml, см. Версионирование конфигов); .env и env.overrides.yaml остаются вне репозитория.

3.2 config/server.yaml

provider — LLM

provider:
  base_url: "https://api.deepseek.com"   # любой OpenAI-совместимый endpoint
  model: "deepseek-v4-flash"
  api_key: ""                            # опционально; предпочтительно .env
  pricing:                               # оценка стоимости инференса
    prompt_per_million: 0.14
    cached_per_million: 0.014
    completion_per_million: 0.28
  fallbacks: ["strong"]                  # цепочка failover при сбое провайдера
  circuit_breaker:                       # пропускать упавший провайдер
    failure_threshold: 5                 # подряд ошибок до размыкания (0 = выкл.)
    cooldown_secs: 30                    # пауза до пробного запроса
    half_open_max: 1                     # успешных проб для замыкания

Circuit breaker (нативный). После failure_threshold ошибок подряд провайдер помечается «open» и пропускается в цепочке failover — запросы идут на следующий провайдер, а не долбятся в упавший. Через cooldown_secs провайдер пробуется одним запросом (half-open): успех замыкает цепь, ошибка снова размыкает. Ключ брейкера — имя model-config (default, strong, …). Механика — часть ядра (agent_os_core::circuit_breaker). Здесь задаётся глобальный дефолт; конкретный агент может переопределить его хуком kind: circuit_breaker (см. 06-hooks-routing §6.17). Сбрасывается оператором через Kernel::provider_breakers().reset(name).

Порядок выбора ключа: provider.api_key → AGENT_OS_API_KEY → DEEPSEEK_API_KEY. Пусто везде → агенты отвечают симулированными ответами.

models — именованные модели

Дополнительные конфиги моделей: каждый становится отдельным провайдером со своим base_url / api_key / model / pricing. Шаблон агента выбирает нужную полем model: в своём agent.yaml. provider: выше — это дефолт (он же регистрируется как "default").

models:
  cheap:
    base_url: "https://api.deepseek.com"
    model: "deepseek-chat"
  strong:
    base_url: "https://api.openai.com/v1"
    model: "gpt-4o"
    api_key: ""

kernel — планировщик и сессии

kernel:
  scheduler: round_robin
  concurrency_limit: 3
  time_slice_secs: 30
  live_reload: true
  session_ttl_secs: 300
  session_cleanup_interval_secs: 60
  max_output_tokens: 4096

logging — логи и хранилища

logging:
  filter: "agent_os=debug"
  jsonl_dir: "logs"
  duckdb_path: "logs/events.db"
  messages_db_path: "logs/messages.db"
  messages_retention_days: 30
  state_db_path: "logs/state.db"
  temp_dir: "logs/temp"
  access_db_path: "logs/access.db"
  cron_db_path: "logs/cron.db"
  user_db_path: "logs/users.db"
  team_db_path: "logs/teams.db"
  monitor_db_path: "logs/monitors.db"
  workflow_db_path: "logs/workflows.db"
  bench_db_path: "logs/bench.db"
  side_effect_db_path: ""            # пусто = идемпотентность выключена
  outbox_db_path: ""                 # пусто = outbox/саги выключены
  dead_letter_db_path: ""            # пусто = dead-letter только в памяти
  durable_db_path: ""                # пусто = durability (durable-агенты) выключена
  pending_db_path: ""                # пусто = pending (approvals/ввод/await_event) только в памяти

teams — командный доступ

Включается наличием logging.team_db_path (см. §45 «Команды и доступ»). Секция выбирает, какие ресурсы гейтятся грантом команды.

teams:
  gated_tools: ["gdrive_upload", "notion_write"]   # только по гранту команды

Доступ к агентам и модульным роутам конфигурируется не здесь: агент — грантом template (плюс per-agent login), роут — объявлением Access::Team.

sandbox — лимиты для процессов на хосте

Глобальная политика для процессов, которые запускают инструменты, скрипты (shell()/exec()) и браузер. Rootless-лимиты: Unix — setrlimit (CPU/AS/NPROC/NOFILE/FSIZE) + новая сессия/process-group; Windows — Job Object (mem/procs/CPU, kill-on-close). ФС-конфайнмент (read_roots/write_roots) — через Landlock (Linux) и проверку путей; tree-wide память/CPU/pids — cgroup v2. Сеть пока не ограничивается. Пусто/enabled: false = выключено. Per-agent override — agent.yaml → sandbox:.

sandbox:
  enabled: true
  cpu_secs: 30          # лимит CPU-времени
  mem_mb: 512           # адресное пространство / память процесса
  max_procs: 64         # число процессов
  max_fds: 256          # открытых файловых дескрипторов
  max_file_mb: 64       # размер создаваемого файла (Unix RLIMIT_FSIZE)
  read_roots: []        # allowlist чтения (пусто = без ограничений); file_tool, fs_read/fs_list
  write_roots: []       # allowlist записи (пусто = без ограничений); file_tool, fs_write
  cgroup_parent: ""     # cgroup v2 для лимитов (Linux); пусто = cgroups выкл
  cpu_quota_percent: null  # доля одного ядра (cgroup cpu.max), напр. 50 = 0.5 ядра
  allow_net: true       # false = процесс в изолированном netns (Linux, без сети)
  clear_env: true       # очистить окружение
  env_allow: [PATH, LANG, HOME]   # что оставить при clear_env

Бэкенды (Linux): лимиты ФС (read_roots/write_roots) применяются через Landlock (rootless, ядро ≥5.13) в file_tool и скриптовых fs_*; лимиты памяти/CPU/pids — через cgroup v2 (tree-wide, включая потомков) когда задан cgroup_parent; сеть (allow_net: false) — через unshare(CLONE_NEWUSER | CLONE_NEWNET) (нет маршрутов). На Windows лимиты ресурсов даёт Job Object.

Наблюдаемость. Отказы песочницы считаются и логируются; GET /metrics отдаёт agentos_sandbox_violations_total{kind="…"} (например fs_read_denied, fs_write_denied).

cgroup v2 — требование к деплою. cgroup_parent должен быть делегирован сервису (rootless-модель): каталог D без процессов, с включёнными D/cgroup.subtree_control (библиотека включает доступные из +memory +pids +cpu), принадлежащий пользователю сервиса, и сам сервис запущен внутри D/<child>. Пример systemd: Delegate=yes на юните + sandbox.cgroup_parent: /sys/fs/cgroup/<slice>/<unit>.

auth — админ-API и web-логин

auth:
  admin_token_env: ""              # имя env-переменной с токенами (опционально)
  admin_tokens:                    # карта имя → токен (или { token, templates })
    admin: "<token>"
    drom-op:
      token: "<token>"
      templates: [drom-agent]
  users:                           # web-логин: логин → пароль (или { password | password_env, templates })
    admin:
      password_env: AGENT_OS_ADMIN_PASSWORD   # пароль из env, а не из git
    drom-viewer:
      password: "<password>"
      templates: [drom-agent]
  web_user_secret_env: ""          # env с HMAC-секретом для токенов конечных пользователей

• users — логины для страницы /login: значение — пароль строкой или объект { password | password_env, templates }. password_env называет переменную окружения с паролем — так реальные пароли не попадают в git; пока переменная не задана, пользователь отключён. Без templates — полный доступ. На /health и в конфиге для модулей пароли всегда заменены на ***.
• admin_tokens — карта имя → токен. Имя пишется в access-лог (для аудита), сам токен никогда не логируется. Значение — либо голый токен (полный доступ), либо объект { token, templates }, ограничивающий принципала перечисленными шаблонами.
• admin_token_env (опционально) — имя env-переменной, чьё значение может быть списком через запятую / ; / перевод строки, каждый элемент имя=токен либо голый токен (имя выводится из отпечатка). Такие токены — всегда полный доступ. Предопределённого имени нет: чтобы заработала переменная AGENT_OS_ADMIN_TOKEN, нужно явно написать admin_token_env: AGENT_OS_ADMIN_TOKEN. Внимание: как только поле задано, auth считается включённым — если переменная при этом пуста, админ-API закрывается (401).
• users — карта логин → пароль для страницы /login; выдаёт session-cookie для админ-UI (/sessions, /budgets). Cookie HttpOnly, живёт 12 часов, имя пользователя пишется в access-лог. Значение — голый пароль или { password, templates }.
• Пустые карты + пустой env = auth выключен (админ-API открыт — только для dev).
• Auth настроен, но ни один токен/пользователь не разрешается → админ-API fails closed (401).

web_user_secret_env — имя env-переменной с HMAC-секретом для подписи токенов идентичности конечных пользователей (POST /v1/user-ticket). Если пусто, сервер сам генерирует и хранит секрет в data/web_user_secret — идентичность подписывается HMAC по умолчанию. Подробности — в 08-http-api.

Админ-эндпоинты принимают либо Authorization: Bearer <токен>, либо cookie agentos_session.

Те же источники (auth.users и auth.oidc) обслуживают и вход конечного пользователя в виджете: агент может требовать авторизацию через login.required: true (providers — OIDC, allow_users — логин/пароль из auth.users). См. 04-building-an-agent и 19-widget-and-channels.

auth.oidc — вход через Google / Яндекс / Тинькофф

Дополнительно к паролям (auth.users) админ-UI может логинить через внешние identity-провайдеры (OIDC / OAuth 2.0, Authorization Code + PKCE). Роль даётся грантами по внешней личности — subject (точный provider:sub), email или email_domain (суффикс). Первое совпадение выигрывает; нет совпадения = вход отклонён (fail-closed).

auth:
  oidc:
    base_url: ""                         # пусто = авто-вывод из запроса (Host + X-Forwarded-Proto)
    providers:
      google:
        issuer: "https://accounts.google.com"   # discovery
        client_id: "<client id>"
        client_secret_env: "GOOGLE_OIDC_CLIENT_SECRET"
      yandex:                                   # discovery нет — явные endpoints
        authorization_endpoint: "https://oauth.yandex.ru/authorize"
        token_endpoint: "https://oauth.yandex.ru/token"
        userinfo_endpoint: "https://login.yandex.ru/info?format=json"
        client_id: "<client id>"
        client_secret_env: "YANDEX_OIDC_CLIENT_SECRET"
        scopes: ["login:email", "login:info"]
        userinfo_sub_field: "id"
        userinfo_email_field: "default_email"
      tinkoff:
        issuer: "https://id.tinkoff.ru/auth/realms/tinkoff"
        client_id: "<client id>"
        client_secret_env: "TINKOFF_OIDC_CLIENT_SECRET"
    grants:
      - email_domain: "example.com"
        role: "admin"                        # полный доступ
      - email: "ops@example.com"
        templates: [drom-agent]              # оператор: только эти шаблоны

• base_url — публичный origin для построения redirect_uri. Пусто (по умолч.) = вывод из запроса: Host (или X-Forwarded-Host) + схема из X-Forwarded-Proto (за TLS-терминирующим прокси — https). Явное значение переопределяет авто-вывод и должно точно совпадать с зарегистрированным в провайдере redirect_uri (для коннекторов — обязательно).
• Секреты (client_secret_env) — только через env, никогда не инлайнить.
• Redirect URI (зарегистрировать у провайдера): {origin}/login/oidc/{provider}/callback (админ) и {origin}/v1/login/widget/{provider}/callback (виджет).
• Провайдер без client_id игнорируется.
• Эти провайдеры доступны конечному пользователю в виджете (GET /v1/login/widget/:provider) — в том числе для обязательного входа login.required у шаблона агента (§19.1).

connectors — доступ к внешним API от имени пользователя

Агент может действовать в сторонних сервисах (Google Drive, Яндекс.Диск и т.п.) от имени конечного пользователя. Коннектор переиспользует OIDC-клиента из auth.oidc.providers и запрашивает собственные scope. Токены хранятся per-user в logging.connector_db_path, зашифрованные AES-256-GCM (ключ из auth.connector_encryption_key_env или авто-секрет data/connector_secret).

connectors:
  gdrive:
    provider: google
    scopes: ["https://www.googleapis.com/auth/drive.file"]
  yandex_disk:
    provider: yandex
    scopes: ["cloud_api:disk.app_folder"]

Инструменты (kind: oauth_connect / kind: connector_request) подключаются в agent.yaml через tool_files — см. 05-tools-reference. Redirect URI коннекторов: {base_url}/v1/connectors/callback.

widget — встраиваемый виджет

widget:
  default_model: "drom-agent"   # агент по умолчанию

Единственная серверная настройка — default_model: агент, к которому виджет обращается, когда модель не задана явно. Полный разбор виджета (встраивание, порядок выбора модели, демо, визуальные блоки) — в §19.

proxy — ограничения HTTP-прокси

proxy:
  allow_hosts: []   # пусто = любой публичный хост

/proxy и /proxy/content всегда блокируют приватные, loopback, link-local и reserved-диапазоны (включая 169.254.169.254) на каждом редиректе. allow_hosts дополнительно ограничивает по хосту (точное совпадение или поддомен).

inbound — входящий webhook

inbound:
  token_env: ""   # env с bearer-токеном для POST /v1/inbound/:template (пусто = открыто, dev)

POST /v1/inbound/:template — внешние системы запускают один ход агента синхронно. См. 08-http-api.

approval — одобрение действий (human-in-the-loop)

approval:
  required_tools: ["refund", "send_email", "delete_*"]  # glob-паттерны тулов, требующих одобрения
  operator_notify:              # доставка операторских запросов в мессенджер/webhook
    - type: telegram
      chat_id: -100123456789
      token_env: TG_OPERATOR_TOKEN
    - type: webhook
      url: https://ops.example.com/approvals
  context_template: |           # необязательный MiniJinja-шаблон контекста
    📝 {{ user_request }}
    {% for m in messages %}{{ m.role }}: {{ m.content }}{% endfor %}

• required_tools — гейтит по имени тула глобально, не правя YAML каждого тула. Поштучная настройка (severity / approver / timeout / контекст) — в approval: секции самого инструмента. Полное описание и примеры — 23-approvals.md.

modules — модули и нативные плагины

Платформа модульная: фичи (workflow, cron, каналы, docs, widget, approvals, …) и нативные расширения подключаются как модули — linked-крейты или DLL.

modules:
  enabled: [docs, widget, analytics]  # активировать на буте (+ requires транзитивно)
  auto_install: false                  # не ходить в сеть за артефактами на старте

• enabled — список id модулей для активации; зависимости (requires) дотягиваются транзитивно, always-on модули (kernel, web) включены неявно, неизвестные id игнорируются. Пусто — встроенный набор по умолчанию.
• enabled ≠ installed: список лишь «что активировать»; установка артефактов (сеть) — отдельное действие, auto_install — опция доустановки на старте.
• Нативные DLL грузятся отдельно — из config/plugins.yaml; отдельный инструмент/хук можно подключить через kind: dll_tool / kind: dll_hook.

См. 20-native-plugins и 32-building-a-module.

3.3 config/budgets.yaml

budget_groups:
  - name: my-shared
    refill_per_sec: 50
    max_bucket: 50000
    max_total: 5000000        # null/отсутствует = без лимита
    warn_at: 0.8              # порог on_budget_threshold для группы
    per_user:                 # опционально
      refill_per_sec: 20
      max_bucket: 20000
      max_total: 500000
      warn_at: 0.8            # порог on_budget_threshold для per_user
    per_session:              # опционально
      refill_per_sec: 30
      max_bucket: 10000
      max_total: 200000

agents:
  - template: my-agent        # перекрывает budget_group / budget из agent.yaml
    group: my-shared
    budget:                   # опционально
      refill_per_sec: 10
      max_bucket: 200
      max_total: 1000

• Группы создаются сразу при старте (не лениво) и видны на /budgets.
• agents: привязывает шаблон (по name) к группе и/или перекрывает его бюджет.
• Перекрытия из budgets.yaml выигрывают у значений из agent.yaml.
• Проверяются при каждом входе в тёрн сверху вниз: группа → per_user → per_session. Исчерпанный уровень показывается сообщением из budget_messages.* агента.

Поля бюджета

warn_at можно задать на каждом слое (группа / per_user / per_session), и хук вызывается для того слоя, чей порог пересёкся (level = group / user / session).

3.4 Запланированные задания (config/cron.yaml)

Cron запускает шаблон агента по расписанию. Задаются в двух местах, оба hot-reload'ятся:

• на агента — список cron: в config/agents/<agent>/agent.yaml (template по умолчанию = сам агент);
• глобально — config/cron.yaml, где каждое задание явно называет template:

jobs:
  - name: morning-digest
    template: rss
    schedule: "0 0 9 * * *"      # sec min hour dom month dow (UTC)
    prompt: "Резюмируй сегодняшние новости."
    notify: [{ type: log }]

Каждое задание задаёт ровно одно из schedule / interval_secs / oneshot_at и доставляет результат в список notify-sink'ов (log, webhook, telegram, vk, yandex_messenger, messages_db, agent, email, workflow). История — в logs/cron.db, эндпоинт GET /v1/cron. Полный справочник — 11-cron-jobs.

3.5 Change-мониторы (config/monitors.yaml)

Монитор — это pull-триггер: следит за внешним источником и запускает ход агента только при появлении новых элементов (в отличие от cron, который стреляет по расписанию независимо). Полное описание — Мониторы.

monitors:
  - name: news-watch
    source:
      type: rss
      url: "https://lenta.ru/rss"
    template: rss-agent
    prompt: "Кратко резюмируй эти новые статьи:\n{{items}}"
    notify: [{ type: telegram, chat_id: 123456 }]
    poll_secs: 300

Монитор хранит курсор в logs/monitors.db: первый опрос только «догоняет» (сохраняет курсор, ничего не запускает), дальше запускается только на элементах новее курсора.

3.6 Переменные окружения

.env подхватывается автоматически при старте (dotenv). Он в .gitignore, шаблон — .env.example.

3.7 Live reload

При kernel.live_reload: true (по умолчанию) сервер следит за config/ и применяет изменения без рестарта:

• config/agents/** — новые сессии получают новые инструкции; инструменты, хуки и маршруты (route_files) перерегистрируются и действуют со следующего вызова. Удалённые tool/hook-файлы снимаются с регистрации. Битый agent.yaml не роняет остальные: набор шаблонов, инструментов и маршрутов сохраняется прежним.
• config/web/** — сайт перерендеривается; добавленные и удалённые страницы подхватываются сразу (см. §13).
• config/routes/**, config/hooks/**, config/workflows/**, config/cron.yaml, config/budgets.yaml — перерегистрируются; удалённые элементы снимаются (у бюджет-групп меняется id, живые процессы перепривязываются при следующем запуске).
• config/server.yaml — не применяется на лету; нужен рестарт.

Если конфиг приходит из git-репозитория, при --config-poll / AGENT_OS_CONFIG_POLL тот же путь применяется после каждого нового коммита; неизменённый SHA пропускается.

3.8 Логирование HTTP-запросов

Каждый HTTP-запрос (метод, путь, статус, длительность, IP клиента, user-agent, X-User-Id, имя админ-токена) пишется в logs/access.jsonl и logs/access.db (оба отключаются пустой строкой в соответствующем поле logging). Значение токена не логируется — только его имя или пометка invalid.

3.9 ONNX-сервис (security.onnx)

Локальный ONNX Runtime для NER / классификации / эмбеддингов. Требует сборки сервера с фичей onnx. Ядро ONNX Runtime не линкуется и не шипится: загружается динамически (load-dynamic) и резолвится/скачивается при первом использовании блоком runtime. Модели грузятся лениво и скачиваются при первом использовании (закреплённая ревизия), если не download: never / offline: true.

security:
  onnx:
    models_dir: data/models
    download: auto            # auto | eager | never
    offline: false
    allow_hosts: []           # пусто = встроенные хосты HF (+ GitHub для runtime)
    runtime:                  # динамически загружаемое ядро ONNX Runtime
      # lib_path: /opt/onnxruntime/lib/libonnxruntime.so  # явный путь (без скачивания)
      version: "1.28.0"       # должно соответствовать ort (rc.13 → 1.28)
      variant: cpu            # cpu | gpu | cuda12 | cuda13 | directml
      # base_url: https://github.com/microsoft/onnxruntime/releases/download/v1.28.0
      # sha256: "..."
    models:
      - id: langid            # используется хуком language_guard (detector: onnx)
        task: text_classification
        # templates: [ngu-agent]        # per-agent селектор (необязательно)
        source:
          hf: { repo: onnx-community/language_detection-ONNX, revision: <commit>, path: onnx/model_quantized.onnx }
        tokenizer: tokenizer.json
        config: config.json

Админ-эндпоинты: GET /v1/onnx/models, GET /v1/onnx/metrics, GET /v1/onnx/runtime.

Модель langid (мини-BERT, ~25 МБ int8, 200 языков) зарегистрирована по умолчанию и используется хуком language_guard с detector: onnx (06 §6.18). Если сервис или модель недоступны, хук нейтрален.