001: Cellblock Phase 1 — Containerized Agents via workmux

Goal

workmux add feature-x opens a tmux window where claude-code runs inside a Docker container with the worktree mounted. SSH works. Nix flakes work. Config controls what each project can access.

What We Build

1. Docker image — Alpine + git + ssh + tools + fuse-overlayfs (~73MB)
2. cellblock CLI — bash prototype (Go rewrite planned), config → docker run
3. Config — ~/.config/cellblock/config.yaml, per-project permissions
4. Nix provider shim — pluggable nix base layer (linux-volume now, host-bind future)
5. Per-project COW overlays — overlayfs for /nix isolation
6. workmux integration — agent: cellblock run claude-code in .workmux.yaml

Core Design: Copy-on-Write Isolation

Everything uses the same pattern: read-only shared base + per-project COW upper.

/nix — two-layer overlay

/nix (overlayfs merge inside container)
├── upper: cellblock-nix-<project>    per-project COW (Docker volume, tiny deltas)
└── lower: <provider-dependent>       shared nix store (read-only)

Providers (shim abstraction for future Apple Containers):

• linux-volume: one-time cellblock nix init runs nix inside a Linux container to install agents into a shared Docker volume. All projects share it read-only.
• host-bind: direct bind-mount, zero copy. Works when container arch matches host.
• The overlay upper is identical either way — only the base source changes.

~/.claude — copy-on-start

• Host ~/.claude mounted read-only at /opt/claude-config
• Entrypoint copies to /home/cellblock/.claude (writable, per-container)
• Isolated, ephemeral — changes die with container

Networking — bridge (default)

• Default Docker bridge — containers isolated from each other
• Host services via host.docker.internal
• Per-project network: host option

Files

cellblock/
  plans/                       # phase plans (001, 002, 003)
  flake.nix                    # nix pkg + dev shell
  bin/cellblock                # CLI (bash prototype)
  lib/common.sh                # logging, path utils
  lib/config.sh                # YAML config reader (yq)
  lib/resolve.sh               # project/branch detection
  lib/docker.sh                # docker run arg assembly
  lib/nix.sh                   # nix provider shim + overlay management
  image/Dockerfile             # Alpine + git + ssh + tools
  image/entrypoint.sh          # UID mapping, overlayfs, config copy
  config/example.yaml          # example config
  tests/                       # bats tests

CLI

cellblock run <agent> [-- args...]   # run agent in container for cwd project
cellblock shell [project]            # interactive shell in container
cellblock stop [project]             # stop container
cellblock status                     # list running containers
cellblock nix init [packages...]     # init shared Linux nix store (one-time)
cellblock nix status                 # list nix volumes
cellblock nix reset-project [proj]   # reset per-project nix overlay
cellblock image build                # build the docker image

Config

~/.config/cellblock/config.yaml:

defaults:
  image: cellblock:latest
  ssh_agent: true
  nix_provider: linux-volume   # "linux-volume" or "host-bind"
  network: bridge              # "bridge" or "host"
  claude_config: ~/.claude

projects:
  treehouse:
    path: ~/work/treehouse
    env: [MIX_ENV=dev]

  petal_pro:
    path: ~/work/petal_pro
    env: [MIX_ENV=dev, DATABASE_URL]
    mounts:
      - ~/work/shared-libs:/shared-libs:ro

What cellblock run claude-code Executes

For cwd /Users/ijcd/work/treehouse, branch main, provider linux-volume:

docker run --rm -it \
  --name cellblock-treehouse-main-claude-code \
  --label cellblock=true \
  --label cellblock.project=treehouse \
  --cap-add SYS_ADMIN \
  -v /Users/ijcd/work/treehouse:/workspace \
  -v cellblock-nix-linux:/nix-base:ro \
  -v cellblock-nix-treehouse:/nix-overlay \
  -v /Users/ijcd/.claude:/opt/claude-config:ro \
  -v /run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock \
  -e SSH_AUTH_SOCK=/run/host-services/ssh-auth.sock \
  -e USER_UID=$(id -u) -e USER_GID=$(id -g) \
  -e MIX_ENV=dev \
  cellblock:latest \
  /nix/var/nix/profiles/default/bin/claude-code

Build Order

1. ✅ image/Dockerfile + entrypoint.sh
2. ✅ lib/common.sh + lib/config.sh
3. ✅ lib/resolve.sh
4. ✅ lib/docker.sh
5. ✅ bin/cellblock — CLI wiring
6. ✅ lib/nix.sh — provider shim + overlay management
7. ✅ flake.nix
8. 🔄 Integration testing (shell, overlay verified; nix init next)
9. ⬜ workmux integration — end-to-end test

Verification

1. ✅ cellblock image build succeeds
2. ✅ cellblock shell → git --version works inside container
3. ✅ Overlay mount confirmed: overlay on /nix type overlay (rw,...)
4. ✅ ~/.claude copy-on-start works, isolated per container
5. ✅ SSH agent socket mounted and accessible
6. ⬜ cellblock nix init populates Linux nix store
7. ⬜ cellblock run claude-code starts agent in container
8. ⬜ Inside: ssh -T git@github.com succeeds
9. ⬜ Inside: nix develop works on a flake project
10. ⬜ workmux add test-feature → tmux window with containerized agent
11. ✅ 36 bats tests passing

Not in Phase 1

• Pluggable isolators / Apple Containers / remote (Docker only, but shim ready; see plan 004)
• Remote isolators: Fly.io, E2B, cloud-vm (see plan 004)
• Treehouse network identity
• Multi-project cellblock up
• Orchestrator tier
• Proxy tracking
• Go rewrite (planned after API stabilizes)
• Watchdog interceptor (see plan 002)
• LiveView workmux UI (see plan 003)

Resolved

1. ~/.claude isolation — copy-on-start. Mount ro, copy in entrypoint. Ephemeral.
2. Networking — bridge default. host.docker.internal for host access.
3. Nix architecture mismatch — host /nix has macOS binaries, containers are Linux. Solved with provider shim: linux-volume (shared Linux nix Docker volume) for now, host-bind (direct mount) when Apple Containers make arch match.
4. Nix isolation — two-layer overlayfs. Shared base (ro) + per-project COW upper. Base protected. Per-project writes persist. nix develop works.