Эта страница переведена с английской документации. Команды, идентификаторы и примеры не изменены. Среда выполнения 7.24.4 · SDK 2.6.7. Английский оригинал

Режим песочницы

Статус: активно Область: текущее состояние Последняя проверка: 2026-08-23 Владелец: среда выполнения ax-code

В AX Code есть встроенная песочница выполнения, которая может ограничить, что агент ИИ делает в вашей системе. По умолчанию AX Code стартует с полным доступом и выключенной песочницей, поэтому запись в файловую систему и доступ к сети не ограничены. Включите workspace-write или read-only, прежде чем работать с недоверенными репозиториями или запускать задачи без присмотра.

Предупреждение безопасности: full-access не является границей безопасности. Агент может менять файлы вне рабочей области, писать .git/ и .ax-code/, выполнять неограниченные команды оболочки и обращаться к сети.

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

Переключите песочницу из TUI:

• введите /sandbox в запросе или
• нажмите Ctrl+P и найдите «sandbox»

Строка состояния показывает текущее состояние:

• песочница вкл (зелёный) — агент ограничен рабочей областью
• песочница выкл (красный) — ограничений нет

Параметр сохраняется между сессиями в ax-code.json.

Что меняется

Конфигурация

Источник истины

Эта страница суммирует поведение для пользователя. Когда поведение меняется, сверьте документацию с:

• packages/ax-code/src/isolation/index.ts — разрешение режима, защищённые пути, проверки сети, записи и bash, а также IsolationDeniedError.
• packages/ax-code/src/config/schema.ts — форма конфигурации, значения по умолчанию и описания.
• packages/ax-code/src/server/routes/isolation.ts — поведение переключателя во время выполнения и сохранение.
• packages/ax-code/test/isolation/isolation.test.ts и packages/ax-code/test/tool/bash.test.ts — ожидаемое поведение принуждения.

Повторяющиеся утверждения в корневом README держите краткими и ссылайтесь сюда за подробностями.

Переключение из TUI

Используйте /sandbox или палитру команд (Ctrl+P → «Включить или выключить песочницу»). Изменение действует сразу и сохраняется в ax-code.json проекта.

Флаг CLI

ax-code --sandbox workspace-write   # sandbox on
ax-code --sandbox full-access       # sandbox off
ax-code --sandbox read-only         # strictest: blocks all mutations

Переменная окружения

AX_CODE_ISOLATION_MODE=workspace-write ax-code

Файл конфигурации

В ax-code.json:

{
  "isolation": {
    "mode": "workspace-write",
    "network": false
  }
}

Приоритет

Флаг CLI > переменная окружения > файл конфигурации > значение по умолчанию (full-access)

Когда активно переопределение CLI или окружения, TUI сообщает этот действующий режим. Переключатель /sandbox может сохранить предпочтение проекта, но переопределение с более высоким приоритетом остаётся активным, пока его не уберут (обычно при перезапуске).

Режимы изоляции

Защищённые пути

В режиме workspace-write эти пути всегда защищены от записи:

• .git/ — не даёт случайно повредить состояние git
• .ax-code/ — не даёт подменить конфигурацию и плагины

Добавьте свои защищённые пути в конфигурации:

{
  "isolation": {
    "mode": "workspace-write",
    "protected": ["secrets", "credentials"]
  }
}

Доступ к сети

Сеть по умолчанию выключена в режимах workspace-write и read-only. Затронутые инструменты:

• webfetch — заблокирован
• websearch — заблокирован
• codesearch — заблокирован
• bash — клиенты только для сети (curl, wget, nc/ncat/netcat, telnet, ftp, tftp, scp, sftp, dig, nslookup, host) заблокированы

Ограничение: блокировка сети в bash работает на уровне приложения и покрывает выделенные сетевые клиенты выше. Она не перехватывает инструменты двойного назначения, которые работают и офлайн (git, npm/pnpm/yarn, pip, go, интерпретаторы языков вроде python/node), потому что их офлайн-вызовы нельзя отличить статически, а блокировка сломала бы обычные процессы. Настоящая исчерпывающая изоляция сети требует средств уровня ОС, которых эта песочница не даёт. Когда встречается запрещённый клиент, агент просит разовое повышение.

Чтобы разрешить сеть, сохранив ограничения записи:

{
  "isolation": {
    "mode": "workspace-write",
    "network": true
  }
}

Бэкенд изоляции (приложение или ОС)

macOS: профили Seatbelt через sandbox-exec (запись ограничена рабочей областью или worktree, сеть запрещена, когда network: false).
Linux: bubblewrap (bwrap), если установлен (--unshare-net, когда сеть выключена, рабочая область смонтирована на запись).
Windows: сегодня только слой приложения.

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

Модель угроз см. в SECURITY.md.

Разрешения и хуки под контролем репозитория

Файлы проекта по умолчанию недоверенные. Правила разрешений в ax-code.json, .ax-code/policy.json и определения агента или режима проекта могут ужесточить доступ через deny, но разрешения allow/ask под контролем репозитория игнорируются. Команды проекта не могут включить раскрытие оболочки. .ax-code/hooks.json, .ax-code/plugin/ и плагины, настроенные проектом, не выполняются.

Недоверенная конфигурация проекта также не может выбрать пользовательскую оболочку, исполняемый LSP или форматтер, пакет провайдера или конечную точку API, переменные окружения учётных данных провайдера, внешний источник навыков или путь инструкций вне worktree. Безопасные относительные пути инструкций и неисполняемые встроенные переопределения остаются доступны. Серверы MCP используют отдельный поток одобрения по отпечатку, описанный в Интеграциях MCP.

После рецензии конфигурации под контролем репозитория пользователи могут согласиться вне репозитория для текущего процесса:

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Переключатель только через окружение не даёт рабочей копии объявить себя доверенной.

Как работает принуждение

Принуждение песочницы всегда на уровне приложения и проверяется при каждом вызове инструмента. Когда backend равен os или auto и платформа это поддерживает, bash дополнительно оборачивается песочницей ядра.

Когда инструмент нарушает изоляцию, он бросает IsolationDeniedError с ясным сообщением, что заблокировано и почему.