Microsandbox

Microsandbox is an open-source, local-first microVM runtime for untrusted workloads. The following are some of the untrusted workloads supported by the runtime:

• AI agents
• User code
• Plugins
• Package installs
• CI jobs
• Development environments
• Scrapers
• Automation

Microsandbox runs workloads in lightweight virtual machines (microVMs) using libkrun. On Arm Linux, it uses Kernel-based VM (KVM) support to run a separate guest kernel for each sandbox.

You’ll install the msb command-line runtime on Ubuntu 24.04 LTS on aarch64. You’ll then run Python inside a sandbox to verify the installation.

In addition to Linux, Microsandbox supports Windows and macOS on Apple silicon. On macOS, you can use the same installation script. For macOS installation and platform-specific setup checks, see the Microsandbox quickstart .

The Microsandbox release bundle supplies the runtime and libkrunfw guest firmware library. You don’t need Docker, Python on the host, or a separate system installation of libkrun.

Before you begin

You need an Arm Linux system running Ubuntu 24.04 LTS, with sudo access and internet access to GitHub and Docker Hub. Allow disk space for the downloaded image and its extracted filesystem. You also need enough available memory for a 512 MiB guest alongside the host operating system.

The install guide was tested on an Arm AGI CPU host. Ensure that your host exposes KVM to run the sandbox. If Ubuntu runs inside a VM, ensure that the outer hypervisor exposes nested virtualization.

Check your host:

    

        
        
uname -m
uname -r
cat /etc/os-release

    

Confirm that the architecture is aarch64 and the operating system is Ubuntu 24.04 LTS.

Check KVM access

Check that your current user can read and write the KVM device:

    

        
        
ls -l /dev/kvm
if [ -c /dev/kvm ] && [ -r /dev/kvm ] && [ -w /dev/kvm ]; then
    echo "KVM device is accessible"
else
    echo "STOP: resolve KVM availability or permissions before continuing"
fi

    

The expected output is:

    

        
        KVM device is accessible

        
    

If the device exists and belongs to the kvm group but your user lacks access, add your user to that group:

    

        
        
sudo usermod -aG kvm "$USER"

    

Log out and log back in to activate the kvm group for your session.

Install Microsandbox

Install the download and extraction tools:

    

        
        
sudo apt update
sudo apt install -y ca-certificates curl tar gzip coreutils

    

Run the official installer from your user account, without sudo:

    

        
        
curl -fsSL https://install.microsandbox.dev | sh

    

By default, the installer installs the runtime and firmware in ~/.microsandbox and creates command links in ~/.local/bin. The ~ directory is the home directory for your current user. For the root directory, the ~ resolves to /root.

The output is similar to the following excerpt:

    

        
          Microsandbox Installer

info Detected platform: linux-aarch64
info Latest version: v0.7.8
info Downloading microsandbox...
...
info Verifying checksum...
done Checksum verified
info Extracting...
done Installed msb to ~/.microsandbox/bin/msb
done Linked microsandbox -> msb in ~/.microsandbox/bin/
done Installed libkrunfw to ~/.microsandbox/lib/
done Linked ~/.local/bin/msb -> ~/.microsandbox/bin/msb
done Linked ~/.local/bin/microsandbox -> ~/.microsandbox/bin/microsandbox

        
    

Home directory paths are shown as ~ in the excerpt. The installer prints their full paths.

Wait for the installer to report that installation is complete. If ~/.local/bin isn’t on your PATH, the installer prints instructions for adding it.

Make the installed commands available in your current Bash session:

    

        
        
export PATH="$HOME/.local/bin:$PATH"
hash -r

    

Add the same export PATH line to ~/.bashrc to make the commands available in future Bash sessions. Run the remaining commands with the same account that you used to install Microsandbox.

Confirm the installed version:

    

        
        
msb --version

    

The output is similar to:

    

        
        msb 0.7.8

        
    

Your version can be newer because the installer selects the latest release.

Verify the installation

Create a sandbox and run a Python command to verify that Microsandbox works as expected.

Create a sandbox

Create a named microVM with one virtual CPU and 512 MiB of memory:

    

        
        
msb create --name arm-install-check --cpus 1 --memory 512M python:3.12-slim

    

The first run downloads the Arm64 image from Docker Hub. The python:3.12-slim tag can change as new Python releases become available. Wait for sandbox creation to finish successfully before continuing.

Run a command in a sandbox

Run Python through the sandbox runtime:

    

        
        
msb exec arm-install-check -- python3 -c 'import platform; print(platform.machine()); print("Python calculation:", 6 * 7)'

    

The expected output is:

    

        
        aarch64
Python calculation: 42

        
    

Inspect the sandbox

Check the sandbox status and resource allocation:

    

        
        
msb inspect arm-install-check

    

The output is similar to:

    

        
        Name:           arm-install-check
Status:         running
Created:        2026-10-19 15:03:42
Updated:        2026-10-19 15:03:42
Image:          python:3.12-slim
Root Disk:      4096 MiB (managed, ext4)

Resources
  CPUs:         1
  Max CPUs:     1
  CPU Placement:inherit
  Memory:       512 MiB
  Max Memory:   512 MiB
  THP:          madvise
Security:       default
Deployment Profile:single-tenant
Shell:          /bin/sh

Environment
  PATH=/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
  LANG=C.UTF-8
  GPG_KEY=7169605F62C751356D054A26A821E680E5FA6305
  PYTHON_VERSION=3.12.15
  PYTHON_SHA256=c2c4321961fab0fb999d66e0cecf521c2ab3994c7992873ea99e306c1094fd5a

        
    

Confirm that the sandbox is running with one CPU and 512 MiB of memory. Timestamps vary between runs. Image environment values can change when the image tag is updated.

List sandboxes

List the sandboxes:

    

        
        
msb ls

    

The output is similar to:

    

        
        NAME                 IMAGE               STATUS     CREATED
arm-install-check    python:3.12-slim    running    2026-10-19 15:03:42

        
    

Confirm that arm-install-check appears with the image python:3.12-slim and status running. Together with the Python output, this output confirms that Microsandbox created the sandbox and ran the verification workload successfully.

Check filesystem isolation

The sandbox has its own filesystem. Host files are accessible only through mounts that you provide, as described in the Microsandbox isolation overview . The sandbox that you created has no host-directory mounts.

In your host terminal, create a temporary file and confirm that you can read it:

    

        
        
msb_host_file=$(mktemp /tmp/msb-host-check.XXXXXX)
printf 'This file belongs to the host.\n' > "$msb_host_file"
cat "$msb_host_file"

    

Keep the same terminal open for the remaining checks and cleanup.

The expected output is:

    

        
        This file belongs to the host.

        
    

Try to read the same absolute path inside the sandbox:

    

        
        
msb exec arm-install-check -- python3 -c '
import pathlib
import sys

try:
    pathlib.Path(sys.argv[1]).read_text()
except FileNotFoundError:
    print("Host file is not visible in the sandbox.")
else:
    sys.exit("Unexpected result: the host file path is readable in the sandbox.")
' "$msb_host_file"

    

The expected output is:

    

        
        Host file is not visible in the sandbox.

        
    

This checks that the host file isn’t exposed at the same path in the sandbox. The result is a missing file, rather than a filesystem permission denial.

Confirm that the sandbox can still write to its own /tmp directory:

    

        
        
msb exec arm-install-check -- python3 -c 'from pathlib import Path; p = Path("/tmp/msb-guest-check.txt"); p.write_text("Sandbox write succeeded."); print(p.read_text())'

    

The expected output is:

    

        
        Sandbox write succeeded.

        
    

Remove the temporary host file:

    

        
        
rm -- "${msb_host_file:?}"

    

Deleting the sandbox removes its test file.

Delete the test sandbox

Stop and remove the verification sandbox:

    

        
        
msb stop arm-install-check
msb rm arm-install-check
msb ls

    

The output is similar to:

    

        
           ✓ Stopped      arm-install-check
   ✓ Removed      arm-install-check
No sandboxes found.

        
    

If you have other sandboxes, msb ls lists those instead.

Confirm that arm-install-check no longer appears. The downloaded images remain cached for reuse.

Optionally remove the verification image if no other sandbox needs it:

    

        
        
msb image rm python:3.12-slim

    

The installed runtime and firmware remain available for future use.

Next steps

You can now use Microsandbox to run Python workloads in microVMs on Arm Linux.

For sandbox lifecycle commands, see the Microsandbox CLI documentation . For more information about programmatic execution, see the Microsandbox SDK documentation .