Back to Microsandbox

Quickstart

docs/getting-started/quickstart.mdx

0.6.105.8 KB
Original Source

Choose where to run

<div className="msb-platform-strip" role="list" aria-label="Supported platforms"> <a className="msb-platform-item msb-platform-link" role="listitem" href="/troubleshooting/linux"> <span className="msb-platform-icon"><Icon icon="linux" size={18} /></span> <span className="msb-platform-copy"><strong>Linux</strong><span>glibc + KVM</span></span> </a> <a className="msb-platform-item msb-platform-link" role="listitem" href="/troubleshooting/macos"> <span className="msb-platform-icon"><Icon icon="apple" size={18} /></span> <span className="msb-platform-copy"><strong>macOS</strong><span>Apple Silicon</span></span> </a> <a className="msb-platform-item msb-platform-link" role="listitem" href="/troubleshooting/windows"> <span className="msb-platform-icon"><Icon icon="windows" size={18} /></span> <span className="msb-platform-copy"><strong>Windows</strong><span>Windows 11 + WHP</span></span> </a> <a className="msb-platform-item msb-platform-link" role="listitem" href="/cloud/overview"> <span className="msb-platform-icon"><Icon icon="cloud" size={18} /></span> <span className="msb-platform-copy"><strong>Cloud</strong><span>No hypervisor setup</span></span> </a> </div> <CodeGroup> ```bash npx npx microsandbox run debian ```
bash
curl -fsSL https://install.microsandbox.dev | sh
msb run debian
powershell
irm https://install.microsandbox.dev/windows | iex
msb run debian
</CodeGroup> <Steps> <Step title="Install microsandbox"> For application code, install the SDK for your language. For terminal workflows, use one of the CLI options above. Both run microsandbox locally by default; there is no separate server or daemon to set up. The same installation also drives [microsandbox cloud](/cloud/overview) when an API key is set.
<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
```

</CodeGroup>

Check local virtualization support with:

```bash
msb doctor
```

For platform-specific setup notes, see [Linux troubleshooting](/troubleshooting/linux), [macOS troubleshooting](/troubleshooting/macos), or [Windows troubleshooting](/troubleshooting/windows).
</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> Want the same sandbox on hosted infrastructure? Set `MSB_BACKEND=cloud` and export `MSB_API_KEY`; the code above then runs on [microsandbox cloud](/cloud/overview) unchanged. </Tip>

Next steps