apple-containers
Skill for managing Apple Containers — macOS-native Docker alternative with per-container VMs on Apple Silicon.
Table of content
A skill that lets Claude Code manage Apple Containers
— the native macOS container runtime shipped in macOS 26. No Docker Desktop, no Colima. Just /usr/local/bin/container running Linux ARM64 images directly on Apple Silicon.
Save the definition to ~/.claude/skills/apple-containers/SKILL.md to activate.
What it does
- Start, stop, create, inspect containers
- Manage networks, volumes, images
- Handle the no-DNS networking workaround (dynamic IP lookup)
- Set up launchd autostart for multi-container stacks
Docker vs Apple Containers
| Feature | Docker Desktop | Apple Containers |
|---|---|---|
| Architecture | Shared Linux VM | VM per container |
| Isolation | Namespace-based | Hardware-level |
| Startup time | Seconds | Subsecond |
| DNS between containers | Yes | No |
| Compose file | Yes | No |
| Restart policies | Yes | No (use launchd) |
| License | Proprietary GUI | Apache 2.0 |
| CPU arch | x86 + ARM | ARM64 only |
Docker runs all containers inside one shared Linux VM. Apple spins up a lightweight VM per container. Better security isolation, but no shared kernel means no inter-container DNS.
Quick Start
container system start
container run docker.io/library/alpine:latest
container list --all
Command Reference
| Task | Command |
|---|---|
| Start system | container system start |
| Create | container create --name myapp image:tag |
| Start / stop | container start <id> / container stop <id> |
| Exec into | container exec <id> <cmd> |
| Logs | container logs <id> |
| Inspect | container inspect <id> |
| Delete | container rm <id> |
| Networks | container network list |
| Images | container image list |
| Volumes | container volume list |
bash
To run bash and interact with the container, you can use the following command:
container exec -it container-name bash
Networking Workaround
No DNS between containers. IPs change on restart. The skill handles this by reading IPs dynamically via container inspect and recreating dependent containers with fresh addresses.
container inspect <id> | python3 -c "
import sys,json
d = json.load(sys.stdin)[0]
print(d['networks'][0]['ipv4Address'].split('/')[0])
"
Known Limitations
- No
container update— stop, delete, recreate to change config - No DNS — containers can’t find each other by name
- No compose — manage multi-container stacks with shell scripts
- No restart policies — use launchd for autostart
- ARM64 only — no x86 emulation
View skill definition
---
name: apple-containers
description: Use when managing Apple Containers (macOS Docker alternative) - starting, stopping, creating, inspecting, networking, troubleshooting containers. Triggers on "container", "apple container".
---
# Apple Containers
macOS-native container runtime at `/usr/local/bin/container`. Linux ARM64 VMs with OCI images.
## Quick Reference
| Task | Command |
|------|---------|
| Start system | `container system start` |
| List all (incl stopped) | `container list --all` |
| Start/stop | `container start <id>` / `container stop <id>` |
| Logs | `container logs <id>` |
| Stats | `container stats` |
| Exec into | `container exec <id> <cmd>` |
| Inspect config | `container inspect <id>` |
| Delete | `container rm <id>` |
| Networks | `container network list` |
| Images | `container image list` |
| Volumes | `container volume list` |
## Create Container
container create \
--name myapp \
--network my_net \
-p 8080:8080 \
-v myvolume:/data \
-c 4 -m 1G \
-e "KEY=value" \
--env-file ./env.list \
docker.io/library/image:tag
Key flags: `--name`, `--network`, `-p host:container`, `-v volume:path`, `-c cpus`, `-m memory`, `-e env`, `--env-file`, `--mount`, `--entrypoint`
## Networking
- Containers on same network share a subnet but **no DNS** — hostnames don't resolve between containers
- IPs change on restart — never hardcode container IPs in env vars
- **Fix:** Use a startup script that reads IP dynamically via `container inspect` and recreates dependent containers
# Get container IP
container inspect <id> | python3 -c "
import sys,json
print(json.load(sys.stdin)[0]['networks'][0]['ipv4Address'].split('/')[0])
"
## Common Patterns
### Parse inspect JSON
container inspect <id> | python3 -c "
import sys,json
d = json.load(sys.stdin)[0]
print(d['status'])
print(d['networks'][0]['ipv4Address'])
print(d['configuration']['initProcess']['environment'])
"
### Autostart via launchd
Create `~/Library/LaunchAgents/com.container-autostart.plist` with `RunAtLoad=true` pointing to a startup script. Script should:
1. `container system start`
2. Start DB containers first, wait for IP
3. Recreate app containers with fresh DB IPs
4. Start remaining containers
## Known Limitations
- No `container update` — can't modify env/config on running container. Must stop, rm, create again
- No inter-container DNS — use IPs or /etc/hosts workarounds
- No docker-compose equivalent — manage multi-container stacks with shell scripts
- No restart policies — use launchd for autostart