Sandbox

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. See Sandbox Examples for runnable examples.

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.SandboxSessionBase

Bases: Generic[RemoteT]

Experimental base for Docker-backed sandbox sessions.

A sandbox session owns the isolated environment container and the remote client connected to it. Closing the session closes the client and stops the container.

Parameters:

• source – Gymnasium id, explicit gym:// source, or pinned environment source such as an EnvHub/Hugging Face reference.

• base_image – Optional Docker base image override.

• rlmesh_package – Optional RLMesh package, wheel, or "local" installed in the sandbox.

• packages – Extra environment packages installed in the sandbox.

• imports – Import names checked during sandbox startup.

• trust_remote_code – Allow remote environment code to execute.

• allow_unpinned_hf – Allow Hugging Face sources without a pinned revision.

• num_envs – Number of environment instances to create.

• vectorization_mode – Optional vectorization mode requested in the sandbox.

• **gym_make_kwargs – Keyword arguments forwarded to environment creation.

__init__(source, *, base_image=None, rlmesh_package=None, packages=None, imports=None, trust_remote_code=False, allow_unpinned_hf=False, num_envs=1, vectorization_mode=None, build_memory=None, task=None, config=None, capabilities=None, override=None, cwd=None, repo_root=None, **gym_make_kwargs)

Parameters:

• source (str)

• base_image (str | None)

• rlmesh_package (str | PathLike[str] | None)

• packages (Sequence[str] | None)

• imports (Sequence[str] | None)

• trust_remote_code (bool)

• allow_unpinned_hf (bool)

• num_envs (int)

• vectorization_mode (str | None)

• build_memory (str | None)

• task (str | None)

• config (Mapping[str, object] | str | PathLike[str] | None)

• capabilities (Sequence[str] | None)

• override (str | PathLike[str] | None)

• cwd (str | PathLike[str] | None)

• repo_root (str | PathLike[str] | None)

• gym_make_kwargs (object)

Return type:

None

property source: str

Original sandbox source string requested by the caller.

close()

Close the remote client and stop the owned sandbox container.

Return type:

None

class rlmesh._sandbox.SandboxEnvBase

Bases: SandboxSessionBase[RemoteEnvHandle], Generic[ValueT, ActionT]

Experimental Docker-backed single-environment session.

Closing the session stops the owned sandbox container.

Parameters:

• source – Gymnasium id, explicit gym:// source, or pinned environment source such as an EnvHub/Hugging Face reference.

• base_image – Optional Docker base image override.

• rlmesh_package – Optional RLMesh package, wheel, or "local" installed in the sandbox.

• packages – Extra environment packages installed in the sandbox.

• imports – Import names checked during sandbox startup.

• trust_remote_code – Allow remote environment code to execute.

• allow_unpinned_hf – Allow Hugging Face sources without a pinned revision.

• **gym_make_kwargs – Keyword arguments forwarded to environment creation.

__init__(source, *, base_image=None, rlmesh_package=None, packages=None, imports=None, trust_remote_code=False, allow_unpinned_hf=False, build_memory=None, task=None, config=None, capabilities=None, override=None, cwd=None, repo_root=None, **gym_make_kwargs)

Parameters:

• source (str)

• base_image (str | None)

• rlmesh_package (str | PathLike[str] | None)

• packages (Sequence[str] | None)

• imports (Sequence[str] | None)

• trust_remote_code (bool)

• allow_unpinned_hf (bool)

• build_memory (str | None)

• task (str | None)

• config (Mapping[str, object] | str | PathLike[str] | None)

• capabilities (Sequence[str] | None)

• override (str | PathLike[str] | None)

• cwd (str | PathLike[str] | None)

• repo_root (str | PathLike[str] | None)

• gym_make_kwargs (object)

Return type:

None

property env_contract: EnvContract

Environment contract reported by the sandboxed endpoint.

property spec: EnvContract

Alias for env_contract.

property render_mode: str | None

Configured render mode reported by the sandboxed endpoint.

property metadata: Mapping[str, object]

Metadata reported by the sandboxed endpoint.

property observation_space: Space[ValueT]

Observation space reported by the sandboxed endpoint.

property action_space: Space[ActionT]

Action space reported by the sandboxed endpoint.

property observation_space_spec: SpaceSpec

Native observation space spec reported by the sandboxed endpoint.

property action_space_spec: SpaceSpec

Native action space spec reported by the sandboxed endpoint.

reset(*, seed=None, options=None)

Reset the sandboxed environment.

Parameters:

• seed (int | None)

• options (dict[str, object] | None)

Return type:

tuple[ValueT, dict[str, object]]

step(action)

Step the sandboxed environment with one action.

Parameters:

action (ActionT)

Return type:

tuple[ValueT, float, bool, bool, dict[str, object]]

render(*, env_index=0)

Render a frame from the sandboxed environment.

Parameters:

env_index (int)

Return type:

ValueT | None

open_viewer(*, env_index=0, fps='env')

Open a local render viewer for the sandboxed environment.

Parameters:

• env_index (int)

• fps (float | None | str)

Return type:

None

close_viewer()

Close the local render viewer if one is open.

Return type:

None

class rlmesh._sandbox.SandboxVectorEnvBase

Bases: SandboxSessionBase[RemoteVectorEnvHandle], Generic[ValueT, ActionT]

Experimental Docker-backed vector-environment session.

Closing the session stops the owned sandbox container.

Parameters:

• source – Gymnasium id, explicit gym:// source, or pinned environment source such as an EnvHub/Hugging Face reference.

• num_envs – Number of environment instances to create.

• vectorization_mode – Vectorization mode requested in the sandbox.

• base_image – Optional Docker base image override.

• rlmesh_package – Optional RLMesh package, wheel, or "local" installed in the sandbox.

• packages – Extra environment packages installed in the sandbox.

• imports – Import names checked during sandbox startup.

• trust_remote_code – Allow remote environment code to execute.

• allow_unpinned_hf – Allow Hugging Face sources without a pinned revision.

• **env_make_kwargs – Keyword arguments forwarded to environment creation.

__init__(source, num_envs, *, vectorization_mode='sync', base_image=None, rlmesh_package=None, packages=None, imports=None, trust_remote_code=False, allow_unpinned_hf=False, build_memory=None, task=None, config=None, capabilities=None, override=None, cwd=None, repo_root=None, **env_make_kwargs)

Parameters:

• source (str)

• num_envs (int)

• vectorization_mode (str)

• base_image (str | None)

• rlmesh_package (str | PathLike[str] | None)

• packages (Sequence[str] | None)

• imports (Sequence[str] | None)

• trust_remote_code (bool)

• allow_unpinned_hf (bool)

• build_memory (str | None)

• task (str | None)

• config (Mapping[str, object] | str | PathLike[str] | None)

• capabilities (Sequence[str] | None)

• override (str | PathLike[str] | None)

• cwd (str | PathLike[str] | None)

• repo_root (str | PathLike[str] | None)

• env_make_kwargs (object)

Return type:

None

property env_contract: EnvContract

Environment contract reported by the sandboxed vector endpoint.

property spec: EnvContract

Alias for env_contract.

property render_mode: str | None

Configured render mode reported by the sandboxed vector endpoint.

property metadata: Mapping[str, object]

Metadata reported by the sandboxed vector endpoint.

property num_envs: int

Number of environments in the sandboxed vector endpoint.

property observation_space: Space[ValueT]

Alias for single_observation_space.

property action_space: Space[ActionT]

Alias for single_action_space.

property single_observation_space: Space[ValueT]

Observation space for one sandboxed environment.

property single_action_space: Space[ActionT]

Action space for one sandboxed environment.

property observation_space_spec: SpaceSpec

Native observation space spec reported by the sandboxed endpoint.

property action_space_spec: SpaceSpec

Native action space spec reported by the sandboxed endpoint.

reset(*, seed=None, options=None)

Reset all environments in the sandboxed vector endpoint.

Parameters:

• seed (int | list[int] | None)

• options (dict[str, object] | None)

Return type:

tuple[ValueT, dict[str, object]]

step(actions)

Step all sandboxed environments with a batch of actions.

Parameters:

actions (ActionT)

Return type:

tuple[ValueT, ValueT, ValueT, ValueT, dict[str, object]]

render(*, env_index=0)

Render a frame from one sandboxed environment.

Parameters:

env_index (int)

Return type:

ValueT | None

open_viewer(*, env_index=0, fps='env')

Open a local render viewer for one sandboxed environment.

Parameters:

• env_index (int)

• fps (float | None | str)

Return type:

None

close_viewer()

Close the local render viewer if one is open.

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 NumPy and Torch for backend-specific class entries and helper functions.