Skip to main content

Run your first sandbox

Prefer short commands such as msb run debian for everyday use. msb sandbox run debian and msb sbx run debian do the same thing, with the same flags. Explore the full group with msb sandbox --help.
Having trouble with a local installation? Choose your platform for setup checks and fixes. For release candidates or an exact version, see Versions.
1

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. To run on cloud, set MSB_BACKEND=cloud and MSB_API_KEY, choose a cloud profile, or select cloud in code in supported SDKs. See Local or cloud.
You can also provision the runtime with the CLI installer above or explicit SDK setup helpers. See Runtime setup for Node’s bundled binaries and Rust’s opt-out options.Check local virtualization support with:
For platform-specific setup notes, see Linux troubleshooting, macOS troubleshooting, or Windows troubleshooting.
2

Run code in a sandbox

Create an ephemeral sandbox, execute code inside it, and stop it when finished. Ephemeral sandboxes are removed after stopping, so the example can reuse the same name.
If you already ran an older version of this example and retained a sandbox named hello, remove it with msb stop hello followed by msb rm hello on the same backend, or choose another name. Stopping a persistent sandbox retains it for later restart.

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.
Want the same sandbox on hosted infrastructure? Set MSB_BACKEND=cloud and export MSB_API_KEY; the code above then runs on microsandbox cloud unchanged.

Next steps