> For the complete documentation index, see [llms.txt](https://docs.computesdk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.computesdk.com/providers/microsandbox.md).

# Microsandbox

Microsandbox provider for ComputeSDK with hardware-isolated local and cloud microVM backends.

Microsandbox runs hardware-isolated Linux microVMs through one SDK. The ComputeSDK provider supports the embedded local runtime and microsandbox cloud without changing the sandbox, command, or filesystem API.

## Installation

Microsandbox requires Node.js 22 or newer.

```bash
npm install computesdk @computesdk/microsandbox
```

## Cloud backend

Cloud is the default backend and does not require virtualization on the caller's machine. Pass an API key directly or let the microsandbox SDK resolve `MSB_API_KEY`, `MSB_PROFILE`, or the active profile:

```typescript
import { compute } from 'computesdk';
import { microsandbox } from '@computesdk/microsandbox';

compute.setConfig({
  provider: microsandbox({
    apiKey: process.env.MSB_API_KEY,
    image: 'python:3.12',
  }),
});

const sandbox = await compute.sandbox.create();
console.log((await sandbox.runCommand('python --version')).stdout);
await sandbox.destroy();
```

You can also select a configured cloud profile with `microsandbox({ profile: 'production' })`. Calling `microsandbox()` with no configuration uses the SDK's cloud credential and profile resolution. If none resolves, the provider reports how to configure cloud or select local mode instead of silently running locally.

## Local backend

Select local execution explicitly when the sandbox should run on the calling machine. It does not require credentials:

```typescript
compute.setConfig({
  provider: microsandbox({
    backend: 'local',
    image: 'python:3.12',
    ports: [{ host: 8000, guest: 8000 }],
  }),
});
```

The local runtime requires supported hardware virtualization: Hypervisor.framework on Apple Silicon macOS, KVM on Linux, or Windows Hypervisor Platform.

## Commands and files

Both backends support command execution, working directories, environment variables, timeouts, background commands, live stdout and stderr callbacks, and native filesystem access.

```typescript
await sandbox.filesystem.mkdir('/workspace');
await sandbox.filesystem.writeFile('/workspace/app.js', 'console.log("hello")');

const result = await sandbox.runCommand('node app.js', {
  cwd: '/workspace',
  onStdout: (chunk) => process.stdout.write(chunk),
});
```

## Local ports and snapshots

Published ports and disk snapshots are currently local-only capabilities. Port mappings must be declared before sandbox creation:

```typescript
const provider = microsandbox({
  backend: 'local',
  ports: [{ host: 3000, guest: 3000 }],
});

compute.setConfig({ provider });
const sandbox = await compute.sandbox.create();
console.log(await sandbox.getUrl({ port: 3000 }));

const snapshot = await provider.snapshot.create(sandbox.sandboxId, {
  name: 'configured',
});
const restored = await compute.sandbox.create({ snapshotId: snapshot.id });
```

Snapshot creation stops the sandbox, captures its writable root disk, and restarts it. Files on that disk survive, but tmpfs paths such as `/tmp` and running processes are not part of the snapshot. Microsandbox cloud currently returns explicit unsupported errors for `getUrl` and snapshot operations because the cloud backend does not yet publish guest ports or provide disk snapshots.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.computesdk.com/providers/microsandbox.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.