Skip to main content

​
Overview

The /convert-to-apple-container skill switches NanoClaw’s container runtime from Docker to Apple Container, providing native macOS container isolation without requiring Docker Desktop.
This skill is macOS-only. Apple Container does not work on Linux or Windows.

​
What It Changes

​
Runtime Binary

  • docker → container

​
Mount Syntax

  • Docker: -v path:path:ro
  • Apple Container: --mount type=bind,source=...,target=...,readonly

​
Startup Checks

  • Docker: docker info
  • Apple Container: container system status with auto-start

​
Build Process

  • Updates container/build.sh to use container command
  • Adjusts Dockerfile for Apple Container compatibility

​
Prerequisites

1

Install Apple Container

Download from github.com/apple/container/releasesInstall the .pkg file for your macOS version.
2

Verify installation

container --version
Should show the installed version.
3

Check system requirements

  • macOS 12 (Monterey) or later
  • Admin access for installation

​
How to Apply

/convert-to-apple-container
The skill will:
  1. Check if already applied (reads .nanoclaw/state.yaml)
  2. Verify current runtime
  3. Apply code transformations via skills engine
  4. Rebuild container image
  5. Verify the new runtime works

​
What Changes

​
Modified Files

  • src/container-runtime.ts - Runtime detection and commands
  • src/container-runner.ts - Mount syntax and container spawn
  • container/build.sh - Build script runtime
  • container/Dockerfile - Entrypoint adjustments for .env shadowing

​
Behavioral Changes

  • Main group containers start as root to use mount --bind for .env shadowing
  • Privileges dropped via setpriv after mount
  • Non-main containers still use --user flag (no change)
Apple Container only supports directory mounts, not file mounts. The .env file is shadowed using mount --bind inside the container instead of Docker’s /dev/null overlay.

​
Advantages

Native macOS

No need for Docker Desktop license

Lighter Weight

Smaller memory footprint than Docker

Apple Support

Maintained by Apple as part of macOS

Security

macOS-native container isolation

​
Verification

After conversion, verify: 
# Check runtime
grep CONTAINER_RUNTIME_BIN src/container-runtime.ts

# Test container spawn
npm run dev
# Send a test message to trigger container

# Check logs
tail -f logs/nanoclaw.log

​
Rollback

To switch back to Docker:
  1. Restore from backup branch (skill creates one automatically)
  2. Or manually edit src/container-runtime.ts to use docker
  3. Rebuild: npm run build && ./container/build.sh

Container Isolation

How container security works

macOS Deployment

macOS-specific setup

Build docs developers (and LLMs) love

Get started for freeTalk to us