style: apply /style-guide pass to sandboxes#2668
Open
johndmulhausen wants to merge 4 commits into
Open
Conversation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Contributor
📚 Mintlify Preview Links📝 Changed (7 total)📄 Pages (7)
🤖 Generated automatically when Mintlify deployment succeeds |
Contributor
🔗 Link Checker Results✅ All links are valid! No broken links were detected. Checked against: https://wb-21fd5541-style-guide-sandboxes-20260526-215517.mintlify.app |
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.
Contributor
|
@johndmulhausen QQ: Did you want to commit the .claude changes in a different branch? (For a cleaner GitHub history?) |
ngrayluna
requested changes
May 29, 2026
| --- | ||
| title: Create sandboxes | ||
| description: Learn how to create Serverless Sandboxes. | ||
| keywords: ["Sandbox.run", "SandboxDefaults", "sandbox session", "container image"] |
Contributor
There was a problem hiding this comment.
Suggested change
| keywords: ["Sandbox.run", "SandboxDefaults", "sandbox session", "container image"] | |
| keywords: ["Sandbox.run", "SandboxDefaults", "Session"] |
| </Warning> | ||
|
|
||
| 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. |
Contributor
There was a problem hiding this comment.
Style questions
A) I was taught to avoid using "This page shows you..."
B) Also was taught to use action-oriented phrasing.
Suggested change
| 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](https://chatgpt.com/sandboxes/file-access)](/sandboxes/file-access), network, and process space. |
Contributor
Author
There was a problem hiding this comment.
Applied in 1159ffa. Kept your action-oriented phrasing; I also fixed the file-access link, which had a stray chatgpt.com URL from the paste.
| ## 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. |
Contributor
There was a problem hiding this comment.
Left original copy intentionally vague since there are other reasons why you might want to read, write a file to/from a sandbox.
Suggested change
| 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. |
Contributor
Author
There was a problem hiding this comment.
Reverted to the original (intentionally vague) copy in 1159ffa.
| 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" | ||
| keywords: ["tool calls", "OPENAI_API_KEY", "AI agent execution", "function calling"] |
Contributor
There was a problem hiding this comment.
These keywords are not specific to the product, page. Removing them. Not sold on what I propose, but it's closer to the right direction.
Suggested change
| keywords: ["tool calls", "OPENAI_API_KEY", "AI agent execution", "function calling"] | |
| keywords: ["tutorial", "invoke agent in sandbox"] |
| </Warning> | ||
|
|
||
| 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. |
Contributor
There was a problem hiding this comment.
Suggested change
| 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. |
| <br></br> | ||
|
|
||
| [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. |
Contributor
There was a problem hiding this comment.
Suggested change
| 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-errors). Use these features to run scripts, training jobs, and other processes in a W&B Serverless Sandbox and programmatically check the results. |
Removes "This page shows you how to..."
Contributor
Author
There was a problem hiding this comment.
Applied in 1159ffa. I also repointed the check-for-errors link to the real heading anchor (#check-for-sandbox-execution-errors) so it is not broken.
| ``` | ||
|
|
||
| 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 |
Contributor
There was a problem hiding this comment.
Ignore markdown comments, they may or may not be used => waste tokens.
Contributor
Author
There was a problem hiding this comment.
Reverted the comment to its original wording in 1159ffa.
| --- | ||
| title: Secrets | ||
| description: Learn how to manage secrets in Serverless Sandboxes. | ||
| keywords: ["W&B Secrets Manager", "API keys", "environment variables", "env_var", "secret injection"] |
Contributor
There was a problem hiding this comment.
Suggested change
| keywords: ["W&B Secrets Manager", "API keys", "environment variables", "env_var", "secret injection"] | |
| keywords: ["sandbox secrets", "W&B Secrets Manager"] |
| ## 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. |
Contributor
There was a problem hiding this comment.
Suggested change
| 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). |
| ## 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`). |
Contributor
There was a problem hiding this comment.
Suggested change
| 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`). |
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.
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.
Contributor
Author
|
Thanks for the thorough review, @ngrayluna. I went through every comment and addressed all of them. Two commits:
Suggestions applied verbatim
Where I used judgment instead of applying verbatim
Re: the
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR applies the
/style-guideskill (Google Developer Style Guide + CoreWeave conventions) to thesandboxessection. The run was automated; only style-level edits were made, with no changes to technical meaning intended.Files edited
sandboxes/create-sandbox.mdxsandboxes/file-access.mdxsandboxes/invoke-agent-sandbox-tutorial.mdxsandboxes/lifecycle.mdxsandboxes/mltrain-in-sandbox-tutorial.mdxsandboxes/run-commands.mdxsandboxes/secrets.mdxRecommendations for technical review
Prerequisites
create-sandbox.mdx,file-access.mdx,lifecycle.mdx, andrun-commands.mdx— likelywandbSDK install, authentication, W&B/CoreWeave account with Serverless Sandboxes access (public preview), and any IAM/entitlement requirements.invoke-agent-sandbox-tutorial.mdxandmltrain-in-sandbox-tutorial.mdx, decide whether the commented-out "(Recommended) Create a Python virtual environment" block should be restored or deleted, and remove the stale MDX comments (e.g., line 16 of the agent tutorial, lines 25–26 offile-access.mdx).mltrain-in-sandbox-tutorial.mdx, confirm the full prereq list (Python version host/container, account entitlement, IAM, local system requirements) and whetherWANDB_API_KEYenv-var auth is supported as an alternative towandb login.invoke-agent-sandbox-tutorial.mdx, theopenaipackage is imported bydemo.pybut not listed as a dependency to install.Verification steps
create-sandbox.mdx,file-access.mdx,run-commands.mdx,invoke-agent-sandbox-tutorial.mdx, andmltrain-in-sandbox-tutorial.mdx, the examples do not describe expected output or how to confirm success. Consider adding "what you should see" lines for: sandbox start, file write/read, mounted commands (pip install,python train.py),wandb login, secret storage and retrieval, and successful agent runs.mltrain-in-sandbox-tutorial.mdx, no guidance on confirming the sandbox started or inspecting logs whensandbox.exec(...)fails; no sanity-check inference snippet or expected file size for the saved model.run-commands.mdx, clarify what happens after thewithblock exits in "Keep the sandbox running for additional commands" — whethersleep infinityis terminated automatically.Technical accuracy
create-sandbox.mdx, confirmpython:3.15(used as the example override image) is a real/intended tag versus a typo forpython:3.13or similar; default ispython:3.11.create-sandbox.mdx, the Tip recommends context-manager use, but "Start a sandbox with a main command" usesSandbox.run("python", "train.py")withoutwith. Confirm this is intentional or update the example.create-sandbox.mdx, the code under "Start a sandbox without a main command" duplicates the parent "Create a sandbox" example. Confirm intentional or replace with a distinct pattern.file-access.mdx:NetworkOptionsis imported but unused (line 77); confirm.result()requirement and how the working directory resolves for"hello.txt"(line 40); verifymounted_filesfield names (mount_path,file_content) match the API; the prose says files mount to "the sandbox root directory" butmount_pathvalues lack a leading/— clarify how bare paths resolve; clean up trailing whitespace / closing-bracket indentation onmounted_files(line 82 andmltrain-in-sandbox-tutorial.mdxline 198).file-access.mdx,lifecycle.mdx, andrun-commands.mdx, reference links point todocs.coreweave.com/products/coreweave-sandbox/...while imports usefrom wandb.sandbox import Sandbox. Confirm the canonical reference URL.lifecycle.mdx: confirm whetherFAILEDcan be reached directly fromPENDINGorCREATINGand update the state diagram; review whether the explicitsandbox.wait()inside awithblock is necessary given the prose; document timeout behavior forSandbox.wait_until_complete(timeout=...); consider tightening "may enterFAILED" to deterministic language if appropriate; verify "Public preview" status is still accurate.mltrain-in-sandbox-tutorial.mdx: re-verify the line-number callouts in the "previous code snippet does the following" list (lines 229–235); confirm the asymmetric pattern of mountingtrain.py/requirements.txtwhile writinghyperparameters.yamlseparately viawrite_file(); justifyNetworkOptions(egress_mode="internet")andmax_lifetime_seconds=3600; confirmpython:3.13is the recommended/supported image; verify the code-fence directive on line 189 (```python Show lines title="train_in_sandbox.py") — likely should beshowLineNumbers; confirm thewandb loginreference link/models/ref/cli/wandb-loginis correct for this audience.invoke-agent-sandbox-tutorial.mdx, the central "Run the agent in a sandbox" procedural section appears to be missing — the tutorial never shows how to start the sandbox, install dependencies inside it, mount/uploaddemo.py, or invoke the script. Clarify whetherdemo.pyis created locally then transferred, or directly in the sandbox.run-commands.mdx: the intro link#check-for-errorsdoes not match the heading anchor#check-for-sandbox-execution-errors; confirm whetherSandbox.run("python", "train.py")positional args versussandbox.exec(["pip", "install", "torch"])list args is intentional; confirm the comment# "hello\\n"renders correctly versus the intended"hello\n".secrets.mdxline 62, the intro says the example checks forHF_TOKEN, but the example checksHUGGINGFACE_TOKEN. Reword to clarify thatHF_TOKENis exposed asHUGGINGFACE_TOKEN.secrets.mdxline 64, the parentheticalSecret(env_var="CUSTOM_NAME")omits the requirednameparameter; update toSecret(name="...", env_var="CUSTOM_NAME").secrets.mdx,f"..."prefixes appear on strings with no interpolation (lines 50, 52, 82); the phrase"OpenAI key token found."(line 52) reads awkwardly — confirm intended wording.Missing content
lifecycle.mdx,graceful_shutdown_secondsandmissing_okare introduced only via inline code comments; "Maximum lifetime" is referenced but never defined or linked. Add brief descriptions or links to theSandbox.stop()reference and the lifetime definition.file-access.mdx: the "Mount a file or directory" heading covers directories but only shows file examples — add a directory example or narrow the heading; document file size limits, supported encodings (binary versus text), and behavior on path collisions; clarify what happens when sandbox code writes to a read-only mounted path; document error handling forread_fileon a missing path; add a reference link formounted_files/Sandbox.run(mounted_files=...).invoke-agent-sandbox-tutorial.mdx, add a "Next steps" or "What you accomplished" closer, and consider linking the<Warning>about public preview to its scope/limitations.mltrain-in-sandbox-tutorial.mdx: the intro mentions starting a sandbox "with the appropriate environment variables" but the body never documents any — either remove the phrase or document them; add troubleshooting guidance (auth errors, sandbox creation timeouts, network egress denied, dependency install failures, lifetime exceeded); add cleanup/cost guidance (context-manager teardown,max_lifetime_secondsenforcement, account-side cost implications); add a "Next steps" with links to a Sandbox API reference and Serverless Sandbox concept page; consider a brief callout explainingtrain.pyat a conceptual level if the audience extends beyond ML practitioners.run-commands.mdx: add a definition of "sandbox" or link to a concept page; explain whattimeout=3600.0controls and what happens on timeout; clarify when to useProcess.result()versussandbox.wait_until_complete(); add guidance on common exit codes beyond "0 indicates success."secrets.mdx, the commented-out "Extract a field from a structured secret" block at the bottom of the file should be either removed or restored.How to review