Claude Code в devcontainer

Песочница для разработки запуска Claude Code с безопасно включённым bypassPermissions. Создана в Trail of Bits для рабочих процессов аудита безопасности.

Зачем это нужно?

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

Предназначен для:

• Аудит безопасности: Просмотр клиентского кода без риска для вашего хоста
• Недоверенные репозитории: Безопасное исследование незнакомых кодовых баз
• Экспериментальная работа: Позволить Claude свободно изменять код в изоляции
• Работа с несколькими репозиториями: Работа с несколькими связанными репозиториями

Необходимые условия

• Среда выполнения Docker (одна из):

  • Docker Desktop — убедитесь, что она запущена
  • OrbStack
  • Colima: brew install colima docker && colima start

• Для терминальной работы (однократная установка):

  npm install -g @devcontainers/cli
  git clone https://github.com/trailofbits/claude-code-devcontainer ~/.claude-devcontainer
  ~/.claude-devcontainer/install.sh self-install
  

# Stop and delete current VM (removes containers/images)
colima stop && colima delete

# Start with optimized settings
colima start \
  --cpu 4 \
  --memory 8 \
  --disk 100 \
  --vm-type vz \
  --vz-rosetta \
  --mount-type virtiofs

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

Выберите шаблон, соответствующий вашему рабочему процессу:

Шаблон A: Контейнер на проект (изолированный)

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

Терминал:

git clone <untrusted-repo>
cd untrusted-repo
devc .          # Installs template + starts container
devc shell      # Opens shell in container

VS Code / Cursor:

1. Установите расширение Dev Containers:

   • VS Code: ms-vscode-remote.remote-containers
   • Cursor: anysphere.remote-containers

2. Настройте devcontainer (выберите один):

   # Option A: Use devc (recommended)
   devc .
   
   # Option B: Clone manually
   git clone https://github.com/trailofbits/claude-code-devcontainer .devcontainer/
   

3. Откройте папку вашего проекта в VS Code, затем:

   • Нажмите Cmd+Shift+P (Mac) или Ctrl+Shift+P (Windows/Linux)
   • Введите "Reopen in Container" и выберите Dev Containers: Reopen in Container

Шаблон B: Общий рабочий контейнер (сгруппированный)

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

# Create workspace for a client engagement
mkdir -p ~/sandbox/client-name
cd ~/sandbox/client-name
devc .          # Install template + start container
devc shell      # Opens shell in container

# Inside container:
git clone <client-repo-1>
git clone <client-repo-2>
cd client-repo-1
claude          # Ready to work

Аутентификация на основе токена (безголовый режим)

Для безголовых серверов или чтобы пропустить интерактивного мастера входа:

claude setup-token                          # run on host, one-time
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
devc rebuild                                # rebuilds with token

Токен передаётся в контейнер. При каждом создании контейнера post_install.py выполняет однократное подтверждение аутентификации, так что claude запускается без мастера входа.

Это обходит проблему постоянного отображения интерактивного мастера настройки Claude Code в контейнерах, даже с действительными учётными данными (#8938).

Если вы не задаёте токен, интерактивный вход работает как прежде.

Вспомогательные команды CLI

devc .              Установить шаблон + запустить контейнер в текущем каталоге
devc up             Запустить devcontainer
devc rebuild        Пересобрать контейнер (сохраняет постоянные тома)
devc destroy [-f]   Удалить контейнер, тома и образ для текущего проекта
devc down           Остановить контейнер
devc shell          Открыть zsh-оболочку в контейнере
devc exec CMD       Выполнить команду внутри контейнера
devc upgrade        Обновить Claude Code в контейнере
devc mount SRC DST  Добавить связывание монтирования (хост → контейнер)
devc sync [NAME]    Синхронизировать сеансы Claude Code из devcontainers на хост
devc template DIR   Скопировать файлы devcontainer в каталог
devc self-install   Установить devc в ~/.local/bin

Примечание: Используйте devc destroy для очистки Docker-ресурсов проекта. Ручное удаление контейнеров (например, docker rm) оставит сиротские тома и образы, которые devc destroy не сможет найти.

Синхронизация сеансов для /insights

Команда /insights анализирует историю ваших сеансов, но она читает только из ~/.claude/projects/ на хосте. Сеансы внутри томов devcontainer для неё невидимы.

devc sync копирует журналы сеансов из всех devcontainers (работающих и остановленных) на хост, чтобы /insights могла их включить:

devc sync              # Sync all devcontainers
devc sync crypto       # Filter by project name (substring match)

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

Общий доступ к файлам

VS Code / Cursor

Перетаскивайте файлы с хост-машины на панель обозревателя VS Code — они автоматически копируются в /workspace/. Никакой настройки не требуется.

Терминал: devc mount

Чтобы сделать каталог хоста доступным внутри контейнера:

devc mount ~/drop /drop           # Read-write
devc mount ~/secrets /secrets --readonly

Это добавляет связывание монтирования в devcontainer.json и пересоздаёт контейнер. Существующие монтирования сохраняются при обновлениях devc template.

Совет: общая "папка для передачи" полезна для передачи файлов без монтирования всей домашней директории.

Замечание по безопасности: Избегайте монтирования больших каталогов хоста (например, $HOME). Каждый смонтированный путь доступен для записи изнутри контейнера, если не указан --readonly, что подрывает изоляцию файловой системы, которую обеспечивает этот проект.

Изоляция сети

По умолчанию контейнеры имеют полный исходящий сетевой доступ. Для более строгой безопасности используйте iptables для ограничения доступа к сети.

Когда включать изоляцию сети

• Просмотр кода, который может содержать вредоносные зависимости
• Аудит программного обеспечения с телеметрией или поведением "звонка домой"
• Максимальная изоляция для высокочувствительных проверок

Пример: Claude + GitHub + Пакетные реестры