# Docker In Machine

Runs a Docker daemon inside a smolvm machine and shows it working there, which is what...

- Repository: https://github.com/smol-machines/smolvm (6894 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add smol-machines/smolvm --skill docker-in-machine -g -a claude-code -y`
Codex: `npx skills add smol-machines/smolvm --skill docker-in-machine -g -a codex -y`
Cursor: `npx skills add smol-machines/smolvm --skill docker-in-machine -g -a cursor -y`
Gemini CLI: `npx skills add smol-machines/smolvm --skill docker-in-machine -g -a gemini-cli -y`

## Description

Runs a Docker daemon inside a smolvm machine and shows it working there, which is what tools that call Docker themselves need, such as a test suite that starts containers, an image build, or a coding agent that launches containers. Use when dockerd will not start inside a machine; when Docker worked on the first boot and broke after a stop and start; when deciding where Docker's data directory has to live; or when checking whether this is possible on a given platform at all. Do not use it to run OCI images, which smolvm boots natively without Docker, and do not attempt it on Windows, where the bundled guest kernel cannot support it.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# A Docker daemon inside a machine

Verified on **smolvm v1.29.0** on macOS arm64, 2026-10-15, and on **v1.18.2** on Linux aarch64, 2026-09-24; the Linux runs used
the Smolfile with `memory = 1024`, for a host reason given below. Done means `docker info` succeeds inside the guest, a nested container runs, and
Docker's data sits on the ext4 storage disk rather than the rootfs overlay.
The Linux runs used the scripts of their date; this version's preflight and cleanup scripts ran
on Linux aarch64 on v1.22.2 on 2026-10-03.

**On Windows, up to and including v1.22.2, `dockerd` does not start in a machine.** The Windows
guest kernel is built without bridge networking and POSIX message queues, so `dockerd` cannot
create its default network and, forced past that, containers still cannot be created.
`references/windows.md` has the evidence and the direct kernel probe, which gave the same answer on
v1.22.2.

## Docker's data has to be on the machine's disk on every start

From v1.28.1 a disk volume, a guest path with no host side, is a directory on the machine's ext4
disk, bound into the workload on every start ([#1787](https://github.com/smol-machines/smolvm/pull/1787)).
`assets/docker.smolfile` declares `/var/lib/docker` and `/var/lib/containerd` that way, and its
`docker:dind` image starts `dockerd` itself on every start, so nothing has to be re-applied after a
stop and start.

**On v1.28.0 and earlier, `init` runs once, so the bind mounts are gone on the second boot** and
have to be re-applied on every start. `assets/docker-bind-mounts.smolfile` is that configuration,
and `scripts/start-dockerd.sh` re-applies the mounts and starts the daemon, as the upstream
example's "Start dockerd" recipe does. Reproduced on both hosts on v1.14.2, v1.18.2 and v1.22.2,
on macOS on v1.16.1, and with that file on v1.29.0:

```
Init already completed, skipping 5 command(s)
NO_BIND_MOUNTS_AFTER_RESTART
DOCKERD_DOWN
```

The rest: https://github.com/smol-machines/smolvm/blob/HEAD/docs/docker-in-machine/SKILL.md