microsandbox

Run captured programs in a running microsandbox 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:

msb create my-registry/mirage-fuse:latest --name mirage-box

Usage

captures defaults to @external. Add python3 to run Python programs in the guest too.

Python
TypeScript
YAML

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)'")

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)'")

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 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, which carries Mirage and fuse3. Put the same mounts at the same paths in a sandbox.yaml inside the guest:

mounts:
  /data:
    vfs: s3
    config:
      bucket: my-bucket
    backend: fuse
    mountpoint: /data

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

Getting Started

Agents

VFS

Integration

CLIs

Mirage Shell

Agent Profiles

Policy

Runtimes

Configuration

Notifications

Access

Help

Installation

Usage

Connecting the workspace

ssh

fuse

Runtime behavior

Notes

​Installation

​Usage

​Connecting the workspace

​ssh

​fuse

​Runtime behavior

​Notes

Installation

Usage

Connecting the workspace

ssh

fuse

Runtime behavior

Notes