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

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

## Installation

Install `msb` 0.7.8 or later 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`](/home/setup/runtime/overview#captures).
Add `python3` to run Python programs in the guest too.

**Python**

```python theme={null}
from mirage import RAMVFS, MountMode, Workspace
from mirage.runtime.sandbox.microsandbox import MicrosandboxRuntime

runtime = MicrosandboxRuntime(
    captures=["python3", "@external"],
    config={"sandbox": "mirage-box"},
)
ws = Workspace({"/data": RAMVFS()}, mode=MountMode.EXEC, runtimes=[runtime])
await ws.shell("python3 -c 'print(1 + 1)'")
```

**TypeScript**

```typescript theme={null}
import { MountMode, RAMVFS, MicrosandboxRuntime, Workspace } from '@struktoai/mirage-node'

const runtime = new MicrosandboxRuntime({
  captures: ['python3', '@external'],
  config: { sandbox: 'mirage-box' },
})
const ws = new Workspace({ '/data': new RAMVFS() }, { mode: MountMode.EXEC, runtimes: [runtime] })
await ws.shell("python3 -c 'print(1 + 1)'")
```

**YAML**

```yaml theme={null}
mode: exec
runtimes:
  - name: microsandbox
    captures: ["python3", "@external"]
    config:
      sandbox: mirage-box
mounts:
  /data:
    vfs: ram
```

## Connecting the workspace

A program in the sandbox opens workspace files at the same paths as in
Mirage. Set `mount_type` in Python or YAML, or `mountType` in TypeScript:

* `ssh` shares the host workspace through guest `sshfs`.
* `fuse` uses a Mirage workspace running inside the guest.
* `both` keeps the guest's own mounts and uses [ssh](#ssh) for the rest.
* Unset leaves file access to you.

### ssh

Add `mount_type: ssh` to the config (`mountType: 'ssh'` in TypeScript).
Install `mirage-ai[ssh]` on a Python host or `ssh2` on a Node host. The
guest needs `sshfs` and access to `/dev/fuse`, but no Mirage installation,
SSH keys or open port. In `ssh` and `both`, each runtime instance serves
its first session only.

### fuse

Use [the sandbox image](/home/setup/runtime/sandbox#the-sandbox-image),
which carries Mirage and `fuse3`. Put the same mounts at the same paths
in a `sandbox.yaml` inside the guest:

```yaml theme={null}
mounts:
  /data:
    vfs: s3
    config:
      bucket: my-bucket
    backend: fuse
    mountpoint: /data
```

```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
```

The guest's config controls these files, not the host workspace's rules.
Mirage refuses commands if session rules restrict a guest mount it cannot
enforce. Matching paths alone does not share data; configure both workspaces
to use the same backend.

## Runtime behavior

| Capability | In the sandbox |
| - | - |
| Command | The captured program and its arguments, through `msb exec` |
| Piped input | stdin |
| Environment | The session's, over the config `env` |
| Working directory | The shell's, unchanged |
| Workspace files | By `mount_type`; see [above](#connecting-the-workspace) |
| Disk and network | The sandbox's own |

## Notes

* Keep the sandbox running while Mirage is connected. Reconnect after a restart.
* Closing the runtime leaves the sandbox running.
* A [timeout](/home/setup/runtime/sandbox#timeouts) cancels the CLI call.
  The guest agent cleans up that call's commands; filesystem cleanup may take longer.
* 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.