Overview - Microsandbox

The SDK embeds the microsandbox runtime directly into your application. Running locally, creating a sandbox spawns a VM as a child process; there is no daemon to install and no server to connect to. With an API key set, the same SDK runs sandboxes on microsandbox cloud instead.

Installation

<CodeGroup> ```bash TypeScript npm install microsandbox ```

bash

cargo add microsandbox

bash

pip install microsandbox

bash

go get github.com/superradcompany/microsandbox/sdk/go

bash

gem install microsandbox

</CodeGroup>

For explicit runtime installation, verification, custom install locations, and environment overrides, see Runtime setup.

Small example

Create a sandbox from a container image, run a command, print the output, and stop it.

<CodeGroup> ```typescript TypeScript import { Sandbox } from "microsandbox";

await using sb = await Sandbox.builder("hello") .image("python") .create();

const output = await sb.exec("python", ["-c", "print('Hello, World!')"]); console.log("Output:", output.stdout());


```rust Rust
use microsandbox::Sandbox;

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

    let output = sb.exec("python", ["-c", "print('Hello, World!')"]).await?;
    println!("{}", output.stdout()?);

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

python

import asyncio
from microsandbox import Sandbox

async def main():
    sb = await Sandbox.create(
        "hello",
        image="python",
    )

    output = await sb.exec("python", ["-c", "print('Hello, World!')"])
    print("Output:", output.stdout_text)

    await sb.stop()

asyncio.run(main())

package main

import (
    "context"
    "fmt"
    "log"

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

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

    if err := m.EnsureInstalled(ctx); err != nil {
        log.Fatal(err)
    }

    sb, err := m.CreateSandbox(ctx, "hello", m.WithImage("python"))
    if err != nil {
        log.Fatal(err)
    }
    defer func() {
        _ = sb.Stop(context.Background())
        _ = sb.Close()
    }()

    out, err := sb.Exec(ctx, "python", []string{"-c", "print('Hello, World!')"})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Output:", out.Stdout())
}

ruby

require "microsandbox"

Microsandbox.install unless Microsandbox.installed?

Microsandbox::Sandbox.with("hello", image: "python") do |sandbox|
  output = sandbox.exec("python", ["-c", "print('Hello, World!')"])
  puts "Output: #{output.stdout}"
end

</CodeGroup>

Reference

Choose the SDK for your language:

For low-level protocol integrations, see the Agent Client references for TypeScript, Rust, Python, and Go. See also error handling.