remote-workbench: self-hosted Mac target — workbench in an apple/container Linux VM (zero cloud cost)

[Hmbown]

Goal

Add a self-hosted Mac target to the remote workbench: run the CodeWhale runtime + Telegram bridge inside an isolated Linux container on Apple silicon via apple/container, instead of renting a VPS. Zero cloud cost, phone-controlled, and the agent is sandboxed away from the host Mac.

Motivating setup: an always-on Apple-silicon desktop (e.g. a Mac Studio with 36 GB RAM) dedicating ~16 GB and a few cores to a containerized workbench.

Why this works

• No inbound ports needed. The bridge is outbound long polling and the runtime binds 127.0.0.1 — a Mac behind home NAT is exactly as reachable as a cloud VM. Nothing about the v0.8.56: Ship DigitalOcean + Telegram remote-workbench setup #2964 lane assumes a public IP.
• arm64 Linux binaries already ship with every release (codewhale-linux-arm64, codewhale-tui-linux-arm64 + sha256 manifest) — native speed in an Apple-silicon Linux VM, no Rust build.
• The existing multi-arch Docker image is OCI-compliant, and apple/container runs OCI images — the distribution artifact already exists (docs/DOCKER.md).
• Isolation is better than running natively on the Mac: a phone-controlled agent with allow_shell=true lives inside a lightweight VM with hard CPU/memory caps (--cpus, --memory 16g), with only explicitly mounted volumes visible. The runtime API on container-localhost is unreachable even from the host LAN. Teardown = delete container + volumes.
• With ≥8 GB the container can run cargo builds and subagents comfortably — more headroom than the entry VPS tiers.

Design sketch

• New target alongside the VPS lane (and a CloudTarget row candidate for the codewhale remote-setup wizard: guided cloud + chat-bridge + provider setup (/remote) #2965 remote-setup wizard, slug e.g. mac-container):
  • Reuse the existing image or a thin variant; reuse the env-file layout (runtime.env, telegram-bridge.env) mounted read-only from a host directory (chmod 600).
  • Supervision without systemd (these containers do not run systemd as init): a small entrypoint that starts codewhale serve --http --host 127.0.0.1 and the bridge, restarts on failure, and exits nonzero when both are down — mirroring the .service units' Restart=on-failure semantics.
  • Boot/restart persistence on the host: a launchd plist that runs container run ... at load and keeps it alive (the macOS equivalent of systemctl enable).
  • Volumes: /opt/whalebro (workspace + checkout), /var/lib/codewhale-telegram-bridge (thread map), env dir.
  • Doctor: adapt scripts/tencent-lighthouse/doctor.sh checks that assume systemd into a container-aware variant (process supervision + health checks still apply; systemctl sections skipped).
  • Host notes: prevent sleep (pmset/caffeinate), Apple silicon required, macOS 26 recommended (macOS 15 has container networking limitations; single-container layout avoids most of them).

Scope

• scripts/remote-smoke/mac-container/: entrypoint, launchd plist template, setup + teardown scripts, README (mirroring digitalocean/).
• Container-aware doctor variant (or doctor flags to skip systemd sections).
• Docs: section in the remote-workbench docs presenting the three lanes side by side (DO VPS / Tencent HK / self-hosted Mac) with cost + isolation tradeoffs.
• Wizard follow-up: register mac-container as a row in codewhale remote-setup wizard: guided cloud + chat-bridge + provider setup (/remote) #2965.

Non-goals

• Intel Macs (Apple silicon only).
• A macOS-native (non-container) supervision path — running the agent loose on the host defeats the isolation purpose here.
• Webhook mode / public ingress (unchanged from the VPS lane).
• Replacing Docker in CI or for the published image build (v0.8.56: Ship DigitalOcean + Telegram remote-workbench setup #2964 lane and release flow unchanged).

Acceptance criteria

• Fresh Apple-silicon Mac → working phone control using only the README: container starts with capped resources, runtime healthy on container-localhost, bridge polls, allowlist enforced.
• The full v0.8.56: Ship DigitalOcean + Telegram remote-workbench setup #2964 phone smoke passes identically: /status, prompt → turn, approval allow/deny, /interrupt (requires telegram-bridge: serial update dispatch deadlocks approvals — poll loop must never await a turn #2966), restart behavior.
• Host reboot → launchd brings the container back; both processes resume (reattach behavior intact).
• Runtime API is not reachable from the host LAN (verify from another device).
• Teardown documented: stop/remove container + volumes + plist; nothing left running.

Related

• v0.8.56: Ship DigitalOcean + Telegram remote-workbench setup #2964 (DO VPS lane — shares binaries, env layout, smoke checklist)
• codewhale remote-setup wizard: guided cloud + chat-bridge + provider setup (/remote) #2965 (remote-setup wizard — this becomes a cloud/target row)
• telegram-bridge: serial update dispatch deadlocks approvals — poll loop must never await a turn #2966 (dispatch fix — prerequisite for the approval/interrupt smoke here too)
• docs/DOCKER.md, docs/REMOTE_VM_US.md