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

# smolvm

> Run captured command lines in an existing smolvm microVM.

[smolvm](https://smolmachines.com) 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](/python/runtime/sandbox) for the shared image
and workspace-mount setup.

## Start the machine

```bash theme={null}
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 Python

```python theme={null}
from mirage import MountMode, Workspace
from mirage.runtime.sandbox.smolvm import SmolvmRuntime

runtime = SmolvmRuntime(captures=["python3"],
                        config={"machine": "mirage-box"})
ws = Workspace({"/data": ...}, 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 or Mirage
extra. 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.

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

<Warning>
  Mirage timeouts stop waiting for the command; they do not kill the process
  inside the microVM. See
  [Resource limits](/python/runtime/sandbox#resource-limits).
</Warning>