Cloud

Run the same sandboxes on hosted infrastructure with an API key

microsandbox cloud is in private beta, and currently requires you to explicitly request access. If you already have access, you can get your API key from the dashboard.

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.

Connect

export MSB_BACKEND=cloud
export MSB_API_KEY="msb_..."

Same code, different backend

Everything from the quickstart works unchanged. With cloud selected and the API key exported, this creates a sandbox on cloud instead of your machine:

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?;

Hardware virtualization support on your machine is not needed for cloud sandboxes; msb doctor checks apply to the local runtime only.

What works on cloud

Sandbox lifecycle

Create, inspect, list, reconnect, start, stop, and remove sandboxes.

Commands and files

Run buffered, streaming, and interactive commands, then move files in or out.

Persistent storage

Create managed volumes and access their files without starting a sandbox.

Network controls

Apply egress policy and hostname-scoped secrets from the same SDK surface.

Compatibility

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 and msb logs -f work. Bounded or historical reads 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.

REST API

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.

What to know

• Backend selection. Cloud is explicit: set MSB_BACKEND=cloud, select a cloud profile, or choose it in code. See Backends.
• Networking. Cloud sandboxes get a platform-assigned hostname. SSH works through the same msb ssh and SDK SSH clients you use locally.
• Images. Specify an OCI image when you create the sandbox; the cloud pulls it for you.
• Keys and billing. API keys, usage, and invoices live in the dashboard.

Next steps

API reference

The REST API behind the SDKs, authenticated with your API key.

Backends

Force local, select in code, or switch with profiles.

Quickstart

New to microsandbox? Start here; everything carries over.