Server configuration

🔵 The platform is configured by two files: config/server.yaml (core, provider, logging, auth, widget) and config/budgets.yaml (budget groups and template binding). Schedules are in config/cron.yaml, change monitoring is in config/monitors.yaml, workflows are in config/workflows/. Secrets are in .env (machine-local) or encrypted in config/secrets.yaml (see Config versioning).

3.1 Config source — local folder or git repository

The entire config tree (server.yaml, agents/, web/, workflows/, budgets.yaml, cron.yaml, monitors.yaml) is loaded from a single root. By default this is a local ./config; instead, a git repository can be cloned so that the config is versioned and reviewed separately from the binary.

Priority: CLI flag → environment variable → local ./config.

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

The repository is cloned into ~/.agent-os/configs/<repo>-<ref> onto a local branch (--config-ref), not into detached HEAD, so that the host can commit and push; the commit SHA is written to the log at startup and is visible on /health in the config field. The config poller does merge --ff-only/rebase — local commits (config versions) are not overwritten. Secrets can be stored in the config repository encrypted (config/secrets.yaml, see Config versioning); .env and env.overrides.yaml remain outside the repository.

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 (native). After failure_threshold consecutive errors the provider is marked "open" and is skipped in the failover chain — requests go to the next provider instead of hammering the failed one. After cooldown_secs the provider is probed with a single request (half-open): success closes the circuit, an error opens it again. The breaker key is the model-config name (default, strong, …). The mechanics are part of the core (agent_os_core::circuit_breaker). Here a global default is set; a specific agent can override it with the kind: circuit_breaker hook (see 06-hooks-routing §6.17). It is reset by the operator via Kernel::provider_breakers().reset(name).

Key selection order: provider.api_key → AGENT_OS_API_KEY → DEEPSEEK_API_KEY. Empty everywhere → agents respond with simulated answers.

models — named models

Additional model configs: each becomes a separate provider with its own base_url / api_key / model / pricing. An agent template selects the desired one via the model: field in its agent.yaml. provider: above is the default (it is also registered as "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 — scheduler and sessions

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 — logs and stores

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 — team access

Enabled by the presence of logging.team_db_path (see §45 "Teams and access"). The section selects which resources are gated by a team grant.

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

Access to agents and modular routes is not configured here: an agent — via an template grant (plus per-agent login), a route — via an Access::Team declaration.

sandbox — limits for processes on the host

Global policy for processes launched by tools, scripts (shell()/exec()) and the browser. Rootless limits: Unix — setrlimit (CPU/AS/NPROC/NOFILE/FSIZE) + a new session/process-group; Windows — Job Object (mem/procs/CPU, kill-on-close). FS confinement (read_roots/write_roots) — via Landlock (Linux) and path validation; tree-wide memory/CPU/pids — cgroup v2. The network is not restricted yet. Empty/enabled: false = disabled. 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

Backends (Linux): FS limits (read_roots/write_roots) are applied via Landlock (rootless, kernel ≥5.13) in file_tool and script fs_*; memory/CPU/pids limits — via cgroup v2 (tree-wide, including descendants) when cgroup_parent is set; network (allow_net: false) — via unshare(CLONE_NEWUSER | CLONE_NEWNET) (no routes). On Windows, resource limits are provided by the Job Object.

Observability. Sandbox denials are counted and logged; GET /metrics exposes agentos_sandbox_violations_total{kind="…"} (e.g. fs_read_denied, fs_write_denied).

cgroup v2 — deployment requirement. cgroup_parent must be delegated to the service (rootless model): the D directory with no processes, with D/cgroup.subtree_control enabled (the library enables those available from +memory +pids +cpu), owned by the service user, and the service itself running inside D/<child>. systemd example: Delegate=yes on the unit + sandbox.cgroup_parent: /sys/fs/cgroup/<slice>/<unit>.

auth — admin API and web login

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 — logins for the /login page: the value is a password as a string or an object { password | password_env, templates }. password_env names the environment variable with the password — this way real passwords don't end up in git; until the variable is set, the user is disabled. Without templates — full access. On /health and in the config for modules, passwords are always replaced with ***.
• admin_tokens — a map of имя → токен. The name is written to the access log (for auditing), the token itself is never logged. The value is either a bare token (full access), or an { token, templates } object restricting the principal to the listed patterns.
• admin_token_env (optional) — the name of an env variable whose value may be a comma-separated list / ; / newline-separated, each element an имя=токен or a bare token (the name is derived from the fingerprint). Such tokens are always full access. There is no predefined name: for the AGENT_OS_ADMIN_TOKEN variable to work, you must explicitly write admin_token_env: AGENT_OS_ADMIN_TOKEN. Note: as soon as the field is set, auth is considered enabled — if the variable is empty in that case, the admin API is closed (401).
• users — a map of логин → пароль for the /login page; issues a session cookie for the admin UI (/sessions, /budgets). The cookie is HttpOnly, lives 12 hours, the user name is written to the access log. The value is a bare password or { password, templates }.
• Empty maps + empty env = auth disabled (admin API open — dev only).
• Auth is configured, but no token/user resolves → the admin API fails closed (401).

web_user_secret_env — the name of the env variable with the HMAC secret for signing end-user identity tokens (POST /v1/user-ticket). If empty, the server generates and stores the secret itself in data/web_user_secret — identity is signed with HMAC by default. Details — in 08-http-api.

Admin endpoints accept either Authorization: Bearer <токен> or the cookie agentos_session.

The same sources (auth.users and auth.oidc) also serve end-user login in the widget: an agent may require authorization via login.required: true (providers — OIDC, allow_users — login/password from auth.users). See 04-building-an-agent and 19-widget-and-channels.

auth.oidc — login via Google / Yandex / Tinkoff

In addition to passwords (auth.users), the admin UI can log in via external identity providers (OIDC / OAuth 2.0, Authorization Code + PKCE). A role is granted by grants based on the external identity — subject (exact provider:sub), email or email_domain (suffix). The first match wins; no match = login rejected (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 — the public origin for constructing redirect_uri. Empty (default) = derived from the request: Host (or X-Forwarded-Host) + the scheme from X-Forwarded-Proto (behind a TLS-terminating proxy — https). An explicit value overrides auto-derivation and must exactly match the one registered in provider redirect_uri (mandatory for connectors).
• Secrets (client_secret_env) — via env only, never inline.
• Redirect URI (register with the provider): {origin}/login/oidc/{provider}/callback (admin) and {origin}/v1/login/widget/{provider}/callback (widget).
• A provider without client_id is ignored.
• These providers are available to the end user in the widget (GET /v1/login/widget/:provider) — including for mandatory login login.required for the agent template (§19.1).

connectors — access to external APIs on behalf of the user

The agent can act in third-party services (Google Drive, Yandex.Disk, etc.) on behalf of the end user. The connector reuses the OIDC client from auth.oidc.providers and requests its own scopes. Tokens are stored per-user in logging.connector_db_path, encrypted with AES-256-GCM (key from auth.connector_encryption_key_env or auto-secret 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"]

Tools (kind: oauth_connect / kind: connector_request) are connected in agent.yaml via tool_files — see 05-tools-reference. Redirect URI for connectors: {base_url}/v1/connectors/callback.

widget — embeddable widget

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

The only server-side setting is default_model: the agent the widget contacts when the model is not explicitly specified. Full breakdown of the widget (embedding, model selection order, demo, visual blocks) — in §19.

proxy — HTTP proxy restrictions

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

/proxy and /proxy/content always block private, loopback, link-local, and reserved ranges (including 169.254.169.254) on every redirect. allow_hosts additionally restricts by host (exact match or subdomain).

inbound — incoming webhook

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

POST /v1/inbound/:template — external systems trigger a single agent turn synchronously. See 08-http-api.

approval — action 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 — gates globally by tool name, without editing the YAML of each tool. Per-tool configuration (severity / approver / timeout / context) — in the approval: section of the tool itself. Full description and examples — 23-approvals.md.

modules — modules and native plugins

The platform is modular: features (workflow, cron, channels, docs, widget, approvals, …) and native extensions are connected as modules — linked crates or DLLs.

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

• enabled — list of module ids to activate; dependencies (requires) are pulled in transitively, always-on modules (kernel, web) are enabled implicitly, unknown ids are ignored. Empty — the built-in default set.
• enabled ≠ installed: the list is only "what to activate"; installing artifacts (network) — a separate action, auto_install — an option to install additionally at startup.
• Native DLLs are loaded separately — from config/plugins.yaml; a separate tool/hook can be connected via kind: dll_tool / kind: dll_hook.

See 20-native-plugins and 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

• Groups are created immediately at startup (not lazily) and are visible at /budgets.
• agents: binds a template (by name) to a group and/or overrides its budget.
• Overrides from budgets.yaml win over values from agent.yaml.
• Checked on every entry into a turn, top-down: group → per_user → per_session. An exhausted level is shown with a message from budget_messages.* of the agent.

Budget fields

warn_at can be set at each layer (группа / per_user / per_session), and the hook is called for the layer whose threshold was crossed (level = group / user / session).

3.4 Scheduled jobs (config/cron.yaml)

Cron runs an agent template on a schedule. They are defined in two places, both hot-reloaded:

• per agent — the list of cron: in config/agents/<agent>/agent.yaml (template defaults to the agent itself);
• globally — config/cron.yaml, where each job explicitly names template:

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

Each job specifies exactly one of schedule / interval_secs / oneshot_at and delivers the result to a list of notify sinks (log, webhook, telegram, vk, yandex_messenger, messages_db, agent, email, workflow). History — in logs/cron.db, endpoint GET /v1/cron. Full reference — 11-cron-jobs.

3.5 Change monitors (config/monitors.yaml)

A monitor is a pull trigger: it watches an external source and starts an agent turn only when new items appear (unlike cron, which fires on a schedule regardless). Full description — Monitors.

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

The monitor stores a cursor in logs/monitors.db: the first poll only "catches up" (saves the cursor, starts nothing), after that it starts only on items newer than the cursor.

3.6 Environment variables

.env is picked up automatically at startup (dotenv). It is in .gitignore, the template is .env.example.

3.7 Live reload

With kernel.live_reload: true (default), the server watches config/ and applies changes without a restart:

• config/agents/** — new sessions get the new instructions; tools, hooks, and routes (route_files) are re-registered and take effect from the next call. Removed tool/hook files are unregistered. A broken agent.yaml does not bring down the rest: the set of templates, tools, and routes is preserved as before.
• config/web/** — the site is re-rendered; added and removed pages are picked up immediately (see §13).
• config/routes/**, config/hooks/**, config/workflows/**, config/cron.yaml, config/budgets.yaml — are re-registered; removed elements are unregistered (budget groups get a new id, live processes are rebound on the next launch).
• config/server.yaml — is not applied on the fly; a restart is required.

If the config comes from a git repository, with --config-poll / AGENT_OS_CONFIG_POLL the same path is applied after each new commit; an unchanged SHA is skipped.

3.8 HTTP request logging

Every HTTP request (method, path, status, duration, client IP, user-agent, X-User-Id, admin token name) is written to logs/access.jsonl and logs/access.db (both are disabled by an empty string in the corresponding logging field). The token value is not logged — only its name or the invalid marker.

3.9 ONNX service (security.onnx)

Local ONNX Runtime for NER / classification / embeddings. Requires building the server with the onnx feature. The ONNX Runtime core is not linked or shipped: it is loaded dynamically (load-dynamic) and resolved/downloaded on first use by the runtime block. Models are loaded lazily and downloaded on first use (pinned revision) unless 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

Admin endpoints: GET /v1/onnx/models, GET /v1/onnx/metrics, GET /v1/onnx/runtime.

The langid model (mini-BERT, ~25 MB int8, 200 languages) is registered by default and is used by the language_guard hook with detector: onnx (06 §6.18). If the service or model is unavailable, the hook is neutral.