rlmesh.torch.SandboxEnv

classExperimentalfrom rlmesh.torch import SandboxEnv[source]

Experimental Torch-backed owned sandbox session for one environment.

SandboxEnv(
    source: str,
    /,
    *,
    build: SandboxBuild | None = None,
    runtime: SandboxRuntime | None = None,
    connect_timeout_seconds: float = SANDBOX_REMOTE_CONNECT_TIMEOUT_SECONDS,
    **params: object,
) -> None

The sandbox starts an isolated environment process, connects a Torch remote client to it, and stops the owned container when closed.

Parameters

Name	Type	Description
`source`	`str`	A gym id / `gym://` / `hf://` source built from source, or a prebuilt rlmesh-serving image (`docker://img` / bare `img:tag`).
`build`	`SandboxBuild \| None`	Optional `SandboxBuild` -- build-from-source infrastructure; ignored for a prebuilt image.
`runtime`	`SandboxRuntime \| None`	Optional `SandboxRuntime` -- `docker run` settings (`gpus` / `devices` / `volumes`); prebuilt-image source only.
`**params`	`object`	Environment construction params -- the binding forwarded to the factory's `make` (validated in the container before construction).

Examples

>>> from rlmesh.torch import SandboxEnv, SandboxBuild
>>> env = SandboxEnv(
...     "CartPole-v1", build=SandboxBuild(packages=["gymnasium==1.3.0"])
... )
>>> observation, info = env.reset(seed=42)
>>> env.close()

Attributes

sandbox
sourceOriginal sandbox source string requested by the caller.
observation_spaceObservation space loaded from the remote environment contract.
action_spaceAction space loaded from the remote environment contract.
addressEndpoint address this client is connected to.
env_idThis connection's container id (UUIDv7).
selected_workflow_editionThe workflow edition this connection negotiated with the env.
env_contractEnvironment contract returned by the endpoint handshake.
render_modeConfigured render mode reported by the endpoint.
metadataEndpoint metadata reported by the environment contract.
observation_space_specNative observation space spec reported by the endpoint.
action_space_specNative action space spec reported by the endpoint.

Methods

close()Detach the remote client and stop the owned sandbox container.
reset()Reset the remote environment and decode the observation.
step()Step the remote environment with one encoded action.
render()Render a frame from the remote environment.
shutdown()Request owner-level shutdown of the remote environment endpoint.

sandbox

attribute[source]

sandbox

source

property[source]

property source: str

Original sandbox source string requested by the caller.

close

function[source]

close() -> None

Detach the remote client and stop the owned sandbox container.

observation_space

property[source]

property observation_space: Space[ValueT]

Observation space loaded from the remote environment contract.

action_space

property[source]

property action_space: Space[ActionT]

Action space loaded from the remote environment contract.

reset

function[source]

reset(
    *,
    seed: int | None = None,
    options: dict[str, object] | None = None,
) -> tuple[ValueT, ResetInfo]

Reset the remote environment and decode the observation.

Parameters

Name	Type	Description
`seed`	`int \| None`	Optional environment reset seed.
`options`	`dict[str, object] \| None`	Optional reset options forwarded to the environment.

Returns

Type	Description
`tuple[ValueT, ResetInfo]`	A decoded observation and reset info dictionary.

step

function[source]

step(action: ActionT) -> tuple[ValueT, float, bool, bool, StepInfo]

Step the remote environment with one encoded action.

Parameters

Name	Type	Description
`action`	`ActionT`	Action accepted by the remote environment action space.

Returns

Type	Description
`tuple[ValueT, float, bool, bool, StepInfo]`	Observation, reward, terminated flag, truncated flag, and step info.

address

property[source]

property address: str

Endpoint address this client is connected to.

env_id

property[source]

property env_id: str

This connection’s container id (UUIDv7).

A stable correlation identity, distinct from the human env name (env_contract.id).

selected_workflow_edition

property[source]

property selected_workflow_edition: str

The workflow edition this connection negotiated with the env.

The highest edition both sides can drive, at or below whatever either declared, in the exact spelling they agreed on – so a prerelease build reports its cohort, not the bare sealed base. Named apart from the workflow_edition declaration surfaces on purpose: this is what was agreed, not what this side asked for.

env_contract

property[source]

property env_contract: EnvContract

Environment contract returned by the endpoint handshake.

render_mode

property[source]

property render_mode: str | None

Configured render mode reported by the endpoint.

metadata

property[source]

property metadata: Metadata

Endpoint metadata reported by the environment contract.

observation_space_spec

property[source]

property observation_space_spec: SpaceSpec

Native observation space spec reported by the endpoint.

action_space_spec

property[source]

property action_space_spec: SpaceSpec

Native action space spec reported by the endpoint.

render

function[source]

render(*, env_index: int = 0) -> ValueT | None

Render a frame from the remote environment.

Parameters

Name	Type	Description
`env_index`	`int`	Environment index to render. Single environments use `0`.

Returns

Type	Description
`ValueT \| None`	A decoded render frame, or `None` when the environment has no frame.

shutdown

function[source]

shutdown(reason: str = 'owner shutdown') -> bool

Request owner-level shutdown of the remote environment endpoint.