🚀 plugrl-env-client

plugrl-env-client runs Gymnasium environments and talks to a centralized PlugRL training server over WebSocket. It carries no deep learning dependencies, so an environment stack and a training stack never have to share a Python environment.

✨ Features

• No deep learning dependencies: The policy stays on the server. The base install declares eight runtime dependencies - gymnasium, websockets and msgpack do the environment and wire work, next to loguru, dm-tree, tyro, plugrl-protocol and imageio - and none of them is a deep learning framework, so environments pinned to old mujoco-py or cython<3 can be used with a modern training stack. Recording videos needs the video extra, which adds ffmpeg. Correction: this line previously said the client needs "only gymnasium, websockets and msgpack", which named three of the nine then declared. Two of those nine have since left the base install. pandas was never imported, and imageio[ffmpeg] became imageio, with ffmpeg moved to video. E45 measured them at 45 MB and 77 MB of the 222 MB install (plugrl-server/experiments/e45-env-side-footprint/).
• Distributed communication: websockets plus msgpack for asynchronous transfer between the server and any number of env clients, across machines.
• Modular design: Separates the environment-side runtime (plugrl-env-client) from the shared protocol layer (plugrl-protocol).
• Command-line interface: A tyro-powered CLI for starting and managing env clients.
• Gymnasium integration: Works with standard Gymnasium environments.

---

🛠️ Installation

The easiest way to get started is by cloning the repository and using uv to manage the environment.

1. Clone the repository:

   git clone https://github.com/PlugRL/plugrl-env-client.git
   cd plugrl-env-client

2. Install dependencies:

   Option A: Use uv (recommended)

   uv sync

   Option B: Editable install with pip

   pip install -e .

3. Install Optional Environment Dependencies

   Most people want mujoco and nothing else - it is the environment the quickstart uses, and the only one here that is dense-reward continuous control needing no assets, no display and no GPU:

   uv sync --extra mujoco

   The six extras do not all go in one environment, because they need different MuJoCo versions:

   • mujoco, classic, atari and d4rl share one, on gymnasium's MuJoCo 3:

     uv sync --extra mujoco --extra classic --extra atari --extra d4rl

   • robomimic and libero each need robosuite 1.4.1 with MuJoCo 2.3.7, which is what the LIBERO experiments ran on. Give each an environment of its own, in a separate checkout:

     uv sync --extra robomimic   # or: uv sync --extra libero

   pyproject.toml declares mujoco in conflict with the other two, so uv refuses to combine them rather than resolving one MuJoCo for both. With pip, keep the two sets in separate virtual environments.

   Correction: this section used to give one command for all six extras. It could not produce a working environment: robosuite 1.4.1 rejects MuJoCo 3, and the mujoco extra needs it. Neither was the lock resolving them correctly. It still held robomimic 0.3.0 after the extra moved to 0.4.0, and resolving it again would have put MuJoCo 2.3.7 under mujoco too.

   The robomimic extra is not a light install. E1 measures it at 7.2G with 16 CUDA wheels, because robomimic ships its own policy learning code.

   video goes with any of them. The recorder needs it for mp4 output (--recorder.record-video, --recorder.record-full-rollout); its PNG snapshots need only the base install.

   Note: robomimic and libero pull in egl-probe, whose legacy CMake build needs CMAKE_POLICY_VERSION_MINIMUM=3.5 when using CMake 4+. uv is configured in this repository to apply that automatically. If you install with pip, set the variable manually, e.g.

   CMAKE_POLICY_VERSION_MINIMUM=3.5 pip install -e ".[libero]"

🚀 Usage

The plugrl-run-env-client tool launches one or more env client processes for specific environments.

Note: plugrl-run-worker is kept as a backwards-compatible alias.

Basic Syntax

uv run plugrl-run-env-client <ENVIRONMENT_TYPE> [OPTIONS]

Available Environments

Type	Extra required	Description
dummy-v1	—	Dummy environment for protocol and connectivity tests
mujoco-v1	mujoco	Gymnasium MuJoCo control, default HalfCheetah-v5
classic-v1	classic	Classic control environments (e.g. CartPole)
atari-v1	atari	Atari games via ALE
d4rl-v1	d4rl	D4RL locomotion tasks
robomimic-v1	robomimic	RoboMimic robotic manipulation
libero-v1	libero	LIBERO manipulation benchmark

An environment whose extra is not installed reports which extra it needs.

mujoco-v1 is the one to reach for first. It is dense-reward continuous control that needs no assets, no display and no GPU, and its default task HalfCheetah-v5 has a 17-dimensional observation and a 6-dimensional action

• exactly plugrl-server's fpo-policy defaults, so the pair runs with no configuration. It renders only with --env.render; a state-only policy never looks at the frames, and producing them costs more per step than the physics does.

uv sync --extra mujoco
uv run plugrl-run-env-client mujoco-v1 --num-envs 1 --num-episodes 600 \
    --runner.replan-steps 1 --runner.seed 0

Examples

Run the dummy-v1 environment with custom parameters:

# Run 100 episodes
uv run plugrl-run-env-client dummy-v1 --num-episodes 100

# Run with custom environment settings (64x64 image, 4-dim action space)
uv run plugrl-run-env-client dummy-v1 --env.img-width 64 --env.img-height 64 --env.action-dim 4

This example used to carry --log-level debug, which the env client has never had - the flag exists on plugrl-run-server, and the line was copied from there. There is no verbosity flag on this side. tests/test_documented_commands.py now runs every command on this page through the parser, which is how that was found.

Get More Help

To see all available options for a specific environment:

uv run plugrl-run-env-client dummy-v1 --help