Back to Microsandbox

Quickstart

docs/getting-started/quickstart.mdx

0.5.43.8 KB
Original Source
<Note> microsandbox requires **Linux with KVM** enabled, or **macOS with Apple Silicon** (M-series chip). Both use hardware virtualization. </Note> <Tip> Boot a microVM in one command.
bash
npx microsandbox run debian
</Tip> <Steps> <Step title="Install microsandbox"> The SDK **embeds the runtime directly**, so no separate server process is needed. Only install the `msb` CLI if you want to manage images, volumes, and sandboxes from the terminal.
<CodeGroup>
```bash Rust
cargo add microsandbox
```

```bash TypeScript
npm install microsandbox
```

```bash Python
pip install microsandbox
```

```bash Go
go get github.com/superradcompany/microsandbox/sdk/go
```

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

</CodeGroup>
</Step> <Step title="Run code in a sandbox"> Create a sandbox, execute code inside it, and get the result back.
<CodeGroup>
```rust Rust
use microsandbox::Sandbox;

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

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

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

```typescript TypeScript
import { Sandbox } from "microsandbox";

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

const output = await sb.exec("python", ["-c", "print('Hello from a microVM!')"]);
console.log(output.stdout()); // Hello from a microVM!
```

```python Python
import asyncio
from microsandbox import Sandbox

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

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

    await sb.stop()

asyncio.run(main())
```

```go Go
sb, err := m.CreateSandbox(ctx, "hello",
    m.WithImage("python"),
    m.WithMemory(512),
)
if err != nil {
    return err
}
defer sb.Stop(ctx)

output, err := sb.Exec(ctx, "python", []string{"-c", "print('Hello from a microVM!')"})
if err != nil {
    return err
}
fmt.Println(output.Stdout()) // Hello from a microVM!
```

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

</CodeGroup>
</Step> </Steps>

What just happened?

Here's what happened behind that Sandbox.builder(...).create() call:

  1. Pulled the image from Docker Hub, unless it was already cached.
  2. Assembled a copy-on-write filesystem so changes inside the sandbox do not modify the base image.
  3. Booted a microVM as a child process with the resource limits you configured.
  4. Started the guest agent so the SDK can run commands and move data in and out.

The exec call uses the host-guest command channel, not SSH and not the sandbox network.

<Tip> Because exec doesn't go through the network, it works even when a sandbox has networking disabled via `.disable_network()` and no network interfaces at all. </Tip>

Next steps