[docs] add initial documentation for Ray sandboxing

[andrewsykim]

Description

Add initial documentation for Ray's experimental sandboxing library.

Related issues

Link related issues: "Fixes #1234", "Closes #1234", or "Related to #1234".

Additional information

Optional: Add implementation details, API changes, usage examples, screenshots, etc.

[gemini-code-assist]

Code Review

This pull request introduces comprehensive documentation for Ray Sandboxes, an experimental feature that utilizes gVisor to provide lightweight, kernel-isolated execution environments on Ray clusters. The changes include a new deployment guide for Kubernetes (GKE) and a detailed core concept guide covering architecture, APIs, and security models. The review feedback highlights several formatting and syntax issues that need to be addressed, such as bullet point inconsistencies, incorrect step numbering, a shell command prefix, and syntax errors in both Markdown and RST files (including incorrect cross-references and Markdown syntax used inside an RST file).

[gemini-code-assist]

For consistency with the other items in this list, please use a hyphen (-) instead of an asterisk (*) for the bullet point.

[gemini-code-assist]

For consistency with the other commands in this guide, please remove the leading $ prefix from this command.

Suggested change

	$ kubectl logs -f -l job-name=rayjob-sandbox
	kubectl logs -f -l job-name=rayjob-sandbox

[gemini-code-assist]

The step numbering skips from Step 3 to Step 6. Please renumber this to Step 4.

Suggested change

	## (Optional) Step 6: Verify Isolation and Security Guarantees
	## (Optional) Step 4: Verify Isolation and Security Guarantees

[gemini-code-assist]

The step numbering skips from Step 3 to Step 7. Please renumber this to Step 5.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 130b8b6. Configure here.}

[pcmoritz]

We should add another section here Example (advanced): Passing configurations directly to gvisor where we show some more of the most common ways to use _oci_spec_transform_fn, e.g. for host mounts, setting up networking and passing capabilities. And maybe a note that we are iterating on this and how to best expose these without needing _oci_spec_transform_fn and we would love to hear about people's feedback in an issue.

[pcmoritz]

We should add here that _by default_, the working directory is the only writable path in the sandbox and that by setting readonly = False the whole file system can be made writeable (and make it clear to the reader that writes will go into an overlayfs filesystem so multiple file systems with the same image that do writes won't interfere with each other). [I believe this is true, let me know if it is not]

[pcmoritz]

Same comment as I made here https://github.com/ray-project/ray/pull/65503/changes#r3793075723 -- this one is arguably more important since the docs to create is linked from the main docs very prominently.

[pcmoritz]

Maybe we should say something like Create a _remote_ sandbox environment. or similar to make the difference to the SandboxRuntime clearer.

[pcmoritz]

Maybe we can modify this a little bit and say something like A Ray actor that serves as a proxy to forward command execution and file I/O to the isolated sandbox instance and manages scheduling and lifecycle of the sandbox or similar, to make the mental model clear to the user that the actor is not actually run in the sandbox.

[pcmoritz]

I imagine this section is actually the most useful for users so we should move it up. Some of the above sections are more interesting from the internal implementation perspective which users will generally be less interested in, it would make more sense to move those down a little more.

[pcmoritz]

Thanks a lot for putting this together, I finished reviewing it now. It looks great, I left a bunch of suggestions.

Also cc @dstrodtman who might have additional comments or suggestions :)

[andrewsykim]

thanks for the review, all comments addressed

[dstrodtman]

Docs style review (Anyscale docs team)

Douglas Strodtman, technical writer on the Anyscale docs team. @pcmoritz cc'd me above, so here's a full pass. Claude Code assisted with the mechanical sweeps and the verification queries below; I read every comment before posting and I stand behind each one.

Scope: style, grammar, and Ray docs conventions only, against the Ray documentation style guide. I don't own whether any of the described behavior is true. Everything technical below is a question for you and @pcmoritz, not a request. Happy to give this a docs-side approval once the content questions settle.

Worth saying plainly: this is the first Claude-aided review I've run against the Kubernetes and KubeRay conventions that landed in #65239, so the guide is getting its first real workout here. I read every recommendation and they all match what I'd have written by hand. But if a specific term or rule reads wrong to you, that's useful signal about the rule rather than a verdict on this PR, and I'd rather hear it and refine the guide than have you apply something that doesn't fit. You reviewed #65239, so you're the right person to push back.

I read the existing threads first. @pcmoritz's six comments and the bot findings all look applied at b1029a1, including the section reorder, the "remote sandbox" wording, the proxy-actor description, and the readonly docstrings. Where I comment on that text I'm styling your applied fix, not reopening the request.

One bot suggestion to skip: the gemini comment asking to point the resource-isolation cross-reference at resource-isolation-with-cgroupv2. I checked the tree; .. _resource-isolation: is the label defined in doc/source/ray-core/resource-isolation-with-cgroupv2.rst and resource-isolation-with-cgroupv2 isn't a label anywhere. What you have is correct.

What the inline comments cover

The bulk is sentence-case headings, about 20 across the three pages. Nothing in CI catches this: Google.Headings is disabled and .vale.ini doesn't scope Vale to Ray Core or KubeRay pages at all, so it's a human check every time. I batched them into two sweep comments rather than 20 separate ones.

The one structural change I'd push for is the "Benefits of gVisor" H4. It's a bolded benefits list, which the guide names twice as something to cut, and it's the page's only H4. The suggestion folds it into two prose paragraphs and keeps every claim.

The rest: numbered lists that aren't sequences, first-person plural, e.g. and via and "utilizing," a few passive constructions with a nameable actor, and bare {ref} links so text tracks titles.

Questions for you and @pcmoritz

1. _oci_spec_transform_fn framing. runtime.py documents it as "PRIVATE -- development/testing only ... No stability guarantees," while the new advanced section presents it as the supported escape hatch. Since @pcmoritz asked for that section, softening the docstring is probably the right direction, but it should say one thing.
2. RAY_SANDBOX_IGNORE_CGROUPS=1 in Troubleshooting. It maps to _ignore_cgroups, also marked "PRIVATE -- testing only" in runtime.py. Is it something users in cgroup-restricted environments should reach for?
3. The inline RayJob script. It's a hand-copy of the sample YAML and has already drifted by one line (see the L93 comment). A literalinclude or a link to the sample would keep them from separating further.
4. Two adjacent sandbox examples. The examples index now lists "Sandboxed Code Execution with Ray and Agent Sandbox" next to "Deploying Ray Sandboxes using KubeRay." They're genuinely different things, but the titles don't say so. One clause on each would help a reader pick.
5. Untested snippets. The Python blocks are bare fences, so the doc tests don't run them, and a couple aren't runnable standalone (sb is undefined in the Step 4 blocks). Fine if that's intentional for illustrative fragments.

Nice work on this. It's a lot of new surface and the structure is right.

[pcmoritz]

Looks great, thanks a lot for writing this!