features / sdk

four languages. one mental model.

rust, typescript, python, and go, all published, all versioned together. create a sandbox, run code, read the output. the api fits in your head.

dithered programming code on a laptop representing the four microsandbox sdks

one model, four languages

rust, typescript, python, and go. all published, all versioned together. the shape is the same everywhere: create a sandbox, run code, read the output, remove it.

the same call, local or cloud

one sdk. one api. local or cloud is a config change, not a rewrite.

pick the backend with config. your integration code does not change.

private beta. access is by request.

how it works

the four calls you will actually use

create

start a sandbox from an oci image with the limits you set.

exec

run a command inside and stream or collect its output.

read

read stdout, stderr, and the exit code.

remove

tear the sandbox down after taking a snapshot if you want to keep the disk.

see it work

rust sdk

microsandbox 0.6.8

rust

use microsandbox::Sandbox;

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

    let output = sandbox.shell("echo 'Hello from microsandbox!'").await?;
    println!("{}", output.stdout()?.trim());

    sandbox.stop().await?;
    Sandbox::remove("rust-readme").await?;
    Ok(())
}

typescript sdk

microsandbox 0.6.8

typescript

import { MiB, Sandbox } from "microsandbox";

await using sandbox = await Sandbox.builder("ts-readme")
  .image("alpine")
  .cpus(1)
  .memory(MiB(512))
  .replace()
  .create();

const output = await sandbox.shell("echo 'Hello from microsandbox!'");
console.log(output.stdout().trim());

python sdk

microsandbox 0.6.8

python

import asyncio
from microsandbox import Sandbox

async def main() -> None:
    async with await Sandbox.create(
        "python-readme", image="alpine", replace=True
    ) as sandbox:
        output = await sandbox.shell("echo 'Hello from microsandbox!'")
        print(output.stdout_text.strip())

asyncio.run(main())

go sdk

sdk/go v0.6.8

package main

import (
    "context"
    "fmt"
    "log"
    "time"

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

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute)
    defer cancel()

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

    name := "go-readme"
    sb, err := microsandbox.CreateSandbox(ctx, name,
        microsandbox.WithImage("alpine:3.19"),
        microsandbox.WithMemory(512),
        microsandbox.WithCPUs(1),
        microsandbox.WithReplace(),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer func() {
        stopCtx, stopCancel := context.WithTimeout(context.Background(), 30*time.Second)
        defer stopCancel()
        _ = sb.Stop(stopCtx)
        _ = sb.Close()
        _ = microsandbox.RemoveSandbox(context.Background(), name)
    }()

    out, err := sb.Shell(ctx, "echo 'Hello from microsandbox!'")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(out.Stdout())
}

common questions

does every method behave identically on cloud?

the core create, exec, and filesystem workflows do. a few operations like metrics and some lifecycle calls differ on cloud today. the sdk reference lists them.

continue readingsdk overview rust package typescript package python package go package

put the boundary inside your application.

open the sdk overview