SpyBara
Go Premium

sandboxing.md 2026-09-09 22:58 UTC to 2026-09-10 23:00 UTC

This page contains 352 additions and 66 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 и её дочерних процессов.

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

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 отправляет запрос классификатору.

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

Настройка 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 в разные каталоги. Чтобы передавать временные файлы между ними, записывайте их в рабочий каталог вместо этого.

Настройка sandboxing

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

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

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

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

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

Если вы исключите источник с помощью --setting-sources в CLI или settingSources в Agent SDK, Claude Code игнорирует его записи sandbox.filesystem, его правила разрешения Edit и его правила отказа Read при построении конфигурации sandbox. Требуется 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 для относительных к проекту. Пути файловой системы sandbox используют стандартные соглашения: /tmp/build — это абсолютный путь. О том, как Claude Code обрабатывает завершающий слэш или подстановочный знак в этих путях, см. Префиксы путей Sandbox.

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

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

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

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

Возврат происходит при запуске sandbox, после того как 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" пути файлов запрещены для чтения внутри sandbox, применяется то же ограничение, что и 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. Чтобы удалить учётные данные из всех подпроцессов независимо от sandboxing, установите CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.

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

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

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

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

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

Прокси подставляет учётные данные внутри содержимого запроса, поэтому он должен их видеть. Установите 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". Прокси сопоставляет каждую запись с голым адресом назначения соединения, игнорируя порты, поэтому скобочная, зона-ID или иначе сжатая орфография никогда не совпадает и прокси никогда не вводит учётные данные там.

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, по-прежнему работает внутри sandbox. Шаблон должен содержать по крайней мере одну захватывающую группу.
  • onExtractNoMatch контролирует, что происходит, когда шаблон ничего не совпадает:
    • warn, по умолчанию, предупреждает и передаёт переменную немаскированной
    • deny отменяет переменную внутри sandbox
    • error останавливает настройку sandbox, пока вы не исправите конфигурацию
  • decode: "jwt": для переменной, содержащей JSON Web Token (JWT). Claude Code проверяет, что значение является JWT, и заменяет его структурно действительным поддельным токеном, поэтому код внутри sandbox, который декодирует токен, продолжает работать. Добавьте 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.
  • Прокси повторно подписывает запросы на хостах, перечисленных в injectHosts записи ID ключа доступа.
  • Именование любой из обычных переменных в паре заменяет автоматическое спаривание.

Как записи 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: изолированные команды читают копию-дозорное значение файла, заменитель, чей секрет заменён значением заполнителя, и прокси sandbox подставляет реальное значение на исходящем трафике.
  • macOS: изолированные команды не могут читать перечисленный файл вообще. Claude Code не строит копию-дозорное значение и не подставляет ничего на исходящем трафике, поэтому инструменты, которые аутентифицируются с файлом, не работают внутри sandbox, тот же эффект, что и 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 и заменяет его структурно действительным поддельным токеном, поэтому код, который декодирует токен внутри sandbox, продолжает работать. Добавьте maskClaims, чтобы маскировать только названные утверждения полезной нагрузки верхнего уровня внутри каждого проверенного токена и оставить другие утверждения читаемыми. Когда ни один кандидат не проверяется или ни одно названное утверждение не совпадает, поле onExtractNoMatch ниже управляет результатом, как оно делает для шаблона, который ничего не совпадает.

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

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

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

    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 там, когда они уже существуют, даже если каталог config принадлежит вашему проекту, а не git. На 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 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.*), всё ещё соответствует выборкам, но не влияет на изолированные команды.

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 и их дочерним процессам.

Два слоя также отличаются способом их применения. 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 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: параметры командной строки