Skip to content

Commit 734eb6e

Browse files
ngraylunajohndmulhausenjamie-rasmussen
authored
W&B Sandboxes (#2426)
## Description W&B Sandboxes (Private Preview). Currently documents: - Overview (what it is, high-level how it works) - Sandbox lifecycle - Create sandboxes - Run commands - File access (read/write/mount) - Secrets - Tutorial: Train PyTorch model in a sandbox - Tutorial: Invoke an agent within a sandbox Things to add? - Compute resourcing info - Authenticating gotchas? (If they exist) --------- Co-authored-by: John Mulhausen <john.mulhausen@wandb.com> Co-authored-by: johndmulhausen <5439615+johndmulhausen@users.noreply.github.com> Co-authored-by: Jamie Rasmussen <112953339+jamie-rasmussen@users.noreply.github.com>
1 parent 4f2a5cd commit 734eb6e

10 files changed

Lines changed: 1095 additions & 4 deletions

‎docs.json‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1157,6 +1157,19 @@
11571157
}
11581158
]
11591159
},
1160+
{
1161+
"tab": "W&B Sandboxes",
1162+
"pages": [
1163+
"sandboxes",
1164+
"sandboxes/lifecycle",
1165+
"sandboxes/create-sandbox",
1166+
"sandboxes/run-commands",
1167+
"sandboxes/file-access",
1168+
"sandboxes/secrets",
1169+
"sandboxes/mltrain-in-sandbox-tutorial",
1170+
"sandboxes/invoke-agent-sandbox-tutorial"
1171+
]
1172+
},
11601173
{
11611174
"tab": "Support",
11621175
"pages": [
@@ -5005,4 +5018,4 @@
50055018
}
50065019
},
50075020
"baseUrl": "https://docs.wandb.ai"
5008-
}
5021+
}

‎sandboxes.mdx‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: W&B Sandboxes
3+
mode: wide
4+
---
5+
6+
<Warning>
7+
W&B Sandboxes is in private preview, available by invitation only. To request enrollment, contact [support](mailto:support@wandb.com) or your AISE.
8+
</Warning>
9+
10+
W&B Sandboxes gives you on-demand, isolated compute environments that you can create, use, and discard using Python.
11+
12+
W&B 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).
13+
14+
## How it works
15+
16+
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.
17+
18+
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.
19+
20+
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.
21+
22+
[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.
23+
24+
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.
25+
26+
## Basic usage
27+
28+
Follow these steps to create a sandbox and run a command inside it:
29+
30+
1. Install the W&B Python SDK (`wandb`) from the source provided by your support team or AISE contact.
31+
32+
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:
33+
34+
```bash
35+
wandb login
36+
```
37+
38+
3. Copy and paste the following code snippet into a Python file and run it. The code snippet accomplishes the following:
39+
40+
1. Create a sandbox with [`Sandbox.run()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#run).
41+
2. Run the command `echo "Hello from W&B Sandboxes!"` inside the sandbox using the [`Sandbox.exec()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#exec) method.
42+
3. Print the output to the console using the `Process` object returned by `Sandbox.exec()`.
43+
44+
```python show lines title="hello_sandbox.py"
45+
from wandb.sandbox import Sandbox
46+
47+
with Sandbox.run() as sandbox:
48+
process = sandbox.exec(["echo", "Hello from W&B Sandboxes!"]).result()
49+
print(process.stdout)
50+
```
51+
52+
You should see the output `Hello from W&B Sandboxes!` printed to the console.
53+
54+
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).
55+
56+
57+
## W&B Sandboxes tutorials
58+
59+
For more in-depth examples, see:
60+
61+
* [Invoke an agent in a W&B Sandbox tutorial](/sandboxes/invoke-agent-sandbox-tutorial)
62+
* [Train a PyTorch model in a W&B Sandbox tutorial](/sandboxes/mltrain-in-sandbox-tutorial)

‎sandboxes/create-sandbox.mdx‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: Create sandboxes
3+
description: Learn how to create W&B Sandboxes.
4+
---
5+
6+
<Warning>
7+
W&B Sandboxes is in private preview, available by invitation only. To request enrollment, contact [support](mailto:support@wandb.com) or your AISE.
8+
</Warning>
9+
10+
Create sandboxes with W&B. Each sandbox runs in its own container with its own [filesystem](/sandboxes/file-access), network, and process space.
11+
12+
<Info>
13+
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.
14+
15+
The following code snippet creates a sandbox with the `python:3.15` image and runs `python --version` inside it.
16+
17+
```python
18+
from wandb.sandbox import Sandbox
19+
20+
with Sandbox.run(container_image="python:3.15") as sandbox:
21+
sandbox.exec(["python", "--version"]).result()
22+
```
23+
</Info>
24+
25+
## Create a sandbox
26+
27+
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.
28+
29+
<Tip>
30+
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.
31+
</Tip>
32+
33+
The following example creates a sandbox with the default container image (`python:3.11`):
34+
35+
```python
36+
from wandb.sandbox import Sandbox
37+
38+
with Sandbox.run() as sandbox:
39+
print(sandbox)
40+
```
41+
42+
To learn how to run commands inside a sandbox, see [Run commands](/sandboxes/run-commands). To learn about sandbox lifecycle and states, see [Sandbox lifecycle](/sandboxes/lifecycle).
43+
44+
### Start a sandbox without a main command
45+
46+
Call `Sandbox.run()` without a command when you want to create a sandbox first and run work inside it later.
47+
48+
```python
49+
from wandb.sandbox import Sandbox
50+
51+
with Sandbox.run() as sandbox:
52+
print(sandbox)
53+
```
54+
55+
This pattern is useful for interactive and multi-step workflows. To learn how to run commands inside a sandbox, see [Run commands](/sandboxes/run-commands).
56+
57+
### Start a sandbox with a main command
58+
59+
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).
60+
61+
The command you provide to `Sandbox.run()` starts as the sandbox's main process.
62+
63+
```python
64+
from wandb.sandbox import Sandbox
65+
66+
sandbox = Sandbox.run("python", "train.py")
67+
```
68+
69+
`Sandbox.run()` returns a `Sandbox` object that you can use to monitor the command and wait for it to finish. For example, to wait for the command to complete and retrieve its result:
70+
71+
```python
72+
from wandb.sandbox import Sandbox
73+
74+
sandbox = Sandbox.run("python", "train.py")
75+
76+
# Optionally wait for the command to complete
77+
sandbox.wait_until_complete().result()
78+
```
79+
80+
81+
## Create multiple sandboxes with a session
82+
83+
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.
84+
85+
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.
86+
87+
`session.sandbox()` returns an unstarted sandbox. It auto-starts when you call `Sandbox.exec()`, `Sandbox.read_file()`, or any other operation.
88+
89+
The following code snippet creates a session that creates two sandboxes that use a default configuration (`SandboxDefaults`):
90+
91+
```python
92+
from wandb.sandbox import Session, SandboxDefaults
93+
94+
defaults = SandboxDefaults(
95+
container_image="python:3.11",
96+
max_lifetime_seconds=300,
97+
tags=("batch-job",),
98+
)
99+
100+
with Session(defaults) as session:
101+
sandbox1 = session.sandbox()
102+
sandbox2 = session.sandbox()
103+
104+
print(sandbox1)
105+
print(sandbox2)
106+
```

‎sandboxes/file-access.mdx‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: File operations
3+
description: Learn how to read, write, and mount files in W&B Sandboxes.
4+
---
5+
6+
<Warning>
7+
W&B Sandboxes is in private preview, available by invitation only. To request enrollment, contact [support](mailto:support@wandb.com) or your AISE.
8+
</Warning>
9+
10+
Use file operations to share data between your local environment and a sandbox. You can read files from a sandbox, write files to it, or mount local files and directories into it.
11+
12+
For example, you can write a Python script to a sandbox, run it, and read the output file back to your local environment. You can also mount a directory of training data into a sandbox for a machine learning job.
13+
14+
<Tip>
15+
**Choose the right file access method**
16+
17+
Mount files or directories when you want the sandbox to access local data without copying it.
18+
19+
Read and write files when you want to transfer smaller files between your local environment and the sandbox, or when you want to save sandbox output locally.
20+
</Tip>
21+
22+
## Write a file to the sandbox
23+
24+
25+
{/* creating, updating, modifying, or saving data */}
26+
{/* transfers a file into the sandbox. Use it to upload inputs your sandbox code needs (scripts, configs, data files). */}
27+
28+
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.
29+
30+
31+
```python
32+
from pathlib import Path
33+
from wandb.sandbox import Sandbox
34+
35+
# Path of the local file you want to write to the sandbox
36+
text_file = Path("hello.txt")
37+
38+
with Sandbox.run() as sandbox:
39+
# Write a file to the sandbox
40+
sandbox.write_file("hello.txt", text_file.read_bytes()).result()
41+
```
42+
43+
See the `Sandbox` class reference documentation for a full list of parameters and options for [`Sandbox.write_file()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#write_file).
44+
45+
## Read a file from the sandbox
46+
47+
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.
48+
49+
```python
50+
from pathlib import Path
51+
from wandb.sandbox import Sandbox
52+
53+
with Sandbox.run() as sandbox:
54+
# Demo creates a file in the sandbox to read back
55+
sandbox.exec(["sh", "-c", "echo 'Hello, world.' > hello.txt"]).result()
56+
57+
# Save the file on local machine (not sandbox)
58+
content = sandbox.read_file("hello.txt").result() # b"Hello, world.\n"
59+
Path("hello.txt").write_bytes(content)
60+
```
61+
62+
See the `Sandbox` class reference documentation for a full list of parameters and options for [`Sandbox.read_file()`](https://docs.coreweave.com/products/coreweave-sandbox/client/ref/core/sandbox#read_file).
63+
64+
65+
## Mount a file or directory
66+
67+
Use mounted files to provide local files to the sandbox at creation time. Unlike `Sandbox.write_file()`, which transfers files to a running sandbox, mounted files are available as soon as the sandbox starts. Mounted files appear in the sandbox at the path you specify.
68+
69+
<Info>
70+
Mounted files are read-only in the sandbox. If you need to modify files in the sandbox, use `Sandbox.write_file()` instead.
71+
</Info>
72+
73+
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`.
74+
75+
```python
76+
from pathlib import Path
77+
from wandb.sandbox import Sandbox, NetworkOptions
78+
79+
mounted_files = [
80+
{"mount_path": "requirements.txt", "file_content": Path("requirements.txt").read_bytes()},
81+
{"mount_path": "train.py", "file_content": Path("train.py").read_bytes()},
82+
]
83+
84+
print("Starting sandbox...")
85+
with Sandbox.run(mounted_files=mounted_files) as sandbox:
86+
87+
# The mounted files are available in the sandbox at the specified mount paths
88+
print("Installing dependencies...")
89+
result = sandbox.exec(["pip", "install", "-r", "requirements.txt"], check=True).result()
90+
print(result.stdout)
91+
92+
print("Running script...")
93+
result = sandbox.exec(["python", "train.py"]).result()
94+
print(result.stdout)
95+
```

0 commit comments

Comments
 (0)