@hor1zonz/microsandbox — Cloud Adapter Fork

A fork of superradcompany/microsandbox that adds a self-hostable cloud API gateway (msb-cloud-adapter) and a fully-wired cloud backend for the SDKs — so the same SDK code can talk to a remote (or your own) microsandbox host over HTTP, not just spawn local microVMs.

Note

This is the fork-specific section. The complete, unmodified upstream README is preserved below → jump to the original README.

  What this fork adds

Upstream microsandbox boots microVMs as local child processes. This fork keeps all of that and adds a network-addressable "cloud" path on top of it:

Addition	Where	What it does
msb-cloud-adapter service	crates/cloud-adapter	An Axum HTTP + WebSocket server that exposes the msb-cloud REST/WS contract on top of a local microsandbox runtime. Run it on any machine that can boot microVMs and you have your own self-hosted "cloud".
Cloud backend in the Rust SDK	sdk/rust/lib/backend/cloud.rs	CloudBackend (url + api_key, from_env, named profiles) wired through the full sandbox / volume / fs / exec / logs / metrics surface.
Cloud backend in the Node/TS SDK	sdk/node-ts	setDefaultBackend / withDefaultBackend / defaultBackendKind, a CloudHttpError type, and CBOR exec-over-WebSocket support.
Published npm package	@hor1zonz/microsandbox	The Node SDK is published under this scope (currently darwin-arm64 / Apple Silicon prebuilt).
Cloud ephemeral-stop cleanup	SDK + adapter	Correctly tears down ephemeral sandboxes on stop() when running against the cloud backend.

The cloud backend is API-compatible with the local one: Sandbox.builder(...).create(), exec, fs.*, logs, metrics, and Volume all behave the same — only the transport changes.

  Architecture

  your app (Rust / TypeScript SDK)
            │  HTTP + WebSocket (Bearer API key)
            ▼
  ┌───────────────────────────┐
  │   msb-cloud-adapter        │   serves the /v1 msb-cloud contract
  │   (crates/cloud-adapter)   │
  └────────────┬──────────────┘
               │  in-process LocalBackend
               ▼
        microsandbox runtime  ──►  microVMs (libkrun)

The adapter boots real microVMs through the local runtime, so it must run on a host that can do so: macOS (Apple Silicon) or Linux with KVM enabled.

  Quick start: run your own cloud

1.  Build & run the adapter

# Requires the msb runtime + libkrunfw under ~/.microsandbox (MSB_HOME).
# Install the upstream CLI once if you don't have them:
#   curl -fsSL https://install.microsandbox.dev | sh

export MSB_CLOUD_ADAPTER_API_KEY="choose-a-strong-key"
cargo run -p msb-cloud-adapter --release -- --api-key "$MSB_CLOUD_ADAPTER_API_KEY"
# Listening on http://127.0.0.1:8088   (override with --bind / MSB_CLOUD_ADAPTER_BIND)
# Health check:  curl http://127.0.0.1:8088/healthz

Adapter configuration:

Flag	Env var	Default	Description
--bind	MSB_CLOUD_ADAPTER_BIND	127.0.0.1:8088	Socket address to listen on.
--api-key	MSB_CLOUD_ADAPTER_API_KEY	(required)	Bearer key every SDK request must present.
—	MSB_HOME	~/.microsandbox	Where the msb binary + libkrunfw live.

2.  Point an SDK at it

Both SDKs read MSB_API_URL + MSB_API_KEY (or use a named MSB_PROFILE):

export MSB_API_URL="http://127.0.0.1:8088"
export MSB_API_KEY="choose-a-strong-key"   # must match the adapter's key

 TypeScript (npm) →

npm i @hor1zonz/microsandbox

import { Sandbox, setDefaultBackend } from "@hor1zonz/microsandbox";

// Route all SDK calls to the cloud adapter instead of spawning local microVMs.
setDefaultBackend({
  kind: "cloud",
  url: process.env.MSB_API_URL!,
  apiKey: process.env.MSB_API_KEY!,
});

await using sandbox = await Sandbox.builder("hello-cloud")
  .image("alpine:3.19")
  .cpus(1)
  .memory(512)
  .create();

const output = await sandbox.shell("uname -m && echo 'hello from the cloud adapter'");
console.log(output.stdout());

 Rust →

use microsandbox::{CloudBackend, Sandbox, set_default_backend};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Reads MSB_API_URL + MSB_API_KEY from the environment.
    set_default_backend(CloudBackend::from_env()?);

    let sandbox = Sandbox::builder("hello-cloud")
        .image("alpine:3.19")
        .cpus(1)
        .memory(512)
        .create()
        .await?;

    let output = sandbox.shell("uname -m && echo 'hello from the cloud adapter'").await?;
    print!("{}", output.stdout()?);

    sandbox.stop().await?;
    Ok(())
}

Runnable end-to-end examples live in examples/typescript/cloud-backend and examples/rust/cloud-backend.

  Cloud HTTP API surface

All routes are under /v1 and require an Authorization: Bearer <api-key> header.

• Sandboxes — create / list / get / start / stop / kill / drain / destroy
• Filesystem — fs/read, fs/write, fs/list, fs/stat, fs/mkdir, fs/copy, fs/rename, fs/exists, delete
• Exec — exec.cbor over WebSocket (msb.cbor subprotocol)
• Logs — Server-Sent Events stream (/logs)
• Metrics — live CPU / memory / network (/metrics)
• Volumes — create / list / get / remove, plus the same fs/* operations

See crates/cloud-adapter/bin/main.rs for the full route table.

  Notes & compatibility

• Prebuilt platform: the published @hor1zonz/microsandbox ships a prebuilt native binary for macOS Apple Silicon (darwin-arm64) only. Other platforms must build the SDK from source.
• Relationship to upstream: this fork tracks superradcompany/microsandbox and only adds the cloud adapter + cloud backend wiring. The local-microVM workflow documented below is unchanged.
• License: unchanged — Apache 2.0.

---

_{↓   Everything below is the original upstream README, preserved unchanged.   ↓}

---

——   easy, fast, local microVMs for untrusted workloads   ——

Microsandbox runs untrusted workloads inside fast, local microVMs: AI agents, user code, plugins, CI jobs, dev environments, scrapers, and automation.

• Hardware Isolation: Hardware-level isolation with microVM technology.
• Cross Platform: Runs on Linux, macOS, and Windows.
• OCI Compatible: Runs standard container images from Docker Hub, GHCR, or any OCI registry.
• Docker-Like Workflows: Familiar image, command, shell, and volume workflows.
• Instant Startup: Average boot times¹ under 100 milliseconds.
• Embeddable: Spawn VMs right within your code. No setup server. No long-running daemon.
• Secrets That Can't Leak: Unexploitable secret keys that never enter the VM.
• Long-Running: Sandboxes can run in detached mode. Great for long-lived sessions.
• Agent-Ready: Your agents can create their own sandboxes with our Agent Skills and MCP server.

  Getting Started

  Install the SDK

cargo add microsandbox                                   # 🦀 Rust

uv add microsandbox                                      # 🐍 Python

npm i microsandbox                                       # 🟦 TypeScript

go get github.com/superradcompany/microsandbox/sdk/go    # 🐹 Go

  Install the CLI

Boot a microVM in a single command:

npx microsandbox run debian

Or install the msb command globally:

curl -fsSL https://install.microsandbox.dev | sh        # 🍎 macOS / 🐧 Linux

irm https://install.microsandbox.dev/windows | iex      # 🪟 Windows

 We also support other package managers →

brew install superradcompany/tap/microsandbox

npm i -g microsandbox

uv tool install microsandbox

cargo install microsandbox

Then you can run msb directly:

msb run debian

Requirements:

• macOS: Apple Silicon.
• Linux: KVM enabled.
• Windows: WHP enabled.

Warning: Microsandbox is still beta software. Expect breaking changes, missing features, and rough edges.

  SDK

The SDK lets you create and control sandboxes directly from your application. Sandbox::builder("...").create() boots a microVM as a child process. No infrastructure required.

  Run Code in a Sandbox

use microsandbox::Sandbox;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let sandbox = Sandbox::builder("my-sandbox")
        .image("python")
        .cpus(1)
        .memory(512)
        .create()
        .await?;

    let output = sandbox
        .exec("python", ["-c", "print('Hello from a microVM!')"])
        .await?;

    println!("{}", output.stdout()?);

    sandbox.stop().await?;

    Ok(())
}

 Python Example →

import asyncio
from microsandbox import Sandbox

async def main():
    sandbox = await Sandbox.create(
        "my-sandbox",
        image="python",
        cpus=1,
        memory=512,
    )

    output = await sandbox.exec("python", ["-c", "print('Hello from a microVM!')"])

    print(output.stdout_text)

    await sandbox.stop()

asyncio.run(main())

 TypeScript Example →

import { Sandbox } from "microsandbox";

await using sandbox = await Sandbox.builder("my-sandbox")
  .image("python")
  .cpus(1)
  .memory(512)
  .create();

const output = await sandbox.exec("python", [
  "-c",
  "print('Hello from a microVM!')",
]);

console.log(output.stdout());

 Go Example →

package main

import (
    "context"
    "fmt"
    "log"

    microsandbox "github.com/superradcompany/microsandbox/sdk/go"
)

func main() {
    ctx := context.Background()

    // Downloads the microsandbox runtime to ~/.microsandbox/ on first run.
    if err := microsandbox.EnsureInstalled(ctx); err != nil {
        log.Fatal(err)
    }

    sandbox, err := microsandbox.CreateSandbox(ctx, "my-sandbox",
        microsandbox.WithImage("python"),
        microsandbox.WithCPUs(1),
        microsandbox.WithMemory(512),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer sandbox.Stop(ctx)

    output, err := sandbox.Exec(ctx, "python", []string{"-c", "print('Hello from a microVM!')"})
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(output.Stdout())
}

The first call to create() pulls the image if it isn't cached locally, so it may take longer depending on your connection. Subsequent runs reuse the cache.

  CLI

The msb CLI provides a complete interface for managing sandboxes, images, and volumes.

  Run a Command

msb run python -- python3 -c "print('Hello from a microVM!')"

  Named Sandboxes

# Create and start a named sandbox
msb create --name app python

# Execute commands
msb exec app -- python -c "import this"
msb exec app -- curl https://example.com

# Lifecycle
msb stop app
msb start app
msb rm app

  Image Management

msb pull python           # Pull an image
msb image ls              # List cached images
msb image rm python       # Remove an image

  Install & Uninstall Sandboxes

msb install ubuntu               # Install ubuntu sandbox as 'ubuntu' command
ubuntu                           # Opens Ubuntu in a microVM
msb uninstall ubuntu             # Uninstall the ubuntu sandbox

  Status & Inspection

msb ls                         # List all sandboxes
msb ps app                     # Show sandbox status
msb inspect app                # Detailed sandbox info
msb metrics app                # Live CPU/memory/network stats

Tip

Run:
· msb --help for quick help menu.
· msb --tree for complete command hierarchy and descriptions.
· msb <command> --tree for a specific command tree.

  AI Agents

  Agent Skills

Teach any AI coding agent how to use microsandbox by installing the Agent Skills. Works with Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and more.

npx skills add superradcompany/skills

  MCP Server

Connect any MCP-compatible agent to microsandbox with the MCP server. Provides structured tool calls for sandbox lifecycle, command execution, filesystem access, volumes, and monitoring.

# Claude Code
claude mcp add --transport stdio microsandbox -- npx -y microsandbox-mcp

  Documentation

For guides, API references, and examples, visit the microsandbox documentation.

  Contributing

Interested in contributing to microsandbox? Check out our CONTRIBUTING.md for guidelines and DEVELOPMENT.md for build, test, and release instructions.

  License

This project is licensed under the Apache License 2.0.

  Acknowledgements

Special thanks to all our contributors, testers, and community members who help make microsandbox better every day! We'd like to thank the following projects and communities that made microsandbox possible: libkrun and smoltcp

Footnotes

1. Boot time refers to guest boot on an M1 machine. ↩