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 IPC protocol are unaffected.

The skill applies changes through the skills engine, which modifies five 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 — adds .env file shadowing via mount --bind (Apple Container only supports directory mounts, not Docker’s file overlay trick) and privilege dropping via setpriv for main-group containers.
• 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

If you need to switch back to Docker, the simplest path is to re-clone NanoClaw’s source files for the five changed files and rebuild. The skills engine records the change in .nanoclaw/state.yaml, so you can track what was modified.

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

• If you’re setting up NanoClaw for the first time on macOS, the /setup skill lets you choose Apple Container during initial setup — no need to run this conversion skill separately.
• 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.