Docker

​

Installation

pip install 'mirage-ai[ssh]'

pnpm add ssh2

docker run -d --cap-add SYS_ADMIN --device /dev/fuse \
  --name my-sandbox my-image sleep infinity

​

Usage

from mirage import RAMVFS, MountMode, Workspace
from mirage.runtime.machine import MachineRuntime

ws = Workspace(
    {"/data": RAMVFS()},
    mode=MountMode.EXEC,
    machines={
        "box": {
            "provider": "docker",
            "container": "my-sandbox",
            "mount_type": "ssh",
        }
    },
    runtimes=[MachineRuntime(["@python", "@external"], machine="box")],
)
await ws.shell("python3 -c 'print(1 + 1)'")

import { MountMode, MachineRuntime, 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' } },
    runtimes: [new MachineRuntime({ captures: ['@python', '@external'], machine: 'box' })],
  },
)
await ws.shell("python3 -c 'print(1 + 1)'")

mode: exec
machines:
  box:
    provider: docker
    container: my-sandbox
    mount_type: ssh
runtimes:
  - name: machine
    captures: ["@python", "@external"]
    machine: box
mounts:
  /data:
    vfs: ram

​

Connecting the workspace

​

ssh

• The image needs only sshfs. No Mirage, keys or open port in the container.
• Each file call is a round trip to the workspace; with both, keep bulk data on the container’s own mounts.
• The container shows one session’s view, the first that runs a line there. Give each agent its own container.
• An sshfs still serving a path Mirage serves, another workspace’s or one of your own, is left alone and the line exits 1. Give each workspace its own container.
• If the container restarts, Mirage mounts the paths again. A line caught mid-restart exits 126 without running.
• The root mount and /dev are not served.

​

fuse

mounts:
  /data:
    vfs: s3
    config:
      bucket: my-bucket
    backend: fuse
    mountpoint: /data

docker cp sandbox.yaml my-sandbox:/tmp/sandbox.yaml
docker exec my-sandbox mirage workspace create /tmp/sandbox.yaml

• This workspace’s rules do not reach those files, so a line is refused while the session’s permissions hide or narrow anything under them.
• If a path the container mounted goes away, as on a restart, lines exit 126 until it is mounted again. Start Mirage from the image’s entrypoint so a restart mounts it again.
• Keep the container’s paths in step with the host’s mounts yourself. sandbox.yaml can differ where it should, such as an endpoint (host.docker.internal) or narrower credentials.

​

Runtime behavior

​

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.