features / sdk

sandbox SDKs for your application.

create sandboxes, execute commands, and work with files from python, typescript, rust, go, or ruby. run locally or connect to microsandbox cloud.

dithered programming code on a laptop representing the microsandbox sdks

choose your language

each sdk follows the same workflow: create a sandbox, run a command, read its output, and manage its lifecycle. follow your language reference for installation, signatures, and supported operations.

the same call, local or cloud

keep core create, exec, and file operations in your application, and select local or cloud through configuration. check the reference for backend differences, including local-only full snapshots and pause/resume.

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 use the same sdk. availability and lifecycle behavior depend on the backend; for example, pause/resume and full snapshots are local-only. check the reference for the operation you need.

continue readingsdk overview python sdk reference typescript sdk reference rust sdk reference go sdk reference ruby sdk reference

put the boundary inside your application.

open the sdk overview