Skip to main content
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

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 needs:

Usage

captures defaults to @external: every program Mirage does not have itself. Name @python to run Python in the container too.
Save the YAML as workspace.yaml and run a line from the CLI:
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. With ssh, the image needs only sshfs. With mirage, it needs fuse3 and uv or npm to install mirage-fuse. With own, copy sandbox.yaml in and start Mirage in the container:

Pausing the container

To pause the container when the workspace pauses, set on_pause: pause on the machine:
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.

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.
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.