Remote Environments

Remote clients connect to an environment endpoint and expose the same core calls as a local Gymnasium environment: reset, step, render, and close.

Use the concrete backend modules in application code:

• rlmesh.RemoteEnv and rlmesh.RemoteVectorEnv preserve RLMesh-native values.

• rlmesh.numpy.RemoteEnv and rlmesh.numpy.RemoteVectorEnv decode tensor leaves as NumPy arrays.

• rlmesh.torch.RemoteEnv and rlmesh.torch.RemoteVectorEnv decode tensor leaves as Torch tensors.

Every remote client keeps the endpoint handshake in env_contract. The spec property is an alias for that same contract. observation_space and action_space are client-side wrappers built from the contract’s SpaceSpec values.

Render Viewer

Every remote client (and the experimental sandbox sessions) inherits two viewer methods from a shared mixin:

• open_viewer(*, env_index=0, fps="env") opens a local render window and streams frames after each reset, step, and render. env_index selects which sub-environment of a vector client to view. fps accepts "env" (read render_fps from environment metadata), a positive number for an explicit limit, or None to disable pacing.

• close_viewer() closes the window if one is open. It is also called on client close().

The viewer is best-effort and experimental. It launches a separate GUI process via python -m rlmesh viewer, so it needs a desktop host. The environment must produce frames, typically render_mode="rgb_array". Frame pushes are dropped instead of blocking the step loop when the viewer stalls.

Single Environment Base

class rlmesh._client.RemoteEnvBase

Bases: ViewerMixin, Generic[ValueT, ActionT]

Base class for backend-specific single-environment remote clients.

Backend modules such as rlmesh.numpy and rlmesh.torch configure the value bridge. User code should normally instantiate those concrete backends instead of this base class.

Parameters:

• address – Endpoint address such as "tcp://127.0.0.1:5555".

• host – TCP host helper used when address is omitted.

• port – TCP port helper used when address is omitted.

• path – Unix socket path helper used when address is omitted.

• transport – Explicit transport selector.

__init__(address=None, *, host=None, port=None, path=None, transport=None)

Parameters:

• address (str | None)

• host (str | None)

• port (int | None)

• path (str | None)

• transport (Literal['tcp', 'unix'] | None)

Return type:

None

property address: str

Endpoint address this client is connected to.

property env_contract: EnvContract

Environment contract returned by the endpoint handshake.

property spec: EnvContract

Alias for env_contract.

property render_mode: str | None

Configured render mode reported by the endpoint.

property observation_space: Space[ValueT]

Observation space loaded from the remote environment contract.

property action_space: Space[ActionT]

Action space loaded from the remote environment contract.

property metadata: Mapping[str, object]

Endpoint metadata reported by the environment contract.

property observation_space_spec: SpaceSpec

Native observation space spec reported by the endpoint.

property action_space_spec: SpaceSpec

Native action space spec reported by the endpoint.

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

Reset the remote environment and decode the observation.

Parameters:

• seed (int | None) – Optional environment reset seed.

• options (dict[str, object] | None) – Optional reset options forwarded to the environment.

Returns:

A decoded observation and reset info dictionary.

Return type:

tuple[ValueT, ResetInfo]

step(action)

Step the remote environment with one encoded action.

Parameters:

action (ActionT) – Action accepted by the remote environment action space.

Returns:

Observation, reward, terminated flag, truncated flag, and step info.

Return type:

tuple[ValueT, float, bool, bool, StepInfo]

render(*, env_index=0)

Render a frame from the remote environment.

Parameters:

env_index (int) – Environment index to render. Single environments use 0.

Returns:

A decoded render frame, or None when the environment has no frame.

Return type:

ValueT | None

close()

Detach this client from the remote endpoint.

Return type:

None

shutdown(reason='owner shutdown')

Request owner-level shutdown of the remote environment endpoint.

Parameters:

reason (str)

Return type:

bool

Vector Environment Base

class rlmesh._client.RemoteVectorEnvBase

Bases: ViewerMixin, Generic[ValueT, ActionT]

Base class for backend-specific vector-environment remote clients.

Backend modules such as rlmesh.numpy and rlmesh.torch configure the value bridge. User code should normally instantiate those concrete backends instead of this base class.

Parameters:

• address – Endpoint address such as "tcp://127.0.0.1:5555".

• host – TCP host helper used when address is omitted.

• port – TCP port helper used when address is omitted.

• path – Unix socket path helper used when address is omitted.

• transport – Explicit transport selector.

__init__(address=None, *, host=None, port=None, path=None, transport=None)

Parameters:

• address (str | None)

• host (str | None)

• port (int | None)

• path (str | None)

• transport (Literal['tcp', 'unix'] | None)

Return type:

None

property address: str

Endpoint address this client is connected to.

property env_contract: EnvContract

Environment contract returned by the endpoint handshake.

property spec: EnvContract

Alias for env_contract.

property render_mode: str | None

Configured render mode reported by the endpoint.

property num_envs: int

Number of environment instances served by the endpoint.

property single_observation_space: Space[ValueT]

Observation space for one environment in the vector.

property single_action_space: Space[ActionT]

Action space for one environment in the vector.

property observation_space: Space[ValueT]

Alias for single_observation_space.

property action_space: Space[ActionT]

Alias for single_action_space.

property metadata: Mapping[str, object]

Endpoint metadata reported by the environment contract.

The wire codec degrades Gymnasium’s AutoresetMode enum to its plain string value, but Gymnasium 1.x vector consumers (for example RecordEpisodeStatistics) assert that metadata["autoreset_mode"] is an AutoresetMode instance. We restore the enum here so a Gymnasium-compliant training loop can read the server-side autoreset convention.

property observation_space_spec: SpaceSpec

Native observation space spec reported by the endpoint.

property action_space_spec: SpaceSpec

Native action space spec reported by the endpoint.

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

Reset all remote environments and decode the observations.

Parameters:

• seed (int | list[int] | None) – Optional seed or per-environment seed list.

• options (dict[str, object] | None) – Optional reset options forwarded to the vector environment.

Returns:

Batched decoded observations and reset info dictionary.

Return type:

tuple[ValueT, ResetInfo]

step(actions)

Step all remote environments with a batch of actions.

Parameters:

actions (ActionT) – Batched actions accepted by the vector endpoint.

Returns:

Batched observations, rewards, terminations, truncations, and info.

Return type:

tuple[ValueT, ValueT, ValueT, ValueT, StepInfo]

render(*, env_index=0)

Render a frame from one environment in the vector.

Parameters:

env_index (int) – Environment index to render.

Returns:

A decoded render frame, or None when the environment has no frame.

Return type:

ValueT | None

close()

Detach this client from the remote endpoint.

Return type:

None

shutdown(reason='owner shutdown')

Request owner-level shutdown of the remote vector environment endpoint.

Parameters:

reason (str)

Return type:

bool