SpyBara
Go Premium

sandboxing.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

This page contains 110 additions and 92 deletions.

2026
Thu 10 23:00 Sat 12 03:02 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

Настройка изолированного инструмента Bash

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

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

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

Sandbox встроен в Claude Code и работает на macOS, Linux и WSL2. Нативная Windows не поддерживается. На Windows запустите Claude Code внутри дистрибьютива WSL2.

На macOS нет необходимости в установке: sandboxing использует встроенную платформу Seatbelt. На Linux и WSL2 sandbox зависит от двух пакетов, описанных в разделе Настройка Linux и WSL2. Даже если вы их ещё не установили, вы можете начать с /sandbox, так как его панель показывает, что-либо отсутствует.

1

Запустите /sandbox

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

/sandbox

Это открывает панель sandbox с тремя вкладками, плюс вкладка Dependencies на Linux, когда отсутствует опциональный фильтр seccomp:

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

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

2

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

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

3

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

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

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

Команды, которые не могут выполняться в sandbox, возвращаются к обычному потоку разрешений. Claude Code озаглавливает их запрос разрешения как "Bash command (unsandboxed)" вместо "Bash command", чтобы вы могли определить, какие команды выполнялись вне sandbox. Чтобы расширить или сузить эти границы, см. Настройка sandboxing.

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

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

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

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

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

На Linux и WSL2 sandbox зависит от двух пакетов:

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

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

sudo apt-get install bubblewrap socat

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

Ripgrep поставляется в комплекте с нативным двоичным файлом Claude Code. Фильтр seccomp является опциональным и добавляет блокировку Unix domain socket. Установите его с помощью 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`, а не к командам, которые он выполняет внутри sandbox. Перезагрузите AppArmor, чтобы применить его:

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

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

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

Режимы sandbox

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

Режим автоматического разрешения

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

Даже в режиме автоматического разрешения применяется следующее:

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

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

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

Механизм выхода для неизолированного повтора

Некоторые команды вообще не могут выполняться внутри sandbox, такие как инструменты, несовместимые с ним, или те, которые требуют хоста, который вы не разрешили. Claude Code сообщает о нарушениях sandbox в результате заблокированной команды, называя путь или хост, который sandbox отклонил, чтобы Claude видел, что sandbox заблокировал. Вместо того чтобы не выполнить задачу или потребовать отключения sandboxing, Claude Code включает механизм выхода: Claude анализирует нарушение и может повторить команду с параметром dangerouslyDisableSandbox.

Повторная команда выполняется вне sandbox, поэтому она проходит через обычный поток разрешений. В режиме Manual вы получаете запрос подтверждения. В режиме auto классификатор оценивает базовую команду. Пока permissions.blockReadsOutsideWorkingDirectories включен, повтор, который требует одобрения для выполнения вне sandbox, запрашивает у вас разрешение вместо этого. Чтобы получить запрос на каждый неизолированный повтор даже в режиме auto, добавьте правило ask для Bash(dangerouslyDisableSandbox:true).

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

Режим strict sandbox применяется к командам, которые выполняет Claude. Команды, которые вы вводите сами в приглашение shell-mode с префиксом !, выполняются вне sandbox, если только сеанс не является одним из следующих:

  • Фоновый сеанс: режим strict sandbox охватывает и команды shell-mode
  • Сеанс Linux с установленной переменной CLAUDE_CODE_SUBPROCESS_ENV_SCRUB: каждая команда выполняется в sandbox, включая команды shell-mode

До версии 2.1.260 режим strict sandbox изолировал команды shell-mode в каждом сеансе.

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

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

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

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

По умолчанию команды в песочнице могут писать в текущий рабочий каталог, временный каталог сеанса и любые каталоги, которые вы добавили с помощью --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 остаётся /tmp/build
~/ Относительно домашнего каталога ~/.kube становится $HOME/.kube
./ или без префикса Относительно корня проекта для параметров проекта или относительно ~/.claude для параметров пользователя ./output в .claude/settings.json разрешается в <project-root>/output

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

Вы также можете запретить доступ на запись или чтение, используя 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 вместо написания правил путей.

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

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

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

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

Параметр отключён по умолчанию и применяется на платформах, где работает песочница: macOS, Linux и WSL2. Требуется 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 из каждого источника, включая управляемые параметры, и сохраняет изоляцию файловой системы включённой.

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

Управляемая запись Закрепляет filesystem.disabled Что защищает файл при отключённой изоляции
"mode": "deny" Да Ничего: блок чтения является частью слоя файловой системы
"mode": "mask", применённый как маска Нет Сама маскировка: копия-дозорный и прокси на Linux и WSL2, собственные правила чтения песочницы на macOS
"mode": "mask", вернулся к deny при настройке Нет Ничего, как deny. Перечислите путь, который не может быть замаскирован, такой как каталог, как явную запись deny, которая закрепляет ключ
"mode": "mask", деградирован к deny валидацией Да, как явная запись deny Ничего, как deny

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

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

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

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

Два других вещи изменяются:

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

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

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

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

Параметр sandbox.credentials объявляет файлы учётных данных и переменные окружения для защиты от команд в песочнице. Каждая запись называет путь файла или переменную окружения и mode. Выделенный блок credentials сохраняет правила учётных данных сгруппированными вместе и отдельно от общих правил файловой системы. Требуется Claude Code v2.1.187 или позже.

Для записей с "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.

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

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

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

"mode": "mask" защищает учётные данные, сохраняя при этом работающими инструменты, которые аутентифицируются с ними. deny полностью удаляет переменную, что также нарушает инструменты, которые её нужны, такие как gh или npm. Требуется Claude Code v2.1.199 или позже.

С mask команда в песочнице видит значение дозорного для каждого сеанса вместо реального. Каждая запись mask может перечислять injectHosts, хосты, которым разрешено достичь реальное значение. Когда запрос покидает песочницу для одного из них, прокси песочницы заменяет дозорный на реальное значение. Команда и всё, что она регистрирует, никогда не содержат реальные учётные данные, но её запросы по-прежнему аутентифицируются.

Прокси подставляет учётные данные внутри содержимого запроса, поэтому он должен их видеть. Установите network.tlsTerminate, чтобы прокси сам завершал TLS.

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

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

Прокси вводит только на соединениях, которые список разрешённых доменов допускает, поэтому каждое назначение injectHosts также должно быть достижимо через network.allowedDomains.

Пример ниже маскирует два токена. 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" }
      ]
    }
  }
}

Напишите назначение IPv6 по-разному в двух списках, потому что каждый список имеет свой собственный сопоставитель:

  • network.allowedDomains: форма в скобках, которую используют списки доменов, такая как "[::1]". Прокси проверяет этот список, чтобы допустить соединение.
  • injectHosts: голый адрес в его канонической сжатой форме, такой как "::1" или "2001:db8::1". Прокси сопоставляет каждую запись с голым адресом назначения соединения, игнорируя порты, поэтому скобочная, зональная или иначе сжатая орфография никогда не совпадает и прокси никогда не вводит учётные данные там.

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

В отличие от deny, маскировка уполномочивает прокси отправлять ваши реальные учётные данные на перечисленные хосты, поэтому Claude Code соблюдает её только из параметров, которые вы или ваш администратор контролируете: параметры пользователя, управляемые параметры и флаг CLI --settings. Claude Code игнорирует записи mask в .claude/settings.json или .claude/settings.local.json репозитория. В этих файлах он также игнорирует network.tlsTerminate и credentials.allowPlaintextInject, параметр, который позволяет прокси вводить учётные данные в незашифрованные запросы. Если вы исключите параметры пользователя, Claude Code отбрасывает записи mask переменной окружения в ~/.claude/settings.json тоже.

Когда ваш администратор доставляет записи mask, network.tlsTerminate или credentials.allowPlaintextInject через управляемые параметры сервера, они считаются параметрами, которые нуждаются в одобрении.

Когда одна и та же переменная указана с deny в любой области, deny имеет приоритет.

Маскировка заменяет всё значение переменной по умолчанию, что подходит для голого токена. Дополнительные поля записи, которые требуют Claude Code v2.1.224 или позже, обрабатывают значения со структурой:

  • extract: регулярное выражение, которое Claude Code применяет по всему значению, заменяя только текст, захваченный группой 1 каждого совпадения, поэтому инструмент, который анализирует значение, такой как строка подключения DATABASE_URL, по-прежнему работает внутри песочницы. Шаблон должен содержать по крайней мере одну захватывающую группу.
  • onExtractNoMatch контролирует, что происходит, когда шаблон ничего не совпадает:
    • warn, по умолчанию, предупреждает и передаёт переменную без маскировки
    • deny не устанавливает переменную внутри песочницы
    • error останавливает настройку песочницы, пока вы не исправите конфигурацию
  • decode: "jwt": для переменной, содержащей JSON Web Token (JWT). Claude Code проверяет, что значение является JWT, и заменяет его структурно действительным поддельным токеном, поэтому код внутри песочницы, который декодирует токен, продолжает работать. Добавьте maskClaims для перечисления утверждений полезной нагрузки верхнего уровня для маскировки отдельно вместо замены всего токена; другие утверждения остаются читаемыми. Когда значение не проверяется как JWT или ни одно перечисленное утверждение не совпадает, Claude Code передаёт переменную без маскировки с предупреждением. decode не может быть объединён с extract.

Полный список полей см. в строках credentials.envVars[] в справке параметров.

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

Запросы AWS содержат подписи SigV4 по содержимому запроса, поэтому маскируйте AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY вместе. Прокси обнаруживает запрос SigV4 по дозорному ключа доступа и повторно подписывает его после подстановки реальных значений. Маскировка только секрета оставляет запросы подписанными с заполнителем, который прокси не может обнаружить, поэтому они не удаются в AWS; Claude Code предупреждает об этом случае при запуске, но не когда маскирован только ID ключа доступа. Обнаруженный запрос, который прокси не может повторно подписать, такой как запрос без заголовка x-amz-date, не удаётся с ошибкой прокси вместо достижения сервера с нарушенной подписью.

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

{
  "sandbox": {
    "credentials": {
      "awsPairs": [
        {
          "accessKeyIdVar": "MY_KEY_ID",
          "secretAccessKeyVar": "MY_SECRET_KEY",
          "sessionTokenVar": "MY_SESSION_TOKEN"
        }
      ]
    }
  }
}

Каждая запись следует этим правилам:

  • accessKeyIdVar и secretAccessKeyVar называют записи envVars с маскировкой, содержащие ID ключа доступа и секретный ключ. Дополнительный sessionTokenVar называет запись, содержащую токен сеанса для временных учётных данных; когда установлен, прокси отправляет реальный токен как x-amz-security-token на повторно подписанных запросах.
  • Каждая названная переменная должна быть записью mask, которая маскирует своё целое значение, без extract или decode.
  • Прокси повторно подписывает запросы на хостах, перечисленных в записи ID ключа доступа injectHosts.
  • Именование любой из обычных переменных в паре заменяет автоматическое спаривание.

Как записи mask, awsPairs соблюдается только из параметров пользователя, управляемых параметров и флага CLI --settings.

Три формы запросов AWS содержат подписи, которые прокси не может пересчитать. Когда такой запрос подписан с заполнителем маскированной пары, прокси не удаётся вместо пересылки нарушенной подписи; запросы, подписанные немаскированными учётными данными, никогда не затрагиваются. Параметр credentials.sigv4, который требует Claude Code v2.1.224 или позже, ослабляет это для каждой формы: установка ключа формы на passthrough пересылает запрос с его подписью, полученной из заполнителя, поэтому вызывающий инструмент получает собственный ответ отказа AWS вместо ошибки прокси. Как awsPairs, sigv4 соблюдается только из параметров пользователя, управляемых параметров и флага CLI --settings.

Форма запроса Ключ sigv4 Почему прокси не может повторно подписать его
потоковые загрузки aws-chunked streaming Подписи для каждого блока связаны с подписью семени, поэтому повторное подписание потребовало бы переписания тела
Предподписанные URL presigned Подпись находится в самом URL, без заголовка Authorization
Асимметричные подписи SigV4A sigv4a Нет общего ключа HMAC для пересчёта

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

Записи файлов также принимают "mode": "mask", что требует Claude Code v2.1.221 или позже. То, что видит команда в песочнице, зависит от платформы:

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

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

Пример ниже маскирует токен GitHub, хранящийся в ~/.config/gh/hosts.yml; шаблон extract, описанный ниже, сообщает Claude Code, какая часть файла является секретом. На Linux и WSL2 команды в песочнице, которые читают файл, получают дозорный вместо токена, и прокси подставляет реальный токен на запросах к api.github.com:

{
  "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 чтение не удаётся вместо этого.

На Linux и WSL2 шаблон extract — это то, что сохраняет остальную часть hosts.yml читаемой. Claude Code применяет регулярное выражение по всему файлу и заменяет только текст, захваченный группой 1 каждого совпадения, поэтому gh по-прежнему анализирует свою конфигурацию и только токен является заполнителем. Используйте extract для любого структурированного файла, который инструменты анализируют, такого как .netrc, JSON или YAML; шаблон должен содержать по крайней мере одну захватывающую группу. Без extract Claude Code заменяет всё содержимое файла одним значением дозорного, что подходит для файла, который содержит один голый секрет и ничего больше.

Для файла, который содержит JSON Web Token (JWT), установите decode: "jwt" вместо или вместе с extract. decode требует Claude Code v2.1.224 или позже. Claude Code находит кандидатов JWT с встроенным шаблоном или с вашим шаблоном extract, когда установлен, проверяет каждого кандидата как JWT и заменяет его структурно действительным поддельным токеном, поэтому код, который декодирует токен внутри песочницы, продолжает работать. Добавьте maskClaims для маскировки только названных утверждений полезной нагрузки верхнего уровня внутри каждого проверенного токена и оставьте другие утверждения читаемыми. Когда ни один кандидат не проверяется или ни одно названное утверждение не совпадает, поле onExtractNoMatch ниже управляет результатом, как оно делает для шаблона, который ничего не совпадает.

Два дополнительных поля уточняют, как ведёт себя сопоставление. Оба применяются только когда mode — это mask и extract или decode установлены. На macOS Claude Code применяет записи mask как deny перед запуском шаблона всякий раз, когда изоляция файловой системы включена, поэтому эти поля и результаты отсутствия совпадения ниже вступают в силу там только когда изоляция файловой системы отключена:

  • onExtractNoMatch контролирует, что происходит, когда сопоставление не находит ничего для маскировки в файле:

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

    Claude Code обрабатывает deny как error всякий раз, когда блок чтения не будет применяться: когда вы отключите изоляцию файловой системы, и когда запись filesystem.allowRead из любого источника параметров повторно открывает путь файла.

  • maskDuplicates также заменяет дословные копии каждого маскированного значения учётных данных, захват extract или проверенный токен decode, найденные вне совпадённых диапазонов, для секрета, повторённого где сопоставление не достигает. Он совпадает с сырыми подстроками, поэтому короткое или обычное значение было бы заменено везде, где оно появляется; зарезервируйте его для длинных, высокоэнтропийных секретов. По умолчанию: false.

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

Как работает sandboxing

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

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

  • Поведение записи по умолчанию: доступ на чтение и запись к текущему рабочему каталогу и его подкаталогам, любым каталогам, которые вы добавили с помощью --add-dir, /add-dir или permissions.additionalDirectories, плюс временный каталог сеанса, на который указывает $TMPDIR
  • Поведение чтения по умолчанию: доступ на чтение ко всему компьютеру, кроме определённых запрещённых каталогов. Обратите внимание, что эта политика по умолчанию всё ещё разрешает чтение файлов учётных данных, таких как ~/.aws/credentials и ~/.ssh/. Используйте sandbox.credentials для блокировки чтения этих файлов и отмены установки переменных окружения с секретами, или добавьте пути в denyRead.
  • Заблокированный доступ: невозможно изменять файлы вне текущего рабочего каталога, добавленных каталогов и временного каталога сеанса без явного разрешения, включая файлы конфигурации оболочки, такие как ~/.bashrc, и системные двоичные файлы в /bin/
  • Git worktrees: когда рабочий каталог является связанным git worktree, sandbox также разрешает запись в общий каталог .git основного репозитория, чтобы команды, такие как git commit, могли обновлять ссылки и индекс. Запись в hooks/ и config внутри этого каталога остаётся запрещённой.
  • Настраиваемо: определите пользовательские разрешённые и запрещённые пути через параметры

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

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

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

  • В вашем рабочем каталоге и каталогах выше него: файлы параметров .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
  • Файлы, которые превратили бы ваш рабочий каталог в голый git репозиторий: HEAD, objects и refs на верхнем уровне, плюс config и hooks там, когда HEAD находится рядом с ними. Файл с именем config запрещён даже без HEAD. На Linux и WSL2 sandbox удаляет файл HEAD верхнего уровня или каталог objects или refs, который появляется во время выполнения изолированной команды
  • В ~/.claude или в каталоге, на который указывает CLAUDE_CONFIG_DIR: большая часть его содержимого, плюс ~/.claude.json и хранилище учётных данных .credentials.json

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

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

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

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

Доступ в сеть контролируется через прокси-сервер, работающий вне sandbox:

  • Ограничения домена: Claude Code не предварительно разрешает никакие домены по умолчанию. Первый раз, когда команде требуется новый домен, Claude Code запрашивает одобрение; в режиме автоматизации Claude вместо этого называет хосты, которые требуются команде, на самой команде, согласно Per-command allowed domains.
  • Варианты одобрения: если вы выберете «Да» при запросе, Claude Code разрешит хост для остальной части текущего сеанса и больше не будет запрашивать подтверждение для более поздних подключений к тому же хосту. Если вы выберете «Да, и больше не спрашивать», Claude Code сохранит правило разрешения WebFetch(domain:...) в ваши локальные параметры, чтобы хост оставался разрешённым в будущих сеансах.
  • Предварительно разрешённые домены: предварительно разрешите домены с помощью allowedDomains, чтобы полностью избежать запроса. Claude Code также предварительно разрешает домены из правил разрешения WebFetch(domain:...), как описано в Permission rules.
  • Строгий список разрешений: если вы установите strictAllowlist в значение true в пользовательских, управляемых или CLI параметрах --settings, Claude Code запретит изолированным командам доступ к любому хосту вне списка разрешений вместо запроса. Список разрешений — это тот же, против которого sandbox иначе запрашивает: allowedDomains плюс домены из правил разрешения WebFetch(domain:...), или только записи управляемых параметров, когда установлен allowManagedDomainsOnly. Claude Code применяет это только для изолированных команд; встроенные инструменты, такие как WebFetch, всё ещё следуют своим правилам разрешения. Установка этого в .claude/settings.json или .claude/settings.local.json репозитория не имеет эффекта. Требуется Claude Code версии 2.1.219 или позже.
  • Управляемая блокировка: если allowManagedDomainsOnly установлен в управляемых параметрах, неразрешённые домены автоматически блокируются вместо запроса, и только allowedDomains и правила разрешения WebFetch(domain:...) из управляемых параметров учитываются.
  • Корпоративный прокси: когда ваша сеть требует, чтобы исходящий трафик проходил через корпоративный прокси, установите HTTPS_PROXY, HTTP_PROXY и NO_PROXY как описано в proxy configuration, в блоке env ваших параметров, чтобы фоновые агенты их получили, или в окружении, из которого вы запускаете Claude Code. Claude Code применяет список разрешений домена и затем туннелирует разрешённые подключения через этот вышестоящий прокси.
  • Поддержка пользовательского прокси: продвинутые пользователи могут реализовать пользовательские правила для исходящего трафика
  • Полное покрытие: ограничения применяются ко всем скриптам, программам и подпроцессам, порожденным командами

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

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

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

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

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

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

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

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

Списки доменов sandbox — это allowedDomains, deniedDomains и правила WebFetch(domain:...), которые их питают. Чтобы соответствовать IPv6 адресу в любом из них, напишите литерал в скобках: "[::1]" соответствует этому адресу на каждом порту, и "[::1]:443" соответствует ему только на порту 443. Напишите порт как число от 1 до 65535 без ведущих нулей. Форма в скобках требует Claude Code версии 2.1.229 или позже. До версии 2.1.229, когда текст после последнего двоеточия записи без скобок был номером порта, Claude Code читал его как один, поэтому ::1:443 назывался адресом ::1 на порту 443.

Когда вы выбираете «Да, и больше не спрашивать» при запросе одобрения сети для IPv6 адреса, Claude Code сохраняет правило WebFetch(domain:...) с адресом в скобках, чтобы правило продолжало соответствовать адресу в будущих сеансах.

Запись без скобок с двумя или более двоеточиями неоднозначна: ::1:443 — это одновременно полный IPv6 адрес и адрес, за которым следует порт. Claude Code применяет неоднозначные написания консервативно вместо угадывания, какое прочтение вы имели в виду:

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

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

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

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

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

WSL1 не поддерживается, потому что bubblewrap требует функций ядра, доступных только в WSL2.

Эти же примитивы доступны как отдельный пакет @anthropic-ai/sandbox-runtime, который страница Sandbox environments описывает как отдельный подход для обёртывания всего процесса 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 для вашей организации

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

Применение sandboxing с управляемыми параметрами

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

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

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

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

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

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

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

Sandbox не работает на нативной Windows, поэтому если ваш парк включает хосты Windows, ограничьте эту конфигурацию macOS и Linux или попросите этих пользователей запустить Claude Code внутри WSL2 или контейнера.

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

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

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

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

excludedCommands не имеет эквивалентной блокировки только для управляемых, поэтому разработчик всегда может добавлять записи, которые выполняют дополнительные команды вне sandbox. Держите управляемый список узким.

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

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

  • Расшифровки и проверки трафика HTTPS
  • Применения пользовательских правил фильтрации
  • Логирования всех сетевых запросов
  • Интеграции с существующей инфраструктурой безопасности

Чтобы указать Claude Code на ваш прокси, установите порты прокси в параметрах sandbox:

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

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

Некоторые команды не выполняются внутри sandbox, хотя они работают вне его. Исправления ниже охватывают наиболее распространённые случаи.

  • Команды не выполняются с ошибкой host-not-allowed: многие инструменты CLI должны достичь определённых хостов. Предоставление разрешения при запросе добавляет хост в ваш список разрешённых, поэтому инструмент выполняется внутри sandbox в будущем.

  • jest зависает или не выполняется: watchman несовместим с sandbox. Вместо этого запустите jest --no-watchman.

  • Go-based CLIs не выполняют проверку TLS на macOS: инструменты, такие как gh, gcloud и terraform, могут не выполнять проверку TLS под Seatbelt. Перечислите эти инструменты в excludedCommands, чтобы запустить их вне sandbox. Если вы используете httpProxyPort с MITM прокси и пользовательским CA, установите enableWeakerNetworkIsolation в true вместо этого.

  • open, osascript или потоки аутентификации на основе браузера не выполняются с ошибкой -600 на macOS: sandbox по умолчанию блокирует Apple Events. Установите allowAppleEvents в true в ваших пользовательских, управляемых или CLI параметрах, чтобы разрешить их. Параметры проекта игнорируются для этого ключа. Включение его удаляет изоляцию выполнения кода, так как изолированные команды могут затем запускать другие приложения без изоляции без запроса пользователя и отправлять команды AppleScript запущенным приложениям, подлежащим запросу автоматизации macOS (TCC). Кроме того, добавьте команду в excludedCommands, чтобы запустить её вне sandbox.

  • Команды docker не выполняются: docker несовместим с sandbox. Добавьте docker * в excludedCommands, чтобы запустить его вне sandbox.

  • pbcopy, xclip или wl-copy не обновляют буфер обмена: эти утилиты буфера обмена могут не достичь системного буфера обмена изнутри sandbox, в этом случае текст, переданный в них, не поступает. Чтобы поместить вывод Claude в ваш буфер обмена, попросите Claude напечатать его в своём ответе, затем запустите /copy, который записывает в буфер обмена из процесса Claude Code, а не из изолированной команды. Кроме того, добавьте pbcopy *, wl-copy * или xclip * в excludedCommands, чтобы запустить команду вне sandbox.

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

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

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

  • Файлы размером 0 байт только для чтения появляются в путях параметров .claude, и "Да, и больше не спрашивать" не сохраняется: на Linux и WSL2 sandbox удерживает запрет на запись в файл, который ещё не существует, создавая 0-байтовый заполнитель только для чтения там, пока выполняется изолированная команда. Sandbox удаляет заполнитель после этого. Если сеанс завершается до выполнения этой очистки, например по SIGKILL, заполнители остаются. Более поздние сеансы привязывают их только для чтения снова при каждом запуске, поэтому запись параметров, такая как сохранение выбора разрешения, не выполняется там, где она находится.

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

  • --dangerously-skip-permissions не выполняется как root: этот флаг блокируется при запуске как root или через sudo на Linux и macOS, потому что доступ root в сочетании с отсутствием запросов разрешений может изменять любой файл или сервис в системе. Проверка автоматически пропускается внутри признанного sandbox. Чтобы запустить автономно в контейнере, используйте конфигурацию dev container, которая запускает Claude Code как непривилегированного пользователя.

Ограничения

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 без привилегированных пространств имён или на хостах Linux, где непривилегированные пользовательские пространства имён отключены sysctl. Эта опция значительно ослабляет безопасность и должна использоваться только когда дополнительная изоляция иным образом применяется.
  • Apple Events на macOS: sandbox на macOS по умолчанию блокирует Apple Events. Параметр allowAppleEvents снимает это ограничение, чтобы инструменты, такие как open и osascript, работали, но он удаляет изоляцию выполнения кода: изолированные команды могут запускать другие приложения без изоляции без запроса пользователя и могут отправлять команды AppleScript запущенным приложениям, в соответствии с запросом согласия на автоматизацию macOS для каждого приложения (TCC). Это учитывается только из пользовательских, управляемых или CLI параметров. Параметры проекта не могут включить это.

Совместимость платформ и инструментов

  • Поддержка платформ: поддерживает macOS, Linux и WSL2. WSL1 и нативная Windows не поддерживаются.
  • Накладные расходы производительности: минимальные, но некоторые операции файловой системы могут быть немного медленнее.
  • Совместимость инструментов: некоторые инструменты, требующие определённых шаблонов доступа к системе, могут потребовать корректировки конфигурации или могут потребовать запуска вне sandbox.

Область

Sandbox изолирует подпроцессы Bash. Другие инструменты работают в разных границах:

  • Встроенные инструменты файлов: Read, Edit и Write используют систему разрешений напрямую, а не работают через sandbox. См. permissions.
  • Использование компьютера: когда Claude открывает приложения и управляет вашим экраном, он работает на вашем фактическом рабочем столе, а не в изолированной среде. Запросы разрешений для каждого приложения контролируют каждое приложение. См. computer use in the CLI или computer use in Desktop.
  • Переменные окружения: изолированные команды Bash наследуют окружение родительского процесса по умолчанию, включая любые учётные данные, установленные там. Используйте sandbox.credentials для удаления или маскирования определённых переменных для изолированных команд или установите CLAUDE_CODE_SUBPROCESS_ENV_SCRUB для удаления учётных данных из всех подпроцессов.
  • Subagents: subagents работают в том же процессе, что и родительский сеанс, и используют ту же конфигурацию sandbox. Команды Bash внутри subagent изолированы, когда sandboxing включен в родительском сеансе.

См. также

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