Аддон Devcontainer

Дайте репозиторию воспроизводимый, изолированный контейнер для разработки — такой, которым могут пользоваться люди, редакторы и агенты для программирования. В DWP v7 (пакет v7.8.0) этот аддон интегрирует devcontainer-kit — продукт под лицензией MIT, работающий без Deep Work Plan. Он опционален: репозиторий без него полностью соответствует требованиям.

Что предоставляет devcontainer-kit

• Шаблон на основе спецификации Dev Containers, который dck init рендерит в репозиторий в одной фиксированной структуре: .devcontainer/devcontainer.json, docker/local/<service>/Dockerfile, docker/local/docker-compose.yaml и dev.sh. При повторном запуске он согласовывает изменения и никогда не затирает ваши правки; любое изменение существующего файла сначала показывается и требует согласия.
• Собственный контейнер репозитория. Dockerfile начинается с официального образа среды выполнения, закреплённого по digest, — node-24, python-3.13 или debian — и копирует шаги сборки kit в docker/local/<service>/dck/. Общий базовый образ не используется.
• dev.sh и dck. bash dev.sh up собирает, запускает контейнер и подключается к нему из обычного терминала; shell, rebuild, doctor и остальные команды работают с VS Code или Cursor либо без них.
• Herdr в обе стороны. Herdr на хосте подключает каждый контейнер как машину через SSH-сервер, доступный только через loopback, а контейнер открывается со стандартной боковой панелью: App, Editor, Development и Agents. Каждое рабочее пространство и каждая панель, включая открытые позже, запускаются в пути приложения (по умолчанию /app). Внутри herdr-peers позволяет агентам обращаться к агентам на хосте и в других контейнерах.
• Навык dck-dockerfile. Агент по запросу создаёт или перегенерирует контейнер репозитория и подтверждает его реальной сборкой.

Установка

git clone --branch v1.0.0 https://github.com/DailybotHQ/devcontainer-kit && ./devcontainer-kit/install.sh
cd your-repo && dck init && bash dev.sh up

Требования: bash 3.2 или новее и python3 3.11 или новее на хосте с Linux или macOS, а также Docker с Compose v2 для команд контейнера. Проверьте релиз по его ресурсу SHA256SUMS. Закрепите v1.0.0: v0.2.0 не поддерживается.

Стабилен начиная с v1.0.0. Публичный интерфейс следует семантическому версионированию и меняется несовместимо только в новой мажорной версии (а для файлов — с новым номером интерфейса): команды dck с их документированными флагами и кодами выхода (0 успех, 1 сбой, 2 использование, 3 конфигурация, 4 окружение, 5 отказ), схемы dck.toml, профиля хоста и dck doctor --json (интерфейс 2), а также контракт рендеринга — файлы, которые dck init записывает и которыми владеет, маркеры dck:managed и пользовательские блоки, которые он сохраняет, и окружение, которое читает entrypoint. При переходе с v0.3.7 ничего не ломается: выполните dck init и dck rebuild, чтобы образ получил новые закреплённые версии (herdr-peers, coding-agents-kit и DeepWorkPlan Vim, каждый на v1.0.0).

Слои

Каждый контейнер содержит инструменты разработки — git, gh, ripgrep, SSH-сервер, Herdr и herdr-peers — и ни одного секрета, если вы не включите учётные записи хоста. Всё остальное — это слой, который вы выбираете в dck.toml:

Входы в аккаунты, gh, конфигурация Herdr и git-идентичность сохраняются после bash dev.sh rebuild. Со слоем agents образ также содержит три навыка coding-agents-kit (agentkit, agentkit-setup, agentkit-orchestrate), которые при каждом запуске подключаются в каталог навыков каждого агента, поэтому пересозданный контейнер их сохраняет.

Том состояния (ключ хоста SSH, ~/.ssh, вход gh, состояние клиента Herdr, история) называется state. Если несколько сервисов используют один проект compose, задайте каждому собственное имя через [compose] state_volume в dck.toml (или dck init --state-volume NAME); иначе все они монтируют один и тот же том, и dck doctor об этом сообщает.

Агенты на разных машинах

Начиная с v0.2.3, dck up в Docker Desktop настраивает двустороннюю сеть без ручных шагов:

• Контейнеры и хост. Агенты внутри контейнера достигают агентов Herdr на хосте, в каждом другом контейнере dck и в других loopback-контейнерах, которыми уже управляет Herdr вашего хоста, — а те достигают их в ответ. У каждого peer-агента закреплённый ключ хоста; ничто не получает доверия при первом подключении.
• Необязательный listener на хосте. dck setup один раз предлагает SSH-сервер уровня пользователя на 127.0.0.1, который принимает только ключ dck и поддерживается в работе через launchd (macOS). Если у вас уже работает loopback-listener, вместо этого укажите его в профиле хоста. dck host listener disable удаляет его.
• Переживает пересборки. Каталог машин Herdr контейнера хранится в томе, поэтому bash dev.sh rebuild сохраняет все зарегистрированные в нём машины. Начиная с v0.3.2, rebuild, start и restart выполняют те же шаги, что и up: контейнер заново регистрируется в Herdr хоста, его ключ хоста закрепляется заново, а конфигурация сети рассылается участникам, поэтому контейнер, собранный с нуля, сразу достигает хоста и своих peer-агентов.
• Панели Codex внутри контейнера. Агенту Codex нужна HERDR_PEERS_SELF — идентификатор машины контейнера, сохранённый на хосте, — чтобы обращаться к peer-агентам на других машинах. Начиная с v0.3.3 kit записывает этот идентификатор при каждой регистрации, а login-оболочки контейнера экспортируют его, поэтому ни одному агенту не нужно задавать его вручную; dck doctor сообщает о несовпадении. Начиная с v0.3.4 собственные конфигурации Codex в контейнере пропускают проверку обновлений Codex при запуске и его фоновый демон (kit фиксирует версию каждого CLI), никогда не затрагивая home Codex на вашем хосте или общий профиль.
• Ответы и с хоста. dck setup устанавливает на хост проверенный herdr-peers, поэтому dck agents и dck ask работают и там, а агенты хоста отвечают через herdr-peers reply.
• Контейнеры, созданные не kit. Перечислите публичные ключи, с которыми они входят, в [ssh] authorized_extra профиля хоста, и они тоже смогут достигать контейнеров dck.

Используйте вместе с coding-agents-kit на хосте и в контейнере, и один и тот же ak будет запускать агентов на обеих сторонах.

Учётные записи хоста в контейнере

Контейнер может использовать учётные записи, которые у вас уже есть на хосте, — так же, как git уже работает через SSH-агент хоста, — без входа внутри. Это включается явно и хранится в вашем профиле хоста, никогда не в dck.toml репозитория:

[agents]
host_profiles = true          # по умолчанию false
host_env_keys = ["ZAI_CODING_API_KEY"]   # список разрешённых имён переменных для общего доступа

Когда host_profiles включён, dck up предоставляет доступ только к профилям тех CLI, которые устанавливает репозиторий:

• Claude Code — через долгоживущий токен на профиль: CLAUDE_CODE_OAUTH_TOKEN для @default и CLAUDE_CODE_OAUTH_TOKEN_<SUFFIX> для @name (суффикс в верхнем регистре, каждый символ вне A-Z, 0-9 и _ заменяется на _).
• Codex — через его файл аутентификации, для @default и для каждого профиля.
• Env-файл kit, только для чтения и сокращённый до имён из host_env_keys.

Весь home agentkit никогда не монтируется, а профили с абсолютными путями хоста пропускаются. Вход Codex, предоставленный на чтение и запись, могут обновить два записывающих одновременно: держите одного активного агента на учётную запись Codex. [agents] default_profile в профиле хоста (например, { claude = "@work3" }) заставляет простой ak claude внутри контейнера использовать эту общую учётную запись (coding-agents-kit ≥ v0.5.2); вход Claude @default в macOS хранится в Связке ключей (Keychain) и не может быть предоставлен контейнеру. Начиная с v0.3.4 оболочки контейнера также направляют простой claude или codex на эту учётную запись, поэтому панели, которые восстанавливает Herdr, открываются в ней, а не на экране входа. Внутри контейнера тот же ak <kind> @<profile> работает на той же учётной записи, что и на хосте, — именно это позволяет ведущему агенту передавать линиям в контейнерах учётные записи, выбранные ak pick, — см. Запуск множества агентов.

Несколько репозиториев, один стек compose

Начиная с v0.3.3, репозиторий, чей сервис — часть более крупного проекта compose (API, веб-приложение, воркеры и база данных в одном проекте), может присоединиться к нему, не правя вручную то, что генерирует dck. Всё аддитивно: репозиторий, не задающий ни одного из этих ключей, генерируется в точности как раньше.

• Один проект, по тому состояния на сервис. [compose] project задаёт общий проект в каждом репозитории; state_volume, [compose] networks и [compose] volumes разделяют состояние каждого сервиса, а также тома данных и сети стека.
• Пользовательский блок. Строки между # >>> user:<service> >>> и # <<< user:<service> <<< внутри сервиса dck сохраняются дословно: обычные ключи — для того, что dck не генерирует (depends_on, healthcheck), и x-dck-merge: — для ключей, которые он генерирует. Файл, содержащий лишь часть маркеров dck, отклоняется с указанием исправления, а не переписывается.
• Порты в виде строк. ssh_port и ports принимают выражения compose, например "${API_PORT:-8000}:8000"; они остаются на 127.0.0.1, если в строке не указан IP хоста.
• Общие сборки и собственный launcher. [build] context и [build] dockerfile покрывают Dockerfile, общий для нескольких сервисов; dev_sh = false сохраняет собственный dev.sh репозитория.
• Спутники рабочего пространства. Начиная с v0.3.5, второй экземпляр сервиса в собственном проекте compose запускается и останавливается через dck (dck --project P --compose-file F --service S up или down), поэтому получает тот же ключ хоста, те же учётные записи, ту же git-идентичность и ту же машину Herdr, что и основной; up --seed-state-from VOLUME копирует в его пустой том состояния только входы в аккаунты. В overlay-файле extends должен указывать файл, который он расширяет.
• Node для агентов. Собственный Node агентов находится в /opt/dck/node и никогда не заменяет Node образа; [agents] node_first = true ставит его первым в PATH, когда этого требуют инструменты репозитория.

SSH-ключи хоста внутри контейнера

Некоторые инструменты читают только файлы ключей и игнорируют пересланный агент: например, gh auth login предлагает сгенерировать новый ключ. Начиная с v0.3.2 это можно включить явно, и только в вашем профиле хоста (dck.toml репозитория не может это задать; dck setup спрашивает один раз, по умолчанию — нет):

[ssh]
copy_keys = true              # default false

Пока параметр включён, dck up монтирует ~/.ssh хоста только для чтения в ~/.ssh_host, а при каждом запуске его ключи id_* копируются в ~/.ssh контейнера (закрытые ключи — 0600) и синхронизируются с хостом. Пересылка агента не меняется, а после отключения копии удаляются при следующем запуске. Цена: весь ~/.ssh хоста доступен для чтения внутри контейнера, а закрытые ключи хранятся в томе состояния.

Настройки безопасности по умолчанию

• Каждый публикуемый порт привязывается к 127.0.0.1, если dck.toml не задаёт bind.
• Git по SSH работает через SSH-агент хоста — его сокет, никогда не файл ключа и никогда не смонтированные ~/.ssh или ~/.gitconfig, если только вы не включили copy_keys в профиле хоста. Git-идентичность берётся из значений DCK_GIT_*, которые заполняет dck setup.
• SSH-ключи хоста генерируются во время выполнения в том отдельного проекта и никогда не запекаются в образ; сервер принимает только публичные ключи, без входа под root и без паролей.
• Шаблон не добавляет cap_add, режим privileged и сокет Docker.
• Каждая загрузка закреплена по версии и проверена контрольной суммой; базовый образ закреплён по digest.
• Сеть Herdr, через которую агенты в одном контейнере достигают остальных, включена по умолчанию и описана вместе со способами её отключения в модели угроз kit. Listener на хосте позволяет коду в запущенном контейнере открыть shell на хосте от вашего имени: он включается только по явному согласию, работает только через loopback, принимает только ключ dck и удаляется командой dck host listener disable.

Примечания

Опционален и никогда не обязателен. Репозиторий без опциональных аддонов полностью соответствует требованиям. Поддерживаются хосты с Linux и macOS; сеть между контейнерами требует Docker Desktop.