SpyBara
Go Premium

sandboxing.md 2026-10-01 23:59 UTC to 2026-10-02 06:02 UTC

This page contains 606 additions and 307 deletions.

2026
Fri 2 07:00

Настройка инструмента Bash в песочнице

Ограничьте файлы и сетевые хосты, к которым могут обращаться shell-команды Claude Code, с помощью встроенной песочницы. Включите её, задайте границы и исправьте то, что она нарушает.

Песочница Bash — это граница, которую операционная система устанавливает вокруг shell-команд, запускаемых Claude на вашем компьютере. Вы задаёте, к каким файлам и сетевым доменам могут обращаться эти команды, и ограничения применяются к командам Bash, PowerShell и Monitor, а также к запускаемым ими процессам. Поскольку операционная система применяет ограничения во время выполнения команды, Claude Code может запускать команды в песочнице, не спрашивая вас о подтверждении каждой из них.

Песочница охватывает только shell-команды. Файловые инструменты Claude, MCP-серверы и хуки работают вне её.

Песочница работает в macOS, Linux и WSL2. В нативной Windows Claude Code запускает команды без песочницы. Чтобы использовать песочницу на компьютере с Windows, запускайте Claude Code внутри дистрибутива WSL2.

Что ограничивает песочница

Пока песочница включена, shell-команды, которые запускает Claude, выполняются внутри её границ, как и процессы, которые эти команды запускают. По умолчанию песочница отключена. Чтобы включить её, выполните /sandbox в сессии, как показано в разделе Начало работы, или установите для sandbox.enabled значение true в файле настроек, например ~/.claude/settings.json.

В таблице показано, к чему изолированная в песочнице команда имеет доступ по умолчанию, и настройки, которые изменяют каждое значение по умолчанию.

Доступ По умолчанию Как изменить
Запись Рабочий каталог, временный каталог пользователя и добавленные вами каталоги. Защищённые пути остаются запрещёнными для записи filesystem.allowWrite, filesystem.denyWrite
Чтение Большая часть машины, включая файлы с учётными данными, такие как ~/.ssh и ~/.aws/credentials filesystem.denyRead, credentials
Сеть Прямого выхода нет. Соединения проходят через прокси на вашей машине, который проверяет каждый хост по списку разрешённых доменов, изначально пустому. Ваш режим разрешений определяет, что происходит с другими хостами network.allowedDomains, network.deniedDomains
Переменные окружения Наследуются от Claude Code, включая любые секреты в его окружении credentials, CLAUDE_CODE_SUBPROCESS_ENV_SCRUB

Claude Code создаёт песочницу на основе пакета с открытым исходным кодом @anthropic-ai/sandbox-runtime.

Что выполняется вне песочницы

Песочница оборачивает shell-команды. Следующие инструменты и процессы выполняются вне её:

  • Встроенные инструменты для работы с файлами и веб-ресурсами: такие инструменты, как Read, Edit, Write, WebFetch и WebSearch, вместо этого подчиняются правилам разрешений. Запись в denyRead не останавливает инструмент Read, а allowedDomains не ограничивает WebFetch
  • Другие процессы, которые запускает Claude Code: командные хуки, локальные MCP-серверы, мониторы плагинов, LSP-серверы и вспомогательные команды, такие как команда вашей строки состояния и apiKeyHelper, выполняются с вашим полным доступом

Некоторые shell-команды также выполняются вне песочницы, в зависимости от ваших настроек:

Чтобы поместить инструменты, процессы и команды из этого раздела за единую границу, запустите сам процесс Claude Code в контейнере, виртуальной машине или среде выполнения песочницы.

Начало работы

Песочница встроена в Claude Code. Что нужно установить, зависит от вашей платформы:

  • macOS: изоляция в песочнице использует встроенный фреймворк Seatbelt, поэтому можно сразу переходить к шагам
  • Linux и WSL2: песочница использует bubblewrap и socat, об этом рассказано в разделе Настройка Linux и WSL2. Даже если вы их ещё не установили, можно начать с /sandbox, потому что его панель показывает, чего не хватает
1

Запустите /sandbox

Начните сессию Claude Code и выполните команду /sandbox:

/sandbox

Откроется панель песочницы с тремя вкладками, а также вкладкой Dependencies в Linux, если отсутствует необязательный фильтр seccomp:

  • Mode: выберите, как подтверждаются команды в песочнице; об этом рассказано на следующем шаге
  • Overrides: выберите, могут ли команды, которые завершаются ошибкой в песочнице, в качестве запасного варианта выполняться вне песочницы. Это настройка allowUnsandboxedCommands
  • Config: просмотр итоговых настроек песочницы

Если на панели отображается только вкладка Dependencies, значит, отсутствует обязательный пакет. Установите его, как описано в разделе Настройка Linux и WSL2, перезапустите Claude Code и снова выполните /sandbox.

2

Выберите режим

На вкладке Mode выберите auto-allow или обычные разрешения. Режим auto-allow выполняет команды в песочнице без запросов, а режим обычных разрешений сохраняет обычные запросы разрешений, даже когда команды выполняются в песочнице. О том, какие команды всё равно вызывают запрос в режиме auto-allow, см. в разделе Режимы песочницы.

3

Выполните команду Bash

Попросите Claude выполнить команду, например сборку или набор тестов. По умолчанию команды в песочнице могут записывать в рабочий каталог, временный каталог пользователя и любые каталоги, которые вы добавили с помощью --add-dir, /add-dir или permissions.additionalDirectories.

Когда команде впервые нужен новый сетевой домен, Claude Code запрашивает подтверждение; в авторежиме Claude вместо этого указывает нужные команде хосты в самой команде, чтобы классификатор проверил их вместе с ней.

Чтобы расширить или сузить то, что разрешает песочница, см. раздел Настройка изоляции в песочнице.

Если команды в песочнице внутри контейнера завершаются ошибкой Operation not permitted, см. раздел Bubblewrap не запускается внутри контейнера.

Когда вы выбираете режим на панели, Claude Code сохраняет его в локальных настройках проекта в .claude/settings.local.json, которые применяются к текущему проекту. Claude Code добавляет этот файл в ваш глобальный gitignore, когда сохраняет туда настройку. Чтобы включить песочницу во всех ваших проектах, задайте для sandbox.enabled значение true в пользовательских настройках в ~/.claude/settings.json. Чтобы обязать использовать песочницу всех разработчиков в организации, используйте управляемые настройки.

Чтобы изменить песочницу для одной сессии без записи в файл настроек, запустите Claude Code с --settings. Например, эта команда запускает сессию в песочнице, в которой Claude не может повторить попытку выполнения заблокированной команды вне песочницы:

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

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

Чтобы убедиться, что песочница работает, попросите Claude выполнить каждую строку из таблицы. То, что вы вводите в промпте !, обычно выполняется вне песочницы, поэтому ввод строки вручную её не проверяет.

Команда Результат в песочнице
touch ~/sandbox-probe Завершается ошибкой Operation not permitted в macOS или Read-only file system в Linux и WSL2
curl --noproxy '*' https://example.com Завершается ошибкой Could not resolve host, потому что у команды нет пути в обход прокси песочницы

Если Claude предлагает повторить попытку выполнения неудавшейся команды вне песочницы, отклоните повторную попытку. Если touch выполняется успешно, а ваш домашний каталог не входит в число каталогов, в которые песочница разрешает командам записывать, удалите ~/sandbox-probe. Затем выполните /sandbox, чтобы проверить, что песочница включена и её зависимости установлены.

Настройка Linux и WSL2

В Linux и WSL2 песочница использует следующие пакеты:

  • bubblewrap: непривилегированный инструмент изоляции, обеспечивающий изоляцию файловой системы
  • socat: ретранслятор, используемый для направления сетевого трафика через прокси песочницы

Установите их с помощью менеджера пакетов вашего дистрибутива:

sudo apt-get install bubblewrap socat

Когда зависимость отсутствует, вкладка Dependencies в /sandbox показывает, чего из ripgrep, bubblewrap, socat и фильтра seccomp не хватает на вашей платформе. Если после установки и перезапуска Claude Code вы не видите эту вкладку, все зависимости на месте.

Ripgrep входит в состав нативного бинарного файла Claude Code. Фильтр seccomp необязателен и добавляет блокировку доменных сокетов Unix. Если он отсутствует, установите его с помощью npm install -g @anthropic-ai/sandbox-runtime.

Когда отсутствует обязательная зависимость, вкладка Dependencies остаётся единственной отображаемой вкладкой, пока вы её не установите. Когда отсутствует только необязательный фильтр seccomp, вкладка Dependencies отображается вместе с остальными вкладками. Проверка зависимостей выполняется при запуске, поэтому после установки пакетов перезапустите Claude Code, чтобы /sandbox их обнаружил.

В Ubuntu 24.04 и новее политика AppArmor по умолчанию не позволяет bubblewrap создавать пространства имён пользователей, необходимые ему для изоляции. 
Чтобы проверить, действует ли это ограничение в вашей среде, в том числе в WSL2, выполните `sysctl kernel.apparmor_restrict_unprivileged_userns`. Если команда возвращает `0`, пропустите этот шаг. Если она выводит ошибку `No such file or directory`, ключ не существует, и этот шаг можно пропустить. Если она возвращает `1`, добавьте профиль AppArmor, предоставляющий `bwrap` эту возможность:

```bash theme={null}
sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF
```

Профиль применяется только к самому `bwrap`, а не к командам, которые он выполняет в песочнице. Перезагрузите AppArmor, чтобы применить его:

```bash theme={null}
sudo systemctl reload apparmor
```
Примечания для WSL2

Проверьте версию WSL с помощью wsl -l -v в PowerShell. Если вы видите Sandboxing requires WSL2, ваш дистрибутив работает на WSL1. Обновите его до WSL2 или запускайте Claude Code без изоляции в песочнице.

В WSL2 запуск бинарного файла Windows, например cmd.exe, powershell.exe или чего-либо в /mnt/c/, WSL передаёт хосту Windows через сокет Unix, поэтому возможность запустить такой файл из команды в песочнице определяется настройками сокетов Unix песочницы: чтобы сокет вообще блокировался, должен быть установлен необязательный фильтр seccomp. Чтобы разрешить такие запуски, задайте allowAllUnixSockets, что открывает все сокеты Unix для команд в песочнице.

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

Claude Code предлагает два режима песочницы. В обоих песочница применяет одинаковые ограничения файловой системы и сети; различие лишь в том, подтверждаются ли команды в песочнице автоматически или требуют явного разрешения.

Режим auto-allow

Claude Code автоматически, без запроса, подтверждает команду, если она выполняется в песочнице. Команда проходит обычный процесс получения разрешений, если она выполняется вне песочницы, потому что соответствует excludedCommands или потому что Claude повторяет попытку её выполнения вне песочницы.

Команда в песочнице, которая подключается к хосту, который вы не разрешили, остаётся в песочнице. О том, кто решает, будет ли установлено соединение, рассказано в разделе Хосты вне разрешённых доменов.

Даже в режиме auto-allow по-прежнему действует следующее:

  • Явные правила запрета всегда соблюдаются
  • Команды rm или rmdir, нацеленные на критический путь, по-прежнему проходят обычный процесс получения разрешений
  • Правила запроса с ограничением по содержимому, например Bash(git push *), по-прежнему вызывают запрос даже для команд в песочнице
  • Голое правило запроса Bash или эквивалентная форма Bash(*) пропускается для команд, выполняемых в песочнице; оно по-прежнему применяется к командам, которые переходят к обычному процессу получения разрешений. В режиме планирования правило не пропускается: оно вызывает запрос и для команд в песочнице, включая команды только для чтения

Режим обычных разрешений

Все команды Bash проходят обычный процесс получения разрешений, даже в песочнице. Это даёт больше контроля, но требует больше подтверждений.

Запасной выход: повторная попытка вне песочницы

Повторная попытка вне песочницы — это запасной выход для команд, которые завершаются ошибкой в песочнице, например для инструментов, несовместимых с ней. Когда песочница блокирует сетевое соединение, Claude Code указывает запрещённый хост в результате команды, чтобы Claude видел, что было заблокировано. Claude анализирует ошибку и может повторить попытку выполнения команды с параметром dangerouslyDisableSandbox.

Повторная команда выполняется вне песочницы. В интерактивной сессии терминала то, кто её подтверждает, зависит от вашего режима разрешений:

  • Режим bypassPermissions: повторная попытка выполняется без запроса
  • Режим Manual и режим acceptEdits: вы получаете запрос с заголовком «Bash command (unsandboxed)»
  • Авторежим: отдельная модель-классификатор оценивает исходную команду
  • Режим dontAsk: Claude Code отклоняет повторную попытку
  • Режим планирования: см. как Claude Code контролирует команды во время планирования

Следующие правила и настройки меняют то, кто подтверждает повторную попытку:

  • Соответствующее правило разрешения: если правило разрешения, например Bash(curl *), соответствует команде, оно также подтверждает повторную попытку, поэтому команда выполняется вне песочницы без запроса
  • Правило запроса для параметра: добавьте правило запроса для Bash(dangerouslyDisableSandbox:true), чтобы получать запрос при повторных попытках Bash. Вы получите запрос и в авторежиме, и в режиме bypassPermissions, а правило имеет приоритет над соответствующим правилом разрешения
  • permissions.blockReadsOutsideWorkingDirectories: о повторных попытках, вызывающих запрос, когда эта настройка включена, рассказано в разделе Действия, которые не подтверждаются автоматически ни в одном режиме

Отключение повторной попытки с помощью строгого режима песочницы

Вы можете отключить повторную попытку вне песочницы, задав "allowUnsandboxedCommands": false в настройках песочницы. Когда повторная попытка отключена, Claude Code игнорирует параметр dangerouslyDisableSandbox. Пока песочница работает, команды, которые выполняет Claude, в этом случае выполняются в песочнице, если они не соответствуют записи excludedCommands. Чтобы Claude Code не выполнял команды вне песочницы, когда песочница не может запуститься, задайте также failIfUnavailable. Вкладка Overrides в /sandbox показывает эту настройку как Strict sandbox mode.

Значение false в ваших пользовательских настройках, --settings или управляемых настройках сохраняет силу, даже когда настройки проекта задают true. Значение false в ваших пользовательских настройках не делает песочницу обязательной по требованию администратора, поэтому остальные настройки песочницы проекта по-прежнему применяются. До v2.1.285 значение true проекта переопределяло false в ваших пользовательских настройках.

Если вы или ваш администратор отключаете повторную попытку в управляемых настройках или с помощью флага --settings, песочница становится обязательной по требованию администратора. Тогда Claude Code игнорирует настройки в файлах репозитория, которые ослабляют песочницу, включая записи excludedCommands. Их список приведён в разделе Настройки репозитория при песочнице, обязательной по требованию администратора.

Строгий режим песочницы применяется к командам, которые выполняет Claude. Команды, которые вы вводите сами в промпте режима оболочки !, выполняются вне песочницы, если только сессия не относится к одному из следующих типов:

  • Фоновая сессия: строгий режим песочницы распространяется и на команды режима оболочки
  • Сессия в Linux с заданной переменной CLAUDE_CODE_SUBPROCESS_ENV_SCRUB: все команды выполняются в песочнице, включая команды режима оболочки

До v2.1.260 строгий режим песочницы помещал команды режима оболочки в песочницу в каждой сессии.

Временные каталоги

По умолчанию в песочнице наряду с рабочим каталогом доступен для записи временный каталог пользователя. Если вы не отключите изоляцию файловой системы, Claude Code задаёт $TMPDIR равным этому каталогу для команд в песочнице, поэтому инструменты, записывающие временные файлы, работают без дополнительной настройки.

Команды вне песочницы наследуют $TMPDIR вашей оболочки, если эта переменная задана, поэтому, пока изоляция файловой системы включена, команды в песочнице и вне её разрешают $TMPDIR в разные каталоги. Если ваша оболочка оставляет $TMPDIR незаданной или пустой, команда вне песочницы, ссылающаяся на $TMPDIR, получает ваше переопределение CLAUDE_CODE_TMPDIR или временный каталог операционной системы, если вы его не задали или переопределение является длинным путём, поэтому переменная не раскрывается в пустую строку. Чтобы передавать временные файлы между ними, записывайте их вместо этого в рабочий каталог.

Настройка изоляции в песочнице

Настройте поведение песочницы в файле settings.json. Полный справочник по конфигурации см. в разделе Настройки.

По умолчанию команды в песочнице могут записывать в текущий рабочий каталог, во временный каталог пользователя и в любые каталоги, которые вы добавили с помощью --add-dir, /add-dir или permissions.additionalDirectories. Если командам подпроцессов, таким как kubectl, terraform или npm, нужно записывать за пределами этих каталогов, используйте sandbox.filesystem.allowWrite, чтобы предоставить доступ к определённым путям:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

Эти пути применяются на уровне ОС, поэтому их соблюдают все команды, выполняемые внутри песочницы, включая их дочерние процессы. Это рекомендуемый подход, когда инструменту нужен доступ на запись к определённому расположению, вместо того чтобы полностью исключать инструмент из песочницы с помощью excludedCommands.

Если вы определяете один и тот же массив файловой системы в нескольких областях действия настроек, Claude Code объединяет их, собирая пути из всех областей действия, а не заменяя массив одной области действия массивом другой.

Если вы исключаете источник с помощью --setting-sources в CLI или settingSources в Agent SDK, Claude Code игнорирует его записи sandbox.filesystem, его правила разрешений Edit и его запрещающие правила Read при построении конфигурации песочницы. Требуется Claude Code v2.1.246 или новее.

Когда вы редактируете эти списки файловой системы во время сессии, Claude Code применяет изменение к текущей сессии, поэтому следующая команда в песочнице выполняется уже с новыми путями.

Пути файловой системы песочницы следуют стандартным соглашениям: /tmp/build — абсолютный путь, а ~/.kube — путь относительно домашнего каталога. Это отличается от правил разрешений Read и Edit, которые используют //path для абсолютных путей и /path для путей относительно проекта. Об относительных путях, завершающей косой черте и подстановочных знаках см. Префиксы путей песочницы.

Вы также можете запретить доступ на запись или чтение с помощью sandbox.filesystem.denyWrite и sandbox.filesystem.denyRead и снова разрешить определённые пути внутри запрещённой области с помощью sandbox.filesystem.allowRead. Когда правила чтения пересекаются, применяется правило с более узким путём:

Примеры правил Результат
"denyRead": ["~/"] с "allowRead": ["~/projects"] ~/projects доступен для чтения, а остальная часть домашнего каталога остаётся заблокированной. Более узкое разрешение снова открывает эту часть запрещённой области
"allowRead": ["~/"] с "denyRead": ["~/.env"] ~/.env остаётся заблокированным, а остальная часть домашнего каталога доступна для чтения. Запрет действует внутри более широкого разрешения, поэтому широкое разрешение не может незаметно снова открыть секрет
"allowRead": ["~/"] с "denyRead": ["~/**/.env"] Все .env в домашнем каталоге остаются заблокированными, а остальное доступно для чтения. Запрет с подстановочным знаком действует внутри более широкого разрешения так же, как и точный путь

Пример ниже блокирует чтение всего домашнего каталога, но по-прежнему разрешает чтение текущего проекта. Поместите его в .claude/settings.json вашего проекта, потому что относительный путь . разрешается в корень проекта, только когда конфигурация находится в настройках проекта:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

Если бы вы поместили ту же конфигурацию в ~/.claude/settings.json, . разрешался бы в ~/.claude, и файлы проекта оставались бы заблокированными правилом denyRead.

Чтобы запретить командам в песочнице чтение домашних каталогов и смонтированных томов, сохранив при этом рабочие каталоги доступными для чтения, задайте permissions.blockReadsOutsideWorkingDirectories вместо написания правил для путей.

Запуск команд вне песочницы с помощью `excludedCommands`

Укажите шаблон команды в sandbox.excludedCommands, чтобы подходящие команды выполнялись вне песочницы, то есть без ограничений файловой системы и без сетевого прокси. Используйте это для инструмента, который не может работать внутри песочницы и которому вы доверяете полный доступ. Инструмент, которому нужен ещё один каталог или ещё один хост, может заработать с allowWrite или allowedDomains, которые оставляют команду в песочнице.

Этот пример выводит команды docker compose из песочницы. Сохраните его в ~/.claude/settings.json, чтобы применить ко всем вашим проектам:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker compose *"]
  }
}

Claude Code проверяет ваши записи для каждого вызова Bash и Monitor. Вызов — это вся командная строка, которую отправляет Claude, и она может объединять несколько команд в цепочку. Следующие правила определяют, покидает ли вызов песочницу:

  • Завершайте шаблон на *: записи используют тот же синтаксис, что и правило разрешений Bash(...), где шаблон без подстановочного знака означает точное совпадение. docker соответствует только docker без аргументов. docker * соответствует docker с аргументами или без них
  • Каждая команда в вызове должна совпадать: npm ci && docker compose build остаётся в песочнице, если другая запись не покрывает npm ci
  • Claude Code сопоставляет текст вызова: скрипт или цель make, которые вызывают docker внутри, не совпадают, как и /usr/local/bin/docker
  • Некоторые вызовы остаются в песочнице: перенаправление в файл, cd или подстановка команды, например $(...), оставляют весь вызов в песочнице. В справочной записи перечислены другие вызовы, которые остаются в песочнице
  • Место сохранения записи может иметь значение: пока песочница обязательна по требованию администратора, Claude Code игнорирует записи в .claude/settings.json и .claude/settings.local.json

Исключённая команда проходит обычный процесс проверки разрешений:

  • Команды только для чтения и команды, покрытые вашими разрешающими правилами, выполняются без запроса
  • В авторежиме другие исключённые команды проверяет классификатор
  • В режиме bypassPermissions исключённая команда выполняется без запроса, если ей не соответствует правило ask

Чтобы убедиться, что запись срабатывает, переключитесь в ручной режим и попросите Claude выполнить подходящую команду, которая что-то изменяет, например docker compose up -d. Запрос разрешения будет озаглавлен «Bash command (unsandboxed)».

Отключение изоляции файловой системы

Задайте для sandbox.filesystem.disabled значение true, чтобы пропустить изоляцию файловой системы, сохранив сетевую изоляцию. Пример ниже отключает изоляцию файловой системы, сохраняя список разрешённых сетевых доменов:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

Песочница имеет два независимых уровня: изоляция файловой системы определяет, какие пути команды в песочнице могут читать и записывать, а сетевая изоляция определяет, к каким доменам они могут обращаться. При отключённом уровне файловой системы команды в песочнице получают неограниченный доступ на чтение и запись к файловой системе хоста, а их исходящий сетевой трафик по-прежнему ограничен разрешёнными доменами. Отключайте этот уровень, когда вы используете песочницу, чтобы контролировать, куда подключаются команды, а не то, что они записывают.

sandbox.filesystem.disabled по умолчанию имеет значение false. Требуется Claude Code v2.1.216 или новее.

Какие настройки могут её отключить

Поскольку отключение изоляции файловой системы расширяет возможности команд в песочнице, Claude Code учитывает filesystem.disabled только из следующих источников настроек:

  • Пользовательские настройки, управляемые настройки и флаг CLI --settings могут её задавать. Настройки проекта в .claude/settings.json и .claude/settings.local.json не могут, поэтому извлечённый проект не может отключить изоляцию файловой системы.
  • Если управляемые настройки вообще настраивают sandbox.filesystem или содержат какую-либо запись sandbox.credentials.files с "mode": "deny", задать этот ключ могут только управляемые настройки. Это сохраняет в силе ограничения файловой системы, развёрнутые администратором; чтобы ослабить такое развёртывание, задайте "disabled": true в управляемых настройках.
  • Если задана CLAUDE_CODE_SUBPROCESS_ENV_SCRUB, Claude Code игнорирует filesystem.disabled из любого источника, включая управляемые настройки, и оставляет изоляцию файловой системы включённой.

Допустимая запись mask не закрепляет ключ, даже если Claude Code переключается для неё на deny при запуске. Путь, который нельзя замаскировать, например каталог учётных данных, укажите в управляемых настройках как явную запись deny, которая закрепляет ключ.

Что меняется при отключённой изоляции файловой системы

Задание filesystem.disabled снимает защиту, которую обеспечивает сам уровень файловой системы. Защита, которую обеспечивают другие уровни, продолжает действовать:

Защита При отключённой изоляции файловой системы
Блокировки чтения filesystem.denyRead и deny в credentials.files Не применяются. Оба механизма обеспечивает уровень файловой системы
Записи deny и mask в credentials.envVars Применяются. Очистка переменных окружения не зависит от уровня файловой системы
Записи mask в credentials.files, применённые как маски Применяются: маскирование не зависит от уровня файловой системы. Запись, которая переключилась на deny, не применяется, как и любая запись deny

Меняются ещё две вещи:

  • Команды в песочнице наследуют $TMPDIR вашей оболочки вместо временного каталога пользователя, потому что все временные каталоги доступны для записи и Claude Code больше не перенаправляет команды во временный каталог пользователя.

    В Linux эта переменная часто не задана в родительской оболочке. Руководство по инструменту Bash указывает Claude создавать временные каталоги с помощью mktemp -d, а не полагаться на $TMPDIR.

  • autoAllowBashIfSandboxed по-прежнему по умолчанию имеет значение true, поэтому команды в песочнице продолжают выполняться без запросов. Задайте значение false, чтобы запрашивать подтверждение для команд в песочнице.

Защита учётных данных

Настройка sandbox.credentials объявляет файлы учётных данных и переменные окружения, которые нужно защитить от команд в песочнице. Каждая запись указывает путь к файлу или переменную окружения и mode. Отдельный блок credentials позволяет держать правила для учётных данных вместе и отдельно от общих правил файловой системы.

Для записей с "mode": "deny" чтение путей к файлам внутри песочницы запрещается, это то же ограничение, которое применяет filesystem.denyRead, а переменные окружения удаляются перед выполнением каждой команды в песочнице. Защита файлов является частью уровня файловой системы, поэтому она не действует, если вы отключите изоляцию файловой системы; защита переменных окружения продолжает действовать.

Пример ниже блокирует чтение файла учётных данных AWS и каталога SSH и удаляет GITHUB_TOKEN и NPM_TOKEN из окружения команд в песочнице:

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

Записи переменных окружения и записи файлов также принимают "mode": "mask", описанный в разделе Маскирование учётных данных.

Пути к файлам следуют тем же правилам префиксов, что и настройки sandbox.filesystem.*.

Claude Code объединяет записи deny из всех областей действия настроек, которые загружает сессия. Запись deny только сужает доступ, поэтому любая область действия может её добавить, но никакая область действия не может удалить запись, добавленную другой.

Когда вы исключаете источник настроек:

  • Настройки проекта или локальные настройки: Claude Code не применяет ни одну из их записей credentials. Требуется Claude Code v2.1.246 или новее.
  • Пользовательские настройки: Claude Code по-прежнему применяет записи deny в ~/.claude/settings.json и сохраняет их записи mask для файлов как ограничения, которые больше не разрешают прокси подставлять реальное значение, но отбрасывает их записи mask для переменных окружения.

Встроенного списка запрещённых учётных данных нет, поэтому ограничиваются только файлы и переменные, которые вы перечислили.

sandbox.credentials влияет только на команды Bash в песочнице. Чтобы удалить учётные данные из всех подпроцессов независимо от изоляции в песочнице, задайте CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.

Маскирование учётных данных

Когда вы маскируете учётные данные, Claude Code показывает командам в песочнице заполнитель, уникальный для сессии, — сигнальное значение, а прокси песочницы подставляет реальное значение в исходящие запросы к разрешённым вами хостам. Запись deny из раздела Защита учётных данных вместо этого блокирует учётные данные. Для файлов в macOS Claude Code вместо маскирования блокирует файл.

Для маскирования переменных окружения требуется Claude Code v2.1.199 или новее. Все поля перечислены в справочнике sandbox.credentials.

Для маскирования необходимо следующее:

  • Завершение TLS: прокси подставляет реальное значение внутрь содержимого запроса, поэтому ему нужно его видеть. Задайте network.tlsTerminate, чтобы прокси сам завершал TLS. Без этого маскирование не срабатывает, но ничего не раскрывает: команда по-прежнему видит только сигнальное значение, но оно доходит до сервера без изменений, и аутентификация завершается ошибкой. Claude Code сообщает об этой ошибке конфигурации при запуске.
  • Разрешённое назначение: каждая запись mask может содержать injectHosts — хосты, которым разрешено получать реальное значение. Прокси выполняет подстановку только в соединениях, которые допускает список разрешённых доменов, поэтому каждый хост из injectHosts также должен быть доступен через network.allowedDomains. Для записи mask без injectHosts прокси подставляет реальное значение в запросы ко всем хостам из network.allowedDomains.
  • Доверенная область действия настроек: маскирование разрешает прокси куда-то отправлять ваши реальные учётные данные, поэтому Claude Code учитывает записи mask, network.tlsTerminate, credentials.allowPlaintextInject, awsPairs и sigv4 только из пользовательских настроек, управляемых настроек и флага --settings. Он игнорирует их в .claude/settings.json или .claude/settings.local.json репозитория. Когда ваш администратор передаёт записи mask, network.tlsTerminate или credentials.allowPlaintextInject через управляемые настройки на сервере, они считаются настройками, требующими подтверждения.

Маскирование переменных окружения

Чтобы замаскировать переменную окружения, задайте "mode": "mask" в её записи credentials.envVars. Команда и всё, что она записывает в лог, никогда не содержат реальных учётных данных, но её запросы по-прежнему проходят аутентификацию. Если та же переменная указана с deny в любой области действия, deny имеет приоритет.

Этот пример маскирует два токена. GH_TOKEN подставляется только в запросы к api.github.com, а у NPM_TOKEN нет injectHosts, и он подставляется в запросы ко всем хостам из network.allowedDomains:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    },
    "credentials": {
      "envVars": [
        { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },
        { "name": "NPM_TOKEN", "mode": "mask" }
      ]
    }
  }
}

По умолчанию маскирование заменяет всё значение. Для значения со структурой, например строки подключения DATABASE_URL или JWT, используйте поля extract, decode, maskClaims и onExtractNoMatch, чтобы инструменты, которые разбирают значение, продолжали работать.

Для IPv6-адреса назначения записывайте адрес в двух списках по-разному:

  • network.allowedDomains: форма в квадратных скобках, например "[::1]"
  • injectHosts: адрес без скобок в канонической сокращённой форме, например "::1"

Прокси сопоставляет каждую запись injectHosts с адресом назначения соединения без скобок, игнорируя порты, поэтому запись в квадратных скобках, с идентификатором зоны или в иной сокращённой форме никогда не совпадёт. claude doctor помечает записи, которые никогда не могут совпасть, предупреждением Sandbox credential injectHosts entries can never match their destination. Эта проверка требует Claude Code v2.1.229 или новее.

Повторная подпись запросов AWS

Запросы AWS содержат подписи SigV4, вычисленные по содержимому запроса, поэтому маскируйте AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY вместе. Прокси распознаёт запрос SigV4 по сигнальному значению ключа доступа и повторно подписывает запрос реальными значениями, для чего требуется Claude Code v2.1.221 или новее. Если замаскирован только секретный ключ, запросы подписываются заполнителем, который прокси не может распознать, поэтому они отклоняются на стороне AWS.

Claude Code автоматически связывает стандартные переменные AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY и AWS_SESSION_TOKEN в один набор учётных данных, если вы маскируете их значения целиком. Если ваши учётные данные AWS хранятся в переменных с другими именами, сгруппируйте их с помощью credentials.awsPairs, для чего требуется Claude Code v2.1.224 или новее.

Потоковые загрузки, предварительно подписанные URL и запросы SigV4A содержат подписи, которые прокси не может пересчитать. Если такой запрос подписан заполнителем замаскированной пары, прокси завершает его ошибкой, а не пересылает с неверной подписью. Запросы, подписанные незамаскированными учётными данными, это не затрагивает. Чтобы вместо этого пересылать одну из этих форм запросов, используйте credentials.sigv4, для чего требуется Claude Code v2.1.224 или новее. AWS всё равно отклоняет запрос, поэтому вызывающий инструмент получает собственный ответ AWS об отказе вместо ошибки прокси.

Маскирование файлов учётных данных

Чтобы замаскировать файл учётных данных, задайте "mode": "mask" в его записи credentials.files. Для маскирования файлов требуется Claude Code v2.1.221 или новее. То, что видит команда в песочнице, зависит от платформы:

  • Linux и WSL2: команды в песочнице читают копию файла с сигнальным значением, а прокси подставляет реальное значение в исходящие запросы.
  • macOS: команды в песочнице вообще не могут прочитать файл. Claude Code не создаёт копию с сигнальным значением, поэтому инструменты, которые проходят аутентификацию с помощью этого файла, не работают внутри песочницы — эффект тот же, что и у deny. Блокировка чтения сохраняется, даже если вы отключите изоляцию файловой системы.

Этот пример маскирует токен GitHub, хранящийся в ~/.config/gh/hosts.yml. Шаблон extract отмечает, какая часть файла является секретом, поэтому в Linux и WSL2 gh по-прежнему разбирает остальную часть своей конфигурации:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com"]
    },
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

Чтобы убедиться, что маска активна, попросите Claude выполнить cat ~/.config/gh/hosts.yml в команде в песочнице. В Linux и WSL2 вывод покажет сигнальное значение вместо токена, а в macOS чтение завершится ошибкой.

Без extract или decode Claude Code заменяет весь файл одним сигнальным значением, что подходит для файла, содержащего только один секрет. Используйте поля extract, decode, maskClaims, onExtractNoMatch и maskDuplicates, чтобы управлять частичным маскированием и тем, что происходит, если шаблон ничего не находит.

mask применяется к одному файлу, поэтому перечисляйте каждый файл учётных данных по отдельности. Claude Code переключается на deny для записи mask, которую не может безопасно замаскировать: путь к каталогу, glob-шаблон, файл размером больше 8 МиБ или файл, не являющийся текстом в UTF-8.

Как работает изоляция в песочнице

Изоляция файловой системы

Инструмент Bash в песочнице ограничивает доступ к файловой системе определёнными каталогами:

  • Поведение записи по умолчанию: доступ на чтение и запись к текущему рабочему каталогу и его подкаталогам, ко всем каталогам, добавленным через --add-dir, /add-dir или permissions.additionalDirectories, а также к пользовательскому временному каталогу, на который указывает $TMPDIR
  • Поведение чтения по умолчанию: доступ на чтение ко всему компьютеру, за исключением некоторых запрещённых каталогов. Это поведение по умолчанию всё равно позволяет читать файлы с учётными данными, поэтому защитите учётные данные, которые команды не должны читать.
  • Блокировка чтения: при включённом permissions.blockReadsOutsideWorkingDirectories команды в песочнице также теряют доступ на чтение к вашему домашнему каталогу и другим каталогам с пользовательскими файлами, за исключением путей, перечисленных в разделе Команды в песочнице при блокировке. В этом же разделе указано, когда эта часть блокировки не применяется.
  • Git worktree: когда рабочий каталог является связанным git worktree, песочница также разрешает запись в общий каталог .git основного репозитория, чтобы такие команды, как git commit, могли обновлять ссылки и индекс. Запись в hooks/ и config внутри этого каталога по-прежнему запрещена.

Чтобы полностью отключить изоляцию файловой системы, сохранив сетевую изоляцию, задайте sandbox.filesystem.disabled.

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

Внутри каталогов, в которые могут записывать команды в песочнице, песочница всё равно запрещает запись в файлы, из которых Claude Code загружает конфигурацию и код. Команда, способная редактировать эти файлы, могла бы выдать себе разрешения или добавить хук или MCP-сервер, который Claude Code запускает вне песочницы. У системы разрешений есть собственные защищённые пути, которые определяют, что Claude Code одобряет до запуска инструмента; список песочницы применяется к уже запущенной команде. Он охватывает четыре группы путей:

  • В рабочем каталоге и каталогах выше него: файлы настроек .claude, каталоги .claude/skills, .claude/agents, .claude/commands и .claude/hooks, .mcp.json, а также файлы, которые Claude Code запускает самостоятельно, например .claude/workflows и .claude/scheduled_tasks.json
  • Только в рабочем каталоге: файлы запуска оболочки, такие как .bashrc и .zshrc, .gitconfig, каталоги .vscode и .idea, а также hooks и config внутри .git
  • Файлы, которые превратили бы рабочий каталог в bare-репозиторий git: HEAD, objects и refs на верхнем уровне, а также существующие там записи config и hooks, когда рядом с ними находится HEAD. Файл с именем config запрещён даже при отсутствии HEAD. В Linux и WSL2 песочница удаляет файл HEAD или каталог objects или refs верхнего уровня, появившийся во время выполнения команды в песочнице
  • В ~/.claude или каталоге, на который указывает CLAUDE_CONFIG_DIR: большая часть его содержимого, а также ~/.claude.json и хранилище учётных данных .credentials.json

Если во время сессии по пути защищённого файла настроек появляется символическая ссылка, песочница, начиная со следующей команды, также запрещает запись в файл, на который она указывает.

Исключить какой-либо из этих путей невозможно: запись allowWrite или разрешающее правило Edit, охватывающее путь, не снимает защиту. Единственный способ отключить защиту — filesystem.disabled, который отключает изоляцию файловой системы для всех путей. Чтобы увидеть большинство этих путей в том виде, в каком они разрешаются на вашей машине, выполните /sandbox и откройте вкладку Config, где они перечислены в разделе Denied within allowed вместе с вашими собственными записями denyWrite.

Если git merge или git checkout завершается ошибкой unable to unlink old на одном из этих путей, см. раздел Команда git завершается ошибкой unable to unlink old.

Сетевая изоляция

У команды в песочнице нет прямого доступа к сети:

  • Linux и WSL2: команда выполняется в отдельном сетевом пространстве имён, не подключённом к вашей сети
  • macOS: фреймворк песочницы Seatbelt по умолчанию блокирует все подключения, кроме подключения к прокси песочницы

Claude Code запускает прокси песочницы на вашей машине вне песочницы и направляет к нему команды с помощью HTTP_PROXY, HTTPS_PROXY, ALL_PROXY и связанных переменных окружения. Прокси проверяет имя хоста каждого подключения по вашим разрешённым и запрещённым доменам.

То, к чему может подключиться инструмент, зависит от того, использует ли он прокси:

  • Инструменты, читающие переменные прокси: curl, npm, git по HTTPS и аналогичные инструменты подключаются, как только их хост разрешён. Запись allowedDomains без порта разрешает все порты на этом хосте
  • Инструменты, игнорирующие переменные прокси: обычный ssh, большинство драйверов баз данных и аналогичные инструменты не могут подключиться даже к разрешённому хосту. См. Клиент базы данных или другой не-HTTP инструмент не может подключиться к разрешённому хосту
  • Всё, что не является TCP: UDP, HTTP/3 поверх QUIC и инструменты ICMP, такие как ping, не могут выйти за пределы песочницы

Следующие настройки и поведение определяют, какие хосты разрешает прокси:

  • Ограничения доменов: изначально список разрешённых доменов пуст. В разделе Хосты вне списка разрешённых доменов описано, что происходит, когда команде впервые нужен новый домен.
  • Варианты подтверждения: если при запросе вы выберете Yes, Claude Code разрешит хост до конца текущей сессии. Если вы выберете "Yes, and don't ask again", Claude Code сохранит разрешающее правило WebFetch(domain:...) в ваших локальных настройках, и хост останется разрешённым в будущих сессиях. Пока песочница обязательна по требованию администратора, Claude Code сохраняет правило в ваших пользовательских настройках, где оно применяется во всех проектах.
  • Заранее разрешённые домены: заранее разрешите домены с помощью allowedDomains, чтобы полностью избежать запроса. Claude Code также заранее разрешает домены из разрешающих правил WebFetch(domain:...), как описано в разделе Правила разрешений.
  • Строгий список разрешённых доменов: если вы зададите strictAllowlist значение true в пользовательских, управляемых настройках или настройках CLI --settings, Claude Code будет запрещать командам в песочнице доступ к любому хосту вне списка разрешённых вместо запроса. Список разрешённых состоит из allowedDomains и доменов из разрешающих правил WebFetch(domain:...) либо только из записей управляемых настроек, если задан allowManagedDomainsOnly. Записи репозитория описаны в разделе Блокировки, действующие без обязательной песочницы. Claude Code применяет это только к командам в песочнице; внутрипроцессные инструменты, такие как WebFetch, по-прежнему следуют своим правилам разрешений. Задание этой настройки в .claude/settings.json или .claude/settings.local.json репозитория ни на что не влияет. Требуется Claude Code v2.1.219 или новее.
  • Управляемая блокировка: если в управляемых настройках задан allowManagedDomainsOnly, неразрешённые домены блокируются автоматически без запроса, и учитываются только allowedDomains и разрешающие правила WebFetch(domain:...) из управляемых настроек.
  • Корпоративный прокси: если ваша сеть требует, чтобы исходящий трафик проходил через корпоративный прокси, задайте HTTPS_PROXY, HTTP_PROXY и NO_PROXY, как описано в разделе Конфигурация прокси, в блоке env ваших настроек, чтобы их также получали фоновые агенты, или в окружении, из которого вы запускаете Claude Code. Claude Code применяет список разрешённых доменов, а затем туннелирует разрешённые подключения через этот вышестоящий прокси. Поддерживаются URL прокси http:// и https://, при необходимости с базовой аутентификацией в URL.

В правиле WebFetch(domain:...) песочница учитывает две формы подстановочных знаков: ведущий *., например *.example.com, и одиночный *. Форма с одиночным * требует Claude Code v2.1.186 или новее. Подстановочный знак в любой другой позиции, например WebFetch(domain:example.*), по-прежнему сопоставляется с запросами, но не влияет на команды в песочнице.

Хосты вне списка разрешённых доменов

Когда команда в песочнице подключается к хосту, которого нет в ваших разрешённых доменах, команда остаётся в песочнице и ожидает решения. В интерактивной сессии терминала решение зависит от вашего режима разрешений:

Режим разрешений Что происходит с подключением
Режим bypassPermissions, а также режим планирования при доступном обходе разрешений Разрешается без запроса
Ручной режим, режим acceptEdits и режим планирования в остальных случаях Вы получаете запрос
Авторежим Отклоняется, если команда не указала хост и классификатор не одобрил список
Режим dontAsk Отклоняется

При включённом strictAllowlist или allowManagedDomainsOnly встроенный прокси песочницы отклоняет подключение в любом режиме разрешений. В режиме bypassPermissions хосты вне ваших разрешённых доменов разрешаются, если не включена ни одна из этих настроек. В разделе Запасной выход через повторную попытку вне песочницы описано, когда команда может покинуть песочницу в этом режиме. Подключение к хосту из deniedDomains также отклоняется в любом режиме разрешений.

Имена хостов, разрешающиеся в локальные адреса

После того как имя хоста прошло проверку по списку разрешённых, прокси песочницы разрешает его и отклоняет подключение, если имя разрешается только в локальные адреса. К локальным адресам относятся loopback-адреса, такие как 127.0.0.1, link-local адреса, такие как эндпоинт облачных метаданных 169.254.169.254, и адреса, назначенные вашей собственной машине. Именам localhost и *.localhost разрешено разрешаться в loopback.

Разрешённое имя хоста интрасети, которое разрешается в частный диапазон, такой как 10.0.0.0/8, подключается. Чтобы разрешить имени разрешаться в отклоняемый адрес, добавьте этот IP-адрес в allowedDomains, например "127.0.0.1:8080".

Проверка применяется к именам хостов. Подключение к IP-адресу определяется вашими разрешёнными доменами и режимом разрешений. Прокси также пропускает проверку для подключений, которые он отправляет через вышестоящий корпоративный прокси, поскольку имя разрешает этот прокси.

Разрешённые домены для отдельных команд в авторежиме

В авторежиме с включённой изоляцией в песочнице Claude указывает хосты, необходимые команде, в самой команде, вместо того чтобы запрашивать сетевое подтверждение для каждого подключения. Каждая команда Bash, PowerShell или Monitor, выполняемая в песочнице, может содержать список хостов сверх списка разрешённых песочницы: домен, например registry.npmjs.org, подстановочный шаблон, например *.pythonhosted.org, или IP-адрес, каждый с необязательным :port. Классификатор проверяет хосты вместе с командой. Требуется Claude Code v2.1.271 или новее.

Одобренный список открывает эти хосты только для одной этой команды и только на время её выполнения. Ничего не добавляется ни в разрешённые хосты вашей сессии, ни в ваши настройки; следующая команда указывает собственные хосты.

Команда, содержащая хосты, передаётся классификатору, а не одобряется правилом разрешений или режимом автоматического разрешения песочницы. Если правило ask принудительно вызывает запрос для команды, диалог разрешения в вашем терминале показывает хосты рядом с ней, и подтверждение там распространяется на то и другое.

Список для отдельной команды расширяет только то, что песочница запрещает по умолчанию. Записи deniedDomains по-прежнему блокируют подключения. Когда strictAllowlist или allowManagedDomainsOnly блокирует список разрешённых, Claude Code отклоняет списки для отдельных команд.

Пока действуют списки для отдельных команд, Claude Code отклоняет подключение к хосту, который не указала ни одна одобренная команда, без запроса и без проверки классификатором. Отказ называет хост в результате команды, и Claude повторно запускает команду с добавленным хостом.

IPv6-адреса в списках доменов

Чтобы указать IPv6-адрес в allowedDomains, deniedDomains или правиле WebFetch(domain:...), запишите адрес в квадратных скобках: "[::1]" соответствует этому адресу на любом порту, а "[::1]:443" — только на порту 443. Форма в квадратных скобках требует Claude Code v2.1.229 или новее.

Запись без скобок, например ::1:443, неоднозначна: её можно прочитать и как адрес, и как адрес с портом:

  • Списки запрещённых: Claude Code запрещает все варианты прочтения записи, поэтому блокируется любой вариант, который вы могли иметь в виду. Для записи, не имеющей ни одного допустимого прочтения, Claude Code ничего не блокирует
  • Списки разрешённых: Claude Code никогда не разрешает больше, чем вы написали. Он переписывает неоднозначную запись в прочтение «хост и порт», если оно корректно разбирается, и может полностью отбросить запись, чтобы не расширять список разрешённых

Чтобы найти неоднозначные записи, выполните claude doctor в терминале и найдите предупреждение Sandbox network domain entries have unreliable spellings. Перепишите каждую неоднозначную запись в форме с квадратными скобками.

Применение на уровне ОС

Инструмент Bash в песочнице использует примитивы безопасности операционной системы:

  • macOS: использует Seatbelt для применения песочницы
  • Linux: использует bubblewrap для изоляции
  • WSL2: использует bubblewrap, как и Linux

Вы также можете запустить пакет @anthropic-ai/sandbox-runtime отдельно, чтобы обернуть им процесс Claude Code. См. Среда выполнения песочницы.

Как sandboxing связан с разрешениями и режимами разрешений

Sandboxing, правила разрешений и режимы разрешений являются дополняющими друг друга слоями. Разделы ниже описывают, как sandbox взаимодействует с каждым.

Правила разрешений

Правила разрешений и sandboxing контролируют разные вещи:

  • Правила разрешений контролируют, какие инструменты может использовать Claude Code, и оцениваются перед запуском любого инструмента. Они применяются ко всем инструментам: Bash, Read, Edit, WebFetch, MCP и другим, за исключением того, что правило deny или ask не может заблокировать EndConversation, пока остаётся любой другой инструмент.
  • Sandboxing обеспечивает применение на уровне ОС, которое ограничивает, к чему могут получить доступ команды Bash на уровне файловой системы и сети. Это применяется только к командам Bash, PowerShell и Monitor и их дочерним процессам.

Два слоя также отличаются способом их применения. Claude Code оценивает решения разрешений перед запуском команды на основе строки команды и, в режиме auto, отдельного классификатора, который судит о безопасности команды. Операционная система применяет границу sandbox к работающему процессу, поэтому она действует независимо от того, что выбрала модель для запуска, и даже если разрешённая команда делает больше, чем предполагает её имя.

Ограничения файловой системы и сети настраиваются как через параметры sandbox, так и через правила разрешений:

Параметр или правило Что оно делает
sandbox.filesystem.allowWrite Предоставляет доступ на запись подпроцесса к путям вне рабочего каталога
sandbox.filesystem.denyWrite и sandbox.filesystem.denyRead Блокируют доступ подпроцесса к определённым путям
sandbox.filesystem.allowRead Повторно разрешают чтение определённых путей в области denyRead
sandbox.filesystem.disabled Полностью отключает слой файловой системы, сохраняя при этом изоляцию сети
Правила разрешения Edit Предоставляют доступ на запись к определённым путям, так же как sandbox.filesystem.allowWrite
Правила отказа Read и Edit Блокируют доступ к определённым файлам или каталогам
Правила разрешения и отказа WebFetch(domain:...) Контролируют доступ к доменам
Sandbox allowedDomains Контролирует, к каким доменам могут получить доступ команды Bash
Sandbox deniedDomains Блокирует определённые домены даже когда более широкий подстановочный знак allowedDomains иначе разрешил бы их

Пути и домены из обоих параметров sandbox и правил разрешений объединяются в окончательную конфигурацию sandbox.

Репозиторий claude-code, каталог примеров включает начальные конфигурации параметров для распространённых сценариев развёртывания, включая примеры, специфичные для sandbox. Используйте их как отправные точки и адаптируйте их в соответствии с вашими потребностями.

Режимы разрешений

/sandbox не является режимом разрешений. Режимы разрешений решают, выполняется ли вызов инструмента и запрашивается ли вас сначала, в то время как sandbox ограничивает, к чему может получить доступ команда Bash после её запуска. Они отличаются в том, что они контролируют и что заменяет запрос для каждого действия:

Что контролирует Что заменяет запрос
/sandbox К чему может получить доступ команда Bash после её запуска Сама граница sandbox в режиме автоматического разрешения
Auto mode Выполняется ли каждый вызов инструмента Классификатор, который проверяет действия
--dangerously-skip-permissions Выполняется ли каждый вызов инструмента Ничего. Проверки защищённого пути также пропускаются; действия, которые ни один режим не одобряет автоматически по-прежнему применяются

Режим автоматического разрешения sandbox отличается от режима auto: автоматическое разрешение одобряет команды Bash, потому что граница sandbox их содержит, в то время как режим auto использует классификатор для проверки действий. Два работают независимо и могут быть объединены, с исключениями, перечисленными в разделе Sandbox modes. Чтобы выбрать границу изоляции для автоматических запусков, см. Sandbox environments. Для таблицы распространённых пар режимов разрешений и sandbox с флагами, которые запускают каждый из них, см. Common setups.

Настройка песочницы для вашей организации

Администраторы могут требовать изоляцию в песочнице для каждого пользователя, не давать разработчикам расширять политику и направлять трафик песочницы через корпоративный прокси.

Принудительная изоляция в песочнице с помощью управляемых настроек

Чтобы требовать песочницу для каждого разработчика, доставьте ключи sandbox через управляемые настройки: либо как файл, управляемый вашей MDM, либо через серверные управляемые настройки на claude.ai.

Следующая конфигурация управляемых настроек включает песочницу, запрещает запуск Claude Code, если платформа не поддерживается или отсутствует зависимость, и не позволяет модели повторять команды вне песочницы:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

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

  • failIfUnavailable: отсутствующая зависимость, такая как bubblewrap на Linux, блокирует запуск Claude Code вместо возврата к выполнению без изоляции
  • allowUnsandboxedCommands: false: Claude Code игнорирует механизм выхода dangerouslyDisableSandbox, поэтому, когда команда завершается ошибкой в песочнице, Claude не может повторить её вне песочницы

Рассмотрите также следующие дополнения:

  • Добавьте excludedCommands для любых одобренных организацией инструментов, которые должны выполняться без изоляции, поскольку эта конфигурация не позволяет настройкам репозитория выводить команды из песочницы
  • Добавьте записи sandbox.credentials для каталогов учётных данных, таких как ~/.aws и ~/.ssh, и для переменных окружения с секретами, поскольку политика чтения по умолчанию всё ещё разрешает к ним доступ

Эта конфигурация изолирует в песочнице команды, которые выполняет Claude. Разработчик по-прежнему может ввести команду в приглашении shell-режима ! и выполнить её вне песочницы с тем же доступом, который у него уже есть в любом терминале вне Claude Code. Сессии, в которых введённые команды выполняются в песочнице, описаны в разделе строгий режим песочницы.

Песочница не работает на нативной Windows, поэтому при установленном failIfUnavailable Claude Code завершает работу при запуске на таких машинах. Если ваш парк включает хосты Windows, вы можете:

  • Доставлять конфигурацию в зависимости от операционной системы: разверните её через MDM или как файл управляемых настроек только на машинах с macOS и Linux. Серверные управляемые настройки применяются ко всем пользователям организации
  • Перевести пользователей Windows в поддерживаемую среду: попросите их запускать Claude Code внутри WSL2 или контейнера

Запрет разработчикам расширять политику

Когда управляемые настройки задают логический ключ, такой как enabled или failIfUnavailable, Claude Code использует управляемое значение и игнорирует всё, что разработчик задаёт локально. Для ключей-массивов, таких как allowRead, Claude Code объединяет записи из областей действия, которые загружает сессия, поэтому разработчик может добавлять записи, расширяющие политику, если этот ключ не защищён блокировкой.

Если управляемые настройки их не задают, пользовательские настройки разработчика или --settings могут включить следующие ключи. Файл .claude/settings.json репозитория тоже может это сделать, если только песочница не является обязательной по требованию администратора. Каждый из них ослабляет песочницу, поэтому установите его в false в управляемых настройках, если не хотите, чтобы он использовался:

Установите allowManagedReadPathsOnly в true в управляемых настройках, чтобы учитывались только записи allowRead из управляемых настроек. Это не позволяет разработчикам расширять доступ на чтение за пределы одобренных организацией путей.

Чтобы таким же образом закрепить сетевые домены за управляемыми значениями, установите allowManagedDomainsOnly. При включённой блокировке порт прокси могут задавать только управляемые настройки.

Когда управляемые настройки настраивают sandbox.filesystem или содержат любую запись sandbox.credentials.files с "mode": "deny", только управляемые настройки могут задать filesystem.disabled, поэтому разработчики не могут отключить ограничения файловой системы, развёрнутые администратором. Допустимая запись mask не закрепляет этот ключ. См. раздел Какие настройки могут её отключить.

Настройки репозитория при обязательной песочнице

Песочница является обязательной по требованию администратора, пока действует одна из следующих настроек:

  • allowUnsandboxedCommands установлен в false в управляемых настройках или через флаг --settings, если только управляемые настройки не устанавливают его в true
  • allowManagedDomainsOnly установлен в true в управляемых настройках

Эти настройки не включают песочницу, поэтому также задайте enabled.

Пока песочница обязательна по требованию администратора, Claude Code принимает настройки, ослабляющие её, только из управляемых настроек, флага --settings и файла ~/.claude/settings.json каждого разработчика. Он игнорирует эти настройки в файлах .claude/settings.json и .claude/settings.local.json репозитория:

Настройка репозитория Что игнорирует Claude Code
excludedCommands, ignoreViolations, network.allowedDomains, network.allowUnixSockets, network.allowMachLookup, network.httpProxyPort, network.socksProxyPort Каждую запись
filesystem.allowWrite, правила разрешения Edit(...), permissions.additionalDirectories Доступ на запись, который каждая запись даёт командам в песочнице. Файловые инструменты Claude по-прежнему следуют правилам Edit(...) и дополнительным каталогам
Правила разрешения WebFetch(domain:...) Хост, который каждое правило добавляет в список разрешённых доменов песочницы. Инструмент WebFetch по-прежнему следует правилу
enableWeakerNestedSandbox, enableWeakerNetworkIsolation, network.allowAllUnixSockets, network.allowLocalBinding true. Значение false по-прежнему применяется
enabled, failIfUnavailable false, если ~/.claude/settings.json разработчика задаёт true
filesystem.allowRead Запись, указывающую на путь или путь внутри него, чтение которого запрещают управляемые настройки, --settings или пользовательские настройки, либо glob-шаблон, который может ему соответствовать

Пока песочница обязательна по требованию администратора, по-прежнему применяются следующие настройки:

  • В файлах репозитория: записи запрета и значение autoAllowBashIfSandboxed. Задайте этот ключ в управляемых настройках, чтобы репозиторий не мог его изменить
  • В собственных настройках разработчика: настройки из таблицы по-прежнему применяются из ~/.claude/settings.json или --settings, если только их не защищает блокировка только для управляемых настроек, такая как allowManagedDomainsOnly. Для большинства из них, например excludedCommands и filesystem.allowWrite, такой блокировки нет

Конфигурация из раздела Принудительная изоляция в песочнице с помощью управляемых настроек делает песочницу обязательной по требованию администратора. Добавьте в управляемые настройки записи excludedCommands, allowWrite и записи сокетов, необходимые вашим одобренным инструментам, поскольку репозиторий не может их предоставить.

Требуется Claude Code v2.1.285 или новее. В версиях с v2.1.282 по v2.1.284 те же настройки заставляли Claude Code игнорировать записи excludedCommands репозитория.

Блокировки, действующие без обязательной песочницы

Некоторые настройки заставляют Claude Code игнорировать ключи репозитория, которые напрямую переопределяют одно ограничение, даже если песочница не является обязательной по требованию администратора. Каждая из них действует так, только если задана в файле, указанном в её строке, а остальные настройки песочницы репозитория по-прежнему применяются. Требуется Claude Code v2.1.285 или новее.

Настройка Где её задать Что Claude Code игнорирует в настройках репозитория
network.deniedDomains или правило запрета WebFetch(domain:...) Управляемые настройки, --settings httpProxyPort и socksProxyPort
network.strictAllowlist Управляемые настройки, --settings, пользовательские настройки Порты прокси, allowedDomains и правила разрешения WebFetch(domain:...)
filesystem.denyRead, правило запрета Read(...) или запись credentials.files Управляемые настройки, --settings Запись allowRead, allowWrite, правило разрешения Edit(...) или additionalDirectories, указывающую на путь или путь внутри него, чтение которого запрещают управляемые настройки, --settings или пользовательские настройки, либо glob-шаблон, который может ему соответствовать

Эти блокировки меняют то, к чему могут обращаться команды в песочнице. Инструмент WebFetch и файловые инструменты Claude по-прежнему следуют правилам и дополнительным каталогам репозитория.

Конфигурация пользовательского прокси

Чтобы проверять, фильтровать или записывать в лог трафик песочницы с помощью собственных инструментов, замените встроенный прокси песочницы прокси-сервером, который вы запускаете на той же машине.

Чтобы направить трафик песочницы через корпоративный прокси в другом месте вашей сети, вместо этого задайте HTTPS_PROXY, как описано в пункте Корпоративный прокси в разделе Сетевая изоляция. Так список разрешённых доменов Claude Code по-прежнему будет применяться.

Чтобы направить команды в песочнице на ваш прокси, задайте порты localhost, которые он прослушивает, в настройках песочницы:

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Если вы задаёте порт и одновременно задаёте HTTPS_PROXY или HTTP_PROXY, Claude Code не пересылает то, что команды в песочнице отправляют вашему прокси, дальше на прокси, указанный в этих переменных. Чтобы обращаться к корпоративному прокси, настройте пересылку на него в собственном прокси.

Какие файлы могут задавать порт, зависит от остальных настроек песочницы:

Claude Code игнорирует порт, заданный в любом другом месте. До v2.1.285 порт мог задавать любой файл настроек.

Устранение неполадок

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

Если песочница в вашей организации обязательна по требованию администратора, Claude Code игнорирует указанные в этих исправлениях настройки в файлах настроек проекта, поэтому сохраняйте их в ~/.claude/settings.json, где они применяются во всех проектах. Если исправление по-прежнему не действует, возможно, этот ключ задан в управляемых настройках вашей организации.

Исправление, которое добавляет шаблон в excludedCommands, выводит из песочницы команды, соответствующие этому шаблону. См. раздел о том, что может делать исключённая команда.

Команды не выполняются с ошибкой host-not-allowed

Многим инструментам CLI нужен доступ к определённым хостам. Одобрите хост при появлении запроса или добавьте его в allowedDomains. Если ваша организация блокирует список разрешённых доменов с помощью allowManagedDomainsOnly, запрос не появляется, поэтому попросите администратора добавить хост.

`jest` зависает или не выполняется

watchman несовместим с песочницей. Вместо этого запустите jest --no-watchman.

CLI на Go не проходят проверку TLS на macOS

Такие инструменты, как gh, gcloud и terraform, могут не проходить проверку TLS под Seatbelt. Чтобы запускать эти инструменты вне песочницы, добавьте шаблон для каждого инструмента, например gh *, в excludedCommands. Тогда инструмент выполняется с вашим полным доступом и своими сохранёнными учётными данными. Если вы используете httpProxyPort с MITM-прокси и пользовательским CA, вместо этого установите enableWeakerNetworkIsolation в true.

`open`, `osascript` или потоки аутентификации через браузер не выполняются с ошибкой `-600` на macOS

Песочница по умолчанию блокирует Apple Events. Установите allowAppleEvents в true в пользовательских, управляемых или CLI-настройках, чтобы разрешить их. Claude Code игнорирует этот ключ в настройках проекта.

Включение allowAppleEvents снимает изоляцию выполнения кода, так как изолированные команды смогут запускать другие приложения вне песочницы без запроса пользователю и отправлять команды AppleScript запущенным приложениям с учётом запроса согласия на автоматизацию macOS (TCC). В качестве альтернативы добавьте шаблон, например open *, в excludedCommands. Тогда каждый вызов open проходит через процедуру запроса разрешения, а open может запустить любой файл или приложение, включая созданное Claude.

Команды `docker` не выполняются

docker несовместим с песочницей. Выведите нужные вам команды docker из песочницы с помощью шаблона excludedCommands, например docker compose *. В разделе Запуск команд вне песочницы с помощью excludedCommands объясняется, к чему может получить доступ исключённая команда docker. Более узкий шаблон выводит из песочницы меньше команд.

`pbcopy`, `xclip` или `wl-copy` не обновляют буфер обмена

Утилиты буфера обмена pbcopy, xclip и wl-copy могут не получить доступ к системному буферу обмена изнутри песочницы, и в этом случае переданный им текст не поступает.

Чтобы поместить вывод Claude в ваш буфер обмена, попросите Claude напечатать его в своём ответе, затем запустите /copy. /copy записывает в буфер обмена из процесса Claude Code, а не из изолированной команды.

Когда Claude передаёт текст одному из этих инструментов, добавление инструмента в excludedCommands само по себе не выводит этот вызов из песочницы.

git merge, git checkout и подобные команды завершаются ошибкой unable to unlink old, когда им нужно заменить файл, запись в который запрещена песочницей. На Linux и WSL2 ошибка заканчивается на Read-only file system. Файл может находиться в одном из следующих мест:

  • Под защищённым путём, таким как .claude/skills
  • Под одной из ваших записей denyWrite
  • Вообще вне каталогов, в которые песочница позволяет командам писать

После сбоя Claude может предложить повторно запустить команду вне песочницы. Одобрите эту повторную попытку или запустите команду git самостоятельно в другом терминале. Если вы установили allowUnsandboxedCommands в false, Claude не может предложить повторную попытку, поэтому запустите команду самостоятельно.

Bubblewrap не запускается внутри контейнера

В непривилегированном контейнере bubblewrap не может смонтировать новую файловую систему /proc, поэтому изолированные команды завершаются ошибкой bwrap, например Can't mount proc on /newroot/proc: Operation not permitted. Установите enableWeakerNestedSandbox в true, чтобы песочница вместо этого выполняла bind-монтирование существующего /proc контейнера. Используйте эту настройку только тогда, когда внешний контейнер уже обеспечивает нужную вам границу изоляции, так как она раскрывает изолированным командам информацию о процессах, которую скрыло бы новое монтирование /proc.

В путях настроек `.claude` появляются файлы размером 0 байт только для чтения, и «Да, и больше не спрашивать» не сохраняется

На Linux и WSL2 песочница удерживает запрет на запись в ещё не существующий файл, создавая там 0-байтовый заполнитель только для чтения, пока выполняется изолированная команда. После этого песочница удаляет заполнитель. Если сессия принудительно завершается до выполнения этой очистки, например по SIGKILL, заполнители остаются. Последующие сессии при каждом запуске снова монтируют их только для чтения, поэтому запись настроек, например сохранение выбора разрешения, не выполняется там, где остаётся такой заполнитель.

Запустите claude doctor в терминале, чтобы перечислить оставшиеся файлы заполнителей. Предупреждение Stale sandbox mask files left by a killed session называет некоторые из них и подсчитывает остальные. Удалите каждый файл с помощью rm, пока в этом проекте не запущена другая сессия Claude Code. До версии 2.1.257 Claude Code оставлял те же заполнители, не помечая их.

`git` через SSH не работает при включённой песочнице

На macOS git fetch, git pull и git push для удалённого репозитория по SSH не выполняются внутри песочницы, даже если хост разрешён. На Linux и WSL2 они работают, как только хост разрешён. Claude Code туннелирует SSH-соединение git через прокси песочницы, а туннель на macOS не может пройти аутентификацию на этом прокси.

На Linux и WSL2 проверьте следующее, если соединение по-прежнему не устанавливается:

  • Хост разрешён на порту 22: это покрывает запись allowedDomains без порта, например "git.example.com"
  • Ваш корпоративный прокси разрешает порт 22: если ваша сеть требует вышестоящего прокси, туннель также проходит через него
  • Ключ доступен для чтения как файл: песочница может блокировать сокет ssh-agent, а запись denyRead или credentials для ~/.ssh скрывает ваши файлы ключей

На macOS переключите удалённый репозиторий на HTTPS, для чего нужны учётные данные HTTPS, например персональный токен доступа:

git remote set-url origin https://git.example.com/example-org/example-repo.git

Если вам нужно сохранить удалённый репозиторий по SSH, выведите сетевые команды git из песочницы с помощью excludedCommands:

{
  "sandbox": {
    "excludedCommands": ["git fetch *", "git pull *", "git push *"]
  }
}

Эти записи соответствуют git push origin main. Вызов, который добавляет cd, использует git -C или содержит подстановку команды, остаётся в песочнице. Исключённые команды git могут обращаться к любому хосту, а не только к указанным в allowedDomains.

Обычные ssh, scp и rsync через SSH не работают по причине, указанной в пункте о клиентах баз данных.

Клиент базы данных или другой не-HTTP инструмент не может подключиться к разрешённому хосту

Инструмент, который игнорирует переменные окружения прокси, не может подключиться изнутри песочницы даже к хосту из allowedDomains. У изолированной команды нет прямого маршрута в сеть, поэтому инструмент, открывающий собственное соединение, завершается сбоем. Так ведут себя большинство драйверов баз данных, обычный ssh и инструменты, использующие UDP.

Сбой выглядит как ошибка сети или разрешения имён:

  • macOS: Operation not permitted или ошибка разрешения имён, например Could not resolve host
  • Linux и WSL2: Network is unreachable или ошибка разрешения имён, например Temporary failure in name resolution

Инструмент, который использует прокси, завершается сбоем иначе, если его хост не разрешён. Вы получаете запрос на доступ к сети, или инструмент получает от прокси ответ 403.

Чтобы инструмент мог подключиться, запустите команду, которой он нужен, вне песочницы с помощью excludedCommands. В этом примере исключается один скрипт и добавляется правило ask, чтобы вы одобряли каждый запуск:

{
  "sandbox": {
    "excludedCommands": ["python scripts/load_orders.py *"]
  },
  "permissions": {
    "ask": ["Bash(python scripts/load_orders.py *)"]
  }
}

Скрипт выполняется с вашим полным доступом, а Claude может редактировать скрипт, находящийся в вашем рабочем каталоге, поэтому проверяйте его при появлении запроса.

Команда не может подключиться к серверу на localhost

По умолчанию изолированная команда не может напрямую подключиться к серверу, запущенному на вашем компьютере вне песочницы, например к dev-серверу или базе данных в контейнере. Что можно изменить, зависит от вашей платформы:

  • macOS: установите network.allowLocalBinding в true. Тогда изолированные команды смогут прослушивать сетевые порты и подключаться к любому порту на localhost, включая все остальные сервисы, которые там слушают. Сервис на localhost, не требующий аутентификации, например отладчик, сможет действовать от имени команды вне песочницы, а команда, прослушивающая адрес, отличный от loopback, будет принимать соединения с других машин
  • Linux и WSL2: localhost изолированной команды является приватным для этой команды. Команда может прослушивать порт и обращаться к серверам, которые она запустила сама. Прямое подключение к localhost или 127.0.0.1 не достигает серверов на хосте, а allowLocalBinding не действует. Запустите команду, которой нужен сервер хоста, вне песочницы с помощью excludedCommands, где у неё нет ограничений файловой системы и сети. О соединениях, проходящих через прокси песочницы, см. Имена хостов, разрешающиеся в локальные адреса

В этом примере настройка включается для macOS:

{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

Запись allowedDomains для localhost применяется к соединениям, проходящим через прокси, поэтому она не влияет на прямое подключение. Claude Code задаёт NO_PROXY для изолированных команд, чтобы они подключались к localhost напрямую, а не через прокси. Кроме того, эта запись открывает все порты localhost вашего компьютера для команды, которая всё же использует прокси. Об имени хоста для разработки, указывающем на 127.0.0.1, см. Разрешённое имя хоста отклоняется с resolved to a loopback address.

Разрешённое имя хоста отклоняется с `resolved to a loopback address`

Прокси песочницы отклоняет разрешённое имя хоста, которое разрешается в локальный адрес; это затрагивает имена для разработки, такие как myapp.test, указывающие на 127.0.0.1. Команда получает ответ 403, тело которого называет тип адреса, например Connection to myapp.test blocked: resolved to a loopback address.

Добавьте IP-адрес, в который разрешается имя, рядом с именем хоста в allowedDomains, каждый с портом, который прослушивает ваш сервер:

{
  "sandbox": {
    "network": {
      "allowedDomains": ["myapp.test:3000", "127.0.0.1:3000"]
    }
  }
}

Запись IP-адреса без порта позволяет изолированным командам обращаться ко всем сервисам, прослушивающим этот адрес.

До версии 2.1.284 прокси подключался к любому адресу, в который разрешалось разрешённое имя хоста.

`/sandbox` завершается ошибкой `Sandbox settings are overridden by a higher-priority configuration`

/sandbox выводит Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally. вместо открытия своей панели, когда более высокий уровень настроек задаёт sandbox.enabled, sandbox.autoAllowBashIfSandboxed или sandbox.allowUnsandboxedCommands. Панель сохраняет ваш выбор в .claude/settings.local.json, а сохранённое там значение не может переопределить эти уровни.

Управляемые настройки и --settings имеют более высокий приоритет, чем локальные настройки. Чтобы узнать, какие из них загружены в этой сессии, запустите /status и посмотрите строку Setting sources:

  • Command line arguments: если вы запустили Claude Code с --settings, проверьте, задаёт ли переданный файл или JSON один из этих ключей. Если да, измените значение там или запустите Claude Code заново без этих ключей.
  • Enterprise managed settings: загружены управляемые настройки вашей организации. Если они задают один из этих ключей, вы не можете изменить его ни через /sandbox, ни через какой-либо файл настроек, которым вы управляете, поэтому обратитесь к администратору.

Ограничения

Sandboxing снижает риск, но не является полной границей изоляции. Просмотрите ограничения ниже перед тем, как полагаться на него как на жёсткий контроль безопасности.

Ограничения безопасности

  • Фильтрация сети: sandbox ограничивает домены, к которым процессы могут подключаться. По умолчанию встроенный прокси не завершает и не проверяет TLS исходящего трафика, поэтому содержимое зашифрованных соединений не проверяется. Экспериментальный параметр network.tlsTerminate завершает TLS на прокси для подстановки учётных данных mask, но не добавляет фильтрацию содержимого. Вы несёте ответственность за обеспечение того, чтобы в вашей политике разрешались только доверенные домены.
  • Повышение привилегий через Unix sockets: конфигурация allowUnixSockets может случайно предоставить доступ к системным сервисам, которые могут привести к обходам sandbox. Например, разрешение доступа к /var/run/docker.sock фактически предоставляет доступ к хост-системе через сокет Docker. Тщательно рассмотрите любые Unix sockets, которые вы разрешаете через sandbox.
  • Повышение привилегий разрешений файловой системы: чрезмерно широкие разрешения на запись в файловую систему могут включить атаки повышения привилегий. Разрешение записи в каталоги, содержащие исполняемые файлы в $PATH, каталоги конфигурации системы или файлы конфигурации оболочки пользователя, такие как .bashrc или .zshrc, может привести к выполнению кода в разных контекстах безопасности, когда другие пользователи или системные процессы получают доступ к этим файлам.
  • Сила Linux sandbox: реализация Linux обеспечивает сильную изоляцию файловой системы и сети, но включает режим enableWeakerNestedSandbox, который позволяет ему работать внутри окружений Docker без привилегированных пространств имён. Эта опция значительно ослабляет безопасность и должна использоваться только когда дополнительная изоляция иным образом применяется.
  • Apple Events на macOS: sandbox на macOS по умолчанию блокирует Apple Events. Параметр allowAppleEvents снимает это ограничение, чтобы инструменты, такие как open и osascript, работали, но он удаляет изоляцию выполнения кода: изолированные команды могут запускать другие приложения без изоляции без запроса пользователя и могут отправлять команды AppleScript запущенным приложениям, в соответствии с запросом согласия на автоматизацию macOS для каждого приложения (TCC). Это учитывается только из пользовательских, управляемых или CLI параметров. Параметры проекта не могут включить это.

Область действия

Песочница изолирует shell-команды и их дочерние процессы. В разделе Что работает вне песочницы перечислены инструменты и вспомогательные процессы, которые она не охватывает. Использование компьютера и субагенты связаны с песочницей следующим образом:

  • Использование компьютера: когда Claude открывает приложения и управляет вашим экраном, он работает на вашем фактическом рабочем столе, а не в изолированной среде. Запросы разрешений для каждого приложения контролируют каждое приложение. См. computer use in the CLI или computer use in Desktop.
  • Субагенты: субагенты работают в том же процессе, что и родительская сессия, и используют ту же конфигурацию sandbox. Команды Bash внутри субагента изолированы, когда изоляция в песочнице включена в родительской сессии.
  • Моды: мод — это плагин, который запускает собственный код внутри Claude Code, и процесс, запущенный модом, работает вне песочницы. См. Что доступно моду.

См. также

  • Sandbox environments: сравните встроенный sandbox с dev containers, контейнерами и ВМ
  • Security: комплексные функции безопасности и лучшие практики
  • Permissions: конфигурация разрешений и контроль доступа
  • All settings: каждый ключ параметров
  • CLI reference: параметры командной строки