> ## 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 programs in a Docker container you started.

The `docker` machine provider reaches a running container, by name, and
runs the programs it captures in it. You start
and stop the container; Mirage only runs programs in it. Python SDK and
Node.

## Installation

> [tab] Python
>
> ```bash theme={null}
> pip install 'mirage-ai[ssh]'
> ```

> [tab] TypeScript
>
> ```bash theme={null}
> pnpm add ssh2
> ```

These serve the workspace into the container with `mount_type: ssh`. Start
the container with FUSE allowed and `sshfs` in it, or from an image that has
what [connecting the workspace](#connecting-the-workspace) needs:

```bash theme={null}
docker run -d --cap-add SYS_ADMIN --device /dev/fuse \
  --name my-sandbox python:3.12-slim sleep infinity
docker exec my-sandbox sh -c 'apt-get update && apt-get install -y sshfs'
```

## Usage

`captures` defaults to [`@external`](https://docs.mirage.strukto.ai/home/setup/machine/overview#captures):
every program Mirage does not have itself. Name `@python` to run
Python in the container too.

> [tab] Python
>
> ```python theme={null}
> from mirage import RAMVFS, MountMode, Workspace
>
> ws = Workspace(
>     {"/data": RAMVFS()},
>     mode=MountMode.EXEC,
>     machines={
>         "box": {
>             "provider": "docker",
>             "container": "my-sandbox",
>             "mount_type": "ssh",
>             "captures": ["@python", "@external"],
>         }
>     },
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'
>
> const ws = new Workspace(
>   { '/data': new RAMVFS() },
>   {
>     mode: MountMode.EXEC,
>     machines: { box: { provider: 'docker', container: 'my-sandbox', mountType: 'ssh', captures: ['@python', '@external'] } },
>   },
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```

> [tab] YAML
>
> ```yaml theme={null}
> mode: exec
> machines:
>   box:
>     provider: docker
>     container: my-sandbox
>     mount_type: ssh
>     captures: ["@python", "@external"]
> mounts:
>   /data:
>     vfs: ram
> ```

Save the YAML as `workspace.yaml` and run a line from the CLI:

```bash theme={null}
mirage workspace create workspace.yaml -w box-demo
mirage shell -w box-demo -c 'echo hello > /data/hi.txt; python3 -c "print(open(\"/data/hi.txt\").read().upper())"'
```

`python3` runs in the container and reads the file Mirage wrote, so this
prints `HELLO`. Remove both with `mirage workspace delete box-demo` and
`docker rm -f my-sandbox`.

## Connecting the workspace

Pick a [`mount_type`](https://docs.mirage.strukto.ai/home/setup/machine/overview#connecting-the-workspace). With `ssh`, the image needs only `sshfs`. With
`mirage`, it needs `fuse3` and `uv` or `npm` to install
[`mirage-fuse`](https://docs.mirage.strukto.ai/home/setup/machine/overview#mirage). With `own`,
copy `sandbox.yaml` in and start Mirage in the container:

```bash theme={null}
docker cp sandbox.yaml my-sandbox:/tmp/sandbox.yaml
docker exec my-sandbox mirage workspace create /tmp/sandbox.yaml
```

## Pausing the container

To pause the container when the workspace pauses, set `on_pause: pause` on the
machine:

```yaml theme={null}
machines:
  box:
    provider: docker
    container: my-sandbox
    on_pause: pause
```

`workspace.pause()` closes the workspace, then runs `docker pause`: the
container's processes are frozen and use no CPU, but it keeps its memory. The
next line's connect runs `docker unpause`. Without `on_pause`,
`workspace.pause()` leaves the container running unless the call names the
machine. See [Pause](https://docs.mirage.strukto.ai/home/setup/machine/overview.md#pause).

## Notes

* `container` takes a name or an ID. The Docker CLI is the transport, so
  Docker Desktop, Colima and a compatible Podman alias all work.
* Sizing, GPUs, networks, volumes and bind mounts go on your own
  `docker run`. You can bake `sandbox.yaml` into the image instead of
  copying it, and point it at `host.docker.internal` for a host service.

> [!WARNING]
>
> Environment values go on the `docker exec` command line, so other users of
> the host can see them in `ps`. Avoid secrets on a host shared with
> untrusted users.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.