> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker

> Run captured command lines in an existing Docker container.

`DockerRuntime` connects to a container you started and executes every captured
line inside it. Mirage does not create, size, stop, or delete the container.
See the [Sandbox overview](/python/runtime/sandbox) first for routing, the
shared image, and how to serve workspace mounts inside the sandbox.

## Start the container

Live FUSE mounts need `SYS_ADMIN`, `/dev/fuse`, and the Mirage fuse image on a
Linux host:

```bash theme={null}
docker run -d --cap-add SYS_ADMIN --device /dev/fuse \
  --name my-sandbox mirage-python-fuse sleep infinity
docker cp sandbox.yaml my-sandbox:/tmp/sandbox.yaml
docker exec my-sandbox mirage workspace create /tmp/sandbox.yaml
```

You can bake `sandbox.yaml` into the image instead of copying it. Sizing, GPUs,
networks, volumes, and bind mounts belong on your own `docker run` command.

## Connect from Python

```python theme={null}
from mirage import MountMode, Workspace
from mirage.accessor.s3 import S3Config
from mirage.resource.s3.s3 import S3Resource
from mirage.runtime.sandbox.docker import DockerRuntime

runtime = DockerRuntime(captures=["python3"],
                        config={"container": "my-sandbox"})
ws = Workspace({"/data": S3Resource(S3Config(bucket="my-bucket"))},
               mode=MountMode.EXEC,
               runtimes=[runtime, "vfs"])
await ws.execute("python3 job.py", cwd="/data")
```

The `container` config accepts a container name or id. Unknown config fields
fail at construction. The Docker CLI is the transport, so there is no SDK or
daemon-socket integration; Docker Desktop, Colima, and a compatible Podman
alias work through the same command surface. Stdin and stderr stay separate.

<Warning>
  Mirage timeouts stop waiting for `docker exec`; they do not kill the process
  inside the container. Stop it yourself or enforce limits at the container
  layer. See [Resource limits](/python/runtime/sandbox#resource-limits).
</Warning>