feat: add apple-container local development provider

[zozo123]

Summary

• add provider: apple-container as a built-in local-development provider for Apple's native container runtime (https://github.com/apple/container) on Apple-silicon macOS
• provider-owned adapter under internal/providers/applecontainer that shells out to the container CLI for lifecycle (run/ls/inspect/delete) and runs command exec + file sync over standard Crabbox SSH, reusing the core SSH helpers exactly as local-container/ascii-box do
• config/env/flags, provider docs, registration, and table-driven regression coverage

Design Notes

Apple's runtime is not assumed Docker-compatible, so this does not reuse the local-container Docker code. Each Apple container gets its own routable IP on the host bridge, so the SSH target is the container IP on port 22 (CIDR-stripped from the inspect networks address) rather than a published loopback host port. Apple-specific lifecycle stays behind the adapter; core stays provider-neutral. The bare container alias is left to local-container; this provider uses apple-container (apple, applecontainer). macOS/Apple-silicon gated (darwin/arm64); rejects non-Linux targets and --tailscale; the container run forces --user root so the bootstrap can install/start sshd regardless of the image's default user; no secrets passed as CLI args.

Config / Secrets

• CLI path env: CRABBOX_APPLE_CONTAINER_CLI; config block appleContainer.*; aliases apple, applecontainer
• default image follows the Crabbox OS image (--os, currently ubuntu:26.04)

Review feedback addressed (ClawSweeper)

• Rebased onto latest main — conflict-free.
• [P3] Removed release-owned CHANGELOG.md entry (now identical to main).
• [P3] Fixed documented default image (debian:bookworm → the --os-derived default).
• [P2] macOS gate now requires darwin/arm64 (rejects amd64 Macs); Doctor reuses requireMacOS().
• [P2] container run --user root so a non-root image USER can't stall the SSH wait (+ regression assertion).
• [P3] Documented the macOS 26 runtime requirement.
• [P1] Full SSH/sync/run E2E now proven — see below.

Verification

gofmt -l ...            # clean
go build -trimpath -o bin/crabbox ./cmd/crabbox   # OK
go vet ./...            # OK
go test ./internal/cli ./internal/providers/applecontainer ./internal/providers/all   # ok

CI: Go · Docs · Plugin · Worker · Release Check all green.

Live / E2E (full path proven on Apple silicon)

Host: Darwin arm64, Apple container CLI v0.3.0. Because Apple's sandbox containers on this host have no outbound network egress, the bootstrap can't apt-get into the stock image — so this uses the documented prebuilt-image path. The image was built once and loaded into the runtime (reproducible):

docker buildx build --platform linux/arm64 -o type=oci,dest=sshd.tar .   # ubuntu:24.04 + openssh-server,git,rsync,curl,sudo,python3
container images load -i sshd.tar    # -> crabbox-sshd:latest

Full crabbox run (create → SSH → sync → remote command → cleanup):

$ crabbox run --provider apple-container --apple-container-image crabbox-sshd:latest -- \
    sh -lc 'echo ===REMOTE_OK===; whoami; uname -sm; python3 --version; cat README.txt'
provisioning provider=apple-container lease=<redacted> slug=jade-crayfish image=crabbox-sshd:latest keep=false
provisioned lease=<redacted> container=crabbox-jade-crayfish-<id> state=ready
syncing /private/tmp/e2e-demo -> 192.168.64.15:/work/crabbox/<lease>/e2e-demo
  ssh=crabbox@192.168.64.15:22 ip=192.168.64.15
sync candidate: 1 files, 39 B
sync complete in 342ms
running on 192.168.64.15 sh -lc 'echo ===REMOTE_OK===; whoami; uname -sm; python3 --version; cat README.txt'
===REMOTE_OK===
crabbox
Linux aarch64
Python 3.12.3
hello crabbox e2e 2026-05-31T11:00:55Z
command complete in 41ms total=397ms
run summary sync=342ms command=41ms total=397ms sync_skipped=false exit=0
releasing <redacted> server=crabbox-jade-crayfish-<id>
lease cleanup stopped=true policy=auto

This exercises the complete path the P1 finding asked for: the container reaches SSH (state=ready), Crabbox syncs the working tree, executes a remote command over SSH (whoami crabbox, Linux aarch64, reads the synced file), and cleans up (stopped=true, container ls clean afterward). doctor and the lifecycle (create/inspect/delete) were also verified live earlier.

Closes #187

🤖 Generated with Claude Code

[clawsweeper]

Codex review: needs changes before merge. Reviewed May 31, 2026, 9:50 AM ET / 13:50 UTC.

Summary
The branch adds an apple-container built-in SSH-lease provider with config/env/flags, provider docs, registration, cache-volume support, actions-runner rejection, and Go regression tests.

Reproducibility: not applicable. as a feature PR; there is no current-main bug path to reproduce. The contributor supplied live terminal proof for create, SSH readiness, sync, remote command execution, and cleanup on Darwin/arm64.

Review metrics: 3 noteworthy metrics.

• Diff size: 18 files, +2044/-3. This is a broad built-in provider addition touching runtime code, config, docs, and tests.
• Built-in providers added: 1 added. A new built-in provider creates maintainer-owned runtime support rather than an external plugin-only path.
• Release-owned files changed: 1 changed. CHANGELOG.md is release-owned and should be cleaned before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Remove the CHANGELOG.md entry from the PR branch before merge.

Risk before merge

• [P1] The provider is opt-in but cannot be exercised by the repository's normal Linux CI, so maintainers are relying on Darwin/arm64 live terminal proof plus source-level tests for the Apple runtime path.
• [P1] The documented default-image bootstrap still needs container network egress on first start; no-egress hosts must use the documented prebuilt-image path.

Maintainer options:

1. Land as documented opt-in provider (recommended)
   Maintainers can accept the Apple-runtime availability risk because the provider is opt-in, documents its constraints, and has Darwin/arm64 terminal proof for the full SSH/sync/run path.
2. Require maintainer-owned Mac smoke
   If maintainers want independent proof before owning the provider, pause merge until the same crabbox run --provider apple-container path is run on a maintainer-controlled Apple silicon host.

Next step before merge

• A narrow automated cleanup can remove the release-owned changelog line; the remaining provider ownership decision stays with maintainers.

Security
Cleared: No concrete security or supply-chain regression was found; the provider shells out to a user-configured local CLI and passes only the per-lease public key into the container bootstrap.

Review findings

• [P3] Remove the release-owned changelog entry — CHANGELOG.md:7

Review details

Best possible solution:

Land the provider-owned adapter after removing the release-owned changelog entry, with maintainers explicitly accepting the documented macOS 26/Apple-silicon and no-egress constraints.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a feature PR; there is no current-main bug path to reproduce. The contributor supplied live terminal proof for create, SSH readiness, sync, remote command execution, and cleanup on Darwin/arm64.

Is this the best way to solve the issue?

Yes, mostly: a provider-owned adapter is the maintainable direction because Apple's runtime is not Docker-compatible and core stays provider-neutral. The release-owned changelog line should be removed before merge.

Full review comments:

• [P3] Remove the release-owned changelog entry — CHANGELOG.md:7
  This PR still adds a release note to CHANGELOG.md, but this repository treats that file as release-owned. Please remove this line and keep the release-note context in the PR body or commit message instead.
  Confidence: 0.97

Overall correctness: patch is correct
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 43eace2507d3.

Label changes

Label changes:

• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• remove rating: 🦞 diamond lobster: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P2: This is a useful built-in provider feature with limited opt-in blast radius and normal maintainer-review urgency.
• merge-risk: 🚨 availability: The new provider can fail or stall at runtime on unsupported Apple/container setups, and normal Linux CI cannot exercise that path.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. A native Apple container provider would give Apple silicon users a zero-cloud Linux lease path without Docker-compatible runtime setup.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes after-fix terminal output from a real Darwin/arm64 setup showing provisioning, SSH readiness, sync, command execution, and cleanup.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix terminal output from a real Darwin/arm64 setup showing provisioning, SSH readiness, sync, command execution, and cleanup.

Evidence reviewed

Acceptance criteria:

• [P1] git diff --check.
• [P1] git diff -- CHANGELOG.md.

What I checked:

• Repository policy read: Read the full target AGENTS.md; provider-neutral boundaries, generic positioning, focused tests, and release-owned changelog guidance affected this review. (AGENTS.md:1, 43eace2507d3)
• Current main does not already implement this provider: No apple-container, applecontainer, or AppleContainer symbols exist on current main, so the PR is not obsolete or implemented on main. (43eace2507d3)
• Provider implementation surface: The PR adds an SSH-lease provider spec with SSH, sync, cleanup, and cache-volume features, keeping the Apple-specific lifecycle behind internal/providers/applecontainer. (internal/providers/applecontainer/provider.go:21, e95f63a9d73d)
• Runtime path source check: The backend builds container run -d with labels, root bootstrap, SSH env, cache volumes, and later waits for SSH readiness at the inspected container IP. (internal/providers/applecontainer/backend.go:350, e95f63a9d73d)
• Regression tests added: The branch adds table-style checks for run arguments, cache volume naming, Darwin/arm64 gating, and doctor run-surface validation. (internal/providers/applecontainer/backend_test.go:152, e95f63a9d73d)
• Real behavior proof: The PR body and follow-up comment include terminal output from Darwin arm64 with Apple container CLI v0.3.0 showing provisioning, SSH readiness, sync, remote command output, and cleanup. (e95f63a9d73d)

Likely related people:

• Peter Steinberger: Current main provider registration, config defaults, actions-runner validation, and local-container cache-volume behavior blame to the recent local-container cache-volume commit; the PR branch also includes follow-up hardening commits by the same person. (role: recent area contributor and adjacent owner; confidence: high; commits: 25ba60b020af, e815ced5703f, e95f63a9d73d; files: internal/cli/config.go, internal/cli/provider_backend.go, internal/providers/all/all.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[zozo123]

Pushed 001bafe addressing the review:

• Rebased onto latest main — the DIRTY/CONFLICTING state is resolved (conflict was in CHANGELOG.md after docs: scope README Release badge to push events #191 + the cache-volumes feature landed).
• [P3] Removed the release-owned CHANGELOG.md entry — it is now byte-identical to main.
• [P3] Fixed the documented default image: docs said debian:bookworm but the effective default is the --os-derived Crabbox OS image (ubuntu:26.04, as doctor reports). All three doc references corrected.
• [P1] Full SSH/sync/run E2E: honestly documented. Lifecycle (create/inspect/delete) is proven live on Apple-silicon + container v0.3.0; the in-guest SSH path can't be proven in this environment (containers have no network egress and no sshd image, so the bootstrap can't install sshd). Docs now state SSH/sync/run needs an egress-capable or sshd-preinstalled image (lifecycle-MVP framing).

Gate green after rebase: build, vet, go test ./internal/cli ./internal/providers/applecontainer ./internal/providers/all.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26709862114
• Updated: 2026-05-31T10:21:03.634Z

[zozo123]

Pushed 7013b81 addressing the new re-review findings:

• [P2] Reject non-Apple-silicon Macs (backend.go): requireMacOS() now requires runtime.GOOS == darwin and runtime.GOARCH == arm64 (error message includes both), and Doctor reuses requireMacOS() instead of its own GOOS-only check — so darwin/amd64 is rejected up front.
• [P2] Keep the bootstrap on a root-capable path (backend.go): container run now passes --user root so the bootstrap can install packages, create the SSH user, write /etc/sudoers.d, and start sshd regardless of the image's default USER. Added a regression assertion (--user root) to TestCreateContainerBuildsRunArgs. Verified live: with --user root the container stays running (IP assigned) instead of exiting early.
• [P3] Document the macOS 26 runtime requirement (apple-container.md): Prerequisites now state macOS 26+ on Apple silicon (older releases unsupported) and that the gate is darwin/arm64.

Gate green: gofmt, build, vet, go test ./internal/providers/applecontainer ./internal/providers/all; doctor still reports ready against container v0.3.0.

On the standing [P1]: full in-guest SSH/sync/run still can't be proven from my environment (sandbox containers have no network egress and no sshd-preinstalled image, so the bootstrap can't bring sshd up; lifecycle create/inspect/delete is proven live). Flagging for maintainer scope decision per the review's lifecycle-MVP option.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Failed
• Detail: The targeted re-review did not finish cleanly. Check the workflow run for details.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26711079584
• Updated: 2026-05-31T11:20:53.022Z

[zozo123]

[P1] Full SSH/sync/run E2E is now proven on Apple silicon (container CLI v0.3.0).

This host's Apple containers have no outbound egress (confirmed at routing level — raw-IP TCP fails, not just DNS), so the bootstrap can't apt-get into the stock image. Per the documented prebuilt-image path, I built an arm64 image with the bootstrap tools and loaded it into the runtime (reproducible):

docker buildx build --platform linux/arm64 -o type=oci,dest=sshd.tar .   # ubuntu:24.04 + openssh-server,git,rsync,curl,sudo,python3
container images load -i sshd.tar    # -> crabbox-sshd:latest

Then a full crabbox run against it:

provisioned lease=<redacted> container=crabbox-jade-crayfish-<id> state=ready
syncing /private/tmp/e2e-demo -> 192.168.64.15:/work/crabbox/<lease>/e2e-demo
sync complete in 342ms
running on 192.168.64.15 sh -lc 'echo ===REMOTE_OK===; whoami; uname -sm; python3 --version; cat README.txt'
===REMOTE_OK===
crabbox
Linux aarch64
Python 3.12.3
hello crabbox e2e 2026-05-31T11:00:55Z
run summary sync=342ms command=41ms exit=0
lease cleanup stopped=true

Complete path exercised: reaches SSH (state=ready) → syncs the working tree → executes a remote command over SSH (whoami crabbox, Linux aarch64, reads the synced file) → cleans up (stopped=true; container ls clean). PR body updated with the full transcript.

@clawsweeper re-review

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26710817382
• Updated: 2026-05-31T11:10:28.380Z

[zozo123]

Pushed d1e78bf addressing both new P2 findings:

• [P2] Wire apple-container into --os defaults (config.go): added appleContainerImageExplicit tracking + MarkAppleContainerImageExplicit, an apple-container branch in applyOSImageProviderDefaults (mirroring local-container), and explicit-marking in the flag/file/env paths. Verified live: CRABBOX_OS=ubuntu:24.04 crabbox doctor --provider apple-container now reports image=ubuntu:24.04 (default stays ubuntu:26.04); an explicitly-set appleContainer.image is preserved. Regression tests: TestAppleContainerImageFollowsOSImageDefault, TestAppleContainerExplicitImageSurvivesOSDefault.
• [P2] Reject --actions-runner (provider_backend.go): validateActionsRunnerCapability now rejects apple-container alongside local-container (the bootstrap execs sshd as PID 1 with no init system, so the runner installer's systemctl can't run). Verified live: warmup --provider apple-container --actions-runner → --actions-runner is not supported for provider=apple-container.... Regression test: TestValidateActionsRunnerCapabilityRejectsAppleContainer; documented in the provider limitations.

Gate green: gofmt, build, vet, go test ./internal/cli ./internal/providers/applecontainer ./internal/providers/all.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Superseded
• Detail: A newer re-review for this item started before this run finished, so GitHub cancelled this older run. Check the latest ClawSweeper run for the current result.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26711564632
• Updated: 2026-05-31T11:42:45.260Z

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26711930746
• Updated: 2026-05-31T12:01:41.945Z

[zozo123]

Pushed c03dced addressing the new finding:

• [P1] Probe the container run surface in doctor (backend.go): Doctor now runs container run --help (no side effects) after system status and verifies the lease-path options --user and --label are advertised, before reporting ready. An install whose service/list API exists but whose run subcommand is absent or incompatible now fails doctor up front instead of passing and failing on the first warmup/run. Doctor message now includes run=ready. Live-verified against container v0.3.0: cli=ready run=ready .... Regression test TestDoctorRejectsIncompatibleRunCLI covers both missing-subcommand and missing-options cases.

Gate green: gofmt, build, vet, go test ./internal/cli ./internal/providers/applecontainer ./internal/providers/all.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26712135891
• Updated: 2026-05-31T12:12:29.929Z