> ## 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](/typescript/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 TypeScript

```ts theme={null}
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.

<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](/typescript/runtime/sandbox#resource-limits).
</Warning>