Sandbox

Note

This is the autodoc API reference. For the guide see Sandbox Environments; for runnable files see Sandbox Examples.

Sandbox APIs are experimental. A sandbox session owns a Docker-backed environment process, connects a remote client to it, and stops the container when the session closes. Reach for one when an environment needs its own dependencies and process: the session handles build, connect, and teardown behind the normal remote client.

Session Info

class rlmesh._sandbox.SandboxInfo

Bases: object

Information about a running RLMesh sandbox container.

__init__(requested_source, resolved_source, address, container_id)

Parameters:

• requested_source (str)

• resolved_source (str)

• address (str)

• container_id (str)

Return type:

None

Base Sessions

class rlmesh._sandbox.session.SandboxLifecycle

Bases: object

Container-lifecycle mixin for Docker-backed env sessions.

Combined with a Remote*EnvBase (which provides the reset/step/contract surface and the client this session attaches to its container): a sandbox env is a remote env that also owns an isolated container. Closing it detaches the client and stops the container. The concrete subclass supplies _detach() (its remote base’s close) and starts the container in __init__ before attaching self.

property source: str

Original sandbox source string requested by the caller.

close()

Detach the remote client and stop the owned sandbox container.

Return type:

None

class rlmesh._sandbox.SandboxEnvBase

Bases: SandboxLifecycle, RemoteEnvBase[ValueT, ActionT]

Experimental Docker-backed single-environment session.

A remote env (reset/step/spaces/contract inherited) that also owns an isolated container; closing the session detaches the client and stops the container.

Parameters:

• source – A gym id / gym:// / hf:// source built from source, or a prebuilt rlmesh-serving image (docker://img / bare img:tag) run directly (see rlmesh._sandbox.session.resolve_source_kind()).

• build – Optional SandboxBuild – build-from- source infrastructure (base image, packages, rlmesh pin, …); ignored for a prebuilt image.

• runtime – Optional SandboxRuntime – docker run settings (gpus / devices / volumes). Needed by sim envs that render through a GPU: gpus="all" (CUDA compute) or, for SAPIEN/Vulkan, devices=["nvidia.com/gpu=all"] (a CDI ref). Also volumes=[...] for bind-mounting large assets. Prebuilt-image source only; rejected when building from a gym:///hf:// source.

• connect_timeout_seconds – Seconds to wait for the container to start serving before giving up (default 30s). The server only binds its port after the env factory’s make() runs, so an env that loads large sims/assets (e.g. a LIBERO task suite) needs headroom; raise it for slower startups.

• **params – Environment construction params – the binding forwarded to the factory’s make (validated against its declared params in the container, before construction). source is positional-only so a param named source flows here cleanly.

__init__(source, /, *, build=None, runtime=None, connect_timeout_seconds=30.0, **params)

Parameters:

• source (str)

• build (SandboxBuild | None)

• runtime (SandboxRuntime | None)

• connect_timeout_seconds (float)

• params (object)

Return type:

None

class rlmesh._sandbox.SandboxVectorEnvBase

Bases: SandboxLifecycle, RemoteVectorEnvBase[ValueT, ActionT]

Experimental Docker-backed vector-environment session.

A remote vector env (reset/step, single_* spaces, contract inherited) that also owns an isolated container; closing the session detaches the client and stops the container.

Parameters:

• source – A gym id / gym:// / hf:// source built from source, or a prebuilt rlmesh-serving image (docker://img / bare img:tag).

• num_envs – Number of environment instances to create (must be >= 2).

• vectorization_mode – Vectorization mode requested in the sandbox.

• build – Optional SandboxBuild – build-from- source infrastructure; ignored for a prebuilt image.

• runtime – Optional SandboxRuntime – docker run settings (gpus / devices / volumes). Needed by sim envs that render through a GPU. Prebuilt-image source only; rejected when building from a gym:///hf:// source.

• connect_timeout_seconds – Seconds to wait for the container to start serving before giving up (default 30s); raise it for envs with slow make().

• **params – Environment construction params – the binding forwarded to the factory’s make (validated in the container before construction).

__init__(source, /, num_envs, *, vectorization_mode='sync', build=None, runtime=None, connect_timeout_seconds=30.0, **params)

Parameters:

• source (str)

• num_envs (int)

• vectorization_mode (str)

• build (SandboxBuild | None)

• runtime (SandboxRuntime | None)

• connect_timeout_seconds (float)

• params (object)

Return type:

None

Backend Sessions

Concrete sandbox classes inherit the base session behavior and only choose the remote client used inside the owned sandbox session.

Class	Remote client	Value decoding
rlmesh.numpy.SandboxEnv	rlmesh.numpy.RemoteEnv	NumPy arrays and primitives
rlmesh.numpy.SandboxVectorEnv	rlmesh.numpy.RemoteVectorEnv	NumPy arrays and primitives
rlmesh.torch.SandboxEnv	rlmesh.torch.RemoteEnv	Torch tensors and primitives
rlmesh.torch.SandboxVectorEnv	rlmesh.torch.RemoteVectorEnv	Torch tensors and primitives

See Framework Backends for backend-specific class entries and helper functions.