docs/cloud/overview.mdx
microsandbox cloud runs your sandboxes on hosted infrastructure. The SDKs and the msb CLI are the same ones you use locally: the same builders, the same commands, the same code. Select the cloud backend and provide an API key; there is no daemon or separate client.
export MSB_BACKEND=cloud
export MSB_API_KEY="msb_..."
Everything from the quickstart works unchanged. With cloud selected and the API key exported, this creates a sandbox on cloud instead of your machine:
<CodeGroup> ```rust Rust use microsandbox::Sandbox;let sb = Sandbox::builder("hello") .image("python") .memory(512) .create() .await?;
let output = sb.exec("python", ["-c", "print('Hello from the cloud!')"]).await?; println!("{}", output.stdout()?);
sb.stop().await?;
```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 the cloud!')"]);
console.log(output.stdout());
from microsandbox import Sandbox
sb = await Sandbox.create("hello", image="python", memory=512)
output = await sb.exec("python", ["-c", "print('Hello from the cloud!')"])
print(output.stdout_text)
await sb.stop()
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 the cloud!')"})
fmt.Println(output.Stdout())
msb run python -- python3 -c "print('Hello from the cloud!')"
Hardware virtualization support on your machine is not needed for cloud sandboxes; msb doctor checks apply to the local runtime only.
The everyday workflow is shared across local and cloud: sandbox lifecycle, command execution, common guest-filesystem operations, network policy, secrets, SSH sessions, and managed storage. The differences below are the ones to plan for.
Across the docs, no badge means a feature works everywhere. Exceptions use only three badges: Local-only, Limited on cloud, and Cloud-only.
| Area | Cloud status | Difference or alternative |
|---|---|---|
| Sandbox lifecycle and execution | Works everywhere | Create, start, inspect, list, stop, remove, exec, shell, streaming, and interactive PTY workflows use the same SDK and CLI surface. |
| Guest filesystem | Limited on cloud | Common path operations and host-to-guest copies work. Low-level open-handle operations are local-only. |
| Managed volumes | Limited on cloud | Default and named directory volumes support lifecycle and filesystem access. Create a named volume before mounting it; disk-kind volumes and create-on-mount are local-only. |
| Volume and host paths | Limited on cloud | Bind and disk-image source paths resolve against the organization's host volume, not the machine running the client. |
| Network policy and secrets | Works everywhere | Egress policies and hostname-scoped secret substitution carry across backends. |
| Custom networking | Local-only | Published ports, custom nameservers, interface overrides, rate limiters, TLS interception, and host-CA trust are not accepted by cloud create. |
| Logs | Limited on cloud | SDK live-follow works. Bounded or historical reads and the msb logs command are local-only; persist followed output externally when retention matters. |
| SSH | Limited on cloud | Native SDK sessions and msb ssh work. msb ssh serve is local-only; reusable SDK servers require explicit key material. |
| Images | Limited on cloud | OCI image references and registry credentials work. Local cache commands, host-directory or disk-image roots, plain-HTTP registries, and custom registry CAs are local-only. |
| Reconfiguration | Local-only | Recreate the sandbox with the new CPU, memory, mounts, or other settings instead of using modify. |
| Snapshots | Local-only | Use a named volume for state that must survive sandbox replacement. |
| Resource metrics | Local-only | Instrument the workload with an external monitoring system. |
| Process controls | Limited on cloud | Graceful stop plus maximum-duration and idle-timeout policies work. Force kill, drain, ping, and touch are local-only. |
The same key also authenticates the REST API directly, so you can manage sandboxes, volumes, and usage over plain HTTPS without an SDK. Command execution, file transfer, and SSH ride the sandbox command channel, which the SDKs and CLI handle for you.
MSB_BACKEND=cloud, select a cloud profile, or choose it in code. See Backends.msb ssh and SDK SSH clients you use locally.