Deploy Ray sandboxes with KubeRay#

This guide covers how to deploy and orchestrate Ray Sandboxes using Ray and KubeRay. It uses Google Kubernetes Engine (GKE) as an example, but the same principles apply to other Kubernetes distributions.

Ray Sandboxes run untrusted, model-generated code safely inside lightweight, kernel-isolated environments, for reinforcement learning (RL) rollout workers and autonomous large language model (LLM) agents. Ray runs gVisor (runsc) directly inside Ray worker Pods, which delivers sub-100 ms startup latencies and dense bin packing of hundreds of concurrent sandboxes per node without the multi-second overhead of provisioning separate Kubernetes Pods.

Warning

Ray Sandboxes (ray.experimental.sandbox) is an alpha library. The API can change or disappear in any release before it graduates to stable.

Prerequisites#

  • kubectl installed and configured with access to your Kubernetes cluster.

  • gcloud CLI installed and authenticated to your Google Cloud project.

  • Helm v3 installed.

  • Ray 2.58.0 or newer with the ray.experimental.sandbox package.

Step 1: Create a GKE cluster#

Create a GKE cluster with standard Linux worker nodes. Because gVisor runs inside the Ray container processes in rootless user space, you can use standard GKE node pools with the containerd container runtime.

gcloud container clusters create ray-sandbox-cluster \
    --region=us-central1 \
    --machine-type=e2-standard-16 \
    --num-nodes=3

Step 2: Install the KubeRay operator#

Follow KubeRay operator installation to install the latest stable KubeRay operator from the Helm repository.

Step 3: Run sandboxes with a RayJob#

Create a RayJob that creates a RayCluster configured with runsc and submits a Ray job that manages Ray sandboxes:

kubectl apply -f https://raw.githubusercontent.com/kuberay-project/kuberay/master/ray-operator/config/samples/ray-job.sandbox.yaml

The RayJob is configured to do the following:

  • Create a RayCluster configured to install runsc at startup with the necessary securityContext required for gVisor

  • Submit a Ray job which will create a sandbox and execute some Python code inside it

  • Terminate sandboxes after the job is done

Below is the script used for the RayJob:

import ray
from ray.experimental import sandbox

ray.init()

sb = sandbox.create(
    image="python:3.12-slim",
    workdir="/workspace",
    cpu=1.0,
    memory="1Gi",
)

script = """\
import platform
import sys

print("=== Hello from inside Ray Sandbox! ===")
print(f"Python Version : {sys.version}")
print(f"Platform       : {platform.platform()}")
"""
ray.get(sb.write_file.remote("/workspace/main.py", script))

result = ray.get(sb.exec.remote("python3 /workspace/main.py"))
print(f"Exit code: {result.exit_code}")
print("Sandbox output:")
print(result.stdout)

ray.get(sb.delete.remote())
print("RayJob completed successfully!")

Monitor the status and output of the job:

# List running job pods (wait for Ray cluster to be in ready state)
kubectl get pods -l job-name=rayjob-sandbox

# Stream the demo logs
kubectl logs -f -l job-name=rayjob-sandbox

The output should be similar to the following:

Sandbox output:
=== Hello from inside Ray Sandbox! ===
Python Version : 3.12.14 (main, Aug 13 2026, 19:41:13) [GCC 14.2.0]
Platform       : Linux-4.19.0-gvisor-x86_64-with-glibc2.41

RayJob completed successfully!
2026-08-15 17:38:41,535	INFO sdk.py:520 -- WebSocket closed for job rayjob-sandbox-gz8j6 with close code 1000
2026-08-15 17:38:41,546	SUCC cli.py:66 -- ------------------------------------
2026-08-15 17:38:41,546	SUCC cli.py:67 -- Job 'rayjob-sandbox-gz8j6' succeeded
2026-08-15 17:38:41,546	SUCC cli.py:68 -- ------------------------------------

(Optional) Step 4: Verify isolation and security guarantees#

You can verify that untrusted code running inside an active sandbox cannot compromise the host environment or escape its sandbox boundary:

Filesystem write protection#

By default, base root filesystems are mounted read-only (readonly=True). Only the designated workdir is writable.

# Assuming an active sandbox `sb = sandbox.create(...)`
# Attempting to modify /etc or rootfs will fail
res = ray.get(sb.exec.remote("touch /etc/hacked.txt"))
print(res.exit_code)  # Non-zero exit code
print(res.stderr)     # "Read-only file system"

Network isolation#

With network="none" (the default), untrusted code cannot establish outbound connections to the internet or probe internal Kubernetes cluster services:

# Attempting network egress will immediately fail
res = ray.get(sb.exec.remote("python3 -c 'import urllib.request; urllib.request.urlopen(\"http://google.com\", timeout=2)'"))
print(res.exit_code)  # Non-zero exit code

With network="public", each sandbox gets a private network namespace that slirp4netns connects to the Pod. Sandboxes can bind the same port at the same time without conflicts, and they can’t reach each other or the Pod’s own services. Ray filters each sandbox’s outbound traffic. By default, it reaches the public internet and leaves out internal addresses as a best effort, which on most clusters keeps other Pods, Services, and the Ray nodes out of reach. Instance metadata and the Kubernetes API Service stay closed whatever the allowlist says. For untrusted code that needs network access, pass a cidr_allowlist that names only the services it needs. See Restrict egress to an allowlist.

Code in a public sandbox can still send data anywhere on the internet, so keep network="none" for untrusted code that doesn’t need the network. This mode needs the slirp4netns and nft binaries on the worker’s $PATH, and /dev/net/tun available in the Ray container, which standard GKE containerd node pools provide.

(Optional) Step 5: Build a custom Ray image with pre-installed runsc#

Ray Sandboxes need runsc in the Ray container’s $PATH, for example /usr/local/bin/runsc, and mkfs.erofs from erofs-utils. For network="public", they also need slirp4netns and nftables. The Ray Sandboxes requirements list the version that each tool needs.

The preceding example downloads runsc at Pod startup. For production, pre-install these tools in your container image. Pre-baking them eliminates runtime network dependencies, avoids external download failures or rate limits, and decreases Pod startup latency.

Build the image with one of the Dockerfiles in the Ray Sandboxes requirements. They add every tool to a Ray image, and they build erofs-utils from source because the package in Ray’s Ubuntu 22.04 images is too old. Base the image on the same Ray version as your RayCluster’s rayVersion, then set it as the image of the Ray container in each worker group that runs sandboxes.

Next steps#