From 7c19f42323acd998a4945d82c5b56136fb24a6a8 Mon Sep 17 00:00:00 2001 From: John Mulhausen Date: Tue, 26 May 2026 21:55:18 -0400 Subject: [PATCH 1/4] style: apply /style-guide pass to sandboxes --- sandboxes/create-sandbox.mdx | 15 ++++---- sandboxes/file-access.mdx | 6 ++-- sandboxes/invoke-agent-sandbox-tutorial.mdx | 20 ++++++----- sandboxes/lifecycle.mdx | 36 ++++++++++--------- sandboxes/mltrain-in-sandbox-tutorial.mdx | 38 ++++++++++++--------- sandboxes/run-commands.mdx | 20 +++++------ sandboxes/secrets.mdx | 10 ++++-- 7 files changed, 80 insertions(+), 65 deletions(-) diff --git a/sandboxes/create-sandbox.mdx b/sandboxes/create-sandbox.mdx index 78fde00612..8b3b508534 100644 --- a/sandboxes/create-sandbox.mdx +++ b/sandboxes/create-sandbox.mdx @@ -7,12 +7,12 @@ description: Learn how to create Serverless Sandboxes. Serverless Sandboxes is in public preview. -Create sandboxes with W&B. Each sandbox runs in its own container with its own [filesystem](/sandboxes/file-access), network, and process space. +This page shows you how to create Serverless Sandboxes with W&B. You learn how to start a single sandbox, run a main command inside it, and manage multiple sandboxes with a session. Each sandbox runs in its own container with its own [filesystem](/sandboxes/file-access), network, and process space, which gives you an isolated environment to run code. By default, sandboxes use `python:3.11` as the base image. To use a different image, pass `container_image` to [`Sandbox.run()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#run) or [`SandboxDefaults`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox-defaults). W&B supports public container images only. -The following code snippet creates a sandbox with the `python:3.15` image and runs `python --version` inside it. +The following code snippet creates a sandbox with the `python:3.15` image and runs `python --version` inside it. ```python from wandb.sandbox import Sandbox @@ -27,7 +27,7 @@ with Sandbox.run(container_image="python:3.15") as sandbox: Use [`Sandbox.run()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#run) to create and start a sandbox. This method returns a `Sandbox` object that you can use to interact with the environment. -W&B recommends using a context manager (`with` statement) to ensure that the sandbox is stopped automatically when it exits the block, even if an error occurs. +W&B recommends using a context manager (`with` statement) to stop the sandbox automatically when the block exits, even if an error occurs. The following example creates a sandbox with the default container image (`python:3.11`): @@ -56,7 +56,7 @@ This pattern is useful for interactive and multi-step workflows. To learn how to ### Start a sandbox with a main command -You can also pass a command to `Sandbox.run()`. Use this pattern when the sandbox is meant to run a single job from start to finish. When the main process exits, the sandbox enters a terminal state such as [COMPLETED or FAILED](/sandboxes/lifecycle). +You can also pass a command to `Sandbox.run()`. Use this pattern when the sandbox runs a single job from start to finish. When the main process exits, the sandbox enters a terminal state such as [COMPLETED or FAILED](/sandboxes/lifecycle). The command you provide to `Sandbox.run()` starts as the sandbox's main process. @@ -77,16 +77,17 @@ sandbox = Sandbox.run("python", "train.py") sandbox.wait_until_complete().result() ``` - ## Create multiple sandboxes with a session -Use [`Session`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/session) to create and manage multiple sandboxes. When the session closes (for example, when exiting a `with` block), all sandboxes created by that session are stopped automatically. +When you need more than one sandbox at a time, or want to share configuration across several sandboxes, use a session. + +Use [`Session`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/session) to create and manage multiple sandboxes. When the session closes (for example, when you exit a `with` block), it automatically stops all sandboxes it created. You can optionally pass a [`SandboxDefaults`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox-defaults) object to a session to define reusable default configuration for all sandboxes created by that session. For example, you can specify a default container image, network configuration, or maximum lifetime for all sandboxes in the session. `session.sandbox()` returns an unstarted sandbox. It auto-starts when you call `Sandbox.exec()`, `Sandbox.read_file()`, or any other operation. -The following code snippet creates a session that creates two sandboxes that use a default configuration (`SandboxDefaults`): +The following code snippet creates a session with two sandboxes that share a default configuration (`SandboxDefaults`): ```python from wandb.sandbox import Session, SandboxDefaults diff --git a/sandboxes/file-access.mdx b/sandboxes/file-access.mdx index c3be2aa1e5..842706ff7a 100644 --- a/sandboxes/file-access.mdx +++ b/sandboxes/file-access.mdx @@ -25,7 +25,7 @@ Read and write files when you want to transfer smaller files between your local {/* creating, updating, modifying, or saving data */} {/* transfers a file into the sandbox. Use it to upload inputs your sandbox code needs (scripts, configs, data files). */} -Transfer a file from your local environment to the sandbox using the [`Sandbox.write_file()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#write_file) method. +Write a file to the sandbox when you need to upload inputs your sandbox code uses, such as scripts, configs, or data files. Transfer a file from your local environment to the sandbox using the [`Sandbox.write_file()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#write_file) method. ```python @@ -44,7 +44,7 @@ See the `Sandbox` class reference documentation for a full list of parameters an ## Read a file from the sandbox -Save a file from the sandbox to your local environment using the [`Sandbox.read_file()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#read_file) method. +Read a file from the sandbox when you want to save its output or generated artifacts back to your local environment. Save a file from the sandbox to your local environment using the [`Sandbox.read_file()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#read_file) method. ```python from pathlib import Path @@ -70,7 +70,7 @@ Use mounted files to provide local files to the sandbox at creation time. Unlike Mounted files are read-only in the sandbox. If you need to modify files in the sandbox, use `Sandbox.write_file()` instead. -In the following code snippet, local files `train.py` and `requirements.txt` are mounted to the sandbox root directory. The sandbox installs dependencies from `requirements.txt` and then runs `train.py`. +The following code snippet mounts the local files `train.py` and `requirements.txt` to the sandbox root directory. The sandbox installs dependencies from `requirements.txt` and then runs `train.py`. ```python from pathlib import Path diff --git a/sandboxes/invoke-agent-sandbox-tutorial.mdx b/sandboxes/invoke-agent-sandbox-tutorial.mdx index 9a60a2b4e2..0f66e1e7b7 100644 --- a/sandboxes/invoke-agent-sandbox-tutorial.mdx +++ b/sandboxes/invoke-agent-sandbox-tutorial.mdx @@ -1,22 +1,24 @@ --- title: "Tutorial: Invoke an agent in a sandbox" -description: "Learn how to invoke OpenAI agent within a Serverless Sandbox environment" +description: "Learn how to invoke an OpenAI agent within a Serverless Sandbox environment" --- Serverless Sandboxes is in public preview. -In this tutorial, you will invoke an agent within a Serverless Sandbox environment. To do this, you will start a sandbox with the appropriate environment variables, install the necessary dependencies, and run a Python script that creates and invokes a simple OpenAI agent that uses tool calls to get the weather for a location and respond with a punny weather forecast. +In this tutorial, you invoke an agent within a Serverless Sandbox environment. To do this, you start a sandbox with the appropriate environment variables, install the necessary dependencies, and run a Python script. The script creates and invokes an OpenAI agent that uses tool calls to get the weather for a location and respond with a punny weather forecast. This lets you test and iterate on agent behavior in a safe, isolated environment without affecting your local setup. This tutorial uses OpenAI as the language model for the agent, which requires an OpenAI API key. -{/* This allows you to test and iterate on your agent's behavior in a safe and isolated environment, without affecting your local setup. */} +{/* This lets you test and iterate on your agent's behavior in a safe and isolated environment, without affecting your local setup. */} ## Prerequisites +Before you begin, install the W&B Python SDK, authenticate with W&B, and store your OpenAI API key as a secret so the sandbox can use it. + {/* ### (Recommended) Create a Python virtual environment Create and activate a Python virtual environment to keep your dependencies organized and avoid conflicts with other projects. Run the following commands in your terminal: @@ -28,9 +30,9 @@ source venv/bin/activate # On Windows, use `venv\Scripts\activate` ### Install W&B Python SDK -Install the W&B Python SDK. You can do this using `pip`: +Install the W&B Python SDK using `pip`: -```bash +```bash pip install wandb ``` @@ -44,15 +46,17 @@ wandb login ### Store API keys in Secret Manager -Store your OpenAI API key in the [W&B Secret Manager](/platform/secrets) as `OPENAI_API_KEY`. See [Secrets](/sandboxes/secrets) for more information about using secrets in sandboxes. +Store your OpenAI API key in the [W&B Secret Manager](/platform/secrets) as `OPENAI_API_KEY`. For more information about using secrets in sandboxes, see [Secrets](/sandboxes/secrets). -This allows you to securely access the API key in the sandbox without hardcoding it in your code or sandbox configuration. +This lets you securely access the API key in the sandbox without hardcoding it in your code or sandbox configuration. ## Copy agent code +With your prerequisites in place, save the agent code locally so you can run it inside a sandbox. The script defines an OpenAI agent with two tools and a structured response format. + -Copy and paste the following code into a file named `demo.py` in the same directory as this tutorial, then run the above code snippet to see how to invoke an OpenAI agent within a sandbox environment. +Copy and paste the following code into a file named `demo.py` in the same directory as this tutorial. The script defines an OpenAI agent that uses tool calls to fetch weather data and respond with a punny forecast. ```python title="demo.py" import json diff --git a/sandboxes/lifecycle.mdx b/sandboxes/lifecycle.mdx index 38bf2050b2..8d13532ad8 100644 --- a/sandboxes/lifecycle.mdx +++ b/sandboxes/lifecycle.mdx @@ -7,11 +7,13 @@ description: Learn about the lifecycle of a Serverless Sandbox, including its st Serverless Sandboxes is in public preview. +This page describes the lifecycle of a Serverless Sandbox so that you can choose the right method for waiting on state changes, stopping a sandbox, and structuring code around its lifetime. Understanding the lifecycle helps you avoid race conditions, distinguish startup failures from runtime errors, and clean up resources predictably. + A Serverless Sandbox goes through several states during its lifecycle. The sandbox's state determines which operations are available. -In most cases, a sandbox starts in `PENDING`, moves to `CREATING` while the container is provisioned, and then enters `RUNNING` when it is ready for use. +Usually, a sandbox starts in `PENDING`, moves to `CREATING` while the container is provisioned, and then enters `RUNNING` when it's ready for use. -If you start a sandbox with a main command, that command becomes the sandbox's main process. When the main process exits, the sandbox enters a terminal state such as `COMPLETED` (exit code `0`) or `FAILED` (an error during startup or execution). A sandbox can also enter `TERMINATED` if it is stopped externally or exceeds its maximum lifetime. +If you start a sandbox with a main command, that command becomes the sandbox's main process. When the main process exits, the sandbox enters a terminal state such as `COMPLETED` (exit code `0`) or `FAILED` (an error during startup or execution). A sandbox can also enter `TERMINATED` if it's stopped externally or exceeds its maximum lifetime. ```text PENDING -> CREATING -> RUNNING -> COMPLETED @@ -19,7 +21,7 @@ PENDING -> CREATING -> RUNNING -> COMPLETED -> TERMINATED ``` -The next sections describe sandbox states, how to wait for readiness or completion, and how to stop a sandbox. For more information about creating sandboxes and running commands, see [Create sandboxes](/sandboxes/create-sandbox) and [Run commands](/sandboxes/run-commands). +The following sections describe sandbox states, how to wait for readiness or completion, and how to stop a sandbox. For more information about creating sandboxes and running commands, see [Create sandboxes](/sandboxes/create-sandbox) and [Run commands](/sandboxes/run-commands). ## Sandbox states @@ -27,27 +29,27 @@ The following table summarizes the states of a sandbox: | State | Description | |-------------|-------------------------------------| -| PENDING | The sandbox request was accepted and is waiting to be scheduled. | -| CREATING | The container is being provisioned. | -| RUNNING | The sandbox is ready for operations. | -| COMPLETED | The main process exited successfully with code 0. | -| FAILED | The sandbox or its main process encountered an error during startup or execution. | -| TERMINATED | The sandbox was stopped externally or ended because it exceeded its maximum lifetime. | +| `PENDING` | The sandbox request was accepted and is waiting to be scheduled. | +| `CREATING` | The container is provisioning. | +| `RUNNING` | The sandbox is ready for operations. | +| `COMPLETED` | The main process exited successfully with code `0`. | +| `FAILED` | The sandbox or its main process encountered an error during startup or execution. | +| `TERMINATED` | An external process stopped the sandbox, or it ended because it exceeded its maximum lifetime. | -Most operations require the sandbox to be in the RUNNING state. However, many operations automatically wait until the sandbox is ready before proceeding. +Most operations require the sandbox to be in the `RUNNING` state. However, many operations wait until the sandbox is ready before proceeding. -After a sandbox enters a terminal state, it is no longer available for additional work. +After a sandbox enters a terminal state, it's no longer available for additional work. ## Wait for readiness or completion -Use different wait methods depending on what you need: +The following sections describe the two methods for waiting on sandbox state changes and when to use each. Use different wait methods depending on what you need: * Use `Sandbox.wait()` to [wait until the sandbox is ready for use](/sandboxes/lifecycle#wait-for-a-sandbox-to-start). * Use `Sandbox.wait_until_complete()` to [wait until the sandbox's main process finishes](/sandboxes/lifecycle#wait-for-a-sandbox-to-complete). ### Wait for a sandbox to start -Use `Sandbox.wait()` to explicitly wait for the sandbox to reach the RUNNING state. This is useful for debugging startup problems or when you want to distinguish startup failures from errors in later commands. +Use `Sandbox.wait()` to wait for the sandbox to reach the `RUNNING` state. This method is useful for debugging startup problems or when you want to distinguish startup failures from errors in later commands. For example, the following code creates a sandbox, waits for it to become ready, and then runs a command: @@ -75,7 +77,7 @@ print(f"Exit code: {sandbox.returncode}") This pattern is useful when you start a sandbox with a main command such as `Sandbox.run("python", "train.py")` and want the sandbox lifecycle to match that command's execution. -When the main process exits, the sandbox enters a terminal state. A successful run typically ends in COMPLETED. If the process fails, the sandbox may enter FAILED. +When the main process exits, the sandbox enters a terminal state. A successful run typically ends in `COMPLETED`. If the process fails, the sandbox may enter `FAILED`. If you need to run commands interactively instead, use a context manager with `Sandbox.exec()`: @@ -90,9 +92,9 @@ with Sandbox.run() as sandbox: ## Explicit lifecycle control -Use methods such as `Sandbox.wait()` and `Sandbox.stop()` when you need explicit control over the sandbox lifecycle. +Use methods such as `Sandbox.wait()` and `Sandbox.stop()` when you need explicit control over the sandbox lifecycle instead of relying on automatic behavior. -In most cases, you do not need to call these methods directly. Operations such as `Sandbox.exec()`, `Sandbox.read_file()`, and `Sandbox.write_file()` automatically wait for readiness, and the context manager (`with Sandbox.run() as sandbox:`) automatically stops the sandbox when the block exits. +Usually, you don't need to call these methods directly. Operations such as `Sandbox.exec()`, `Sandbox.read_file()`, and `Sandbox.write_file()` wait for readiness, and the context manager (`with Sandbox.run() as sandbox:`) stops the sandbox when the block exits. ### Stop a sandbox @@ -116,6 +118,6 @@ from wandb.sandbox import Sandbox with Sandbox.run("sleep", "infinity") as sandbox: sandbox.stop( graceful_shutdown_seconds=30.0, # Wait before force-killing the sandbox. - missing_ok=True, # Do not raise an error if it is already stopped. + missing_ok=True, # Don't raise an error if it's already stopped. ).result() ``` \ No newline at end of file diff --git a/sandboxes/mltrain-in-sandbox-tutorial.mdx b/sandboxes/mltrain-in-sandbox-tutorial.mdx index 9c13133c23..5385c9f065 100644 --- a/sandboxes/mltrain-in-sandbox-tutorial.mdx +++ b/sandboxes/mltrain-in-sandbox-tutorial.mdx @@ -7,11 +7,13 @@ description: "Learn how to train a PyTorch model in a Serverless Sandbox environ Serverless Sandboxes is in public preview. -In this tutorial you will train a PyTorch model in a Serverless Sandbox environment. To do this, you will start a sandbox with the appropriate environment variables, install the necessary dependencies, and run a Python script that trains a simple neural network on the UCI Zoo dataset. +In this tutorial, you train a PyTorch model in a Serverless Sandbox environment. To do this, you start a sandbox with the appropriate environment variables, install the necessary dependencies, and run a Python script. The script trains a neural network on the UCI Zoo dataset. + +By the end of this tutorial, you have a trained PyTorch model file saved locally. This demonstrates how to use a Serverless Sandbox to run isolated ML training workloads without configuring local infrastructure. This tutorial is intended for ML practitioners and developers who want to evaluate Serverless Sandboxes for reproducible training jobs. ## Prerequisites -Before you get started, make sure you have the following: +Before you get started, complete the following setup steps. {/* ### (Recommended) Create a Python virtual environment @@ -22,27 +24,27 @@ python -m venv venv source venv/bin/activate # On Windows, use `venv\Scripts\activate` ``` */} -### Install W&B Python SDK +### Install the W&B Python SDK -Install the W&B Python SDK. You can do this using `pip`: +The W&B Python SDK provides the `Sandbox` interface you use later to create and interact with the Serverless Sandbox. Install it using `pip`: ```bash pip install wandb ``` -## Log in and authenticate with W&B +### Log in and authenticate with W&B -If you have not done so already, log in to W&B. Use the `wandb login` CLI command and follow the prompts to log in to your W&B account: +The Serverless Sandbox runs under your W&B account, so you must be authenticated before you can create one. If you haven't done so already, log in to W&B. Use the `wandb login` CLI command and follow the prompts to log in to your W&B account: ```bash wandb login ``` -See [`wandb login`](/models/ref/cli/wandb-login) reference documentation for more information on how W&B searches for credentials. +See the [`wandb login`](/models/ref/cli/wandb-login) reference documentation for more information about how W&B searches for credentials. -### Copy the training script and dependencies +## Copy the training script and dependencies -Expand the following dropdown to acess the code required for this tutorial. Copy and paste the code into three separate files in the same directory as this tutorial. In the next section, you will run a script that reads in these files and trains a PyTorch model within a Serverless Sandbox environment. +In this step, you prepare the three files that the sandbox needs: a requirements file, a hyperparameters file, and the training script itself. Expand the following dropdown to access the code required for this tutorial. Copy and paste the code into three separate files in the same directory as this tutorial. In the next section, you run a script that reads in these files and trains a PyTorch model within a Serverless Sandbox environment. @@ -64,7 +66,7 @@ epochs: 1000 model_type: Multivariate_neural_network_classifier ``` -Copy and paste the following code into a file named `train.py`. This script trains a simple PyTorch model on the UCI Zoo dataset and saves the trained model to a file named `zoo_wandb.pth`. +Copy and paste the following code into a file named `train.py`. This script trains a PyTorch model on the UCI Zoo dataset and saves the trained model to a file named `zoo_wandb.pth`. ```python title="train.py" import argparse @@ -180,7 +182,7 @@ if __name__ == "__main__": ## Create the sandbox and run the training script -The following code snippet shows how to create a sandbox, copy the training script and dependencies into it, run the training script, and download the generated model file. The next section provides a line-by-line explanation of the code. +With your training files in place, you can now drive the sandbox from a single Python script. The following code snippet shows how to create a sandbox and copy the training script and dependencies into it. It then runs the training script and downloads the generated model file. The next section explains the code line by line. Copy and paste the following code into a Python file and run it. Save it in the same directory as the `train.py`, `requirements.txt`, and `hyperparameters.yaml` files you created in the previous step. @@ -224,10 +226,12 @@ with Sandbox.run( The previous code snippet does the following: -1. (Lines 6 - 9) Lists the files to mount to the sandbox: `train.py` and `requirements.txt`. +1. (Lines 6-9) List the files to mount to the sandbox: `train.py` and `requirements.txt`. 2. (Line 12) Start the sandbox. The sandbox is configured to use the `python:3.13` container image, have internet access, and a maximum lifetime of 3600 seconds (1 hour). -3. (Line 18) Write the `hyperparameters.yaml` file to the sandbox. This allows the training script (`train.py`) to access the hyperparameters when it runs. -4. (Line 22) Install dependencies. You run the command `pip install -r requirements.txt` inside the sandbox to install the necessary dependencies for the training script. -5. (Line 26) Run the training script. You execute the command `python train.py --config hyperparameters.yaml` inside the sandbox to start the training process. The script trains a PyTorch model on the UCI Zoo dataset and saves the trained model to a file named `zoo_wandb.pth`. -6. (Lines 27-29) Print the output and exit code. After the training script finishes executing, you print the standard output, standard error, and exit code to the console for debugging and verification purposes. -7. (Lines 33-34) Download the generated model file. You read the `zoo_wandb.pth` file from the sandbox using the `read_file()` method and save it locally. \ No newline at end of file +3. (Line 18) Write the `hyperparameters.yaml` file to the sandbox. This lets the training script (`train.py`) access the hyperparameters when it runs. +4. (Line 22) Install dependencies. The command `pip install -r requirements.txt` runs inside the sandbox to install the necessary dependencies for the training script. +5. (Line 26) Run the training script. The command `python train.py --config hyperparameters.yaml` runs inside the sandbox to start the training process. The script trains a PyTorch model on the UCI Zoo dataset and saves the trained model to a file named `zoo_wandb.pth`. +6. (Lines 27-29) Print the output and exit code. After the training script finishes, the standard output, standard error, and exit code are printed to the console for debugging and verification. +7. (Lines 33-34) Download the generated model file. The `read_file()` method reads `zoo_wandb.pth` from the sandbox, and the script saves it locally. + +After the script completes, you have a trained PyTorch model saved as `zoo_wandb.pth` in your working directory. The sandbox that produced it is created, used, and torn down on demand. \ No newline at end of file diff --git a/sandboxes/run-commands.mdx b/sandboxes/run-commands.mdx index 4011421617..6937fe0eaf 100644 --- a/sandboxes/run-commands.mdx +++ b/sandboxes/run-commands.mdx @@ -9,14 +9,14 @@ Serverless Sandboxes is in public preview.

-[Run commands in a sandbox](#run-commands-in-a-sandbox), [read their output and exit code](#read-output-and-exit-codes), and [check for errors](#check-for-errors). Use these features to run scripts, training jobs, and other processes in a sandbox and programmatically check the results. +This page shows you how to [run commands in a sandbox](#run-commands-in-a-sandbox), [read their output and exit code](#read-output-and-exit-codes), and [check for errors](#check-for-errors). Use these features to run scripts, training jobs, and other processes in a sandbox and programmatically check the results. ## Run commands in a sandbox -Based on your use case, use one of these patterns to run commands in a sandbox: +The sandbox client supports two patterns for running commands, depending on whether you need to run a single command or a sequence of related commands. Based on your use case, use one of these patterns to run commands in a sandbox: -* [Single command](#run-a-single-command): Pass the command to `Sandbox.run()` and call `Sandbox.wait_until_complete()` to block until it finishes. Best for batch jobs, tests, or training runs. +* [Single command](#run-a-single-command): Pass the command to `Sandbox.run()` and call `Sandbox.wait_until_complete()` to block until it finishes. Best for batch jobs, tests, or training runs. * [Multiple commands](#run-multiple-commands-sequentially): Call `Sandbox.run()` with no arguments, then use `Sandbox.exec()` for each step. Best for workflows that combine setup, execution, and result retrieval. @@ -53,15 +53,15 @@ with Sandbox.run() as sandbox: print(result.stdout) ``` -`Sandbox.exec()` runs a command in the sandbox and returns a `Process` object. You can use the returned object to wait for the command to finish, read output, and inspect the exit code. +`Sandbox.exec()` runs a command in the sandbox and returns a `Process` object. Use the returned object to wait for the command to finish, read output, and inspect the exit code. For more information about `Sandbox.exec()` and its parameters, see [`Sandbox.exec()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#exec) in the CoreWeave Sandboxes reference documentation. -#### Keep the sandbox running for additional commands +#### Keep the sandbox running for additional commands -In some cases, you might want to start the sandbox with a long-running main process to keep it available while you run other commands with `Sandbox.exec()`. +Sometimes, you might want to start the sandbox with a long-running main process to keep it available while running other commands with `Sandbox.exec()`. -The following example starts a sandbox with `sleep infinity` as the main process, then runs a training script inside the sandbox with Sandbox.exec(). +The following example starts a sandbox with `sleep infinity` as the main process, then runs a training script inside the sandbox with `Sandbox.exec()`. ```python from wandb.sandbox import Sandbox @@ -73,11 +73,11 @@ with Sandbox.run("sleep", "infinity") as sandbox: ## Read output and exit codes -`Sandbox.exec()` returns a [`Process`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/types/process) object. Call `Process.result()` to wait for the command to finish and get its result. `Process.result()` includes the standard output (`stdout`), standard error (`stderr`), and exit code (`returncode`). +After a command runs, you often need to read its output and check whether it succeeded. `Sandbox.exec()` returns a [`Process`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/types/process) object. Call `Process.result()` to wait for the command to finish and get its result. `Process.result()` includes the standard output (`stdout`), standard error (`stderr`), and exit code (`returncode`). Use the exit code to determine whether the command succeeded. By convention, an exit code of 0 indicates success. The possible exit codes and their meanings depend on the command. -For example, the following code snippet runs a Python command that prints the standard output (`stdout`) and the exit code (`returncode`). After the command finishes, it prints the standard output, standard error, and exit code to the console. +For example, the following code snippet runs a Python command that prints the standard output (`stdout`) and the exit code (`returncode`). After the command finishes, the snippet prints the standard output, standard error, and exit code to the console. ```python from wandb.sandbox import Sandbox @@ -90,7 +90,7 @@ with Sandbox.run() as sandbox: ## Check for sandbox execution errors -Specify `check=True` (`Sandbox.exec(check=True)`) to raise an error if the command exits with a non-zero exit code. A [`SandboxExecutionError`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/exceptions/exceptions#sandboxexecutionerror) is raised if the command exits with a non-zero code. This example runs a script `might_fail.py` and checks the result. +The `check` parameter raises an exception when a command fails, so you don't need to inspect exit codes manually. Specify `check=True` (`Sandbox.exec(check=True)`) to raise a [`SandboxExecutionError`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/exceptions/exceptions#sandboxexecutionerror) if the command exits with a non-zero exit code. This example runs a script `might_fail.py` and checks the result. ```python from wandb.sandbox import Sandbox, SandboxExecutionError diff --git a/sandboxes/secrets.mdx b/sandboxes/secrets.mdx index 0b00327639..3cb23db031 100644 --- a/sandboxes/secrets.mdx +++ b/sandboxes/secrets.mdx @@ -9,9 +9,13 @@ Serverless Sandboxes is in public preview. Use the [W&B Secrets Manager](/platform/secrets) with the W&B Python SDK to access sensitive information such as API keys and tokens in a sandbox. -To use a secret in a sandbox, first add it to your team's Secrets Manager. Then reference that secret by name when you create the sandbox. Do not include the secret's value directly in your code or in the sandbox configuration. +To use a secret in a sandbox, first add it to your team's Secrets Manager. Then reference that secret by name when you create the sandbox. -W&B injects each requested secret into the sandbox as an environment variable. By default, the environment variable name matches the secret name. You can customize the environment variable name with the `env_var` parameter. + +Don't include the secret's value directly in your code or in the sandbox configuration. Reference secrets by name only. + + +W&B injects each requested secret into the sandbox as an environment variable. By default, the environment variable name matches the secret name. You can customize the environment variable name with the `env_var` parameter. @@ -106,4 +110,4 @@ print(f"Database password: {os.environ['DB_PASS'][:8]}...") print(result.stdout) ``` -In this example, the sandbox does not receive the full structured secret. It receives only the extracted password field as the value of `DB_PASS`. */} \ No newline at end of file +In this example, the sandbox doesn't receive the full structured secret. It receives only the extracted password field as the value of `DB_PASS`. */} \ No newline at end of file From 7a8427f34058cd5cdb11a5c1f4119a18956e1178 Mon Sep 17 00:00:00 2001 From: John Mulhausen Date: Wed, 27 May 2026 13:23:03 -0400 Subject: [PATCH 2/4] style: add frontmatter keywords to sandboxes pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Applies keyword guidance from docs-skills #21 (732f738) to all seven sandboxes content pages. Each page now has 3–5 search-optimized keywords prioritizing API method names, specific technology names, and action phrases not already present in the page title or description. Also bumps the .claude submodule pointer to the commit that introduced the keyword guidance. --- .claude | 2 +- sandboxes/create-sandbox.mdx | 1 + sandboxes/file-access.mdx | 1 + sandboxes/invoke-agent-sandbox-tutorial.mdx | 1 + sandboxes/lifecycle.mdx | 1 + sandboxes/mltrain-in-sandbox-tutorial.mdx | 1 + sandboxes/run-commands.mdx | 1 + sandboxes/secrets.mdx | 1 + 8 files changed, 8 insertions(+), 1 deletion(-) diff --git a/.claude b/.claude index 8167d20cbd..732f738152 160000 --- a/.claude +++ b/.claude @@ -1 +1 @@ -Subproject commit 8167d20cbd9b51685485fbbf45f73324ce18d588 +Subproject commit 732f738152c6bcac7aba596a9867f07ca1e57df2 diff --git a/sandboxes/create-sandbox.mdx b/sandboxes/create-sandbox.mdx index 8b3b508534..5762599af1 100644 --- a/sandboxes/create-sandbox.mdx +++ b/sandboxes/create-sandbox.mdx @@ -1,6 +1,7 @@ --- title: Create sandboxes description: Learn how to create Serverless Sandboxes. +keywords: ["Sandbox.run", "SandboxDefaults", "sandbox session", "container image"] --- diff --git a/sandboxes/file-access.mdx b/sandboxes/file-access.mdx index 842706ff7a..a5d2103822 100644 --- a/sandboxes/file-access.mdx +++ b/sandboxes/file-access.mdx @@ -1,6 +1,7 @@ --- title: File operations description: Learn how to read, write, and mount files in Serverless Sandboxes. +keywords: ["Sandbox.write_file", "Sandbox.read_file", "file mount", "upload to sandbox"] --- diff --git a/sandboxes/invoke-agent-sandbox-tutorial.mdx b/sandboxes/invoke-agent-sandbox-tutorial.mdx index 0f66e1e7b7..8e93cdfe77 100644 --- a/sandboxes/invoke-agent-sandbox-tutorial.mdx +++ b/sandboxes/invoke-agent-sandbox-tutorial.mdx @@ -1,6 +1,7 @@ --- title: "Tutorial: Invoke an agent in a sandbox" description: "Learn how to invoke an OpenAI agent within a Serverless Sandbox environment" +keywords: ["tool calls", "OPENAI_API_KEY", "AI agent execution", "function calling"] --- diff --git a/sandboxes/lifecycle.mdx b/sandboxes/lifecycle.mdx index 8d13532ad8..2192caaf41 100644 --- a/sandboxes/lifecycle.mdx +++ b/sandboxes/lifecycle.mdx @@ -1,6 +1,7 @@ --- title: Sandbox lifecycle description: Learn about the lifecycle of a Serverless Sandbox, including its states, how to wait for state changes, and how to stop a sandbox. +keywords: ["SandboxState", "wait_until_complete", "wait_until_ready", "sandbox timeout", "resource cleanup"] --- diff --git a/sandboxes/mltrain-in-sandbox-tutorial.mdx b/sandboxes/mltrain-in-sandbox-tutorial.mdx index 5385c9f065..31e7827ebe 100644 --- a/sandboxes/mltrain-in-sandbox-tutorial.mdx +++ b/sandboxes/mltrain-in-sandbox-tutorial.mdx @@ -1,6 +1,7 @@ --- title: "Tutorial: Train a PyTorch model" description: "Learn how to train a PyTorch model in a Serverless Sandbox environment with this step-by-step tutorial." +keywords: ["W&B experiment tracking", "UCI Zoo dataset", "neural network", "isolated ML training", "wandb logging"] --- diff --git a/sandboxes/run-commands.mdx b/sandboxes/run-commands.mdx index 6937fe0eaf..ff51db1b32 100644 --- a/sandboxes/run-commands.mdx +++ b/sandboxes/run-commands.mdx @@ -1,6 +1,7 @@ --- title: Run commands in a sandbox description: Learn how to run commands in a sandbox environment and read output and exit codes. +keywords: ["Sandbox.exec", "Process.result", "SandboxExecutionError", "stdout stderr"] --- diff --git a/sandboxes/secrets.mdx b/sandboxes/secrets.mdx index 3cb23db031..1444fbd11b 100644 --- a/sandboxes/secrets.mdx +++ b/sandboxes/secrets.mdx @@ -1,6 +1,7 @@ --- title: Secrets description: Learn how to manage secrets in Serverless Sandboxes. +keywords: ["W&B Secrets Manager", "API keys", "environment variables", "env_var", "secret injection"] --- From 1159ffaa8a67fad5828548a6da36d4a3c92300ad Mon Sep 17 00:00:00 2001 From: John Mulhausen Date: Fri, 29 May 2026 18:37:08 -0400 Subject: [PATCH 3/4] style: address ngrayluna review feedback on sandboxes Apply review suggestions from PR #2668: action-oriented page intros, keyword cleanups, tightened lifecycle and run-command copy, the corrected check-for-errors anchor, and reverts of style edits to markdown comments per reviewer guidance. --- sandboxes/create-sandbox.mdx | 4 ++-- sandboxes/file-access.mdx | 2 +- sandboxes/invoke-agent-sandbox-tutorial.mdx | 8 ++++---- sandboxes/lifecycle.mdx | 6 +++--- sandboxes/mltrain-in-sandbox-tutorial.mdx | 10 +++++++--- sandboxes/run-commands.mdx | 10 ++++++---- sandboxes/secrets.mdx | 4 ++-- 7 files changed, 25 insertions(+), 19 deletions(-) diff --git a/sandboxes/create-sandbox.mdx b/sandboxes/create-sandbox.mdx index 5762599af1..059352aeb4 100644 --- a/sandboxes/create-sandbox.mdx +++ b/sandboxes/create-sandbox.mdx @@ -1,14 +1,14 @@ --- title: Create sandboxes description: Learn how to create Serverless Sandboxes. -keywords: ["Sandbox.run", "SandboxDefaults", "sandbox session", "container image"] +keywords: ["Sandbox.run", "SandboxDefaults", "Session"] --- Serverless Sandboxes is in public preview. -This page shows you how to create Serverless Sandboxes with W&B. You learn how to start a single sandbox, run a main command inside it, and manage multiple sandboxes with a session. Each sandbox runs in its own container with its own [filesystem](/sandboxes/file-access), network, and process space, which gives you an isolated environment to run code. +Create W&B Serverless Sandboxes to run code in isolated environments. Start a single sandbox, run commands in it, and manage multiple sandboxes with a session. Each sandbox runs in its own container, with its own [file system](/sandboxes/file-access), network, and process space. By default, sandboxes use `python:3.11` as the base image. To use a different image, pass `container_image` to [`Sandbox.run()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#run) or [`SandboxDefaults`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox-defaults). W&B supports public container images only. diff --git a/sandboxes/file-access.mdx b/sandboxes/file-access.mdx index a5d2103822..bf4545fe22 100644 --- a/sandboxes/file-access.mdx +++ b/sandboxes/file-access.mdx @@ -45,7 +45,7 @@ See the `Sandbox` class reference documentation for a full list of parameters an ## Read a file from the sandbox -Read a file from the sandbox when you want to save its output or generated artifacts back to your local environment. Save a file from the sandbox to your local environment using the [`Sandbox.read_file()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#read_file) method. +Save a file from the sandbox to your local environment using the [`Sandbox.read_file()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#read_file) method. ```python from pathlib import Path diff --git a/sandboxes/invoke-agent-sandbox-tutorial.mdx b/sandboxes/invoke-agent-sandbox-tutorial.mdx index 8e93cdfe77..83d99280b0 100644 --- a/sandboxes/invoke-agent-sandbox-tutorial.mdx +++ b/sandboxes/invoke-agent-sandbox-tutorial.mdx @@ -1,20 +1,20 @@ --- title: "Tutorial: Invoke an agent in a sandbox" description: "Learn how to invoke an OpenAI agent within a Serverless Sandbox environment" -keywords: ["tool calls", "OPENAI_API_KEY", "AI agent execution", "function calling"] +keywords: ["tutorial", "invoke agent in sandbox"] --- Serverless Sandboxes is in public preview. -In this tutorial, you invoke an agent within a Serverless Sandbox environment. To do this, you start a sandbox with the appropriate environment variables, install the necessary dependencies, and run a Python script. The script creates and invokes an OpenAI agent that uses tool calls to get the weather for a location and respond with a punny weather forecast. This lets you test and iterate on agent behavior in a safe, isolated environment without affecting your local setup. +In this tutorial, you invoke an agent in a W&B Serverless Sandbox. You start a sandbox with the required environment variables, install dependencies, and run a Python script that creates and invokes a simple OpenAI agent. The agent uses tool calls to get weather for a location and return a punny forecast. This tutorial uses OpenAI as the language model for the agent, which requires an OpenAI API key. -{/* This lets you test and iterate on your agent's behavior in a safe and isolated environment, without affecting your local setup. */} +{/* This allows you to test and iterate on your agent's behavior in a safe and isolated environment, without affecting your local setup. */} ## Prerequisites @@ -57,7 +57,7 @@ With your prerequisites in place, save the agent code locally so you can run it -Copy and paste the following code into a file named `demo.py` in the same directory as this tutorial. The script defines an OpenAI agent that uses tool calls to fetch weather data and respond with a punny forecast. +Copy the following code into a file named `demo.py` in the same directory as this tutorial. Then, run the previous code snippet to invoke an OpenAI agent in a sandbox. ```python title="demo.py" import json diff --git a/sandboxes/lifecycle.mdx b/sandboxes/lifecycle.mdx index 2192caaf41..1b212a68df 100644 --- a/sandboxes/lifecycle.mdx +++ b/sandboxes/lifecycle.mdx @@ -10,7 +10,7 @@ Serverless Sandboxes is in public preview. This page describes the lifecycle of a Serverless Sandbox so that you can choose the right method for waiting on state changes, stopping a sandbox, and structuring code around its lifetime. Understanding the lifecycle helps you avoid race conditions, distinguish startup failures from runtime errors, and clean up resources predictably. -A Serverless Sandbox goes through several states during its lifecycle. The sandbox's state determines which operations are available. +A W&B Serverless Sandbox goes through several states during its lifecycle. The sandbox state determines which operations are available. Usually, a sandbox starts in `PENDING`, moves to `CREATING` while the container is provisioned, and then enters `RUNNING` when it's ready for use. @@ -50,7 +50,7 @@ The following sections describe the two methods for waiting on sandbox state cha ### Wait for a sandbox to start -Use `Sandbox.wait()` to wait for the sandbox to reach the `RUNNING` state. This method is useful for debugging startup problems or when you want to distinguish startup failures from errors in later commands. +Use `Sandbox.wait()` to explicitly wait for the sandbox to reach the `RUNNING` state. This method is useful for debugging startup problems or when you want to distinguish startup failures from errors in later commands. For example, the following code creates a sandbox, waits for it to become ready, and then runs a command: @@ -93,7 +93,7 @@ with Sandbox.run() as sandbox: ## Explicit lifecycle control -Use methods such as `Sandbox.wait()` and `Sandbox.stop()` when you need explicit control over the sandbox lifecycle instead of relying on automatic behavior. +Use methods such as `Sandbox.wait()` and `Sandbox.stop()` when you need explicit control over the sandbox lifecycle. Usually, you don't need to call these methods directly. Operations such as `Sandbox.exec()`, `Sandbox.read_file()`, and `Sandbox.write_file()` wait for readiness, and the context manager (`with Sandbox.run() as sandbox:`) stops the sandbox when the block exits. diff --git a/sandboxes/mltrain-in-sandbox-tutorial.mdx b/sandboxes/mltrain-in-sandbox-tutorial.mdx index 31e7827ebe..f49d04a700 100644 --- a/sandboxes/mltrain-in-sandbox-tutorial.mdx +++ b/sandboxes/mltrain-in-sandbox-tutorial.mdx @@ -35,7 +35,7 @@ pip install wandb ### Log in and authenticate with W&B -The Serverless Sandbox runs under your W&B account, so you must be authenticated before you can create one. If you haven't done so already, log in to W&B. Use the `wandb login` CLI command and follow the prompts to log in to your W&B account: +W&B Serverless Sandboxes run under your W&B account, so you must authenticate before you create one. Use the `wandb login` CLI command and follow the prompts to log in: ```bash wandb login @@ -45,7 +45,9 @@ See the [`wandb login`](/models/ref/cli/wandb-login) reference documentation for ## Copy the training script and dependencies -In this step, you prepare the three files that the sandbox needs: a requirements file, a hyperparameters file, and the training script itself. Expand the following dropdown to access the code required for this tutorial. Copy and paste the code into three separate files in the same directory as this tutorial. In the next section, you run a script that reads in these files and trains a PyTorch model within a Serverless Sandbox environment. +Prepare the three files required for this tutorial: a requirements file, a hyperparameters file, and a training script. Expand the following dropdown, then copy each code sample into a separate file in the same directory as this tutorial. + +In the next section, you run a script that reads these files and trains a PyTorch model in a W&B Serverless Sandbox. @@ -183,7 +185,9 @@ if __name__ == "__main__": ## Create the sandbox and run the training script -With your training files in place, you can now drive the sandbox from a single Python script. The following code snippet shows how to create a sandbox and copy the training script and dependencies into it. It then runs the training script and downloads the generated model file. The next section explains the code line by line. +With your training files in place, create and manage a W&B Serverless Sandbox from a single Python script. The following code snippet creates a sandbox, copies the training script and dependencies into it, runs the training script, and downloads the generated model file. + +The next section explains the code line by line. Copy and paste the following code into a Python file and run it. Save it in the same directory as the `train.py`, `requirements.txt`, and `hyperparameters.yaml` files you created in the previous step. diff --git a/sandboxes/run-commands.mdx b/sandboxes/run-commands.mdx index ff51db1b32..954c245291 100644 --- a/sandboxes/run-commands.mdx +++ b/sandboxes/run-commands.mdx @@ -1,7 +1,7 @@ --- title: Run commands in a sandbox description: Learn how to run commands in a sandbox environment and read output and exit codes. -keywords: ["Sandbox.exec", "Process.result", "SandboxExecutionError", "stdout stderr"] +keywords: ["Sandbox.run", "Sandbox.exec", "Process.result", "SandboxExecutionError", "stdout", "stderr"] --- @@ -10,7 +10,7 @@ Serverless Sandboxes is in public preview.

-This page shows you how to [run commands in a sandbox](#run-commands-in-a-sandbox), [read their output and exit code](#read-output-and-exit-codes), and [check for errors](#check-for-errors). Use these features to run scripts, training jobs, and other processes in a sandbox and programmatically check the results. +[Run commands in a sandbox](#run-commands-in-a-sandbox), [read command output and exit codes](#read-output-and-exit-codes), and [check for errors](#check-for-sandbox-execution-errors). Use these features to run scripts, training jobs, and other processes in a W&B Serverless Sandbox and programmatically check the results. ## Run commands in a sandbox @@ -74,7 +74,9 @@ with Sandbox.run("sleep", "infinity") as sandbox: ## Read output and exit codes -After a command runs, you often need to read its output and check whether it succeeded. `Sandbox.exec()` returns a [`Process`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/types/process) object. Call `Process.result()` to wait for the command to finish and get its result. `Process.result()` includes the standard output (`stdout`), standard error (`stderr`), and exit code (`returncode`). +After you run a command, you can read its output and check whether it succeeded. `Sandbox.exec()` returns a [`Process`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/types/process) object. To wait for the command to finish, call `Process.result()`. + +The result includes standard output (`stdout`), standard error (`stderr`), and the exit code (`returncode`). Use the exit code to determine whether the command succeeded. By convention, an exit code of 0 indicates success. The possible exit codes and their meanings depend on the command. @@ -91,7 +93,7 @@ with Sandbox.run() as sandbox: ## Check for sandbox execution errors -The `check` parameter raises an exception when a command fails, so you don't need to inspect exit codes manually. Specify `check=True` (`Sandbox.exec(check=True)`) to raise a [`SandboxExecutionError`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/exceptions/exceptions#sandboxexecutionerror) if the command exits with a non-zero exit code. This example runs a script `might_fail.py` and checks the result. +Use `check=True` to raise an exception when a command fails instead of inspecting exit codes manually. If the command exits with a non-zero exit code, `Sandbox.exec(check=True)` raises a [SandboxExecutionError](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/exceptions/exceptions#sandboxexecutionerror). ```python from wandb.sandbox import Sandbox, SandboxExecutionError diff --git a/sandboxes/secrets.mdx b/sandboxes/secrets.mdx index 1444fbd11b..cf16ee3bef 100644 --- a/sandboxes/secrets.mdx +++ b/sandboxes/secrets.mdx @@ -1,7 +1,7 @@ --- title: Secrets description: Learn how to manage secrets in Serverless Sandboxes. -keywords: ["W&B Secrets Manager", "API keys", "environment variables", "env_var", "secret injection"] +keywords: ["sandbox secrets", "W&B Secrets Manager"] --- @@ -111,4 +111,4 @@ print(f"Database password: {os.environ['DB_PASS'][:8]}...") print(result.stdout) ``` -In this example, the sandbox doesn't receive the full structured secret. It receives only the extracted password field as the value of `DB_PASS`. */} \ No newline at end of file +In this example, the sandbox does not receive the full structured secret. It receives only the extracted password field as the value of `DB_PASS`. */} \ No newline at end of file From 3945e5e158936e2fbbef2d219d436e049a55b31b Mon Sep 17 00:00:00 2001 From: John Mulhausen Date: Fri, 29 May 2026 18:37:26 -0400 Subject: [PATCH 4/4] chore: drop accidental .claude submodule bump from style PR Reset the .claude submodule pointer to the merge-base commit so this style-only PR no longer modifies the submodule, keeping GitHub history clean per review feedback. --- .claude | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude b/.claude index 732f738152..8167d20cbd 160000 --- a/.claude +++ b/.claude @@ -1 +1 @@ -Subproject commit 732f738152c6bcac7aba596a9867f07ca1e57df2 +Subproject commit 8167d20cbd9b51685485fbbf45f73324ce18d588