Ray Sandbox API, Actor, and OCI Lifecycle Guide
On this page
Quick answer
The high-level Ray Sandbox API creates an isolated OCI-image environment and returns a Ray ActorHandle. The actor proxies command execution and file I/O while Ray handles placement and resource accounting. A complete lifecycle is not only create and exec: it must include input validation, timeouts, output limits, cancellation, deletion, failure recovery, and evidence that resources were actually removed.
The entire ray.experimental.sandbox package is alpha. Pin the exact Ray version and keep API compatibility tests.
High-level lifecycle
approve image + inputs
-> sandbox.create(image, cpu, memory, workdir, timeout)
-> Ray schedules a Sandbox Actor
-> actor starts a gVisor OCI environment
-> write or upload bounded inputs
-> exec with a command timeout
-> inspect exit code, stdout, stderr, duration, and artifacts
-> read or download approved outputs
-> delete sandbox
-> verify process, file, network, actor, and resource cleanupRay’s examples use ray.get around remote actor calls. Add an application-level deadline and cancellation strategy so a lost actor, blocked command, or unreachable worker does not leave the workflow indefinitely pending.
Choose the right surface
| Surface | Use | Additional control |
|---|---|---|
sandbox.create() | Simple distributed sandbox placement and lifecycle | Validate every option and record the returned actor identity |
Sandbox Actor | Custom Ray scheduling, resources, placement, and TTL | Test actor restart and node-failure behavior |
SandboxRuntime | Local sandbox pools inside a custom actor | Own pooling, reuse, contamination tests, deletion, and capacity accounting |
_oci_spec_transform_fn | Advanced OCI mounts or namespace details not covered by first-class options | Treat as unstable, security-sensitive code with narrow review |
Do not expose the low-level hook to untrusted input. A host bind mount or permissive namespace change can cross the intended isolation boundary.
Command and file boundaries
Ray documents command results with fields such as exit code, stdout, and duration. Define limits for command length, execution time, process count, output bytes, log bytes, working-directory size, and returned file size. Treat stdout and generated files as untrusted content.
The file API can write and read inside the sandbox and upload or download between host and sandbox paths. Require:
- normalized allowlisted paths under the intended working directory;
- maximum file and total transfer sizes;
- content type and archive-expansion limits;
- source provenance and malware or policy scanning;
- no implicit credentials, sockets, device files, or sensitive host mounts;
- destination ownership and retention rules for downloaded output.
The documented default root filesystem is read-only while the configured work directory is writable. Verify the exact image and mount configuration.
OCI images and configuration
Pin images by digest, scan them, record provenance and software inventory, and test registry unavailability. A familiar image name does not prove the bytes that ran.
Ray’s image manager can pull from sources such as Docker Hub, GHCR, or local archives and cache extracted images on worker storage. Plan cache quotas, eviction, integrity, tenant separation, disk-pressure monitoring, and cleanup.
First-class network, dns, and capabilities options should be preferred over a custom OCI transformation when they cover the need. The default network mode is none. Giving an untrusted sandbox host networking or broad capabilities materially changes the threat model.
Failure and cleanup test
- Fail image pull, OCI creation, command startup, file transfer, and result collection independently.
- Cancel before and during execution.
- Kill the actor, Ray worker, and Kubernetes node.
- Exhaust CPU, memory, disk, output, process, and deadline limits.
- Retry with one idempotency key and confirm work is not duplicated silently.
- Verify gVisor processes, overlays, working files, actor state, object references, and resource reservations are gone.
- Preserve enough evidence to explain what ran, where, with which image and inputs, and how it ended.
For deployment prerequisites, read the Ray Sandboxes on GKE guide.
Frequently asked questions
What does sandbox.create return in Ray?
Ray documents sandbox.create as creating an OCI-image sandbox and returning a Ray ActorHandle that proxies command execution, file operations, scheduling, and lifecycle management.
How do you delete a Ray Sandbox?
The documented high-level flow calls the sandbox actor’s delete method and waits for the Ray result. Production code should also handle timeout, cancellation, actor loss, node loss, and partial cleanup.
Can a Ray Sandbox transfer files?
Ray documents write_file, read_file, upload_file, and download_file operations. Bound paths, sizes, types, provenance, secrets, and destination rights before enabling transfers.
Is the OCI specification transform hook stable?
No. Ray marks _oci_spec_transform_fn as experimental and says it is likely to change as higher-level configuration APIs are designed.
Official sources
Source check: August 27, 2026. Recheck alpha APIs, result types, lifecycle methods, image behavior, file operations, network modes, capabilities, cache paths, and cleanup semantics.