W&B Sandboxes

[ngrayluna]

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)

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
wandb	🟢 Ready	View Preview	Apr 7, 2026, 2:19 AM

[github-actions]

📚 Mintlify Preview Links

🔗 View Full Preview

✨ Added (8 total)

📄 Pages (8)

File	Preview
sandboxes.mdx	Sandboxes
sandboxes/create-sandbox.mdx	Create Sandbox
sandboxes/file-access.mdx	File Access
sandboxes/invoke-agent-sandbox-tutorial.mdx	Invoke Agent Sandbox Tutorial
sandboxes/lifecycle.mdx	Lifecycle
sandboxes/mltrain-in-sandbox-tutorial.mdx	Mltrain In Sandbox Tutorial
sandboxes/run-commands.mdx	Run Commands
sandboxes/secrets.mdx	Secrets

📝 Changed (2 total)

📄 Pages (1)

File	Preview
support/models/articles/how-can-i-recover-deleted-runs.mdx	How Can I Recover Deleted Runs

⚙️ Other (1)

File
docs.json

---

🤖 Generated automatically when Mintlify deployment succeeds
📍 Deployment: 138636a at 2026-04-16 17:23:00 UTC

[github-actions]

🔗 Link Checker Results

✅ All links are valid!

No broken links were detected.

Checked against: https://wb-21fd5541-sandboxes.mintlify.app

[trane293]

Review

Overall the docs are well-structured and cover the right topics. The API patterns are mostly accurate against the SDK. Flagging the following issues before merge.

---

Must Fix

1. wait_until_complete() missing .result() call
Files: sandboxes/lifecycle.mdx (line 63), sandboxes/run-commands.mdx (line 23)

Both show:

sandbox.wait_until_complete(timeout=3600.0)
print(f"Exit code: {sandbox.returncode}")

wait_until_complete() returns an OperationRef[Sandbox], not Sandbox. Without .result(), the call doesn't block and sandbox.returncode will be None. The SDK's own docstring shows the correct pattern:

sandbox.wait_until_complete(timeout=3600.0).result()
print(f"Exit code: {sandbox.returncode}")

---

2. Credential propagation claim is inaccurate
File: sandboxes.mdx (line 12)

"your W&B credentials work automatically, and sandbox sessions can report metrics to an active W&B run"

This is not true today. W&B credentials authenticate you to the sandbox service (creating/managing sandboxes via ATC), but they are not propagated inside the sandbox container. Code running inside the sandbox has no access to your W&B API key, so wandb.init(), wandb.log(), and Weave calls won't work without explicitly passing WANDB_API_KEY via environment_variables or the Secrets API.

Suggested rewrite: "Sandboxes authenticate using your existing W&B credentials. To use W&B or Weave inside a sandbox, pass your API key using the Secrets Manager or environment variables."

---

3. echo > file doesn't work without a shell
File: sandboxes/file-access.mdx (line 53)

sandbox.exec(["echo", "Hello, world.", ">", "hello.txt"]).result()

When args are passed as a list, exec() doesn't invoke a shell. The > is passed as a literal argument to echo, so no file is created and the subsequent read_file("hello.txt") would fail. Should be:

sandbox.exec(["sh", "-c", "echo 'Hello, world.' > hello.txt"]).result()

Also, Path is used on line 57 (Path("hello.txt").write_bytes(content)) but is never imported in this example.

---

4. LangChain agent tutorial should be replaced
File: sandboxes/invoke_agent_sandbox_tutorial.mdx

LangChain is a direct competitor. We should not be featuring their library in our docs. Beyond the competitive concern, the code has technical issues:

• ToolRuntime[Context] (line 94): ToolRuntime is a dataclass, not a generic type
• No version pins: create_agent was removed in LangChain v1.1.0, so pip install langchain langgraph langchain_anthropic without version constraints will break
• @dataclass used for ResponseFormat where ToolStrategy typically expects a Pydantic BaseModel
• Passes Anthropic API key via environment_variables instead of using the Secrets API, which contradicts the guidance on the secrets page

Recommend replacing with a framework-agnostic example, or using Weave.

---

5. from cwsandbox import SandboxExecutionError is a direct import from the underlying library
File: sandboxes/run-commands.mdx (line 88)

This is the only place in the docs that imports from cwsandbox directly. Every other import goes through wandb.sandbox. The issue is that wandb.sandbox doesn't re-export any exception classes from cwsandbox today (there are 12 missing). Working with Pinglei to get this fixed on the SDK side. Once that lands, this import should become from wandb.sandbox import SandboxExecutionError.

---

Should Fix

6. Typos

• sandboxes/run-commands.mdx (line 52): "explictly" -> "explicitly", "runnig" -> "running"
• sandboxes/mltrain_in_sandbox_tutorial.mdx (line 34) and sandboxes/invoke_agent_sandbox_tutorial.mdx (line 46): "documenation" -> "documentation"

7. .mdx extension in links
File: sandboxes/lifecycle.mdx (line 20)

Links use /sandboxes/create-sandbox.mdx and /sandboxes/run-commands.mdx but every other page drops the .mdx extension. Should be /sandboxes/create-sandbox and /sandboxes/run-commands.

8. Line number references off by 2
File: sandboxes/mltrain_in_sandbox_tutorial.mdx (lines 223-224)

"Lines 29-31" should be "Lines 27-29" (the three print statements). "Lines 35-36" should be "Lines 33-34" (read_file and write_bytes).

9. docs.json formatting
The new entry uses "pages" : (space before colon) while the rest of the file uses "pages":.

[trane293]

Review (Round 3)

Cross-referenced all code snippets against the SDK source (cwsandboxes-client v0.16.0 and wandb/sandbox on pinglei/sandbox-auth-v3). Ran offline verification for import paths, return types, and enum values.

Must Fix

1. print(result) prints object repr, not script output
File: invoke-agent-sandbox-tutorial.mdx

result = sandbox.exec(["python", "demo.py"], check=True).result()
print("Script output:")
print(result)  # prints ProcessResult(stdout='...', stderr='...', returncode=0, stdout_bytes=b'...', ...)

exec().result() returns a ProcessResult dataclass with no custom __str__. This dumps the full repr with all fields including raw bytes. Change to print(result.stdout).

2. result.stdout / result.stderr after wait_until_complete will crash
File: run-commands.mdx

If any code still shows:

result = sandbox.wait_until_complete(timeout=3600.0).result()
print(f"Standard output: {result.stdout}")

This raises AttributeError. wait_until_complete().result() returns a Sandbox object, which has .returncode and .status but not .stdout or .stderr. Remove the .stdout/.stderr lines and use sandbox.returncode only. If you want to show stdout/stderr, use an exec() example instead:

sandbox.wait_until_complete(timeout=3600.0).result()
print(f"Exit code: {sandbox.returncode}")

3. Auth language still slightly misleading
File: sandboxes.mdx

"Sandboxes authenticate using your existing W&B credentials."

This conflates authenticating to the sandbox service (which does use your W&B credentials) with using W&B inside the sandbox (which does not work automatically). Credentials are not propagated into the container. Reword to: "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 Secrets Manager or environment_variables."

Should Fix

4. result variable naming is misleading across multiple pages
Files: run-commands.mdx, create-sandbox.mdx, lifecycle.mdx

result = sandbox.wait_until_complete(...).result()

This assigns a Sandbox object to a variable called result. Readers will expect a ProcessResult. Drop the assignment and call .result() inline, then use sandbox.returncode:

sandbox.wait_until_complete(timeout=3600.0).result()
print(f"Exit code: {sandbox.returncode}")

5. Context manager + wait_until_complete is a confusing pattern
File: lifecycle.mdx

with Sandbox.run("python", "train.py") as sandbox:
    sandbox.wait_until_complete(timeout=3600.0).result()

The context manager calls stop() on exit, but the sandbox is already in a terminal state after wait_until_complete. Two things managing the lifecycle at once. The SDK's own docstring examples don't combine these. Split into two separate examples:

Interactive sandbox (context manager):

with Sandbox.run() as sandbox:
    result = sandbox.exec(["python", "train.py"]).result()
    print(result.stdout)
# sandbox automatically stopped on exit

Fire-and-forget with main command (no context manager):

sandbox = Sandbox.run("python", "train.py")
sandbox.wait_until_complete(timeout=3600.0).result()
print(f"Exit code: {sandbox.returncode}")

6. Missing PAUSED state from lifecycle page
File: lifecycle.mdx

The SDK defines SandboxStatus.PAUSED and includes it in _RUNNING_STATUSES. The state diagram and table omit it. Either add a row to the table or add a note that PAUSED is not expected in the W&B hosted environment.

7. sleep infinity pattern doesn't mention default behavior
File: run-commands.mdx

The "Keep the sandbox running" section shows Sandbox.run("sleep", "infinity") without mentioning that Sandbox.run() with no args already uses tail -f /dev/null as a keep-alive. Add: "Note: Sandbox.run() with no arguments keeps the sandbox alive by default."

8. session.sandbox() returns unstarted sandbox, not explained
File: create-sandbox.mdx

The Session example calls session.sandbox() and prints the result. No mention that this returns an unstarted sandbox that auto-starts on first operation. Add: "session.sandbox() returns an unstarted sandbox. It auto-starts when you call exec(), read_file(), or any other operation."

Low Severity

9. Missing description in frontmatter - sandboxes.mdx and mltrain-in-sandbox-tutorial.mdx lack the description field that other landing pages include.

10. Stray id attribute - secrets.mdx line 28 has ```python id="11o5yi" which no other code block uses. Remove the id.

11. Broken anchor in secrets.mdx - [structured secrets](#extract-a-field-from-a-structured-secret) links to a section that's commented out. Either remove the link or uncomment the section.

12. File naming inconsistency - Tutorial files use underscores (invoke_agent_sandbox_tutorial.mdx) while other pages use hyphens. Rest of the docs repo uses hyphens consistently. Rename to match (and update docs.json).

[mdlinville]

This might be better promoted to an H3 and titled something like "Keep a sandbox running for a period of time". or even "indefinitely". The example is indefinite but also makes it pretty obvious that you could sleep for a given period instead.

[mdlinville]

Pre-approving after taking a first pass through all of the pages in this PR. Let me know if you'd like a second look at anything before you merge.