---
title: Docker in a sandbox
description: Start dockerd inside a microsandbox VM and run containers from an interactive shell
icon: "docker"
---

This example starts a complete Docker environment inside a microsandbox VM. It is useful for sandboxed builds, agent workflows that need their own Docker daemon, or experiments you do not want leaking onto the dev machine. The host's Docker setup, if any, is left untouched.

The command below boots the `docker:dind` image on a flat root disk, starts Docker inside the sandbox, waits for it to be ready, and then opens an interactive shell. From there, Docker commands run against the daemon inside the sandbox, not your host.

## Run Docker in a sandbox

<Steps>

<Step title="Start Docker">

<Tooltip tip="Flat root disks are not yet available on microsandbox cloud."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

<CodeGroup>
```sh macOS & Linux
msb run --name docker-demo --replace \
  --memory 2G \
  --root-disk flat:10G \
  --script start='dockerd >/tmp/dockerd.log 2>&1 &
  timeout 60 sh -c "until docker info>/dev/null 2>&1;do sleep 1;done" || {
    cat /tmp/dockerd.log
    false
  }
  exec sh' \
  --entrypoint start \
  docker:dind
```

```powershell Windows
msb run --name docker-demo --replace `
  --memory 2G `
  --root-disk flat:10G `
  --script start='dockerd >/tmp/dockerd.log 2>&1 &
  timeout 60 sh -c "until docker info>/dev/null 2>&1;do sleep 1;done" || {
    cat /tmp/dockerd.log
    false
  }
  exec sh' `
  --entrypoint start `
  docker:dind
```
</CodeGroup>

This command does three things:

- Starts the `docker:dind` image in a sandbox named `docker-demo`.
- Gives the sandbox a 10 GiB flat root disk for the image, Docker data, and build cache.
- Runs the inline `start` script as the entrypoint. The script starts Docker, waits until it is ready, and then opens a shell.

The flat root mounts ext4 directly, so Docker's overlay storage is not nested on the default sandbox OverlayFS. Docker's images, containers, and build cache persist when the sandbox stops and starts, but are removed with the sandbox.

</Step>

<Step title="Run a container">

From the sandbox shell, run a nested Ubuntu container:

```sh
docker run -it --rm ubuntu bash
```

You are now in a container running inside Docker, which is itself running inside the microsandbox VM. Exit the Ubuntu container with `exit` to return to the `docker-demo` sandbox shell.

You can also verify the daemon with a short non-interactive command:

```sh
docker run --rm hello-world
```

</Step>

<Step title="Clean up">

Exit the sandbox shell:

```sh
exit
```

Back on the host, remove the sandbox:

```sh
msb rm -f docker-demo
```

Removing the sandbox also removes the nested daemon's images, containers, and build cache.

</Step>

</Steps>

## Details

The flat root gives Docker a direct ext4 filesystem. That matters because Docker's default storage driver uses overlay layers; a normal managed root would place those layers on top of the sandbox's own OverlayFS.

### Alternative: a separate disk for Docker data

A flat root disk is the easiest way to run Docker in a sandbox. If you prefer to keep the default layered root, give Docker a separate owned ext4 disk at `/var/lib/docker`:

<CodeGroup>
```sh macOS & Linux
msb run --name docker-demo --replace \
  --memory 2G \
  --mount-owned /var/lib/docker:kind=disk,size=10G \
  --script start='dockerd >/tmp/dockerd.log 2>&1 &
  timeout 60 sh -c "until docker info>/dev/null 2>&1;do sleep 1;done" || {
    cat /tmp/dockerd.log
    false
  }
  exec sh' \
  --entrypoint start \
  docker:dind
```

```powershell Windows
msb run --name docker-demo --replace `
  --memory 2G `
  --mount-owned /var/lib/docker:kind=disk,size=10G `
  --script start='dockerd >/tmp/dockerd.log 2>&1 &
  timeout 60 sh -c "until docker info>/dev/null 2>&1;do sleep 1;done" || {
    cat /tmp/dockerd.log
    false
  }
  exec sh' `
  --entrypoint start `
  docker:dind
```
</CodeGroup>

Docker gets a private ext4 disk for its data while the rest of the sandbox keeps its layered root. The disk survives stop/start and is removed with the sandbox.

To keep Docker data independently of the sandbox, use a [named volume](/sandboxes/volumes#named-volumes) instead:

```sh
--mount-named docker-data:/var/lib/docker:kind=disk,size=10G
```

## Notes

- **Memory.** The example uses `--memory 2G`. Increase it for larger builds or memory-hungry containers.
- **Not the same as [Sandbox in Docker](/examples/docker/docker).** That example covers the opposite direction.