> ## 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 programs in a smolvm microVM with its own kernel.

The `smolvm` machine provider reaches a running
[smolvm](https://smolmachines.com) microVM, by name, and runs the programs it
captures 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](#connecting-the-workspace) needs:

```bash theme={null}
smolvm machine create --net --name mirage-box --image my-mirage-image
smolvm machine start --name mirage-box
```

## Usage

`captures` defaults to [`@external`](https://docs.mirage.strukto.ai/home/setup/machine/overview#captures):
every program Mirage does not have itself. Name `@python` to run
Python in the machine too.

> [tab] Python
>
> ```python theme={null}
> from mirage import RAMVFS, MountMode, Workspace
>
> ws = Workspace(
>     {"/data": RAMVFS()},
>     mode=MountMode.EXEC,
>     machines={"box": {"provider": "smolvm", "machine": "mirage-box", "captures": ["@python", "@external"]}},
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'
>
> const ws = new Workspace(
>   { '/data': new RAMVFS() },
>   {
>     mode: MountMode.EXEC,
>     machines: { box: { provider: 'smolvm', machine: 'mirage-box', captures: ['@python', '@external'] } },
>   },
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```

> [tab] YAML
>
> ```yaml theme={null}
> mode: exec
> machines:
>   box:
>     provider: smolvm
>     machine: mirage-box
>     captures: ["@python", "@external"]
> mounts:
>   /data:
>     vfs: ram
> ```

## Connecting the workspace

Pick a [`mount_type`](https://docs.mirage.strukto.ai/home/setup/machine/overview#connecting-the-workspace). With `ssh`, the guest needs `sshfs`; with `mirage`, `mirage-fuse`. With `own`,
put `sandbox.yaml` in the machine, in its image or a directory passed with
`--volume`, and start Mirage:

```bash theme={null}
smolvm machine exec --name mirage-box -- mirage workspace create /tmp/sandbox.yaml
```

## Pausing the machine

To pause the machine when the workspace pauses, set `on_pause: pause` on it:

```yaml theme={null}
machines:
  box:
    provider: smolvm
    machine: mirage-box
    on_pause: pause
```

`workspace.pause()` closes the workspace, then runs `smolvm machine pause`,
which saves the machine's memory and disks to its data directory and stops
its VM. The next line resumes it with `smolvm machine resume`, running
processes included. This needs smolvm 1.18 or later, and a host that can
take smolvm's portable checkpoints; where smolvm refuses the pause,
`workspace.pause()` raises smolvm's error and the machine keeps running.
Without `on_pause`,
`workspace.pause()` leaves the machine running unless the call names it. See
[Pause](https://docs.mirage.strukto.ai/home/setup/machine/overview.md#pause).

## Notes

* Host files reach the machine only through directories passed with
  `--volume` at boot.
* The machine must be `running` or `paused`; Mirage resumes a `paused`
  one. 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.