---
title: Quickstart
description: Get a sandbox running in under 5 minutes
icon: "bolt"
---

<Note>
  Running locally requires **glibc-based Linux with KVM**, **macOS with Apple Silicon** (M-series chip), or **Windows 11 with Windows Hypervisor Platform** enabled. All local backends use hardware virtualization. [microsandbox cloud](/cloud/overview) has no hardware requirements.
</Note>

<Tip>
  Boot a microVM in one command.

  ```bash
  npx microsandbox run debian
  ```
</Tip>

<Steps>
  <Step title="Install microsandbox">
    Install the SDK for the language you are using, and install the `msb` CLI for terminal workflows such as managing images, volumes, and sandboxes. Both run microsandbox locally by default; there is no separate server or daemon to set up. The same install 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
    ```

    ```bash CLI (Linux & macOS)
    curl -fsSL https://install.microsandbox.dev | sh
    ```

    ```bash Homebrew (macOS)
    brew install superradcompany/tap/microsandbox
    ```

    ```powershell CLI (Windows)
    irm https://install.microsandbox.dev/windows | iex
    ```

    </CodeGroup>

    microsandbox uses hardware virtualization: Linux needs KVM, macOS needs Apple Silicon, and Windows needs Windows Hypervisor Platform. Check your local setup 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>
  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>

<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

- [Run on microsandbox cloud](/cloud/overview): the same code on hosted infrastructure
- [Tune sandbox settings](/sandboxes/tuning): resize headroom, labels, secrets, and storage
- [Troubleshoot Linux setup](/troubleshooting/linux): KVM, `/dev/kvm`, and permissions
- [Troubleshoot macOS setup](/troubleshooting/macos): Apple Silicon and local runtime checks
- [Troubleshoot Windows setup](/troubleshooting/windows): WHP, `msb doctor`, and Windows 11 notes
- [Run commands and stream output](/sandboxes/commands): `exec`, `shell`, `attach`, and streaming
- [Control network access](/networking/overview): policies, DNS interception, and secret protection
- [Manage sandboxes with the CLI](/cli/overview): create, inspect, and manage sandboxes from the terminal