How to use the Docker Inside a smolvm Machine agent skill

What the skill makes the agent do

An agent skill is a folder of instructions and scripts that an AI agent loads when a request matches it. This one teaches the agent to run a Docker daemon (dockerd) inside a smolvm machine. Tools that call Docker themselves, such as a test suite that starts containers, an image build, or a coding agent that launches containers, need that daemon to exist.

The skill's own checks define success: docker info succeeds inside the guest, a nested container runs, and Docker's data sits on the machine's ext4 storage disk rather than the rootfs overlay.

• Set up the machine with a Docker image and two disk volumes for Docker's data
• Wait for the daemon to come up on every start
• Prove that containers run and that Docker's data is on the right disk
• Clean up the machine only when it is no longer wanted

Install the docker-in-machine skill

Download the ZIP for this skill from this page. Then add it to your agent in one of two ways.

For Claude Code, unzip the folder into ~/.claude/skills/ to make it available for you everywhere, or into a project's .claude/skills/ folder to make it available only in that project. For the Claude apps, upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Single project: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload

Know what you need before you start

The skill needs the smolvm binary installed on the host. It has been verified on macOS (Apple Silicon) and on Linux (aarch64). Its scripts run in a Bash shell, and the machine needs internet access to pull images such as docker:dind and alpine.

A Docker client on the host is optional. It is only needed if you want to use the host-side socket, and the skill does not verify that path.

Windows is not supported. The bundled guest kernel cannot run dockerd there, so the skill stops at its preflight step.

• smolvm binary
• Bash shell for the provided scripts
• Internet access to pull images
• Optional: a Docker client on the host

Run the setup scripts in order

The skill runs a fixed sequence. Start with the preflight check, which reports whether this platform can run Docker inside a machine. On macOS and Linux it reports verified; on Windows it reports unavailable with the reason.

Next, create the machine. On recent smolvm releases the default configuration is assets/docker.smolfile, which uses the docker:dind image with two disk volumes. Older releases need assets/docker-bind-mounts.smolfile instead. Then start the daemon and run the verify script. Verification pulls alpine:latest and checks the storage driver, the device under /var/lib/docker, nested container networking, and the host-side socket.

Why Docker stops working after a stop and start

On older smolvm releases, init runs only on the first start. Bind mounts applied there are gone on the second boot, so Docker comes back with its data directory on the wrong filesystem or with no running daemon. The symptoms are a daemon that will not start, or one that is running on the wrong filesystem. Your images are not lost, because they live on /storage.

The fix is to run scripts/start-dockerd.sh after every start. It re-applies the bind mounts, clears a stale pid file, and starts dockerd. On recent releases that use disk volumes, the image starts the daemon itself, but the script still waits for it to answer.

Where Docker's data has to live

Docker's data directories, /var/lib/docker and /var/lib/containerd, must be on the machine's ext4 disk. The machine's rootfs overlay cannot be used as the upper layer for Docker's nested overlay. Both Smolfiles therefore set storage = 20 and place the directories there, either as disk volumes or as bind mounts from /storage.

The check that matters is docker_root_device. docker info can succeed while Docker's data still sits on the rootfs overlay, and the resulting failure appears much later and is hard to trace.

• Check that docker_root_device reports /dev/vda
• Do not rely on docker info alone

Use the machine and be careful with the host socket

A machine someone asked for is the deliverable, so leave it running and give them its name, which is smolskill-docker by default. Copy code in with smolvm machine cp, or mount a folder with -v when you create the machine, then run it with smolvm machine exec.

The host socket is useful but powerful. Setting docker_socket = true bridges the guest's Docker socket to a host path, and anything on the host that can open that socket can start containers inside the machine. Leave it off unless a host tool needs it. Also note that net = true gives the whole machine outbound access, which the setup requires for pulling images. Scope it with --allow-host where you know which registries are used.

• Copy files in: smolvm machine cp <file> smolskill-docker:/workspace/<file>
• Run commands: smolvm machine exec --name smolskill-docker -- ...
• Remove when finished: scripts/cleanup.sh --purge