🚀 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 nine runtime dependencies - gymnasium, websockets and msgpack do the environment and wire work, next to loguru, dm-tree, tyro, plugrl-protocol, pandas and imageio[ffmpeg] - 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. E1 measures that bare install at 30 packages and 224M on Linux with no CUDA wheels (plugrl-server/experiments/e1-dependency-conflict/, round 4). Correction: this line previously said the client needs "only gymnasium, websockets and msgpack", which named three of the nine declared dependencies. pandas is declared but is not imported anywhere in src/ today - it is weight in the install, not a requirement of the runtime.
• 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

   All six extras, with uv:

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

   pip install -e ".[mujoco, robomimic, atari, classic, libero, d4rl]"
   

   Correction: these two lines were labelled "Everything" but listed only five of the six extras pyproject.toml declares - d4rl was missing, while the environment table below names it as the extra for d4rl-v1. Against the committed uv.lock, all six resolve to 100 packages and the old five to 97 (uv sync --frozen --dry-run, uv 0.9.8): robomimic already carries d4rl and mujoco-py, so the d4rl extra itself adds gymnasium-robotics, mujoco-py-cython3 and pettingzoo. Note that "all six" is not a light install - E1 measures the env client with the robomimic extra at 7.2G with 16 CUDA wheels, because robomimic ships its own policy learning code.

   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