Security

🔵 How auth, isolation, secrets, and audit are structured in Agent OS.

15.1 Access configuration — summary table

All authentication/authorization and secrets in one place (details are in the referenced sections):

What it controls	Where it is set	Type	Section
Admin tokens (bearer)	`auth.admin_tokens` — `имя → токен` or `{token, templates}`	YAML	§15.2
Tokens from env	variable named in `auth.admin_token_env` (e.g. `AGENT_OS_ADMIN_TOKEN`), format `имя=токен`	env	§15.2
Web login passwords	`auth.users` — `логин → пароль` or `{password, templates}`	YAML	§15.2
Roles (scope by templates)	`templates: [...]` on a token/user	YAML	§15.3
LLM provider key	`provider.api_key` / `DEEPSEEK_API_KEY` / `AGENT_OS_API_KEY`	YAML/env	§15.4
End-user identity	`auth.web_user_secret_env` (HMAC)	env	§15.8
Incoming webhook token	`inbound.token_env`	env	§15.7
Workflow webhook token	`triggers.webhook.token_env`	env	§15.7
Cron/webhook sink tokens	`notify[].token_env`	env	§15.7
Telegram bot token	`telegram.token_env` (in `agent.yaml`)	env	§15.4
VK community token	`vk.token_env` (in `agent.yaml`)	env	§15.4
Yandex Messenger bot token	`yandex_messenger.token_env` (in `agent.yaml`)	env	§15.4
IMAP / SMTP password	`email.imap_password_env`, `smtp.password_env`	env	§15.4
Proxy host restriction	`proxy.allow_hosts`	YAML	§15.6
TLS (certificate/key)	`AGENT_OS_TLS_CERT` / `AGENT_OS_TLS_KEY`	env	§15.5
Action approval	`approval.required_tools` + `approval:` in `tool.yaml`	YAML	§15.10
Commands: membership and grants	`logging.team_db_path` + `teams.gated_tools` + OIDC groups	YAML	§45

General principle: secret values live only in .env; the YAML contains only the name of the env variable (token_env / password_env). The tokens and passwords themselves are never logged.

15.2 Admin API authentication

Protected endpoints (/v1/agents*, /v1/sessions*, /v1/budgets, /v1/cron, /v1/workflows*, /v1/dashboard, /v1/users*, /v1/memory*, …) accept either Authorization: Bearer <токен> (API clients) or the agentos_session cookie (browser after /login).

Bearer tokens — from auth.admin_tokens (the имя → токен map) or auth.admin_token_env (the имя=токен list separated by comma/;/newline).
Web login — from auth.users (логин → пароль); issues a HttpOnly cookie for 12 hours.

Failure behavior: if auth is configured but no credential is allowed — the admin API fails closed (401 for everything). With no tokens and no users — it is open (dev mode). Details — §8.3.

15.3 Role-based access (RBAC)

A token or web user can be restricted by templates — this is a scoped operator:

auth:
  admin_tokens:
    drom-op:
      token: "<token>"
      templates: [drom-agent]        # принципал видит только эти шаблоны
  users:
    drom-viewer:
      password: "<password>"
      templates: [drom-agent]

A full token (bare имя → токен) = full access. Workflows additionally declare their own templates — a scoped operator can run only those that are within their scope (§12.4).

Separately from operator RBAC there is command access for end users: membership in commands and grants for templates/tools/routes (without escalation). See §45 "Commands and access".

15.4 Handling secrets

Secrets — only in .env (API keys, token_env, password_env). YAML stores only the name of the environment variable, never the value itself.
Tokens are not logged: the access log records only the name of the token/user (or invalid), not the value.
.env in .gitignore; template — .env.example.

15.5 TLS / HTTPS

Set AGENT_OS_TLS_CERT and AGENT_OS_TLS_KEY (paths to PEM) — the server will come up with HTTPS. Otherwise — plain HTTP (for example behind a reverse proxy that terminates TLS).

15.6 Proxy SSRF protection

/proxy and /proxy/content block private, loopback, link-local, and reserved ranges (including 169.254.169.254) on every redirect. proxy.allow_hosts additionally restricts hosts (exact match or subdomain); empty = any public host. Only http/https, ports 80/443.

15.7 Webhook authentication

Incoming webhook POST /v1/inbound/:template — bearer token from inbound.token_env (empty = open, dev).
Workflow webhook POST /v1/workflows/:name/webhook — token from triggers.webhook.token_env; not set/empty → all requests are rejected.
Cron/webhook sinks — optional token_env for the bearer token.

15.8 Data isolation

Agents are isolated: one agent does not read another's context and does not spend its budget (the "concepts" section).
trace_tool returns only what is permitted to the caller: full access for the admin (admin_templates: "*"), limited — for a scoped admin, while an end-user's agent without an admin token gets the user scope from X-User-Id and sees only its own history (trace_tool).
Memory (memory) and state store are scoped to the user (user_id); without a user id — fallback to session → template → process.
Identity of end users is signed by HMAC by default (POST /v1/user-ticket, X-User-Token) — see §8.8.

15.9 Audit

Access log (logs/access.jsonl + logs/access.db) — every HTTP request: method, path, status, duration, IP, user-agent, X-User-Id, name of the admin token/user. Token values are not written.
Event store (logs/events.db) — audit of agent actions (tool calls, budgets, errors).
Canonical user registry (logs/users.db) — channel → id mapping.

15.10 Action approval (human-in-the-loop)

Sensitive actions (payment, charge, mailing, a change in CRM) can be gated by mandatory approval in the core — the agent cannot bypass it (including via prompt injection). Who decides is configured by approver: any | end_user | operator | admin; operator decisions are written to the audit with their name (ApprovalResolved in events.db). In detail — 23-approvals.md.