smolvm

The smolvm machine provider reaches a running smolvm microVM, by name, and the machine runtime runs captured programs in it. Each machine has its own guest kernel, on macOS, Linux and Windows. You create and start the machine; Mirage only runs programs in it. Python SDK and Node.

Installation

Install the smolvm CLI. Create and start a machine from an image that has what connecting the workspace needs:

smolvm machine create --net --name mirage-box --image my-mirage-image
smolvm machine start --name mirage-box

Usage

captures defaults to @external: every program Mirage does not have itself. Name @python to run Python in the machine too.

Python
TypeScript
YAML

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

ws = Workspace(
    {"/data": RAMVFS()},
    mode=MountMode.EXEC,
    machines={"box": {"provider": "smolvm", "machine": "mirage-box"}},
    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: 'smolvm', machine: 'mirage-box' } },
    runtimes: [new MachineRuntime({ captures: ['@python', '@external'], machine: 'box' })],
  },
)
await ws.shell("python3 -c 'print(1 + 1)'")

mode: exec
machines:
  box:
    provider: smolvm
    machine: mirage-box
runtimes:
  - name: machine
    captures: ["@python", "@external"]
    machine: box
mounts:
  /data:
    vfs: ram

Connecting the workspace

A program in the machine opens workspace files at the same paths as in Mirage, so the machine must see the mounts there. mount_type picks how, as for Docker: ssh serves every mount over smolvm machine exec (the guest needs sshfs), fuse leaves them to a Mirage inside, and both mixes the two. For fuse, use the machine image, which carries Mirage and fuse3. Write the same mounts at the same paths into sandbox.yaml, put it in the machine (in its image, or a directory passed with --volume), and start Mirage with it:

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

smolvm machine exec --name mirage-box -- mirage workspace create /tmp/sandbox.yaml

This workspace’s mount modes and permissions do not reach those files; sandbox.yaml decides.
Keep the machine’s paths in step with the host’s mounts yourself.

Runtime behavior

Capability	In the machine
Command	The captured program and its words, as typed
Piped input	stdin
Environment	The session’s, over the config `env`
Working directory	The shell’s, unchanged
Workspace files	By `mount_type`; see above
Host files	Only directories passed with `--volume` at boot
Disk and network	The machine’s own

Notes

The machine must be running. Start a stopped or created machine, or clone a frozen machine before using it. Mirage cannot run commands while a machine is unreachable.
Lines sent to one machine share its files and processes. Give each tenant its own machine.

Getting Started

Examples

Agents

VFS

Integration

CLIs

Mirage Shell

Agent Profiles

Policy

Runtimes

Machines

Infrastructure

Configuration

Notifications

Help

Installation

Usage

Connecting the workspace

Runtime behavior

Notes

​Installation

​Usage

​Connecting the workspace

​Runtime behavior

​Notes

Installation

Usage

Connecting the workspace

Runtime behavior

Notes