Аддон Devcontainer

Надайте репозиторію відтворюваний, ізольований контейнер для розробки — такий, яким можуть користуватися люди, редактори та агенти для програмування. У DWP v7 (пакет v7.9.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.1.1 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.1.1: 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 v1.1.0, coding-agents-kit v1.1.0 і DeepWorkPlan Vim v1.0.1).

Шари

Кожен контейнер містить інструменти розробки — 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.