> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud

> Run the same sandboxes on hosted infrastructure with an API key

<Note>
  microsandbox cloud is in **private beta**, and currently requires you to explicitly [request access](https://dashboard.microsandbox.dev/signup). If you already have access, you can get your API key from the [dashboard](https://dashboard.microsandbox.dev/access/api-keys).
</Note>

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

```bash theme={null}
export MSB_BACKEND=cloud
export MSB_API_KEY="msb_..."
msb context
```

`msb context` confirms that subsequent commands will run on cloud and shows what selected it without exposing the API key. For profiles, SDK selection, and precedence, see [Local or cloud](/operations/backends).

## Sandbox identity

Looking up a sandbox by name selects the sandbox currently using that name.
The returned object retains that sandbox's ID for lifecycle operations, commands,
and file access. If the sandbox is deleted and its name reused, operations on
an old object fail instead of reaching the replacement. Fetch the sandbox by
name again to select the replacement; you do not need to manage IDs yourself.

## Same code, different backend

Everything from the [quickstart](/getting-started/quickstart) works unchanged. With cloud selected and the API key exported, this creates a sandbox on cloud instead of your machine:

<CodeGroup>
  ```typescript TypeScript theme={null}
  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());
  ```

  ```rust Rust theme={null}
  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?;
  ```

  ```python Python theme={null}
  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()
  ```

  ```go Go theme={null}
  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())
  ```

  ```ruby Ruby theme={null}
  require "microsandbox"

  Microsandbox::Sandbox.with("hello", image: "python", memory: 512) do |sb|
    output = sb.exec("python", ["-c", "print('Hello from the cloud!')"])
    puts output.stdout
  end
  ```

  ```bash CLI theme={null}
  msb run python -- python3 -c "print('Hello from the cloud!')"
  ```
</CodeGroup>

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

<CardGroup cols={2}>
  <Card title="Sandbox lifecycle" icon="box">
    Create, inspect, list, reconnect, start, stop, and remove sandboxes.
  </Card>

  <Card title="Commands and files" icon="terminal">
    Run buffered, streaming, and interactive commands, then move files in or out.
  </Card>

  <Card title="Persistent storage" icon="hard-drive">
    Create managed volumes and access their files without starting a sandbox.
  </Card>

  <Card title="Network controls" icon="shield-halved">
    Apply egress policy and hostname-scoped secrets from the same SDK surface.
  </Card>
</CardGroup>

## 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 | **Limited on cloud** | Capture disk snapshots from stopped persistent sandboxes and restore them into new sandboxes. Live capture, full checkpoints, forking, groups, and local artifact archives remain local-only. |
| 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](/api-reference/overview) 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

* **Local or cloud.** Cloud is explicit: set `MSB_BACKEND=cloud`, select a cloud profile, or choose it in code. See [Local or cloud](/operations/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.
* **Managed settings.** [Device policy](/enterprise/managed-configuration) applies to create requests and CLI/SDK SSH sessions. Unsupported create settings fail before the request is sent. Existing cloud sandboxes and the hosted SSH gateway keep their settings.
* **Keys and billing.** API keys, usage, and invoices live in the [dashboard](https://dashboard.microsandbox.dev).

## Next steps

<CardGroup cols={2}>
  <Card title="API reference" icon="brackets-curly" href="/api-reference/overview">
    The REST API behind the SDKs, authenticated with your API key.
  </Card>

  <Card title="Local or cloud" icon="cloud-arrow-up" href="/operations/backends">
    Force local, select in code, or switch with profiles.
  </Card>

  <Card title="Quickstart" icon="bolt" href="/getting-started/quickstart">
    New to microsandbox? Start here; everything carries over.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.