smolvm - Mirage

smolvm boots a hardware-isolated microVM with its own guest kernel on Hypervisor.framework (macOS), KVM (Linux), or WHP (Windows). Mirage connects to a machine you created; it never starts or deletes one. See the Sandbox overview for the shared image and workspace-mount setup.

Start the machine

smolvm machine create --net --name mirage-box --image my-mirage-image
smolvm machine start --name mirage-box
smolvm machine exec --name mirage-box -- mirage workspace create /tmp/sandbox.yaml

Host directories reach the guest only if you pass them at boot with --volume; the guest otherwise sees nothing from the host filesystem.

Connect from TypeScript

import { MountMode, SmolvmRuntime, Workspace } from '@struktoai/mirage-node'

const runtime = new SmolvmRuntime({
  captures: ['python3'],
  config: { machine: 'mirage-box' },
})
const ws = new Workspace(
  { '/data': resource },
  { mode: MountMode.EXEC, runtimes: [runtime, 'vfs'] },
)
await ws.execute('python3 job.py', { cwd: '/data' })

The smolvm CLI is the transport, so there is no SDK dependency. The first captured line checks machine status and accepts only running. A stopped or created machine needs machine start; unreachable means its guest agent is not answering; frozen is a fork base, so point Mirage at a clone instead.

One machine is one guest. Concurrent lines sent to the same machine share its filesystem and process table. Give each tenant its own machine when workload-to-workload isolation matters.

Mirage timeouts stop waiting for the command; they do not kill the process inside the microVM. See Resource limits.