Skip to content

[docs] Style pass on the Ray Sandboxes networking section #65627

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dstrodtman merged 1 commit into from
Aug 20, 2026
+11 −16
Merged

[docs] Style pass on the Ray Sandboxes networking section #65627

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 11 additions & 16 deletions doc/source/ray-core/sandboxes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,9 @@ For advanced workloads, you might need to configure low-level runtime options su
The `_oci_spec_transform_fn` callable receives the fully generated OCI specification dictionary. It can mutate the dictionary in place or return a modified one. Common use cases include the following:

* **Host mounts**: Mount host directories, read-only datasets, or model weights into the sandbox container.

@ronny-anyscale ronny-anyscale Aug 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **Host mounts**: Mount host directories, read-only datasets, or model weights into the sandbox container.
* **Host mounts:** Mount host directories, read-only datasets, or model weights into the sandbox container.

I have a feeling this list is longer than I see here and these suggestions are wrong for consistency, but here we are.

* **Namespace or mount details** that the first-class options don't cover. Internet access, DNS, and Linux capabilities no longer need this hook — use `network=`, `dns=`, and `capabilities=` (including `capabilities=[]` to run with none at all; see [Networking and DNS](#networking-and-dns)). The hook remains for advanced network or capability configurations beyond those options.
* **Namespace and mount details**: Configure namespace or mount behavior that the first-class options don't cover.

@ronny-anyscale ronny-anyscale Aug 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **Namespace and mount details**: Configure namespace or mount behavior that the first-class options don't cover.
* **Namespace and mount details:** Configure namespace or mount behavior that the first-class options don't cover.


Internet access, DNS, and Linux capabilities each have a first-class option: `network=`, `dns=`, and `capabilities=`. Pass `capabilities=[]` to run with no capabilities at all. Reserve the hook for network or capability configurations those options don't reach. See [Networking and DNS](#networking-and-dns).

```python
import ray
Expand Down Expand Up @@ -237,20 +239,16 @@ ray.get(sb.delete.remote())

## Networking and DNS

Sandboxes support four network modes. `none` is the default, following the
safe-defaults principle; `public` is the recommended mode when a sandbox
needs internet access.
Sandboxes support four network modes. The default is `none`, which follows the safe-defaults principle. Use `public` when a sandbox needs internet access.

| Mode | Network access | `/etc/resolv.conf` | Security property |
| --- | --- | --- | --- |
| `none` *(default)* | None | untouched | No egress. |
| `public` — **recommended for internet access** | Host egress | Generated from `dns` (default `8.8.8.8`, `1.1.1.1`), mounted read-only | Egress works, but the sandbox inherits *nothing* from the host's resolver configuration — no internal search domains, resolver addresses, or `ndots` options leak in, and the sandbox config stays portable across clusters. |
| `host` | Full host network identity | Host's own file, mounted read-only (`dns=` overrides it) | Strictly more permissive than `public`: the sandbox can reach anything the node can reach, including internal networks and node-local services. Prefer `public` for untrusted code. |
| `sandbox` | gVisor netstack | untouched | Requires `rootless=False`; runsc doesn't support the sandbox netstack in rootless mode. |
| `public` | Host egress | Generated from `dns` (default `8.8.8.8`, `1.1.1.1`), mounted read-only | Egress works, but the sandbox inherits nothing from the host's resolver configuration. No internal search domains, resolver addresses, or `ndots` options leak in, and the sandbox config stays portable across clusters. |
| `host` | Full host network identity | Host's own file, mounted read-only (`dns=` overrides it) | Strictly more permissive than `public`. The sandbox can reach anything the node can reach, including internal networks and node-local services. Use `public` for untrusted code. |
| `sandbox` | gVisor netstack | untouched | Requires `rootless=False`. runsc doesn't support the sandbox netstack in rootless mode. |

@gemini-code-assist gemini-code-assist Bot Aug 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

To answer your question: yes, network="sandbox" runs gVisor's internal user-space network stack (Netstack). Since Ray Sandboxes do not configure external network interfaces for this mode by default, it has no egress/external connectivity (only loopback). It is isolated like none, but with a full network stack running inside the sandbox. We can clarify this in the table by updating the 'Network access' column to specify that there is no egress by default.

Suggested change
| `sandbox` | gVisor netstack | untouched | Requires `rootless=False`. runsc doesn't support the sandbox netstack in rootless mode. |
| `sandbox` | gVisor netstack (no egress by default) | untouched | Requires `rootless=False`. runsc doesn't support the sandbox netstack in rootless mode. |


The recommended way to give a sandbox internet access — together with
Docker-parity capabilities so standard images behave the way they do under
Docker (`apt-get`, `tar` ownership restore, and similar all need them):
To give a sandbox internet access, use `network="public"`. Pair it with `DOCKER_DEFAULT_CAPABILITIES` so standard images behave the way they do under Docker, because `apt-get`, `tar` ownership restore, and similar operations all need those capabilities:

```python
from ray.experimental import sandbox
Expand All @@ -264,12 +262,9 @@ sb = sandbox.create(
)
```

**DNS in locked-down networks.** Some VPCs block outbound port 53 to public
resolvers, where the `public` defaults can't resolve. Pass your internal
resolver instead — `network="public", dns=["10.0.0.2"]` — or fall back to
`network="host"` (which uses the host's resolv.conf) at the cost of full host
network identity. Anything beyond that can be configured through the OCI spec
(see [Pass custom OCI configurations to gVisor](#pass-custom-oci-configurations-to-gvisor)).
### DNS in locked-down networks

Some VPCs block outbound port 53 to public resolvers, where the `public` defaults can't resolve. Pass your internal resolver instead with `network="public", dns=["10.0.0.2"]`. If that isn't an option, fall back to `network="host"`, which uses the host's `/etc/resolv.conf`, at the cost of full host network identity. Configure anything beyond that through the OCI spec. See [Pass custom OCI configurations to gVisor](#pass-custom-oci-configurations-to-gvisor).

## Architecture

Expand Down
Loading