> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-workspaces-notebooks.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Serverless Sandboxes

> On-demand, isolated compute environments that you can create, use, and discard from Python with W&B Serverless Sandboxes.

<Warning>
  **`wandb.sandbox` is deprecated** and will be removed in a future release of the W\&B Python SDK. Use the `cwsandbox` package instead, documented in the [CoreWeave sandbox docs](https://docs.coreweave.com/products/sandboxes).

  Migrating changes two things:

  * **The import.** Install `cwsandbox` with the W\&B extra (`pip install "cwsandbox[wandb]"`) and import from `cwsandbox` instead of `wandb.sandbox`.
  * **The credential.** `cwsandbox` authenticates with a CoreWeave API access token in `CWSANDBOX_API_KEY` by default, so pass `auth=AuthStrategy.WANDB` to keep using your W\&B API key. See [Choose a credential](https://docs.coreweave.com/products/sandboxes/get-started#choose-a-credential).

  The examples on this page still use `wandb.sandbox`. For the equivalent `cwsandbox` code, see [Migrate to `cwsandbox`](/sandboxes#migrate-to-cwsandbox).
</Warning>

<Warning>
  Serverless Sandboxes is in **public preview**. Access is enabled per organization. To request access for your organization, contact [support](mailto:support@wandb.com).
</Warning>

Serverless Sandboxes gives you on-demand, isolated compute environments that you can create, use, and discard using Python.

Serverless Sandboxes is built using the CoreWeave Sandbox library. For the underlying API reference and library docs, see the [CoreWeave Sandbox documentation](https://docs.coreweave.com/products/coreweave-sandbox).

## How it works

A *sandbox* is a single isolated compute environment. You [create](/sandboxes/create-sandbox) it, [run commands inside it](/sandboxes/run-commands), and stop it when it is done. Each sandbox runs in its own container with its own filesystem, network, and process space.

W\&B authenticates your identity when you create and manage sandboxes. To use W\&B or Weave inside a sandbox, pass your API key using the [W\&B Secrets Manager](/platform/secrets#manage-access-to-secrets) or environment variables. See [Secrets](/sandboxes/secrets) for more information about using secrets in sandboxes.

A sandbox goes through [several states in its lifecycle](/sandboxes/lifecycle). When a container is running, you can [execute commands](/sandboxes/run-commands) inside it.

[Read, write, and mount read-only](/sandboxes/file-access) files to and from the sandbox. Common examples include reading in a Python script to execute, writing out logs or results, or mounting a directory of data read-only for the sandbox to access.

Use a *session* to manage multiple sandboxes that share configuration. When a session closes, all of its sandboxes are stopped automatically. See [Manage multiple sandboxes](/sandboxes/create-sandbox#create-multiple-sandboxes-with-a-session) for more details.

## Basic usage

Follow these steps to create a sandbox and run a command inside it:

1. Install the W\&B Python SDK (`wandb`) and the serverless sandbox dependencies with the following command:
   ```bash theme={null}
   pip install wandb[sandbox]
   ```

2. Log in to W\&B with the [`wandb login`](/models/ref/cli/wandb-login) CLI command. When prompted, provide your API key to authenticate your identity and access your W\&B account:

   ```bash theme={null}
   wandb login
   ```

3. Copy and paste the following code snippet into a Python file and run it. The code snippet accomplishes the following:

   1. Create a sandbox with [`Sandbox.run()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#run).
   2. Run the command `echo "Hello from Serverless Sandboxes!"` inside the sandbox using the [`Sandbox.exec()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#exec) method.
   3. Print the output to the console using the `Process` object returned by `Sandbox.exec()`.

   ```python show lines title="hello_sandbox.py" theme={null}
   from wandb.sandbox import Sandbox

   with Sandbox.run() as sandbox:
       process = sandbox.exec(["echo", "Hello from Serverless Sandboxes!"]).result()
       print(process.stdout)
   ```

   You should see the output `Hello from Serverless Sandboxes!` printed to the console.

   The sandbox automatically stops when the context manager (the `with` block) exits. For more information on sandbox lifecycle and states, see [Lifecycle of sandboxes](/sandboxes/lifecycle).

## Migrate to cwsandbox

`wandb.sandbox` is deprecated and will be removed in a future release of the W\&B Python SDK. The `cwsandbox` package replaces it and accepts either a W\&B API key or a CoreWeave API access token. Its reference documentation lives in the [CoreWeave sandbox docs](https://docs.coreweave.com/products/sandboxes).

To migrate, change how you install the package, how you import it, and how you select your credential:

1. Install `cwsandbox` with the W\&B extra. The extra pulls in the `wandb` library, which `cwsandbox` uses to resolve W\&B credentials:

   ```bash theme={null}
   pip install "cwsandbox[wandb]"
   ```

2. Import from `cwsandbox` instead of `wandb.sandbox`, and pass `auth=AuthStrategy.WANDB` when you create a sandbox or a session. `cwsandbox` reads a CoreWeave API access token from `CWSANDBOX_API_KEY` by default, so W\&B authentication must be selected explicitly:

   ```python title="Before: wandb.sandbox" theme={null}
   from wandb.sandbox import Sandbox

   with Sandbox.run() as sandbox:
       process = sandbox.exec(["echo", "Hello from Serverless Sandboxes!"]).result()
       print(process.stdout)
   ```

   ```python title="After: cwsandbox" theme={null}
   from cwsandbox import AuthStrategy, Sandbox

   with Sandbox.run(auth=AuthStrategy.WANDB) as sandbox:
       process = sandbox.exec(["echo", "Hello from Serverless Sandboxes!"]).result()
       print(process.stdout)
   ```

Your W\&B credentials resolve the same way they do today: from an active `wandb login` session, the `WANDB_API_KEY` environment variable, or the `api.wandb.ai` entry in `~/.netrc`. To bill sandboxes to a CoreWeave account instead, omit `auth` and set `CWSANDBOX_API_KEY` to a CoreWeave API access token. For a comparison of the two credentials, see [Choose a credential](https://docs.coreweave.com/products/sandboxes/get-started#choose-a-credential).

### Behavior that changes after you migrate

`wandb.sandbox` wraps `cwsandbox` and applies W\&B Serverless defaults that the `cwsandbox` package doesn't apply on its own. Account for these differences when you migrate:

| Behavior                 | `wandb.sandbox`                                          | `cwsandbox`                                     |
| ------------------------ | -------------------------------------------------------- | ----------------------------------------------- |
| Maximum sandbox lifetime | Defaults to 12 hours                                     | No default; set `max_lifetime_seconds` yourself |
| Secret store             | `Secret` defaults to the W\&B team secret store          | `Secret` requires an explicit `store` argument  |
| Placement arguments      | Rejects `profile_ids`, `profile_names`, and `runner_ids` | Accepts them for CoreWeave sandbox runners      |

## Serverless Sandboxes tutorials

For more in-depth examples, see:

* [Invoke an agent in a Serverless Sandbox tutorial](/sandboxes/invoke-agent-sandbox-tutorial)
* [Train a PyTorch model in a Serverless Sandbox tutorial](/sandboxes/mltrain-in-sandbox-tutorial)

## Integrations

The following third-party frameworks support Serverless Sandboxes as a sandbox provider.

* [Harbor](https://github.com/harbor-framework/harbor)