Песочница Claude Code: туториал и настройка /sandbox
Запустите /sandbox, выберите auto-allow — и каждая bash-команда окажется внутри границы, которую навязывает ОС, — с реальными ключами настроек, а не с фольклором. 12 шагов, сверенных с официальной документацией.
TL;DR
- Команда /sandbox открывает панель с вкладками Mode, Overrides и Config. Режим auto-allow запускает изолированные bash-команды без запроса разрешения; regular permissions сохраняет каждое подтверждение.
- Границу навязывает ядро, а не диалоги: Seatbelt на macOS, bubblewrap на Linux и WSL2. Нативный Windows и WSL1 не поддерживаются.
- Изолированные команды могут писать только в рабочий каталог, пользовательский временный каталог и пути из --add-dir. Сетевой трафик идёт через прокси, который заранее не разрешает ни один домен.
- Чтения по умолчанию не блокируются — ~/.ssh и ~/.aws остаются читаемыми, пока вы не добавите правила sandbox.credentials. Диалог Sandbox в VS Code появился в v2.1.280.
Claude Code Sandbox Explained
Канал:The Art of Vibe Coding4:29
How auto mode works with Claude Code
Канал:Claude5:42
Configure the sandboxed Bash tool (official docs)
Документация:code.claude.com
Первое видео — ролик с motion-графикой: его кадры на этой странице — стилизованные иллюстрации, а не скриншоты, и часть его утверждений исправлена в шагах ниже (учётные данные по умолчанию читаемы; примеры ключей настроек из видео не совпадают с настоящими). Второе видео — официальная запись Anthropic; используются только её настоящий терминал и настройки UI.
Факты сверены с code.claude.com/docs/en/sandboxing и CHANGELOG проекта anthropics/claude-code (v2.1.280–2.1.283). Кадры цитируют краткие фрагменты записей для комментария.
Настройте песочницу Claude Code за 12 шагов
Поймите границу
- 1
Осознайте проблему усталости от одобрений
Без песочницы каждая предложенная команда останавливается ради y/n: npm install, git status, потом следующая. Anthropic измерила, что 97% запросов разрешений Claude Code одобряются, — именно поэтому песочница выносит проверку за пределы каждой команды, в границу, которую настраиваешь один раз.
Реконструкция цикла y/n на каждую команду, который заменяет песочница, — нажать Enter 47 раз и перестать читать.Смотреть на 0:22 - 2
Запустите Claude Code на поддерживаемой платформе
Откройте сессию в своём проекте. В macOS изоляция встроена: Seatbelt поставляется с системой, устанавливать ничего не нужно. На Linux и WSL2 сначала поставьте bubblewrap и socat пакетным менеджером. Нативный Windows и WSL1 не поддерживаются — пользователям Windows запускать Claude Code внутри дистрибутива WSL2.
Сессия в ~/Documents/code/acme — именно этот рабочий каталог песочница сочтёт доступным для записи.Смотреть на 0:35 - 3
Запустите /sandbox и прочитайте панель
Введите /sandbox в сессии. У панели три вкладки: Mode (как одобряются изолированные команды), Overrides (может ли упавшая команда повториться без песочницы — настройка allowUnsandboxedCommands) и Config (полностью разрешённые настройки песочницы). В Linux добавляется вкладка Dependencies со списком недостающего: bubblewrap, socat или опциональный фильтр seccomp. С v2.1.281 вкладки переключаются стрелками, а VS Code получил диалог Sandbox с теми же настройками в v2.1.280.
Включите её
- 4
Выберите auto-allow или обычные разрешения
На вкладке Mode auto-allow запускает изолированные команды без вопросов, а regular permissions сохраняет вопросы даже для изолированных команд. Выбор сохраняется в .claude/settings.local.json проекта, который Claude Code сам добавляет в gitignore. Чтобы покрыть все проекты, задайте "sandbox": undefined в ~/.claude/settings.json; для одной сессии передайте через --settings.
Быстрый старт в два шага: /sandbox выбирает режим, settings.json хранит всё долговечное.Смотреть на 4:00 - 5
Знайте, о чём auto-allow всё ещё спрашивает
Auto-allow — не кнопка «без звука». Явные deny-правила всегда побеждают, rm или rmdir по критическим путям всё ещё спрашивают, а контентные ask-правила вроде Bash(git push *) всё ещё требуют подтверждения. Команды, которые не могут работать в песочнице, откатываются к обычному потоку с вопросом под заголовком "Bash command (unsandboxed)". Auto-allow также независим от режима разрешений — изолированный bash запускается без вопросов даже в режиме Manual.
shift+tab листает режимы разрешений — отдельный механизм, не auto-allow песочницы.Смотреть на 0:28 - 6
Посмотрите, как ОС проводит границу
Ограничения навязаны ядром, это не вежливые уговоры: macOS использует Seatbelt, Linux и WSL2 — bubblewrap. Команда с промпт-инъекцией, которая попытается прочитать ~/.ssh или сбежать домой, ударится о ту же стену: правила связывают запущенный процесс и всех его детей, — модель не уговорит ядро красноречием.
Проверки разрешений на уровне приложения можно обойти; уровень ядра — нет.Смотреть на 2:07
Файловая система, учётные данные и сеть
- 7
Поймите файловые значения по умолчанию — и подвох с чтением
Изолированные команды могут писать в рабочий каталог и подкаталоги, в пользовательский временный каталог и в папки, добавленные через --add-dir или permissions.additionalDirectories. Чтения открыты по умолчанию: читаем весь диск, включая ~/.aws/credentials и ~/.ssh, пока вы не запретите. Объясняющие видео любят говорить, что учётные данные становятся «невидимыми», — документация суха: защищать их — ваша работа, через sandbox.credentials или denyRead-правила.
Записи упираются в стену песочницы; чтения остаются открытыми, пока вы их не закроете на следующем шаге.Смотреть на 1:30 - 8
Защитите учётные данные до автономного режима
Добавьте блок sandbox.credentials: перечислите файлы вроде ~/.ssh или ~/.aws/credentials с "mode": "deny" и секретные переменные окружения вроде GITHUB_TOKEN, чтобы они очищались в каждой изолированной команде. Режим mask идёт дальше — команда видит значение-пустышку, а прокси песочницы подставляет настоящее только на разрешённых вами хостах. Правила Read в permissions.deny накрывают файловые инструменты сверху.
Deny-правила для curl и чтений .env — ваш блок sandbox лежит в том же файле настроек.Смотреть на 4:35 - 9
Разрешите сетевые домены, нужные вашему стеку
Весь изолированный трафик идёт через прокси, и ни один домен не разрешён заранее. Когда команде впервые понадобится хост, Claude Code спросит; ответьте "Yes, and don't ask again" — сохранится allow-правило WebFetch(domain:...) для будущих сессий. Разрешайте реестры заранее через sandbox.network.allowedDomains, блокируйте конкретные хосты через deniedDomains и включите strictAllowlist, чтобы список стал жёстким потолком, а не перечнем вопросов.
Запросы к registry проходят прокси; postinstall, стучащийся на evil.com, — нет.Смотреть на 1:51 - 10
Разложите конфиг по уровням: проект, пользователь или управление
Настройки проекта в .claude/settings.json могут добавлять пути для записи и домены, но не могут отключать изоляцию файловой системы или включать Apple Events — эти ключи признаются только из пользовательских, управляемых настроек или флага --settings, так что склонированный репозиторий не ослабит вашу песочницу. Команды навязывают песочницу управляемыми настройками: enabled, failIfUnavailable и allowUnsandboxedCommands в true/false/false.
Файл управляемых настроек описывает доверенную среду организации — настраивают админы, разработчики наследуют.Смотреть на 4:10
Проверьте и почините
- 11
Проверьте на реальной задаче
Попросите сборку или прогон тестов. Изолированные команды исполняются без вопросов, а при блокировке нарушение называет путь или хост в результате команды, чтобы Claude адаптировался. Откройте вкладку Config в /sandbox и прочитайте каждое действующее правило, включая защищённые пути, которые не переиграет никакая настройка. Для разовой строгой пробы запустите: claude --settings 'undefined}'.
Одна введённая задача, ни одного вопроса на команду — граница держится без вас.Смотреть на 0:32 - 12
Диагностируйте типовые сбои
jest виснет — watchman несовместим, запустите jest --no-watchman. docker падает — он не умеет работать в песочнице, добавьте "docker *" в excludedCommands. open или osascript падает с ошибкой -600 на macOS — Apple Events заблокированы, пока allowAppleEvents не true. git merge или checkout падает с "unable to unlink old" — мешает защищённый путь или denyWrite-правило: одобрите повтор без песочницы или запустите команду сами. bwrap выдаёт Operation not permitted внутри контейнера — включите enableWeakerNestedSandbox. Пайпы в буфер обмена не доходят — используйте /copy вместо pbcopy.
Настройки песочницы, которые имеют значение
Панель /sandbox пишет основу, но настоящая сила — в settings.json. Вот ключи, которые документирует официальный справочник по sandboxing, — все живут под блоком "sandbox" (последний — под "permissions").
- 1sandbox.enabled — выключен, пока вы не включите. true в ~/.claude/settings.json покрывает все ваши проекты; панель /sandbox пишет локальную для проекта копию в .claude/settings.local.json.
- 2sandbox.autoAllowBashIfSandboxed — переключатель auto-allow, по умолчанию true. Поставьте false, чтобы сохранить запросы разрешений даже для команд внутри песочницы.
- 3sandbox.allowUnsandboxedCommands и sandbox.failIfUnavailable — false на первом убивает повтор dangerouslyDisableSandbox (на вкладке Overrides показан как Strict sandbox mode); true на втором превращает недостающие зависимости в жёсткий отказ на старте вместо предупреждения.
- 4sandbox.filesystem — allowWrite для внешних путей, нужных инструментам ("~/.kube", "/tmp/build"), denyRead плюс allowRead для секретных мест и disabled (v2.1.216+), чтобы снять файловый слой, сохранив сетевую изоляцию.
- 5sandbox.network — allowedDomains и deniedDomains, strictAllowlist (v2.1.219+), чтобы запретить всё неописанное, allowLocalBinding, чтобы dev-серверы могли занимать порты, и tlsTerminate для маскировки учётных данных на прокси.
- 6sandbox.credentials — записи files и envVars в режимах deny или mask; маски требуют tlsTerminate и признаются только из источников user, managed или --settings. Пара к ним — permissions.blockReadsOutsideWorkingDirectories, отсекающая все чтения за пределами рабочих каталогов.
Seatbelt против bubblewrap: платформенные различия
macOS использует Seatbelt, встроенный в систему, — ставить ничего не нужно. Шероховатости конкретные: CLI на Go вроде gh, gcloud и terraform могут падать на TLS-проверке под Seatbelt — внесите их в excludedCommands; open, osascript и браузерные флоу авторизации падают с ошибкой -600, пока не включите allowAppleEvents, — это ослабляет изоляцию и игнорируется в настройках проекта.
Linux и WSL2 используют bubblewrap плюс socat, ставятся пакетным менеджером. Опциональный фильтр seccomp (npm install -g @anthropic-ai/sandbox-runtime) добавляет блокировку Unix domain sockets и именно он не пускает Windows-бинарники в WSL2. В Ubuntu 24.04 и новее политика AppArmor мешает bubblewrap создавать user namespaces — добавьте bwrap-профиль из документации и перечитайте AppArmor. Внутри непривилегированного контейнера включите enableWeakerNestedSandbox, чтобы bubblewrap bind-монтировал существующий /proc.
WSL1 не поддерживается вовсе — bubblewrap нужны фичи ядра, которые есть только у WSL2. Накладные расходы минимальны, хотя отдельные файловые операции идут чуть медленнее. Субагенты работают в том же процессе, что и родительская сессия, и наследуют её конфигурацию песочницы, так что фоновый bash внутри агента тоже изолирован.
Обращение с песочницей ещё гуляет между релизами: v2.1.280 добавила диалог Sandbox в VS Code, v2.1.281 улучшила навигацию по вкладкам /sandbox и подсказку allowLocalBinding для dev-серверов, а v2.1.282–2.1.283 починила сопоставление excludedCommands, записи в TMPDIR и парсинг управляемых настроек. Пролистайте CHANGELOG, прежде чем полагаться на пограничное поведение.