Apple Container

How it works

The /convert-to-apple-container skill switches NanoClaw’s container runtime from Docker to Apple Container, Apple’s native container technology for macOS. The migration changes the runtime binary, mount syntax, and a few internal details, but everything else stays the same — your channels, agent behavior, mount allowlists, and exported interfaces are unaffected.

The conversion isn’t bundled with a fresh install — it’s distributed as the skill/apple-container branch on the upstream repo (see docs/BRANCH-FORK-MAINTENANCE.md). The skill applies it by merging that branch (git fetch upstream skill/apple-container && git merge upstream/skill/apple-container), which brings in five changed files:

• src/container-runtime.ts — the main runtime interface, rewritten for Apple Container’s API. Mount syntax changes from Docker’s -v path:path:ro to --mount type=bind,source=...,target=...,readonly.
• src/container-runner.ts — removes Docker’s /dev/null .env shadow mount and starts main-group containers as root so the entrypoint can mount --bind (Apple Container only supports directory mounts, not Docker’s file overlay trick), then drops privileges via setpriv.
• container/Dockerfile — updated entrypoint that handles .env shadowing inside the container.
• container/build.sh — defaults to the container binary instead of docker.
• src/container-runtime.test.ts — tests updated for Apple Container behavior.

After the code changes, you rebuild the container image with ./container/build.sh and restart the service. The switchover is immediate.

Why switch

Apple Container is a first-party macOS runtime optimized for Apple Silicon. Compared to Docker Desktop:

• Faster startup. Containers launch faster because there’s no Linux VM layer — Apple Container runs containers natively on macOS.
• Lower overhead. No Docker daemon running in the background consuming memory and CPU.
• Simpler stack. One fewer dependency to install and maintain. Apple Container is a single binary.

The trade-off is that Apple Container is macOS-only and newer than Docker, so edge cases may exist. If you run NanoClaw on Linux, Docker is the only option.

What changes

The security model stays the same. NanoClaw’s mount allowlist still controls which directories the agent can access. Containers still run as a non-root user (uid 1000). Read-only mounts are still the default.

One internal difference: Apple Container doesn’t support mounting individual files, only directories. Docker uses a /dev/null overlay to hide the .env file inside the container (so agents can’t read secrets). Apple Container achieves the same result using mount --bind to shadow the file, which requires the container entrypoint to start as root and then drop privileges with setpriv. The end result is identical — the agent can’t read .env — but the mechanism is different.

Rollback

The change lands as a git merge of the upstream skill/apple-container branch, so it’s tracked in your git history. If you need to switch back to Docker, revert the merge commit with git, rebuild the container image with ./container/build.sh, and restart the service.

Troubleshooting

Apple Container not found. Download from Apple’s container releases, install the .pkg file, and verify with container --version.

Runtime won’t start. Run container system start followed by container system status to check.

Image build fails. Apple Container caches aggressively. A clean rebuild usually fixes it: container builder stop && container builder rm && container builder start, then re-run ./container/build.sh.

Container can’t write to mounted directories. Check directory permissions on the host. The container runs as uid 1000, so the mounted directory needs to be writable by that user.

Tips

• Fresh installs use Docker by default — setup doesn’t offer a runtime choice. Run this conversion after setup completes if you want Apple Container.
• Apple Container and Docker can coexist on the same machine. Switching NanoClaw to Apple Container doesn’t affect other Docker workloads.
• The container image format is compatible. You don’t need to maintain separate Dockerfiles.