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

# microsandbox

> Run captured programs in an existing microsandbox microVM.

The `microsandbox` machine provider reaches a running
[microsandbox](https://microsandbox.dev) microVM, by name, and
runs the programs it captures in it. You create and start the sandbox; Mirage runs programs in
it through the `msb` CLI. Python SDK and Node.

## Installation

Install `msb` 0.7.14 or newer on the host and put it on `PATH`. Create a
sandbox from an image with `sh`, your programs, and the tools needed for
[connecting the workspace](#connecting-the-workspace):

```bash theme={null}
msb create my-registry/mirage-fuse:latest --name mirage-box
```

## Usage

`captures` defaults to [`@external`](https://docs.mirage.strukto.ai/home/setup/machine/overview#captures).
Add `@python` to run Python programs in the guest too.

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

> [tab] YAML
>
> ```yaml theme={null}
> mode: exec
> machines:
>   box:
>     provider: microsandbox
>     sandbox: 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`, install `mirage-ai[ssh]` on a Python
host or `ssh2` on a Node host; the guest needs `sshfs` and access to
`/dev/fuse`; with `mirage`, `mirage-fuse` and the same access. With `own`, copy `sandbox.yaml` in and start Mirage in the
guest:

```bash theme={null}
msb copy sandbox.yaml mirage-box:/tmp/sandbox.yaml
msb exec mirage-box -- mkdir -p /data
msb exec mirage-box -- mirage workspace create /tmp/sandbox.yaml
```

Matching paths alone does not share data; configure both workspaces to use
the same backend.

## Pausing the sandbox

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

```yaml theme={null}
machines:
  box:
    provider: microsandbox
    sandbox: mirage-box
    on_pause: pause
```

`workspace.pause()` closes the workspace, then runs `msb pause`: the sandbox
is suspended and its memory stays on the host. The next line resumes it with
`msb resume`. Without `on_pause`, `workspace.pause()` leaves the sandbox
running unless the call names the machine. See
[Pause](https://docs.mirage.strukto.ai/home/setup/machine/overview.md#pause).

## Notes

* Keep the sandbox running while Mirage uses it. Each line runs its own
  `msb exec`, so a restart needs no reconnect. With `own` or `both`, start the
  sandbox's Mirage again after a restart, or from its image's entrypoint;
  until then lines exit 126.
* Stopping or closing the workspace leaves the sandbox running.
* A [timeout](https://docs.mirage.strukto.ai/home/setup/machine/overview.md#timeouts) cancels the CLI call and
  stops that run's processes in the sandbox.
* A program's output reaches Mirage as it prints, except when Mirage pipes
  input into the program: then the output arrives when the program ends.
* Commands share the sandbox's files and processes. Use one sandbox per tenant.
* Environment values are passed as CLI arguments. Avoid secrets on hosts shared
  with untrusted users.


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