Песочница всерьёз: каталоги, сеть, профили прав

В курсе «Codex с нуля» вы познакомились с двумя осями безопасности: песочница (sandbox) задаёт, что технически можно, а политика одобрений — когда агент останавливается и спрашивает (урок «Песочница и одобрения»). Режима workspace-write хватает для учебного репозитория. В рабочем проекте быстро выясняется, что агенту нужен соседний каталог, доступ к Packagist и npm, а вот .env с ключами CRM ему читать незачем. Этот урок — о точной настройке границ.

Что на самом деле разрешает workspace-write

В режиме workspace-write агент читает файлы, правит их внутри рабочей области и запускает команды. Рабочая область — текущий каталог плюс временные ($TMPDIR, /tmp). Точный список покажет /status. Песочница распространяется на все порождённые процессы: composer, npm, phpunit, Playwright работают в тех же границах.

Внутри рабочей области есть защищённые пути, которые остаются только для чтения: .git (включая настоящий каталог git, если .git — файл-указатель, как в worktree), .agents, .codex и .aws. Поэтому git commit часто требует одобрения: запись в .git — выход за границу. Это не ошибка, а защита истории и конфигурации агента от него самого.

Дополнительные каталоги на запись

Типичная ситуация: сайт и общая библиотека компонентов лежат в соседних репозиториях. Не нужно переходить на полный доступ — добавьте каталог:

codex --add-dir ../shared-components

Флаг можно повторять. Чтобы не набирать его каждый раз:

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
writable_roots = ["/Users/me/work/shared-components"]
exclude_tmpdir_env_var = false   # true — убрать $TMPDIR из рабочей области
exclude_slash_tmp = false        # true — убрать /tmp

Документация прямо рекомендует --add-dir вместо danger-full-access, когда нужен ещё один каталог.

Сеть: выключена, включена или по списку

В workspace-write сеть для команд по умолчанию выключена. Включить её целиком:

[sandbox_workspace_write]
network_access = true

Но «целиком» — это и Packagist, и любой адрес, который агент вычитал из подозрительного README. Аккуратнее включить сетевой прокси (экспериментальная функция network_proxy) и разрешить только нужные домены:

[sandbox_workspace_write]
network_access = true

[features.network_proxy]
enabled = true
domains = { "repo.packagist.org" = "allow", "registry.npmjs.org" = "allow", "*.github.com" = "allow", "objects.githubusercontent.com" = "allow" }

Как сочетаются две настройки:

• сеть выключена — прокси ни на что не влияет, сети нет;
• сеть включена, прокси выключен — прямой доступ куда угодно;
• сеть включена, прокси включён — трафик идёт через прокси, и он пропускает только разрешённые домены.

Правила доменов: точное имя совпадает только с собой; *.example.com — поддомены без самого домена; **.example.com — домен и поддомены; * — всё (только для allow). deny всегда сильнее allow.

По умолчанию прокси блокирует локальные и частные адреса — это защита от DNS rebinding. Если e2e-тестам нужен ваш локальный стенд, разрешите точное имя: "localhost" = "allow" или "127.0.0.1" = "allow". Шаблоны вроде * локальные адреса не открывают.

Важная граница: прокси фильтрует только команды из песочницы. Веб-поиск, MCP-серверы, коннекторы, встроенный браузер и Computer Use ходят в сеть своими путями и настраиваются отдельно — например, веб-поиск ключом web_search, MCP — в уроке про MCP.

Профили прав (beta)

Старая схема — sandbox_mode плюс [sandbox_workspace_write] — описывает три режима и пару исключений. В 2026 году появились профили прав (permission profiles): именованные политики, где файлы и сеть описаны вместе и с точностью до пути. Функция в статусе beta, синтаксис может меняться.

Встроенные профили: :read-only, :workspace и :danger-full-access. Свой профиль лучше строить от встроенного — тогда защита .git, .agents, .codex и .aws сохраняется:

default_permissions = "site-dev"

[features]
network_proxy = true               # без этого правила доменов не применяются

[permissions.site-dev]
description = "Сайт на OctoberCMS: правки в репозитории, без .env, сеть по списку"
extends = ":workspace"

[permissions.site-dev.workspace_roots]
"~/work/shared-components" = true

[permissions.site-dev.filesystem]
glob_scan_max_depth = 4

[permissions.site-dev.filesystem.":workspace_roots"]
"**/*.env" = "deny"
"storage/app/uploads" = "read"

[permissions.site-dev.network]
enabled = true

[permissions.site-dev.network.domains]
"repo.packagist.org" = "allow"
"registry.npmjs.org" = "allow"
"localhost" = "allow"

Что здесь происходит:

• extends = ":workspace" — базой служит обычный режим рабочей области.
• workspace_roots добавляет соседний репозиторий, и к нему применяются те же правила, что к основному.
• Под ":workspace_roots" пути считаются относительно каждого корня: все .env закрыты на чтение, загрузки пользователей — только чтение.
• glob_scan_max_depth ограничивает глубину раскрытия ** перед стартом песочницы на Linux, WSL и Windows; без него неограниченный шаблон может не сработать как ожидается.
• network.enabled = true разрешает сеть, а features.network_proxy = true заставляет соблюдать список доменов. Без второго ключа сеть будет открыта целиком.

Доступы — read, write, deny. Более конкретный путь сильнее общего; на одном пути deny сильнее write, а write сильнее read. Кроме :workspace_roots есть специальные пути :minimal (системные каталоги, без которых не работают инструменты), :root, :tmpdir, :slash_tmp, а также абсолютные и ~/....

Одна тонкость с запретами по шаблону: на Linux, WSL и Windows совпадения ищутся при старте каждого процесса в песочнице. Если долго работающий процесс — dev-сервер, watcher — уже запущен, а .env создан после, этот процесс его прочитает. Не полагайтесь на шаблон для файлов, которые появляются по ходу работы.

Две схемы не смешиваются

Профили прав и старые настройки не комбинируются. Если sandbox_mode есть в любом загруженном конфиге, в выбранном профиле конфигурации или вы передали --sandbox, Codex использует старую схему и игнорирует default_permissions. Переходя на профили, уберите sandbox_mode и [sandbox_workspace_write] отовсюду. Переключать профили в сессии можно через /permissions — там появятся ваши профили с описаниями. В организациях администратор может ограничить список допустимых профилей через requirements.toml.

Как песочница устроена на разных ОС

• macOS — встроенный Seatbelt, ничего ставить не нужно.
• Linux и WSL2 — bubblewrap и seccomp. Установите пакет: sudo apt install bubblewrap или sudo dnf install bubblewrap. Без bwrap в PATH Codex берёт встроенного помощника, которому нужны непривилегированные user namespaces. На Ubuntu 24.04 может понадобиться AppArmor-профиль bwrap-userns-restrict — инструкция на странице Sandbox. WSL1 не поддерживается с версии 0.115. Если вы читали про Landlock — это прошлая реализация.
• Windows — предпочтительна MXC ([features] prefer_mxc = true), запасные варианты задаются в [windows] sandbox: elevated (нужна настройка администратором) и unelevated (слабее изоляция сети). Нужна семантика Linux — работайте через WSL2.
• Docker — вложенная песочница может не запуститься. Тогда границей служит сам контейнер, а Codex внутри запускают с --sandbox danger-full-access. Это допустимо только для доверенных репозиториев: всё, что есть в контейнере, включая учётные данные Codex, становится доступно агенту.

Проверка без агента

Прогнать команду в песочнице можно напрямую, не тратя токены:

codex sandbox macos --log-denials -- cat .env
codex sandbox linux -- curl -sI https://example.com

С профилем прав — флаг --permissions-profile <имя>; для Windows есть codex sandbox windows. Флаги этой подкоманды ещё меняются, поэтому сверьтесь с codex sandbox --help вашей версии. На macOS --log-denials после выполнения печатает, что именно заблокировала песочница.