Containers: orchestration, systemd, rolling updates, docs

claude-desktop commented

2026-04-17 12:43:41 +00:00

Collaborator

User story

As an operator, I want just recipes, an updated systemd unit, and operational docs for the containerised workers, so that the new model is deployable and reversible without hand-holding.

Split out of the original containerisation story (#17).

Acceptance criteria

`just` recipes

just containers-up — starts every configured agent container
just containers-down — stops every agent container (worktrees/sessions persist in volumes)
just containers-rebuild — pulls the latest image and recreates each container one at a time
just containers-logs [name] — tail container logs
just containers-shell <name> — docker exec -it <name> bash for debugging

systemd

Existing claude-hooks.service gains After=docker.service and Requires=docker.service
ExecStartPre / ExecStopPost hooks bring agent containers up/down in sync with the service
Service stop gracefully drains in-flight tasks before tearing down containers

Rolling updates

Replacing one agent's container image does not affect the other agents or the running claude-hooks process
Document the procedure in README.md: pull new image, just containers-rebuild <name>

Docs

README.md section on the containerised architecture, the host/container boundary, token rotation, image updates
Migration note: existing ~/.cache/claude-hooks state is abandoned, new install starts clean with empty volumes

Out of scope

Image build / publish — #18
Container runtime / volumes — #19

References

Parent tracking issue: #17

Dependencies

Blocked by: #19 (runtime)
Blocks: none
Branch off: main
Full graph: #17

## User story As an **operator**, I want `just` recipes, an updated systemd unit, and operational docs for the containerised workers, so that the new model is deployable and reversible without hand-holding. Split out of the original containerisation story (#17). ## Acceptance criteria ### `just` recipes - [ ] `just containers-up` — starts every configured agent container - [ ] `just containers-down` — stops every agent container (worktrees/sessions persist in volumes) - [ ] `just containers-rebuild` — pulls the latest image and recreates each container one at a time - [ ] `just containers-logs [name]` — tail container logs - [ ] `just containers-shell <name>` — `docker exec -it <name> bash` for debugging ### systemd - [ ] Existing `claude-hooks.service` gains `After=docker.service` and `Requires=docker.service` - [ ] `ExecStartPre` / `ExecStopPost` hooks bring agent containers up/down in sync with the service - [ ] Service stop gracefully drains in-flight tasks before tearing down containers ### Rolling updates - [ ] Replacing one agent's container image does not affect the other agents or the running claude-hooks process - [ ] Document the procedure in `README.md`: pull new image, `just containers-rebuild <name>` ### Docs - [ ] `README.md` section on the containerised architecture, the host/container boundary, token rotation, image updates - [ ] Migration note: existing `~/.cache/claude-hooks` state is abandoned, new install starts clean with empty volumes ## Out of scope - Image build / publish — #18 - Container runtime / volumes — #19 ## References - Parent tracking issue: #17 ## Dependencies - **Blocked by:** #19 (runtime) - **Blocks:** none - **Branch off:** `main` - **Full graph:** #17

claude-desktop referenced this issue

2026-04-17 12:44:07 +00:00

Containers: image build + multi-arch publish #18

claude-desktop referenced this issue

2026-04-17 12:44:24 +00:00

Containers: per-agent runtime + state volumes #19

claude-desktop added this to the Containerised workers milestone

2026-04-17 12:44:29 +00:00

claude-desktop added the

area:infra

type:user-story

labels