Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/cartpole.png filter=lfs diff=lfs merge=lfs -text
+assets/quadruped.png filter=lfs diff=lfs merge=lfs -text
+envs/dm_control_env/assets/cartpole.png filter=lfs diff=lfs merge=lfs -text
+envs/dm_control_env/assets/quadruped.png filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,75 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build for dm_control environment
+# Uses pip for package installation
+
+FROM python:3.11-slim AS builder
+
+WORKDIR /app
+
+# Install build dependencies including OpenGL for MuJoCo
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    git \
+    libgl1 \
+    libglx-mesa0 \
+    libglew-dev \
+    libosmesa6-dev \
+    libgl1-mesa-dev \
+    libglfw3 \
+    patchelf \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy environment code
+COPY . /app/env
+
+WORKDIR /app/env
+
+# Install dependencies using pip
+RUN pip install --upgrade pip && \
+    pip install --no-cache-dir -e .
+
+# Final runtime stage
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install runtime dependencies (OpenGL for MuJoCo rendering, curl for healthcheck)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    libgl1 \
+    libglx-mesa0 \
+    libglew-dev \
+    libosmesa6-dev \
+    libglfw3 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy installed packages from builder
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy the environment code
+COPY . /app/env
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env"
+
+# Set MuJoCo to use OSMesa for headless rendering
+ENV MUJOCO_GL="osmesa"
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# Use exec to replace the shell with uvicorn so it receives SIGINT/SIGTERM directly
+CMD ["sh", "-c", "cd /app/env && exec uvicorn server.app:app --host 0.0.0.0 --port 8000"]
+
+ENV ENABLE_WEB_INTERFACE=true

README.md

@@ -1,10 +1,183 @@
 ---
-title: Dm Control Env-v2-1-0
-emoji: ⚡
+title: dm_control Environment Server
+emoji: 🤖
 colorFrom: blue
-colorTo: purple
+colorTo: green
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Hugging Face Space Deployment
+
+This Space is built from OpenEnv environment `dm_control_env`.
+
+- Space URL: `https://huggingface.co/spaces/openenv/dm_control_env-v2-1-0`
+- OpenEnv pinned ref: `v2.1.0`
+- Hub tag: `openenv`
+
+### Connecting from Code
+
+```python
+from envs.dm_control_env import Env
+
+env = Env(base_url="https://huggingface.co/spaces/openenv/dm_control_env-v2-1-0")
+```
+
+# dm_control OpenEnv Environment
+
+A generic OpenEnv environment for [dm_control.suite](https://github.com/google-deepmind/dm_control), providing access to all MuJoCo-based continuous control tasks.
+
+<p align="center">
+  <img src="assets/cartpole.png" width="45%" alt="Cartpole Balance"/>
+  <img src="assets/quadruped.png" width="45%" alt="Quadruped Walk"/>
+</p>
+
+## Supported Environments
+
+| Domain | Tasks |
+|--------|-------|
+| cartpole | balance, swingup, swingup_sparse |
+| walker | stand, walk, run |
+| humanoid | stand, walk, run |
+| cheetah | run |
+| hopper | stand, hop |
+| reacher | easy, hard |
+| pendulum | swingup |
+| finger | spin, turn_easy, turn_hard |
+| fish | upright, swim |
+| ball_in_cup | catch |
+| And more... | See `dm_control.suite.BENCHMARKING` |
+
+## Quick Start
+
+### Using the Client
+
+```python
+from envs.dm_control_env import DMControlEnv, DMControlAction
+
+# Connect to a running server
+with DMControlEnv(base_url="http://localhost:8000") as env:
+    # Reset with default (cartpole/balance)
+    result = env.reset()
+    print(f"Observations: {result.observation.observations.keys()}")
+
+    # Take actions
+    for _ in range(100):
+        action = DMControlAction(values=[0.5])  # Push cart right
+        result = env.step(action)
+        print(f"Reward: {result.reward}, Done: {result.done}")
+
+        if result.done:
+            result = env.reset()
+```
+
+### Switching Environments
+
+```python
+# Start with cartpole
+result = env.reset(domain_name="cartpole", task_name="balance")
+
+# Switch to walker (on next reset)
+result = env.reset(domain_name="walker", task_name="walk")
+# Note: walker has 6 action dimensions
+action = DMControlAction(values=[0.0] * 6)
+result = env.step(action)
+```
+
+### Running the Server
+
+```bash
+# From OpenEnv root
+cd envs/dm_control_env
+uvicorn server.app:app --host 0.0.0.0 --port 8000
+
+# Or using uv
+uv run --project . server
+```
+
+### Using Docker
+
+```bash
+# Build
+docker build -t dm_control:latest -f server/Dockerfile .
+
+# Run
+docker run -p 8000:8000 dm_control:latest
+```
+
+## API
+
+### Action
+
+```python
+class DMControlAction(Action):
+    values: List[float]  # Continuous action values
+```
+
+Action dimensions vary by environment:
+- cartpole: 1 (force on cart)
+- walker: 6 (joint torques)
+- humanoid: 21 (joint torques)
+
+### Observation
+
+```python
+class DMControlObservation(Observation):
+    observations: Dict[str, List[float]]  # Named observation arrays
+    pixels: Optional[str]  # Base64 PNG (if render=True)
+    reward: float
+    done: bool
+```
+
+### State
+
+```python
+class DMControlState(State):
+    domain_name: str
+    task_name: str
+    action_spec: Dict[str, Any]
+    observation_spec: Dict[str, Any]
+    physics_timestep: float
+    control_timestep: float
+    episode_id: str
+    step_count: int
+```
+
+## Examples
+
+See the `examples/` directory:
+- `cartpole_control.py` - Interactive cartpole control with arrow keys
+- `hopper_control.py` - Interactive hopper control with spacebar for random forces
+- `quadruped_control.py` - Interactive quadruped control with spacebar for random forces
+- `list_environments.py` - Print all available environments
+
+All examples support consistent CLI arguments:
+
+```bash
+# Default: interactive mode with minimal pygame window
+python examples/cartpole_control.py
+
+# Visual mode with rendered MuJoCo frames
+python examples/cartpole_control.py --visual
+
+# Headless mode (no pygame, automated control)
+python examples/cartpole_control.py --headless --max-steps 500
+
+# Select a different task
+python examples/cartpole_control.py --task swingup
+python examples/hopper_control.py --task stand
+python examples/quadruped_control.py --task run
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DMCONTROL_DOMAIN` | cartpole | Default domain |
+| `DMCONTROL_TASK` | balance | Default task |
+| `DMCONTROL_RENDER_HEIGHT` | 480 | Render height |
+| `DMCONTROL_RENDER_WIDTH` | 640 | Render width |

__init__.py

@@ -0,0 +1,14 @@
+"""dm_control OpenEnv Environment.
+
+A generic OpenEnv environment for dm_control.suite supporting all domains/tasks.
+"""
+
+from .models import DMControlAction, DMControlObservation, DMControlState
+from .client import DMControlEnv
+
+__all__ = [
+    "DMControlAction",
+    "DMControlObservation",
+    "DMControlState",
+    "DMControlEnv",
+]

client.py

@@ -0,0 +1,375 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+dm_control Environment Client.
+
+This module provides the client for connecting to a dm_control
+Environment server via WebSocket for persistent sessions.
+"""
+
+from typing import Any, Dict, List, Optional, Tuple
+
+try:
+    from openenv.core.client_types import StepResult
+    from openenv.core.env_client import EnvClient
+
+    from .models import (
+        AVAILABLE_ENVIRONMENTS,
+        DMControlAction,
+        DMControlObservation,
+        DMControlState,
+    )
+except ImportError:
+    from openenv.core.client_types import StepResult
+    from openenv.core.env_client import EnvClient
+
+    try:
+        from models import (
+            AVAILABLE_ENVIRONMENTS,
+            DMControlAction,
+            DMControlObservation,
+            DMControlState,
+        )
+    except ImportError:
+        try:
+            from dm_control_env.models import (
+                AVAILABLE_ENVIRONMENTS,
+                DMControlAction,
+                DMControlObservation,
+                DMControlState,
+            )
+        except ImportError:
+            from envs.dm_control_env.models import (
+                AVAILABLE_ENVIRONMENTS,
+                DMControlAction,
+                DMControlObservation,
+                DMControlState,
+            )
+
+
+class DMControlEnv(EnvClient[DMControlAction, DMControlObservation, DMControlState]):
+    """
+    Client for dm_control.suite environments.
+
+    This client maintains a persistent WebSocket connection to the environment
+    server, enabling efficient multi-step interactions with lower latency.
+
+    Supported Environments (via dm_control.suite):
+    - cartpole: balance, swingup, swingup_sparse
+    - walker: stand, walk, run
+    - humanoid: stand, walk, run
+    - cheetah: run
+    - hopper: stand, hop
+    - reacher: easy, hard
+    - And many more...
+
+    Example:
+        >>> # Connect to a running server
+        >>> with DMControlEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(f"Observations: {result.observation.observations.keys()}")
+        ...
+        ...     # Take action (cartpole: push right)
+        ...     result = client.step(DMControlAction(values=[0.5]))
+        ...     print(f"Reward: {result.reward}")
+
+    Example switching environments:
+        >>> client = DMControlEnv(base_url="http://localhost:8000")
+        >>> # Start with cartpole balance
+        >>> result = client.reset(domain_name="cartpole", task_name="balance")
+        >>> # ... train on cartpole ...
+        >>> # Switch to walker walk
+        >>> result = client.reset(domain_name="walker", task_name="walk")
+        >>> # ... train on walker ...
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        connect_timeout_s: float = 10.0,
+        message_timeout_s: float = 60.0,
+        provider: Optional[Any] = None,
+    ):
+        """
+        Initialize dm_control environment client.
+
+        Args:
+            base_url: Base URL of the environment server (http:// or ws://).
+            connect_timeout_s: Timeout for establishing WebSocket connection.
+            message_timeout_s: Timeout for receiving responses.
+            provider: Optional container/runtime provider for lifecycle management.
+        """
+        super().__init__(
+            base_url=base_url,
+            connect_timeout_s=connect_timeout_s,
+            message_timeout_s=message_timeout_s,
+            provider=provider,
+        )
+
+    def _step_payload(self, action: DMControlAction) -> Dict:
+        """
+        Convert DMControlAction to JSON payload for step request.
+
+        Args:
+            action: DMControlAction instance
+
+        Returns:
+            Dictionary representation suitable for JSON encoding
+        """
+        payload: Dict[str, Any] = {"values": action.values}
+
+        if action.metadata:
+            payload["metadata"] = action.metadata
+
+        return payload
+
+    def _parse_result(self, payload: Dict) -> StepResult[DMControlObservation]:
+        """
+        Parse server response into StepResult[DMControlObservation].
+
+        Args:
+            payload: JSON response from server
+
+        Returns:
+            StepResult with DMControlObservation
+        """
+        obs_data = payload.get("observation", {})
+
+        observation = DMControlObservation(
+            observations=obs_data.get("observations", {}),
+            pixels=obs_data.get("pixels"),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            metadata=obs_data.get("metadata", {}),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> DMControlState:
+        """
+        Parse server response into DMControlState object.
+
+        Args:
+            payload: JSON response from /state endpoint
+
+        Returns:
+            DMControlState object with environment information
+        """
+        return DMControlState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            domain_name=payload.get("domain_name", ""),
+            task_name=payload.get("task_name", ""),
+            action_spec=payload.get("action_spec", {}),
+            observation_spec=payload.get("observation_spec", {}),
+            physics_timestep=payload.get("physics_timestep", 0.002),
+            control_timestep=payload.get("control_timestep", 0.02),
+        )
+
+    def reset(
+        self,
+        domain_name: Optional[str] = None,
+        task_name: Optional[str] = None,
+        seed: Optional[int] = None,
+        render: bool = False,
+        **kwargs,
+    ) -> StepResult[DMControlObservation]:
+        """
+        Reset the environment.
+
+        Args:
+            domain_name: Optionally switch to a different domain.
+            task_name: Optionally switch to a different task.
+            seed: Random seed for reproducibility.
+            render: If True, include pixel observations in response.
+            **kwargs: Additional arguments passed to server.
+
+        Returns:
+            StepResult with initial observation.
+        """
+        reset_kwargs = dict(kwargs)
+        if domain_name is not None:
+            reset_kwargs["domain_name"] = domain_name
+        if task_name is not None:
+            reset_kwargs["task_name"] = task_name
+        if seed is not None:
+            reset_kwargs["seed"] = seed
+        reset_kwargs["render"] = render
+
+        return super().reset(**reset_kwargs)
+
+    def step(
+        self,
+        action: DMControlAction,
+        render: bool = False,
+        **kwargs,
+    ) -> StepResult[DMControlObservation]:
+        """
+        Execute one step in the environment.
+
+        Args:
+            action: DMControlAction with continuous action values.
+            render: If True, include pixel observations in response.
+            **kwargs: Additional arguments passed to server.
+
+        Returns:
+            StepResult with new observation, reward, and done flag.
+        """
+        # Note: render flag needs to be passed differently
+        # For now, the server remembers the render setting from reset
+        return super().step(action, **kwargs)
+
+    @staticmethod
+    def available_environments() -> List[Tuple[str, str]]:
+        """
+        List available dm_control environments.
+
+        Returns:
+            List of (domain_name, task_name) tuples.
+        """
+        return AVAILABLE_ENVIRONMENTS
+
+    @classmethod
+    def from_direct(
+        cls,
+        domain_name: str = "cartpole",
+        task_name: str = "balance",
+        render_height: int = 480,
+        render_width: int = 640,
+        port: int = 8765,
+    ) -> "DMControlEnv":
+        """
+        Create a dm_control environment client with an embedded local server.
+
+        This method starts a local uvicorn server in a subprocess and returns
+        a client connected to it.
+
+        Args:
+            domain_name: Default domain to use.
+            task_name: Default task to use.
+            render_height: Height of rendered images.
+            render_width: Width of rendered images.
+            port: Port for the local server.
+
+        Returns:
+            DMControlEnv client connected to the local server.
+
+        Example:
+            >>> client = DMControlEnv.from_direct(domain_name="walker", task_name="walk")
+            >>> try:
+            ...     result = client.reset()
+            ...     for _ in range(100):
+            ...         result = client.step(DMControlAction(values=[0.0] * 6))
+            ... finally:
+            ...     client.close()
+        """
+        import os
+        import subprocess
+        import sys
+        import time
+
+        import requests
+
+        try:
+            from pathlib import Path
+
+            client_dir = Path(__file__).parent
+            server_app = "envs.dm_control_env.server.app:app"
+            cwd = client_dir.parent.parent
+
+            if not (cwd / "envs" / "dm_control_env" / "server" / "app.py").exists():
+                if (client_dir / "server" / "app.py").exists():
+                    server_app = "server.app:app"
+                    cwd = client_dir
+        except Exception:
+            server_app = "envs.dm_control_env.server.app:app"
+            cwd = None
+
+        env = {
+            **os.environ,
+            "DMCONTROL_DOMAIN": domain_name,
+            "DMCONTROL_TASK": task_name,
+            "DMCONTROL_RENDER_HEIGHT": str(render_height),
+            "DMCONTROL_RENDER_WIDTH": str(render_width),
+            "NO_PROXY": "localhost,127.0.0.1",
+            "no_proxy": "localhost,127.0.0.1",
+        }
+
+        if cwd:
+            src_path = str(cwd / "src")
+            existing_path = env.get("PYTHONPATH", "")
+            env["PYTHONPATH"] = (
+                f"{src_path}:{cwd}:{existing_path}"
+                if existing_path
+                else f"{src_path}:{cwd}"
+            )
+
+        cmd = [
+            sys.executable,
+            "-m",
+            "uvicorn",
+            server_app,
+            "--host",
+            "127.0.0.1",
+            "--port",
+            str(port),
+        ]
+
+        server_process = subprocess.Popen(
+            cmd,
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            cwd=str(cwd) if cwd else None,
+        )
+
+        base_url = f"http://127.0.0.1:{port}"
+        healthy = False
+        for _ in range(30):
+            try:
+                response = requests.get(
+                    f"{base_url}/health",
+                    timeout=2,
+                    proxies={"http": None, "https": None},
+                )
+                if response.status_code == 200:
+                    healthy = True
+                    break
+            except requests.exceptions.RequestException:
+                pass
+            time.sleep(1)
+
+        if not healthy:
+            server_process.kill()
+            raise RuntimeError(
+                f"Failed to start local dm_control server on port {port}. "
+                "Check that the port is available and dependencies are installed."
+            )
+
+        class DirectModeProvider:
+            """Provider that manages the embedded server subprocess."""
+
+            def __init__(self, process: subprocess.Popen):
+                self._process = process
+
+            def stop(self):
+                """Stop the embedded server."""
+                if self._process:
+                    self._process.terminate()
+                    try:
+                        self._process.wait(timeout=10)
+                    except subprocess.TimeoutExpired:
+                        self._process.kill()
+                    self._process = None
+
+        provider = DirectModeProvider(server_process)
+        client = cls(base_url=base_url, provider=provider)
+        return client

envs/dm_control_env/README.md

@@ -0,0 +1,167 @@
+---
+title: dm_control Environment Server
+emoji: 🤖
+colorFrom: green
+colorTo: blue
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# dm_control OpenEnv Environment
+
+A generic OpenEnv environment for [dm_control.suite](https://github.com/google-deepmind/dm_control), providing access to all MuJoCo-based continuous control tasks.
+
+<p align="center">
+  <img src="assets/cartpole.png" width="45%" alt="Cartpole Balance"/>
+  <img src="assets/quadruped.png" width="45%" alt="Quadruped Walk"/>
+</p>
+
+## Supported Environments
+
+| Domain | Tasks |
+|--------|-------|
+| cartpole | balance, swingup, swingup_sparse |
+| walker | stand, walk, run |
+| humanoid | stand, walk, run |
+| cheetah | run |
+| hopper | stand, hop |
+| reacher | easy, hard |
+| pendulum | swingup |
+| finger | spin, turn_easy, turn_hard |
+| fish | upright, swim |
+| ball_in_cup | catch |
+| And more... | See `dm_control.suite.BENCHMARKING` |
+
+## Quick Start
+
+### Using the Client
+
+```python
+from envs.dm_control_env import DMControlEnv, DMControlAction
+
+# Connect to a running server
+with DMControlEnv(base_url="http://localhost:8000") as env:
+    # Reset with default (cartpole/balance)
+    result = env.reset()
+    print(f"Observations: {result.observation.observations.keys()}")
+
+    # Take actions
+    for _ in range(100):
+        action = DMControlAction(values=[0.5])  # Push cart right
+        result = env.step(action)
+        print(f"Reward: {result.reward}, Done: {result.done}")
+
+        if result.done:
+            result = env.reset()
+```
+
+### Switching Environments
+
+```python
+# Start with cartpole
+result = env.reset(domain_name="cartpole", task_name="balance")
+
+# Switch to walker (on next reset)
+result = env.reset(domain_name="walker", task_name="walk")
+# Note: walker has 6 action dimensions
+action = DMControlAction(values=[0.0] * 6)
+result = env.step(action)
+```
+
+### Running the Server
+
+```bash
+# From OpenEnv root
+cd envs/dm_control_env
+uvicorn server.app:app --host 0.0.0.0 --port 8000
+
+# Or using uv
+uv run --project . server
+```
+
+### Using Docker
+
+```bash
+# Build
+docker build -t dm_control:latest -f server/Dockerfile .
+
+# Run
+docker run -p 8000:8000 dm_control:latest
+```
+
+## API
+
+### Action
+
+```python
+class DMControlAction(Action):
+    values: List[float]  # Continuous action values
+```
+
+Action dimensions vary by environment:
+- cartpole: 1 (force on cart)
+- walker: 6 (joint torques)
+- humanoid: 21 (joint torques)
+
+### Observation
+
+```python
+class DMControlObservation(Observation):
+    observations: Dict[str, List[float]]  # Named observation arrays
+    pixels: Optional[str]  # Base64 PNG (if render=True)
+    reward: float
+    done: bool
+```
+
+### State
+
+```python
+class DMControlState(State):
+    domain_name: str
+    task_name: str
+    action_spec: Dict[str, Any]
+    observation_spec: Dict[str, Any]
+    physics_timestep: float
+    control_timestep: float
+    episode_id: str
+    step_count: int
+```
+
+## Examples
+
+See the `examples/` directory:
+- `cartpole_control.py` - Interactive cartpole control with arrow keys
+- `hopper_control.py` - Interactive hopper control with spacebar for random forces
+- `quadruped_control.py` - Interactive quadruped control with spacebar for random forces
+- `list_environments.py` - Print all available environments
+
+All examples support consistent CLI arguments:
+
+```bash
+# Default: interactive mode with minimal pygame window
+python examples/cartpole_control.py
+
+# Visual mode with rendered MuJoCo frames
+python examples/cartpole_control.py --visual
+
+# Headless mode (no pygame, automated control)
+python examples/cartpole_control.py --headless --max-steps 500
+
+# Select a different task
+python examples/cartpole_control.py --task swingup
+python examples/hopper_control.py --task stand
+python examples/quadruped_control.py --task run
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DMCONTROL_DOMAIN` | cartpole | Default domain |
+| `DMCONTROL_TASK` | balance | Default task |
+| `DMCONTROL_RENDER_HEIGHT` | 480 | Render height |
+| `DMCONTROL_RENDER_WIDTH` | 640 | Render width |

envs/dm_control_env/__init__.py

@@ -0,0 +1,14 @@
+"""dm_control OpenEnv Environment.
+
+A generic OpenEnv environment for dm_control.suite supporting all domains/tasks.
+"""
+
+from .models import DMControlAction, DMControlObservation, DMControlState
+from .client import DMControlEnv
+
+__all__ = [
+    "DMControlAction",
+    "DMControlObservation",
+    "DMControlState",
+    "DMControlEnv",
+]

envs/dm_control_env/client.py

@@ -0,0 +1,375 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+dm_control Environment Client.
+
+This module provides the client for connecting to a dm_control
+Environment server via WebSocket for persistent sessions.
+"""
+
+from typing import Any, Dict, List, Optional, Tuple
+
+try:
+    from openenv.core.client_types import StepResult
+    from openenv.core.env_client import EnvClient
+
+    from .models import (
+        AVAILABLE_ENVIRONMENTS,
+        DMControlAction,
+        DMControlObservation,
+        DMControlState,
+    )
+except ImportError:
+    from openenv.core.client_types import StepResult
+    from openenv.core.env_client import EnvClient
+
+    try:
+        from models import (
+            AVAILABLE_ENVIRONMENTS,
+            DMControlAction,
+            DMControlObservation,
+            DMControlState,
+        )
+    except ImportError:
+        try:
+            from dm_control_env.models import (
+                AVAILABLE_ENVIRONMENTS,
+                DMControlAction,
+                DMControlObservation,
+                DMControlState,
+            )
+        except ImportError:
+            from envs.dm_control_env.models import (
+                AVAILABLE_ENVIRONMENTS,
+                DMControlAction,
+                DMControlObservation,
+                DMControlState,
+            )
+
+
+class DMControlEnv(EnvClient[DMControlAction, DMControlObservation, DMControlState]):
+    """
+    Client for dm_control.suite environments.
+
+    This client maintains a persistent WebSocket connection to the environment
+    server, enabling efficient multi-step interactions with lower latency.
+
+    Supported Environments (via dm_control.suite):
+    - cartpole: balance, swingup, swingup_sparse
+    - walker: stand, walk, run
+    - humanoid: stand, walk, run
+    - cheetah: run
+    - hopper: stand, hop
+    - reacher: easy, hard
+    - And many more...
+
+    Example:
+        >>> # Connect to a running server
+        >>> with DMControlEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(f"Observations: {result.observation.observations.keys()}")
+        ...
+        ...     # Take action (cartpole: push right)
+        ...     result = client.step(DMControlAction(values=[0.5]))
+        ...     print(f"Reward: {result.reward}")
+
+    Example switching environments:
+        >>> client = DMControlEnv(base_url="http://localhost:8000")
+        >>> # Start with cartpole balance
+        >>> result = client.reset(domain_name="cartpole", task_name="balance")
+        >>> # ... train on cartpole ...
+        >>> # Switch to walker walk
+        >>> result = client.reset(domain_name="walker", task_name="walk")
+        >>> # ... train on walker ...
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        connect_timeout_s: float = 10.0,
+        message_timeout_s: float = 60.0,
+        provider: Optional[Any] = None,
+    ):
+        """
+        Initialize dm_control environment client.
+
+        Args:
+            base_url: Base URL of the environment server (http:// or ws://).
+            connect_timeout_s: Timeout for establishing WebSocket connection.
+            message_timeout_s: Timeout for receiving responses.
+            provider: Optional container/runtime provider for lifecycle management.
+        """
+        super().__init__(
+            base_url=base_url,
+            connect_timeout_s=connect_timeout_s,
+            message_timeout_s=message_timeout_s,
+            provider=provider,
+        )
+
+    def _step_payload(self, action: DMControlAction) -> Dict:
+        """
+        Convert DMControlAction to JSON payload for step request.
+
+        Args:
+            action: DMControlAction instance
+
+        Returns:
+            Dictionary representation suitable for JSON encoding
+        """
+        payload: Dict[str, Any] = {"values": action.values}
+
+        if action.metadata:
+            payload["metadata"] = action.metadata
+
+        return payload
+
+    def _parse_result(self, payload: Dict) -> StepResult[DMControlObservation]:
+        """
+        Parse server response into StepResult[DMControlObservation].
+
+        Args:
+            payload: JSON response from server
+
+        Returns:
+            StepResult with DMControlObservation
+        """
+        obs_data = payload.get("observation", {})
+
+        observation = DMControlObservation(
+            observations=obs_data.get("observations", {}),
+            pixels=obs_data.get("pixels"),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            metadata=obs_data.get("metadata", {}),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> DMControlState:
+        """
+        Parse server response into DMControlState object.
+
+        Args:
+            payload: JSON response from /state endpoint
+
+        Returns:
+            DMControlState object with environment information
+        """
+        return DMControlState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            domain_name=payload.get("domain_name", ""),
+            task_name=payload.get("task_name", ""),
+            action_spec=payload.get("action_spec", {}),
+            observation_spec=payload.get("observation_spec", {}),
+            physics_timestep=payload.get("physics_timestep", 0.002),
+            control_timestep=payload.get("control_timestep", 0.02),
+        )
+
+    def reset(
+        self,
+        domain_name: Optional[str] = None,
+        task_name: Optional[str] = None,
+        seed: Optional[int] = None,
+        render: bool = False,
+        **kwargs,
+    ) -> StepResult[DMControlObservation]:
+        """
+        Reset the environment.
+
+        Args:
+            domain_name: Optionally switch to a different domain.
+            task_name: Optionally switch to a different task.
+            seed: Random seed for reproducibility.
+            render: If True, include pixel observations in response.
+            **kwargs: Additional arguments passed to server.
+
+        Returns:
+            StepResult with initial observation.
+        """
+        reset_kwargs = dict(kwargs)
+        if domain_name is not None:
+            reset_kwargs["domain_name"] = domain_name
+        if task_name is not None:
+            reset_kwargs["task_name"] = task_name
+        if seed is not None:
+            reset_kwargs["seed"] = seed
+        reset_kwargs["render"] = render
+
+        return super().reset(**reset_kwargs)
+
+    def step(
+        self,
+        action: DMControlAction,
+        render: bool = False,
+        **kwargs,
+    ) -> StepResult[DMControlObservation]:
+        """
+        Execute one step in the environment.
+
+        Args:
+            action: DMControlAction with continuous action values.
+            render: If True, include pixel observations in response.
+            **kwargs: Additional arguments passed to server.
+
+        Returns:
+            StepResult with new observation, reward, and done flag.
+        """
+        # Note: render flag needs to be passed differently
+        # For now, the server remembers the render setting from reset
+        return super().step(action, **kwargs)
+
+    @staticmethod
+    def available_environments() -> List[Tuple[str, str]]:
+        """
+        List available dm_control environments.
+
+        Returns:
+            List of (domain_name, task_name) tuples.
+        """
+        return AVAILABLE_ENVIRONMENTS
+
+    @classmethod
+    def from_direct(
+        cls,
+        domain_name: str = "cartpole",
+        task_name: str = "balance",
+        render_height: int = 480,
+        render_width: int = 640,
+        port: int = 8765,
+    ) -> "DMControlEnv":
+        """
+        Create a dm_control environment client with an embedded local server.
+
+        This method starts a local uvicorn server in a subprocess and returns
+        a client connected to it.
+
+        Args:
+            domain_name: Default domain to use.
+            task_name: Default task to use.
+            render_height: Height of rendered images.
+            render_width: Width of rendered images.
+            port: Port for the local server.
+
+        Returns:
+            DMControlEnv client connected to the local server.
+
+        Example:
+            >>> client = DMControlEnv.from_direct(domain_name="walker", task_name="walk")
+            >>> try:
+            ...     result = client.reset()
+            ...     for _ in range(100):
+            ...         result = client.step(DMControlAction(values=[0.0] * 6))
+            ... finally:
+            ...     client.close()
+        """
+        import os
+        import subprocess
+        import sys
+        import time
+
+        import requests
+
+        try:
+            from pathlib import Path
+
+            client_dir = Path(__file__).parent
+            server_app = "envs.dm_control_env.server.app:app"
+            cwd = client_dir.parent.parent
+
+            if not (cwd / "envs" / "dm_control_env" / "server" / "app.py").exists():
+                if (client_dir / "server" / "app.py").exists():
+                    server_app = "server.app:app"
+                    cwd = client_dir
+        except Exception:
+            server_app = "envs.dm_control_env.server.app:app"
+            cwd = None
+
+        env = {
+            **os.environ,
+            "DMCONTROL_DOMAIN": domain_name,
+            "DMCONTROL_TASK": task_name,
+            "DMCONTROL_RENDER_HEIGHT": str(render_height),
+            "DMCONTROL_RENDER_WIDTH": str(render_width),
+            "NO_PROXY": "localhost,127.0.0.1",
+            "no_proxy": "localhost,127.0.0.1",
+        }
+
+        if cwd:
+            src_path = str(cwd / "src")
+            existing_path = env.get("PYTHONPATH", "")
+            env["PYTHONPATH"] = (
+                f"{src_path}:{cwd}:{existing_path}"
+                if existing_path
+                else f"{src_path}:{cwd}"
+            )
+
+        cmd = [
+            sys.executable,
+            "-m",
+            "uvicorn",
+            server_app,
+            "--host",
+            "127.0.0.1",
+            "--port",
+            str(port),
+        ]
+
+        server_process = subprocess.Popen(
+            cmd,
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            cwd=str(cwd) if cwd else None,
+        )
+
+        base_url = f"http://127.0.0.1:{port}"
+        healthy = False
+        for _ in range(30):
+            try:
+                response = requests.get(
+                    f"{base_url}/health",
+                    timeout=2,
+                    proxies={"http": None, "https": None},
+                )
+                if response.status_code == 200:
+                    healthy = True
+                    break
+            except requests.exceptions.RequestException:
+                pass
+            time.sleep(1)
+
+        if not healthy:
+            server_process.kill()
+            raise RuntimeError(
+                f"Failed to start local dm_control server on port {port}. "
+                "Check that the port is available and dependencies are installed."
+            )
+
+        class DirectModeProvider:
+            """Provider that manages the embedded server subprocess."""
+
+            def __init__(self, process: subprocess.Popen):
+                self._process = process
+
+            def stop(self):
+                """Stop the embedded server."""
+                if self._process:
+                    self._process.terminate()
+                    try:
+                        self._process.wait(timeout=10)
+                    except subprocess.TimeoutExpired:
+                        self._process.kill()
+                    self._process = None
+
+        provider = DirectModeProvider(server_process)
+        client = cls(base_url=base_url, provider=provider)
+        return client

envs/dm_control_env/examples/__init__.py

@@ -0,0 +1 @@
+"""dm_control examples."""

envs/dm_control_env/examples/cartpole_control.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""Interactive cartpole control via OpenEnv.
+
+This example demonstrates using the dm_control OpenEnv client with
+the cartpole environment. Use arrow keys to control the cart.
+
+Controls:
+    LEFT/RIGHT arrows: Apply force to move cart
+    R: Reset environment
+    ESC or Q: Quit
+
+Requirements:
+    pip install pygame
+
+Usage:
+    1. Start the server: uvicorn server.app:app --host 0.0.0.0 --port 8000
+    2. Run this script: python examples/cartpole_control.py
+
+    For visual mode (requires working MuJoCo rendering):
+        python examples/cartpole_control.py --visual
+"""
+
+import argparse
+import random
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from client import DMControlEnv
+from models import DMControlAction
+
+
+def run_headless(env: DMControlEnv, task: str = "balance", max_steps: int = 500):
+    """Run cartpole control in headless mode."""
+    print("\n=== Headless Mode (OpenEnv Step/Observation Pattern) ===")
+    print("This mode demonstrates the OpenEnv API with the cartpole.\n")
+
+    # Reset environment using OpenEnv pattern
+    result = env.reset(domain_name="cartpole", task_name=task)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+    print(f"  position: {result.observation.observations.get('position', [])}")
+    print(f"  velocity: {result.observation.observations.get('velocity', [])}")
+
+    total_reward = 0.0
+    step_count = 0
+
+    print("\nRunning with random actions to demonstrate step/observation pattern...\n")
+
+    while not result.done and step_count < max_steps:
+        # Random action in [-1, 1]
+        action_value = random.uniform(-1.0, 1.0)
+
+        # Step the environment using OpenEnv pattern
+        action = DMControlAction(values=[action_value])
+        result = env.step(action)
+
+        # Access observation and reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Print progress periodically
+        if step_count % 50 == 0:
+            pos = result.observation.observations.get("position", [])
+            vel = result.observation.observations.get("velocity", [])
+            print(
+                f"Step {step_count}: reward={result.reward:.3f}, "
+                f"total={total_reward:.2f}, done={result.done}"
+            )
+            print(f"  position={pos}, velocity={vel}")
+
+    print(f"\nEpisode finished: {step_count} steps, total reward: {total_reward:.2f}")
+
+
+def run_interactive(env: DMControlEnv, task: str = "balance"):
+    """Run interactive control with keyboard input via pygame."""
+    import pygame
+
+    print("\n=== Interactive Mode (OpenEnv Step/Observation Pattern) ===")
+    print("Use LEFT/RIGHT arrows to control cart, R to reset, ESC to quit.\n")
+
+    # Reset environment using OpenEnv pattern
+    result = env.reset(domain_name="cartpole", task_name=task)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Initialize pygame for keyboard input (minimal window)
+    pygame.init()
+    screen = pygame.display.set_mode((400, 100))
+    pygame.display.set_caption("Cartpole Control - Arrow keys to move, R to reset")
+    clock = pygame.time.Clock()
+
+    # Font for display
+    font = pygame.font.Font(None, 24)
+
+    running = True
+    total_reward = 0.0
+    step_count = 0
+
+    print("\nControls:")
+    print("  LEFT/RIGHT arrows: Move cart")
+    print("  R: Reset environment")
+    print("  ESC or Q: Quit\n")
+
+    while running:
+        # Handle events
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                running = False
+            elif event.type == pygame.KEYDOWN:
+                if event.key in (pygame.K_ESCAPE, pygame.K_q):
+                    running = False
+                elif event.key == pygame.K_r:
+                    result = env.reset(domain_name="cartpole", task_name=task)
+                    total_reward = 0.0
+                    step_count = 0
+                    print("Environment reset")
+
+        # Check for held keys (for continuous control)
+        keys = pygame.key.get_pressed()
+        if keys[pygame.K_LEFT]:
+            action_value = -1.0
+        elif keys[pygame.K_RIGHT]:
+            action_value = 1.0
+        else:
+            action_value = 0.0
+
+        # Step the environment using OpenEnv pattern
+        action = DMControlAction(values=[action_value])
+        result = env.step(action)
+
+        # Track reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Check if episode is done
+        if result.done:
+            print(
+                f"Episode finished! Steps: {step_count}, "
+                f"Total reward: {total_reward:.2f}"
+            )
+            # Auto-reset on done
+            result = env.reset(domain_name="cartpole", task_name=task)
+            total_reward = 0.0
+            step_count = 0
+
+        # Update display
+        direction = (
+            "<--" if action_value < 0 else ("-->" if action_value > 0 else "---")
+        )
+        screen.fill((30, 30, 30))
+        text = font.render(
+            f"Step: {step_count} | Reward: {total_reward:.1f} | {direction}",
+            True,
+            (255, 255, 255),
+        )
+        screen.blit(text, (10, 40))
+        pygame.display.flip()
+
+        # Print progress periodically
+        if step_count % 200 == 0 and step_count > 0:
+            print(f"Step {step_count}: Total reward: {total_reward:.2f}")
+
+        # Cap at 30 FPS
+        clock.tick(30)
+
+    pygame.quit()
+    print(f"Session ended. Final reward: {total_reward:.2f}")
+
+
+def run_visual(env: DMControlEnv, task: str = "balance"):
+    """Run with pygame visualization showing rendered frames."""
+    import base64
+    import io
+
+    import pygame
+
+    print("\n=== Visual Mode (OpenEnv Step/Observation Pattern) ===")
+
+    # Reset environment with rendering enabled
+    result = env.reset(domain_name="cartpole", task_name=task, render=True)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get first frame to determine window size
+    if result.observation.pixels is None:
+        print("Error: Server did not return rendered pixels.")
+        print("Make sure the server supports render=True")
+        print("\nTry running in interactive mode (default) instead.")
+        sys.exit(1)
+
+    # Decode base64 PNG to pygame surface
+    png_data = base64.b64decode(result.observation.pixels)
+    frame = pygame.image.load(io.BytesIO(png_data))
+    frame_size = frame.get_size()
+
+    # Initialize pygame
+    pygame.init()
+    screen = pygame.display.set_mode(frame_size)
+    pygame.display.set_caption(
+        "Cartpole (OpenEnv) - Arrow Keys to Move, R to Reset, ESC to Quit"
+    )
+    clock = pygame.time.Clock()
+
+    print("Controls:")
+    print("  LEFT/RIGHT arrows: Move cart")
+    print("  R: Reset environment")
+    print("  ESC or Q: Quit")
+
+    running = True
+    total_reward = 0.0
+    step_count = 0
+
+    while running:
+        # Handle events
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                running = False
+            elif event.type == pygame.KEYDOWN:
+                if event.key in (pygame.K_ESCAPE, pygame.K_q):
+                    running = False
+                elif event.key == pygame.K_r:
+                    result = env.reset(
+                        domain_name="cartpole", task_name=task, render=True
+                    )
+                    total_reward = 0.0
+                    step_count = 0
+                    print("Environment reset")
+
+        # Check for held keys (for continuous control)
+        keys = pygame.key.get_pressed()
+        if keys[pygame.K_LEFT]:
+            action_value = -1.0
+        elif keys[pygame.K_RIGHT]:
+            action_value = 1.0
+        else:
+            action_value = 0.0
+
+        # Step the environment using OpenEnv pattern
+        action = DMControlAction(values=[action_value])
+        result = env.step(action, render=True)
+
+        # Track reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Check if episode is done
+        if result.done:
+            print(
+                f"Episode finished! Steps: {step_count}, "
+                f"Total reward: {total_reward:.2f}"
+            )
+            result = env.reset(domain_name="cartpole", task_name=task, render=True)
+            total_reward = 0.0
+            step_count = 0
+
+        # Render the frame from observation pixels
+        if result.observation.pixels:
+            png_data = base64.b64decode(result.observation.pixels)
+            frame = pygame.image.load(io.BytesIO(png_data))
+            screen.blit(frame, (0, 0))
+            pygame.display.flip()
+
+        # Print progress periodically
+        if step_count % 200 == 0 and step_count > 0:
+            print(f"Step {step_count}: Total reward: {total_reward:.2f}")
+
+        # Cap at 30 FPS
+        clock.tick(30)
+
+    pygame.quit()
+    print(f"Session ended. Final reward: {total_reward:.2f}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Interactive cartpole control via OpenEnv"
+    )
+    parser.add_argument(
+        "--visual",
+        action="store_true",
+        help="Enable pygame visualization with rendered frames",
+    )
+    parser.add_argument(
+        "--headless",
+        action="store_true",
+        help="Run in headless mode (no pygame, automated control)",
+    )
+    parser.add_argument(
+        "--max-steps",
+        type=int,
+        default=500,
+        help="Maximum steps for headless mode (default: 500)",
+    )
+    parser.add_argument(
+        "--task",
+        type=str,
+        default="balance",
+        choices=["balance", "balance_sparse", "swingup", "swingup_sparse"],
+        help="Cartpole task (default: balance)",
+    )
+    args = parser.parse_args()
+
+    server_url = "http://localhost:8000"
+    print(f"Connecting to {server_url}...")
+
+    try:
+        with DMControlEnv(base_url=server_url) as env:
+            print("Connected!")
+
+            # Get environment state
+            state = env.state()
+            print(f"Domain: {state.domain_name}, Task: {state.task_name}")
+            print(f"Action spec: {state.action_spec}")
+
+            if args.headless:
+                run_headless(env, task=args.task, max_steps=args.max_steps)
+            elif args.visual:
+                run_visual(env, task=args.task)
+            else:
+                run_interactive(env, task=args.task)
+
+    except ConnectionError as e:
+        print(f"Failed to connect: {e}")
+        print("\nMake sure the server is running:")
+        print("  cd OpenEnv")
+        print(
+            "  PYTHONPATH=src:envs uvicorn envs.dm_control_env.server.app:app --port 8000"
+        )
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

envs/dm_control_env/examples/hopper_control.py

@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+"""Interactive hopper control via OpenEnv.
+
+This example demonstrates using the dm_control OpenEnv client with
+the hopper environment. Press SPACE to apply random forces to the joints.
+
+Controls:
+    SPACE: Apply random force to all joints
+    R: Reset environment
+    ESC or Q: Quit
+
+Requirements:
+    pip install pygame
+
+Usage:
+    1. Start the server: uvicorn server.app:app --host 0.0.0.0 --port 8000
+    2. Run this script: python examples/hopper_control.py
+
+    For visual mode (requires working MuJoCo rendering):
+        python examples/hopper_control.py --visual
+"""
+
+import argparse
+import random
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from client import DMControlEnv
+from models import DMControlAction
+
+
+def get_action_dim(env: DMControlEnv) -> int:
+    """Get the action dimension from the environment state."""
+    state = env.state()
+    action_spec = state.action_spec
+    if action_spec and "shape" in action_spec:
+        shape = action_spec["shape"]
+        if isinstance(shape, list) and len(shape) > 0:
+            return shape[0]
+    # Hopper default: 4 actuators (hip, knee, ankle, toe)
+    return 4
+
+
+def generate_random_action(action_dim: int, magnitude: float = 1.0) -> DMControlAction:
+    """Generate a random action with values in [-magnitude, magnitude]."""
+    values = [random.uniform(-magnitude, magnitude) for _ in range(action_dim)]
+    return DMControlAction(values=values)
+
+
+def generate_zero_action(action_dim: int) -> DMControlAction:
+    """Generate a zero action (no force applied)."""
+    return DMControlAction(values=[0.0] * action_dim)
+
+
+def run_headless(env: DMControlEnv, task: str = "hop", max_steps: int = 1000):
+    """Run hopper control in headless mode."""
+    print("\n=== Headless Mode (OpenEnv Step/Observation Pattern) ===")
+    print("This mode demonstrates the OpenEnv API with the hopper.\n")
+
+    # Reset environment using OpenEnv pattern
+    result = env.reset(domain_name="hopper", task_name=task)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get action dimension
+    action_dim = get_action_dim(env)
+    print(f"Action dimension: {action_dim}")
+
+    total_reward = 0.0
+    step_count = 0
+
+    print("\nRunning with periodic random forces...")
+    print("Every 30 steps, a random force burst is applied.\n")
+
+    while not result.done and step_count < max_steps:
+        # Apply random force every 30 steps, otherwise zero action
+        if step_count % 30 < 5:
+            # Random force burst for 5 steps
+            action = generate_random_action(action_dim, magnitude=0.8)
+        else:
+            # No force
+            action = generate_zero_action(action_dim)
+
+        # Step the environment using OpenEnv pattern
+        result = env.step(action)
+
+        # Access observation and reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Print progress periodically
+        if step_count % 100 == 0:
+            # Get some observation values
+            position = result.observation.observations.get("position", [])
+            velocity = result.observation.observations.get("velocity", [])
+            print(
+                f"Step {step_count}: reward={result.reward:.3f}, "
+                f"total={total_reward:.2f}, done={result.done}"
+            )
+            if position:
+                print(f"  position: {position[:3]}")
+            if velocity:
+                print(f"  velocity: {velocity[:3]}")
+
+    print(f"\nEpisode finished: {step_count} steps, total reward: {total_reward:.2f}")
+
+
+def run_interactive(env: DMControlEnv, task: str = "hop"):
+    """Run interactive control with keyboard input via pygame."""
+    import pygame
+
+    print("\n=== Interactive Mode (OpenEnv Step/Observation Pattern) ===")
+    print("Press SPACE to apply random force, R to reset, ESC to quit.\n")
+
+    # Reset environment using OpenEnv pattern
+    result = env.reset(domain_name="hopper", task_name=task)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get action dimension
+    action_dim = get_action_dim(env)
+    print(f"Action dimension: {action_dim}")
+
+    # Initialize pygame for keyboard input (minimal window)
+    pygame.init()
+    screen = pygame.display.set_mode((400, 100))
+    pygame.display.set_caption("Hopper Control - SPACE for random force, R to reset")
+    clock = pygame.time.Clock()
+
+    # Font for display
+    font = pygame.font.Font(None, 24)
+
+    running = True
+    total_reward = 0.0
+    step_count = 0
+    apply_random_force = False
+
+    print("\nControls:")
+    print("  SPACE: Apply random force to joints")
+    print("  R: Reset environment")
+    print("  ESC or Q: Quit\n")
+
+    while running:
+        # Handle events
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                running = False
+            elif event.type == pygame.KEYDOWN:
+                if event.key in (pygame.K_ESCAPE, pygame.K_q):
+                    running = False
+                elif event.key == pygame.K_r:
+                    result = env.reset(domain_name="hopper", task_name=task)
+                    total_reward = 0.0
+                    step_count = 0
+                    print("Environment reset")
+
+        # Check for held keys
+        keys = pygame.key.get_pressed()
+        apply_random_force = keys[pygame.K_SPACE]
+
+        # Generate action based on input
+        if apply_random_force:
+            action = generate_random_action(action_dim, magnitude=2.0)
+        else:
+            action = generate_zero_action(action_dim)
+
+        # Step the environment using OpenEnv pattern
+        result = env.step(action)
+
+        # Track reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Check if episode is done
+        if result.done:
+            print(
+                f"Episode finished! Steps: {step_count}, "
+                f"Total reward: {total_reward:.2f}"
+            )
+            # Auto-reset on done
+            result = env.reset(domain_name="hopper", task_name=task)
+            total_reward = 0.0
+            step_count = 0
+
+        # Update display
+        screen.fill((30, 30, 30))
+        status = "FORCE!" if apply_random_force else "idle"
+        text = font.render(
+            f"Step: {step_count} | Reward: {total_reward:.1f} | {status}",
+            True,
+            (255, 255, 255),
+        )
+        screen.blit(text, (10, 40))
+        pygame.display.flip()
+
+        # Print progress periodically
+        if step_count % 200 == 0 and step_count > 0:
+            print(f"Step {step_count}: Total reward: {total_reward:.2f}")
+
+        # Cap at 30 FPS
+        clock.tick(30)
+
+    pygame.quit()
+    print(f"Session ended. Final reward: {total_reward:.2f}")
+
+
+def run_visual(env: DMControlEnv, task: str = "hop"):
+    """Run with pygame visualization showing rendered frames."""
+    import base64
+    import io
+
+    import pygame
+
+    print("\n=== Visual Mode (OpenEnv Step/Observation Pattern) ===")
+
+    # Reset environment with rendering enabled
+    result = env.reset(domain_name="hopper", task_name=task, render=True)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get action dimension
+    action_dim = get_action_dim(env)
+    print(f"Action dimension: {action_dim}")
+
+    # Get first frame to determine window size
+    if result.observation.pixels is None:
+        print("Error: Server did not return rendered pixels.")
+        print("Make sure the server supports render=True")
+        print("\nTry running in interactive mode (default) instead.")
+        sys.exit(1)
+
+    # Decode base64 PNG to pygame surface
+    png_data = base64.b64decode(result.observation.pixels)
+    frame = pygame.image.load(io.BytesIO(png_data))
+    frame_size = frame.get_size()
+
+    # Initialize pygame
+    pygame.init()
+    screen = pygame.display.set_mode(frame_size)
+    pygame.display.set_caption(
+        "Hopper (OpenEnv) - SPACE for random force, R to Reset, ESC to Quit"
+    )
+    clock = pygame.time.Clock()
+
+    print("Controls:")
+    print("  SPACE: Apply random force to joints")
+    print("  R: Reset environment")
+    print("  ESC or Q: Quit")
+
+    running = True
+    total_reward = 0.0
+    step_count = 0
+
+    while running:
+        # Handle events
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                running = False
+            elif event.type == pygame.KEYDOWN:
+                if event.key in (pygame.K_ESCAPE, pygame.K_q):
+                    running = False
+                elif event.key == pygame.K_r:
+                    result = env.reset(
+                        domain_name="hopper", task_name=task, render=True
+                    )
+                    total_reward = 0.0
+                    step_count = 0
+                    print("Environment reset")
+
+        # Check for held keys
+        keys = pygame.key.get_pressed()
+        apply_random_force = keys[pygame.K_SPACE]
+
+        # Generate action based on input
+        if apply_random_force:
+            action = generate_random_action(action_dim, magnitude=2.0)
+        else:
+            action = generate_zero_action(action_dim)
+
+        # Step the environment using OpenEnv pattern
+        result = env.step(action, render=True)
+
+        # Track reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Check if episode is done
+        if result.done:
+            print(
+                f"Episode finished! Steps: {step_count}, "
+                f"Total reward: {total_reward:.2f}"
+            )
+            result = env.reset(domain_name="hopper", task_name=task, render=True)
+            total_reward = 0.0
+            step_count = 0
+
+        # Render the frame from observation pixels
+        if result.observation.pixels:
+            png_data = base64.b64decode(result.observation.pixels)
+            frame = pygame.image.load(io.BytesIO(png_data))
+            screen.blit(frame, (0, 0))
+            pygame.display.flip()
+
+        # Print progress periodically
+        if step_count % 200 == 0 and step_count > 0:
+            print(f"Step {step_count}: Total reward: {total_reward:.2f}")
+
+        # Cap at 30 FPS
+        clock.tick(30)
+
+    pygame.quit()
+    print(f"Session ended. Final reward: {total_reward:.2f}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Interactive hopper control via OpenEnv"
+    )
+    parser.add_argument(
+        "--visual",
+        action="store_true",
+        help="Enable pygame visualization with rendered frames",
+    )
+    parser.add_argument(
+        "--headless",
+        action="store_true",
+        help="Run in headless mode (no pygame, automated control)",
+    )
+    parser.add_argument(
+        "--max-steps",
+        type=int,
+        default=1000,
+        help="Maximum steps for headless mode (default: 1000)",
+    )
+    parser.add_argument(
+        "--task",
+        type=str,
+        default="hop",
+        choices=["stand", "hop"],
+        help="Hopper task (default: hop)",
+    )
+    args = parser.parse_args()
+
+    server_url = "http://localhost:8000"
+    print(f"Connecting to {server_url}...")
+
+    try:
+        with DMControlEnv(base_url=server_url) as env:
+            print("Connected!")
+
+            # Get environment state
+            state = env.state()
+            print(f"Domain: {state.domain_name}, Task: {state.task_name}")
+            print(f"Action spec: {state.action_spec}")
+
+            if args.headless:
+                run_headless(env, task=args.task, max_steps=args.max_steps)
+            elif args.visual:
+                run_visual(env, task=args.task)
+            else:
+                run_interactive(env, task=args.task)
+
+    except ConnectionError as e:
+        print(f"Failed to connect: {e}")
+        print("\nMake sure the server is running:")
+        print("  cd OpenEnv")
+        print(
+            "  PYTHONPATH=src:envs uvicorn envs.dm_control_env.server.app:app --port 8000"
+        )
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

envs/dm_control_env/examples/list_environments.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""List all available dm_control.suite environments.
+
+This utility prints all available domain/task combinations from dm_control.suite.
+"""
+
+from dm_control import suite
+
+
+def main():
+    print("Available dm_control.suite environments:")
+    print("=" * 50)
+
+    # Group by domain
+    domains = {}
+    for domain, task in suite.BENCHMARKING:
+        if domain not in domains:
+            domains[domain] = []
+        domains[domain].append(task)
+
+    for domain in sorted(domains.keys()):
+        tasks = sorted(domains[domain])
+        print(f"\n{domain}:")
+        for task in tasks:
+            # Load env to get action spec
+            try:
+                env = suite.load(domain_name=domain, task_name=task)
+                action_spec = env.action_spec()
+                action_dim = action_spec.shape[0]
+                obs_keys = list(env.observation_spec().keys())
+                env.close()
+                print(f"  - {task:20s} (action_dim={action_dim}, obs={obs_keys})")
+            except Exception as e:
+                print(f"  - {task:20s} (error: {e})")
+
+    print("\n" + "=" * 50)
+    print(f"Total: {len(suite.BENCHMARKING)} environments")
+
+
+if __name__ == "__main__":
+    main()

envs/dm_control_env/examples/quadruped_control.py

@@ -0,0 +1,373 @@
+#!/usr/bin/env python3
+"""Interactive quadruped control via OpenEnv.
+
+This example demonstrates using the dm_control OpenEnv client with
+the quadruped environment. Press SPACE to apply random forces to the joints.
+
+Controls:
+    SPACE: Apply random force to all joints
+    R: Reset environment
+    ESC or Q: Quit
+
+Requirements:
+    pip install pygame
+
+Usage:
+    1. Start the server: uvicorn server.app:app --host 0.0.0.0 --port 8000
+    2. Run this script: python examples/quadruped_control.py
+
+    For visual mode (requires working MuJoCo rendering):
+        python examples/quadruped_control.py --visual
+"""
+
+import argparse
+import random
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from client import DMControlEnv
+from models import DMControlAction
+
+
+def get_action_dim(env: DMControlEnv) -> int:
+    """Get the action dimension from the environment state."""
+    state = env.state()
+    action_spec = state.action_spec
+    if action_spec and "shape" in action_spec:
+        shape = action_spec["shape"]
+        if isinstance(shape, list) and len(shape) > 0:
+            return shape[0]
+    # Quadruped default: 12 actuators (3 per leg x 4 legs)
+    return 12
+
+
+def generate_random_action(action_dim: int, magnitude: float = 1.0) -> DMControlAction:
+    """Generate a random action with values in [-magnitude, magnitude]."""
+    values = [random.uniform(-magnitude, magnitude) for _ in range(action_dim)]
+    return DMControlAction(values=values)
+
+
+def generate_zero_action(action_dim: int) -> DMControlAction:
+    """Generate a zero action (no force applied)."""
+    return DMControlAction(values=[0.0] * action_dim)
+
+
+def run_headless(env: DMControlEnv, max_steps: int = 1000):
+    """Run quadruped control in headless mode."""
+    print("\n=== Headless Mode (OpenEnv Step/Observation Pattern) ===")
+    print("This mode demonstrates the OpenEnv API with the quadruped.\n")
+
+    # Reset environment using OpenEnv pattern
+    result = env.reset(domain_name="quadruped", task_name="walk")
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get action dimension
+    action_dim = get_action_dim(env)
+    print(f"Action dimension: {action_dim}")
+
+    total_reward = 0.0
+    step_count = 0
+
+    print("\nRunning with periodic random forces...")
+    print("Every 50 steps, a random force burst is applied.\n")
+
+    while not result.done and step_count < max_steps:
+        # Apply random force every 50 steps, otherwise zero action
+        if step_count % 50 < 10:
+            # Random force burst for 10 steps
+            action = generate_random_action(action_dim, magnitude=0.5)
+        else:
+            # No force
+            action = generate_zero_action(action_dim)
+
+        # Step the environment using OpenEnv pattern
+        result = env.step(action)
+
+        # Access observation and reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Print progress periodically
+        if step_count % 100 == 0:
+            # Get some observation values
+            egocentric_state = result.observation.observations.get(
+                "egocentric_state", []
+            )
+            print(
+                f"Step {step_count}: reward={result.reward:.3f}, "
+                f"total={total_reward:.2f}, done={result.done}"
+            )
+            if egocentric_state:
+                print(f"  egocentric_state (first 5): {egocentric_state[:5]}")
+
+    print(f"\nEpisode finished: {step_count} steps, total reward: {total_reward:.2f}")
+
+
+def run_interactive(env: DMControlEnv):
+    """Run interactive control with keyboard input via pygame."""
+    import pygame
+
+    print("\n=== Interactive Mode (OpenEnv Step/Observation Pattern) ===")
+    print("Press SPACE to apply random force, R to reset, ESC to quit.\n")
+
+    # Reset environment using OpenEnv pattern
+    result = env.reset(domain_name="quadruped", task_name="walk")
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get action dimension
+    action_dim = get_action_dim(env)
+    print(f"Action dimension: {action_dim}")
+
+    # Initialize pygame for keyboard input (minimal window)
+    pygame.init()
+    screen = pygame.display.set_mode((400, 100))
+    pygame.display.set_caption("Quadruped Control - SPACE for random force, R to reset")
+    clock = pygame.time.Clock()
+
+    # Draw instructions on the window
+    font = pygame.font.Font(None, 24)
+
+    running = True
+    total_reward = 0.0
+    step_count = 0
+    apply_random_force = False
+
+    print("\nControls:")
+    print("  SPACE: Apply random force to joints")
+    print("  R: Reset environment")
+    print("  ESC or Q: Quit\n")
+
+    while running:
+        # Handle events
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                running = False
+            elif event.type == pygame.KEYDOWN:
+                if event.key in (pygame.K_ESCAPE, pygame.K_q):
+                    running = False
+                elif event.key == pygame.K_r:
+                    result = env.reset(domain_name="quadruped", task_name="walk")
+                    total_reward = 0.0
+                    step_count = 0
+                    print("Environment reset")
+
+        # Check for held keys
+        keys = pygame.key.get_pressed()
+        apply_random_force = keys[pygame.K_SPACE]
+
+        # Generate action based on input
+        if apply_random_force:
+            action = generate_random_action(action_dim, magnitude=2.0)
+        else:
+            action = generate_zero_action(action_dim)
+
+        # Step the environment using OpenEnv pattern
+        result = env.step(action)
+
+        # Track reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Check if episode is done
+        if result.done:
+            print(
+                f"Episode finished! Steps: {step_count}, "
+                f"Total reward: {total_reward:.2f}"
+            )
+            # Auto-reset on done
+            result = env.reset(domain_name="quadruped", task_name="walk")
+            total_reward = 0.0
+            step_count = 0
+
+        # Update display
+        screen.fill((30, 30, 30))
+        status = "FORCE!" if apply_random_force else "idle"
+        text = font.render(
+            f"Step: {step_count} | Reward: {total_reward:.1f} | {status}",
+            True,
+            (255, 255, 255),
+        )
+        screen.blit(text, (10, 40))
+        pygame.display.flip()
+
+        # Print progress periodically
+        if step_count % 200 == 0 and step_count > 0:
+            print(f"Step {step_count}: Total reward: {total_reward:.2f}")
+
+        # Cap at 30 FPS
+        clock.tick(30)
+
+    pygame.quit()
+    print(f"Session ended. Final reward: {total_reward:.2f}")
+
+
+def run_visual(env: DMControlEnv):
+    """Run with pygame visualization showing rendered frames."""
+    import base64
+    import io
+
+    import pygame
+
+    print("\n=== Visual Mode (OpenEnv Step/Observation Pattern) ===")
+
+    # Reset environment with rendering enabled
+    result = env.reset(domain_name="quadruped", task_name="walk", render=True)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get action dimension
+    action_dim = get_action_dim(env)
+    print(f"Action dimension: {action_dim}")
+
+    # Get first frame to determine window size
+    if result.observation.pixels is None:
+        print("Error: Server did not return rendered pixels.")
+        print("Make sure the server supports render=True")
+        print("\nTry running in interactive mode (default) instead.")
+        sys.exit(1)
+
+    # Decode base64 PNG to pygame surface
+    png_data = base64.b64decode(result.observation.pixels)
+    frame = pygame.image.load(io.BytesIO(png_data))
+    frame_size = frame.get_size()
+
+    # Initialize pygame
+    pygame.init()
+    screen = pygame.display.set_mode(frame_size)
+    pygame.display.set_caption(
+        "Quadruped (OpenEnv) - SPACE for random force, R to Reset, ESC to Quit"
+    )
+    clock = pygame.time.Clock()
+
+    print("Controls:")
+    print("  SPACE: Apply random force to joints")
+    print("  R: Reset environment")
+    print("  ESC or Q: Quit")
+
+    running = True
+    total_reward = 0.0
+    step_count = 0
+
+    while running:
+        # Handle events
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                running = False
+            elif event.type == pygame.KEYDOWN:
+                if event.key in (pygame.K_ESCAPE, pygame.K_q):
+                    running = False
+                elif event.key == pygame.K_r:
+                    result = env.reset(
+                        domain_name="quadruped", task_name="walk", render=True
+                    )
+                    total_reward = 0.0
+                    step_count = 0
+                    print("Environment reset")
+
+        # Check for held keys
+        keys = pygame.key.get_pressed()
+        apply_random_force = keys[pygame.K_SPACE]
+
+        # Generate action based on input
+        if apply_random_force:
+            action = generate_random_action(action_dim, magnitude=2.0)
+        else:
+            action = generate_zero_action(action_dim)
+
+        # Step the environment using OpenEnv pattern
+        result = env.step(action, render=True)
+
+        # Track reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Check if episode is done
+        if result.done:
+            print(
+                f"Episode finished! Steps: {step_count}, "
+                f"Total reward: {total_reward:.2f}"
+            )
+            result = env.reset(domain_name="quadruped", task_name="walk", render=True)
+            total_reward = 0.0
+            step_count = 0
+
+        # Render the frame from observation pixels
+        if result.observation.pixels:
+            png_data = base64.b64decode(result.observation.pixels)
+            frame = pygame.image.load(io.BytesIO(png_data))
+            screen.blit(frame, (0, 0))
+            pygame.display.flip()
+
+        # Print progress periodically
+        if step_count % 200 == 0 and step_count > 0:
+            print(f"Step {step_count}: Total reward: {total_reward:.2f}")
+
+        # Cap at 30 FPS
+        clock.tick(30)
+
+    pygame.quit()
+    print(f"Session ended. Final reward: {total_reward:.2f}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Interactive quadruped control via OpenEnv"
+    )
+    parser.add_argument(
+        "--visual",
+        action="store_true",
+        help="Enable pygame visualization with rendered frames",
+    )
+    parser.add_argument(
+        "--headless",
+        action="store_true",
+        help="Run in headless mode (no pygame, automated control)",
+    )
+    parser.add_argument(
+        "--max-steps",
+        type=int,
+        default=1000,
+        help="Maximum steps for headless mode (default: 1000)",
+    )
+    parser.add_argument(
+        "--task",
+        type=str,
+        default="walk",
+        choices=["walk", "run", "escape", "fetch"],
+        help="Quadruped task (default: walk)",
+    )
+    args = parser.parse_args()
+
+    server_url = "http://localhost:8000"
+    print(f"Connecting to {server_url}...")
+
+    try:
+        with DMControlEnv(base_url=server_url) as env:
+            print("Connected!")
+
+            # Get environment state
+            state = env.state()
+            print(f"Domain: {state.domain_name}, Task: {state.task_name}")
+            print(f"Action spec: {state.action_spec}")
+
+            if args.headless:
+                run_headless(env, max_steps=args.max_steps)
+            elif args.visual:
+                run_visual(env)
+            else:
+                run_interactive(env)
+
+    except ConnectionError as e:
+        print(f"Failed to connect: {e}")
+        print("\nMake sure the server is running:")
+        print("  cd OpenEnv")
+        print(
+            "  PYTHONPATH=src:envs uvicorn envs.dm_control_env.server.app:app --port 8000"
+        )
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

envs/dm_control_env/models.py

@@ -0,0 +1,186 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Data models for the dm_control OpenEnv Environment.
+
+This environment wraps dm_control.suite, providing access to all MuJoCo-based
+continuous control tasks (cartpole, walker, humanoid, cheetah, etc.).
+"""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import Field
+
+try:
+    from openenv.core.env_server.types import Action, Observation, State
+except ImportError:
+    from openenv.core.env_server.types import Action, Observation, State
+
+
+class DMControlAction(Action):
+    """
+    Action for dm_control environments.
+
+    All dm_control.suite environments use continuous actions represented as
+    a list of float values. The size and bounds depend on the specific
+    domain/task combination.
+
+    Example (cartpole - 1D action):
+        >>> action = DMControlAction(values=[0.5])  # Push cart right
+
+    Example (walker - 6D action):
+        >>> action = DMControlAction(values=[0.1, -0.2, 0.3, 0.0, -0.1, 0.2])
+
+    Attributes:
+        values: List of continuous action values. Shape and bounds depend on
+            the loaded environment's action_spec.
+    """
+
+    values: List[float] = Field(
+        default_factory=list,
+        description="Continuous action values matching the environment's action_spec",
+    )
+
+
+class DMControlObservation(Observation):
+    """
+    Observation from dm_control environments.
+
+    dm_control environments return observations as a dictionary of named arrays.
+    Common observation keys include 'position', 'velocity', 'orientations', etc.
+    The exact keys depend on the domain/task combination.
+
+    Example observation keys by domain:
+        - cartpole: 'position' (cos/sin of angle), 'velocity'
+        - walker: 'orientations', 'height', 'velocity'
+        - humanoid: 'joint_angles', 'head_height', 'extremities', 'torso_vertical', 'com_velocity'
+
+    Attributes:
+        observations: Dictionary mapping observation names to their values.
+            Each value is a flattened list of floats.
+        pixels: Optional base64-encoded PNG image of the rendered scene.
+            Only included when render=True is passed to reset/step.
+    """
+
+    observations: Dict[str, List[float]] = Field(
+        default_factory=dict,
+        description="Named observation arrays from the environment",
+    )
+    pixels: Optional[str] = Field(
+        default=None,
+        description="Base64-encoded PNG image (when render=True)",
+    )
+
+
+class DMControlState(State):
+    """
+    Extended state for dm_control environments.
+
+    Provides metadata about the currently loaded environment including
+    the domain/task names and action/observation specifications.
+
+    Attributes:
+        episode_id: Unique identifier for the current episode.
+        step_count: Number of steps taken in the current episode.
+        domain_name: The dm_control domain (e.g., 'cartpole', 'walker').
+        task_name: The specific task (e.g., 'balance', 'walk').
+        action_spec: Specification of the action space including shape and bounds.
+        observation_spec: Specification of the observation space.
+        physics_timestep: The physics simulation timestep in seconds.
+        control_timestep: The control timestep (time between actions) in seconds.
+    """
+
+    domain_name: str = Field(
+        default="cartpole",
+        description="The dm_control domain name",
+    )
+    task_name: str = Field(
+        default="balance",
+        description="The task name within the domain",
+    )
+    action_spec: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Specification of the action space (shape, dtype, bounds)",
+    )
+    observation_spec: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Specification of the observation space",
+    )
+    physics_timestep: float = Field(
+        default=0.002,
+        description="Physics simulation timestep in seconds",
+    )
+    control_timestep: float = Field(
+        default=0.02,
+        description="Control timestep (time between actions) in seconds",
+    )
+
+
+# Available dm_control.suite environments
+# Format: (domain_name, task_name)
+AVAILABLE_ENVIRONMENTS = [
+    # Cartpole
+    ("cartpole", "balance"),
+    ("cartpole", "balance_sparse"),
+    ("cartpole", "swingup"),
+    ("cartpole", "swingup_sparse"),
+    # Pendulum
+    ("pendulum", "swingup"),
+    # Point mass
+    ("point_mass", "easy"),
+    ("point_mass", "hard"),
+    # Reacher
+    ("reacher", "easy"),
+    ("reacher", "hard"),
+    # Ball in cup
+    ("ball_in_cup", "catch"),
+    # Finger
+    ("finger", "spin"),
+    ("finger", "turn_easy"),
+    ("finger", "turn_hard"),
+    # Fish
+    ("fish", "upright"),
+    ("fish", "swim"),
+    # Cheetah
+    ("cheetah", "run"),
+    # Walker
+    ("walker", "stand"),
+    ("walker", "walk"),
+    ("walker", "run"),
+    # Hopper
+    ("hopper", "stand"),
+    ("hopper", "hop"),
+    # Swimmer
+    ("swimmer", "swimmer6"),
+    ("swimmer", "swimmer15"),
+    # Humanoid
+    ("humanoid", "stand"),
+    ("humanoid", "walk"),
+    ("humanoid", "run"),
+    # Manipulator
+    ("manipulator", "bring_ball"),
+    ("manipulator", "bring_peg"),
+    ("manipulator", "insert_ball"),
+    ("manipulator", "insert_peg"),
+    # Acrobot
+    ("acrobot", "swingup"),
+    ("acrobot", "swingup_sparse"),
+    # Stacker
+    ("stacker", "stack_2"),
+    ("stacker", "stack_4"),
+    # Dog
+    ("dog", "stand"),
+    ("dog", "walk"),
+    ("dog", "trot"),
+    ("dog", "run"),
+    ("dog", "fetch"),
+    # Quadruped
+    ("quadruped", "walk"),
+    ("quadruped", "run"),
+    ("quadruped", "escape"),
+    ("quadruped", "fetch"),
+]

envs/dm_control_env/openenv.yaml

@@ -0,0 +1,6 @@
+spec_version: 1
+name: dm_control_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000

envs/dm_control_env/pyproject.toml

@@ -0,0 +1,48 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-dmcontrol-env"
+version = "0.1.0"
+description = "dm_control Environment for OpenEnv - wraps MuJoCo-based continuous control tasks (cartpole, walker, humanoid, etc.)"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv dependencies
+    "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git@v2.1.0",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0.0",
+    "uvicorn>=0.24.0",
+    "requests>=2.31.0",
+    # dm_control dependencies
+    "mujoco>=3.0.0",
+    "dm_control>=1.0.0",
+    "numpy>=1.20.0",
+    # Optional: for pixel observations
+    "pillow>=9.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+interactive = [
+    # For interactive examples with keyboard control
+    "pygame>=2.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+server = "dm_control_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["dm_control_env", "dm_control_env.server"]
+package-dir = { "dm_control_env" = ".", "dm_control_env.server" = "server" }

envs/dm_control_env/server/Dockerfile

@@ -0,0 +1,73 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build for dm_control environment
+# Uses pip for package installation
+
+FROM python:3.11-slim AS builder
+
+WORKDIR /app
+
+# Install build dependencies including OpenGL for MuJoCo
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    git \
+    libgl1 \
+    libglx-mesa0 \
+    libglew-dev \
+    libosmesa6-dev \
+    libgl1-mesa-dev \
+    libglfw3 \
+    patchelf \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy environment code
+COPY . /app/env
+
+WORKDIR /app/env
+
+# Install dependencies using pip
+RUN pip install --upgrade pip && \
+    pip install --no-cache-dir -e .
+
+# Final runtime stage
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install runtime dependencies (OpenGL for MuJoCo rendering, curl for healthcheck)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    libgl1 \
+    libglx-mesa0 \
+    libglew-dev \
+    libosmesa6-dev \
+    libglfw3 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy installed packages from builder
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy the environment code
+COPY . /app/env
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env"
+
+# Set MuJoCo to use OSMesa for headless rendering
+ENV MUJOCO_GL="osmesa"
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# Use exec to replace the shell with uvicorn so it receives SIGINT/SIGTERM directly
+CMD ["sh", "-c", "cd /app/env && exec uvicorn server.app:app --host 0.0.0.0 --port 8000"]

envs/dm_control_env/server/__init__.py

@@ -0,0 +1,5 @@
+"""dm_control OpenEnv server module."""
+
+from .dm_control_environment import DMControlEnvironment
+
+__all__ = ["DMControlEnvironment"]

envs/dm_control_env/server/app.py

@@ -0,0 +1,78 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the dm_control Environment.
+
+This module creates an HTTP server that exposes dm_control.suite environments
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+
+    from ..models import DMControlAction, DMControlObservation
+    from .dm_control_environment import DMControlEnvironment
+except ImportError:
+    from openenv.core.env_server.http_server import create_app
+
+    try:
+        import sys
+        from pathlib import Path
+
+        _parent = str(Path(__file__).parent.parent)
+        if _parent not in sys.path:
+            sys.path.insert(0, _parent)
+        from models import DMControlAction, DMControlObservation
+        from server.dm_control_environment import DMControlEnvironment
+    except ImportError:
+        try:
+            from dm_control_env.models import DMControlAction, DMControlObservation
+            from dm_control_env.server.dm_control_environment import (
+                DMControlEnvironment,
+            )
+        except ImportError:
+            from envs.dm_control_env.models import DMControlAction, DMControlObservation
+            from envs.dm_control_env.server.dm_control_environment import (
+                DMControlEnvironment,
+            )
+
+# Create the app with web interface
+# Pass the class (factory) for concurrent session support
+app = create_app(
+    DMControlEnvironment,
+    DMControlAction,
+    DMControlObservation,
+    env_name="dm_control_env",
+)
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.dm_control_env.server.app
+        openenv serve dm_control_env
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

envs/dm_control_env/server/dm_control_environment.py

@@ -0,0 +1,428 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+dm_control Environment Implementation.
+
+Wraps dm_control.suite environments (cartpole, walker, humanoid, etc.)
+with the OpenEnv interface for standardized reinforcement learning.
+"""
+
+import base64
+import io
+import os
+import sys
+from typing import Any, Dict, Optional
+from uuid import uuid4
+
+# Configure MuJoCo rendering backend before importing dm_control
+# On macOS, we don't set MUJOCO_GL - use default (glfw) which works
+# when running synchronously in the main thread (see reset_async/step_async)
+# On Linux, use egl for headless rendering
+if "MUJOCO_GL" not in os.environ and sys.platform != "darwin":
+    os.environ.setdefault("MUJOCO_GL", "egl")
+
+import numpy as np
+
+try:
+    from openenv.core.env_server.interfaces import Environment
+
+    from ..models import DMControlAction, DMControlObservation, DMControlState
+except ImportError:
+    from openenv.core.env_server.interfaces import Environment
+
+    try:
+        import sys
+        from pathlib import Path
+
+        _parent = str(Path(__file__).parent.parent)
+        if _parent not in sys.path:
+            sys.path.insert(0, _parent)
+        from models import DMControlAction, DMControlObservation, DMControlState
+    except ImportError:
+        try:
+            from dm_control_env.models import (
+                DMControlAction,
+                DMControlObservation,
+                DMControlState,
+            )
+        except ImportError:
+            from envs.dm_control_env.models import (
+                DMControlAction,
+                DMControlObservation,
+                DMControlState,
+            )
+
+
+class DMControlEnvironment(Environment):
+    """
+    Wraps dm_control.suite environments with the OpenEnv interface.
+
+    This environment supports all dm_control.suite domains and tasks including
+    cartpole, walker, humanoid, cheetah, and more.
+
+    Features:
+    - Dynamic environment switching via reset(domain_name="...", task_name="...")
+    - Support for all continuous control tasks
+    - Optional visual observations (base64-encoded images)
+    - Configurable via constructor or environment variables
+
+    Example:
+        >>> env = DMControlEnvironment()
+        >>> obs = env.reset()  # Default: cartpole/balance
+        >>> print(obs.observations)
+        >>>
+        >>> # Take an action
+        >>> obs = env.step(DMControlAction(values=[0.5]))  # Push cart right
+        >>> print(obs.reward)
+
+    Example with different environment:
+        >>> env = DMControlEnvironment(domain_name="walker", task_name="walk")
+        >>> obs = env.reset()
+        >>>
+        >>> # Or switch environment on reset
+        >>> obs = env.reset(domain_name="cheetah", task_name="run")
+    """
+
+    # dm_control environments are isolated and thread-safe
+    SUPPORTS_CONCURRENT_SESSIONS = True
+
+    def __init__(
+        self,
+        domain_name: Optional[str] = None,
+        task_name: Optional[str] = None,
+        render_height: Optional[int] = None,
+        render_width: Optional[int] = None,
+    ):
+        """
+        Initialize the dm_control environment.
+
+        Args:
+            domain_name: The dm_control domain to load.
+                Env var: DMCONTROL_DOMAIN (default: cartpole)
+            task_name: The task within the domain.
+                Env var: DMCONTROL_TASK (default: balance)
+            render_height: Height of rendered images (when render=True).
+                Env var: DMCONTROL_RENDER_HEIGHT (default: 480)
+            render_width: Width of rendered images (when render=True).
+                Env var: DMCONTROL_RENDER_WIDTH (default: 640)
+        """
+        self._env = None
+
+        self._domain_name = domain_name or os.environ.get(
+            "DMCONTROL_DOMAIN", "cartpole"
+        )
+        self._task_name = task_name or os.environ.get("DMCONTROL_TASK", "balance")
+        self._render_height = (
+            render_height
+            if render_height is not None
+            else int(os.environ.get("DMCONTROL_RENDER_HEIGHT", "480"))
+        )
+        self._render_width = (
+            render_width
+            if render_width is not None
+            else int(os.environ.get("DMCONTROL_RENDER_WIDTH", "640"))
+        )
+        self._include_pixels = False
+
+        self._state = DMControlState(
+            episode_id=str(uuid4()),
+            step_count=0,
+            domain_name=self._domain_name,
+            task_name=self._task_name,
+        )
+
+    def _load_environment(self, domain_name: str, task_name: str) -> None:
+        """Load or switch to a dm_control environment."""
+        if self._env is not None:
+            try:
+                self._env.close()
+            except Exception:
+                pass
+
+        try:
+            from dm_control import suite
+        except ImportError as e:
+            raise ImportError(
+                "dm_control is required. Install with: pip install dm_control"
+            ) from e
+        except Exception as e:
+            # MuJoCo/OpenGL initialization can fail on macOS
+            error_msg = str(e)
+            if sys.platform == "darwin":
+                raise RuntimeError(
+                    f"Failed to import dm_control (MuJoCo error): {error_msg}\n\n"
+                    "On macOS, try one of these solutions:\n"
+                    "1. Install osmesa: brew install mesa\n"
+                    "2. Run with MUJOCO_GL=glfw (requires display)\n"
+                    "3. Run with MUJOCO_GL=egl (if EGL is available)"
+                ) from e
+            raise
+
+        try:
+            self._env = suite.load(domain_name=domain_name, task_name=task_name)
+        except Exception as e:
+            error_msg = str(e).lower()
+            # Check for MuJoCo/OpenGL errors
+            if "gl" in error_msg or "render" in error_msg or "display" in error_msg:
+                if sys.platform == "darwin":
+                    raise RuntimeError(
+                        f"MuJoCo initialization failed: {e}\n\n"
+                        "On macOS, try one of these solutions:\n"
+                        "1. Install osmesa: brew install mesa\n"
+                        "2. Run with MUJOCO_GL=glfw (requires display)\n"
+                        "3. Set PYOPENGL_PLATFORM=osmesa"
+                    ) from e
+            # Check if it's an invalid environment error
+            try:
+                available = [(d, t) for d, t in suite.BENCHMARKING]
+                raise ValueError(
+                    f"Failed to load {domain_name}/{task_name}. "
+                    f"Available environments: {available[:10]}... "
+                    f"(use dm_control.suite.BENCHMARKING for full list)"
+                ) from e
+            except Exception:
+                raise
+
+        self._domain_name = domain_name
+        self._task_name = task_name
+
+        self._state.domain_name = domain_name
+        self._state.task_name = task_name
+        self._state.action_spec = self._get_action_spec_info()
+        self._state.observation_spec = self._get_observation_spec_info()
+        self._state.physics_timestep = self._env.physics.timestep()
+        self._state.control_timestep = self._env.control_timestep()
+
+    def _get_action_spec_info(self) -> Dict[str, Any]:
+        """Get information about the action space."""
+        spec = self._env.action_spec()
+        return {
+            "shape": list(spec.shape),
+            "dtype": str(spec.dtype),
+            "minimum": spec.minimum.tolist(),
+            "maximum": spec.maximum.tolist(),
+            "name": spec.name,
+        }
+
+    def _get_observation_spec_info(self) -> Dict[str, Any]:
+        """Get information about the observation space."""
+        specs = self._env.observation_spec()
+        obs_info = {}
+        for name, spec in specs.items():
+            obs_info[name] = {
+                "shape": list(spec.shape),
+                "dtype": str(spec.dtype),
+            }
+        return obs_info
+
+    def _get_observation(
+        self,
+        time_step,
+        include_pixels: bool = False,
+    ) -> DMControlObservation:
+        """Convert dm_control TimeStep to DMControlObservation."""
+        import dm_env
+
+        observations = {}
+        for name, value in time_step.observation.items():
+            observations[name] = np.asarray(value).flatten().tolist()
+
+        pixels = None
+        if include_pixels:
+            try:
+                frame = self._env.physics.render(
+                    height=self._render_height,
+                    width=self._render_width,
+                    camera_id=0,
+                )
+                from PIL import Image
+
+                img = Image.fromarray(frame)
+                buffer = io.BytesIO()
+                img.save(buffer, format="PNG")
+                pixels = base64.b64encode(buffer.getvalue()).decode("utf-8")
+            except Exception:
+                pass
+
+        done = time_step.step_type == dm_env.StepType.LAST
+        reward = float(time_step.reward) if time_step.reward is not None else 0.0
+
+        return DMControlObservation(
+            observations=observations,
+            pixels=pixels,
+            reward=reward,
+            done=done,
+        )
+
+    def reset(
+        self,
+        domain_name: Optional[str] = None,
+        task_name: Optional[str] = None,
+        seed: Optional[int] = None,
+        render: bool = False,
+        **kwargs,
+    ) -> DMControlObservation:
+        """
+        Reset the environment and return initial observation.
+
+        Args:
+            domain_name: Optionally switch to a different domain.
+            task_name: Optionally switch to a different task.
+            seed: Random seed for reproducibility.
+            render: If True, include pixel observations.
+            **kwargs: Additional arguments (ignored).
+
+        Returns:
+            DMControlObservation with initial state.
+        """
+        self._include_pixels = render
+
+        target_domain = domain_name or self._domain_name
+        target_task = task_name or self._task_name
+
+        if (
+            self._env is None
+            or target_domain != self._domain_name
+            or target_task != self._task_name
+        ):
+            self._load_environment(target_domain, target_task)
+
+        if seed is not None:
+            np.random.seed(seed)
+
+        time_step = self._env.reset()
+
+        self._state = DMControlState(
+            episode_id=str(uuid4()),
+            step_count=0,
+            domain_name=self._domain_name,
+            task_name=self._task_name,
+            action_spec=self._state.action_spec,
+            observation_spec=self._state.observation_spec,
+            physics_timestep=self._state.physics_timestep,
+            control_timestep=self._state.control_timestep,
+        )
+
+        return self._get_observation(time_step, include_pixels=render)
+
+    def step(
+        self,
+        action: DMControlAction,
+        render: bool = False,
+        **kwargs,
+    ) -> DMControlObservation:
+        """
+        Execute one step in the environment.
+
+        Args:
+            action: DMControlAction with continuous action values.
+            render: If True, include pixel observations.
+
+        Returns:
+            DMControlObservation with new state, reward, and done flag.
+        """
+        if self._env is None:
+            raise RuntimeError("Environment not initialized. Call reset() first.")
+
+        action_array = np.array(action.values, dtype=np.float64)
+
+        action_spec = self._env.action_spec()
+        expected_shape = action_spec.shape
+        if action_array.shape != expected_shape:
+            if action_array.size == np.prod(expected_shape):
+                action_array = action_array.reshape(expected_shape)
+            else:
+                raise ValueError(
+                    f"Action shape {action_array.shape} doesn't match "
+                    f"expected shape {expected_shape}"
+                )
+
+        action_array = np.clip(action_array, action_spec.minimum, action_spec.maximum)
+
+        time_step = self._env.step(action_array)
+        self._state.step_count += 1
+
+        return self._get_observation(
+            time_step, include_pixels=render or self._include_pixels
+        )
+
+    async def reset_async(
+        self,
+        domain_name: Optional[str] = None,
+        task_name: Optional[str] = None,
+        seed: Optional[int] = None,
+        render: bool = False,
+        **kwargs,
+    ) -> DMControlObservation:
+        """Async version of reset.
+
+        On macOS, runs synchronously to avoid MuJoCo threading crashes.
+        On other platforms, runs in a thread pool.
+        """
+        if sys.platform == "darwin":
+            # On macOS, MuJoCo crashes when run in a background thread
+            # Run synchronously (blocks event loop but avoids crash)
+            return self.reset(
+                domain_name=domain_name,
+                task_name=task_name,
+                seed=seed,
+                render=render,
+                **kwargs,
+            )
+        else:
+            import asyncio
+
+            return await asyncio.to_thread(
+                self.reset,
+                domain_name=domain_name,
+                task_name=task_name,
+                seed=seed,
+                render=render,
+                **kwargs,
+            )
+
+    async def step_async(
+        self,
+        action: DMControlAction,
+        render: bool = False,
+        **kwargs,
+    ) -> DMControlObservation:
+        """Async version of step.
+
+        On macOS, runs synchronously to avoid MuJoCo threading crashes.
+        On other platforms, runs in a thread pool.
+        """
+        if sys.platform == "darwin":
+            # On macOS, MuJoCo crashes when run in a background thread
+            # Run synchronously (blocks event loop but avoids crash)
+            return self.step(action, render=render, **kwargs)
+        else:
+            import asyncio
+
+            return await asyncio.to_thread(self.step, action, render=render, **kwargs)
+
+    @property
+    def state(self) -> DMControlState:
+        """Get the current environment state."""
+        return self._state
+
+    def close(self) -> None:
+        """Close the dm_control environment."""
+        env = getattr(self, "_env", None)
+        if env is not None:
+            try:
+                env.close()
+            except Exception:
+                pass
+            self._env = None
+
+    def __del__(self):
+        """Cleanup on deletion."""
+        try:
+            self.close()
+        except Exception:
+            pass

examples/__init__.py

@@ -0,0 +1 @@
+"""dm_control examples."""

examples/cartpole_control.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""Interactive cartpole control via OpenEnv.
+
+This example demonstrates using the dm_control OpenEnv client with
+the cartpole environment. Use arrow keys to control the cart.
+
+Controls:
+    LEFT/RIGHT arrows: Apply force to move cart
+    R: Reset environment
+    ESC or Q: Quit
+
+Requirements:
+    pip install pygame
+
+Usage:
+    1. Start the server: uvicorn server.app:app --host 0.0.0.0 --port 8000
+    2. Run this script: python examples/cartpole_control.py
+
+    For visual mode (requires working MuJoCo rendering):
+        python examples/cartpole_control.py --visual
+"""
+
+import argparse
+import random
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from client import DMControlEnv
+from models import DMControlAction
+
+
+def run_headless(env: DMControlEnv, task: str = "balance", max_steps: int = 500):
+    """Run cartpole control in headless mode."""
+    print("\n=== Headless Mode (OpenEnv Step/Observation Pattern) ===")
+    print("This mode demonstrates the OpenEnv API with the cartpole.\n")
+
+    # Reset environment using OpenEnv pattern
+    result = env.reset(domain_name="cartpole", task_name=task)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+    print(f"  position: {result.observation.observations.get('position', [])}")
+    print(f"  velocity: {result.observation.observations.get('velocity', [])}")
+
+    total_reward = 0.0
+    step_count = 0
+
+    print("\nRunning with random actions to demonstrate step/observation pattern...\n")
+
+    while not result.done and step_count < max_steps:
+        # Random action in [-1, 1]
+        action_value = random.uniform(-1.0, 1.0)
+
+        # Step the environment using OpenEnv pattern
+        action = DMControlAction(values=[action_value])
+        result = env.step(action)
+
+        # Access observation and reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Print progress periodically
+        if step_count % 50 == 0:
+            pos = result.observation.observations.get("position", [])
+            vel = result.observation.observations.get("velocity", [])
+            print(
+                f"Step {step_count}: reward={result.reward:.3f}, "
+                f"total={total_reward:.2f}, done={result.done}"
+            )
+            print(f"  position={pos}, velocity={vel}")
+
+    print(f"\nEpisode finished: {step_count} steps, total reward: {total_reward:.2f}")
+
+
+def run_interactive(env: DMControlEnv, task: str = "balance"):
+    """Run interactive control with keyboard input via pygame."""
+    import pygame
+
+    print("\n=== Interactive Mode (OpenEnv Step/Observation Pattern) ===")
+    print("Use LEFT/RIGHT arrows to control cart, R to reset, ESC to quit.\n")
+
+    # Reset environment using OpenEnv pattern
+    result = env.reset(domain_name="cartpole", task_name=task)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Initialize pygame for keyboard input (minimal window)
+    pygame.init()
+    screen = pygame.display.set_mode((400, 100))
+    pygame.display.set_caption("Cartpole Control - Arrow keys to move, R to reset")
+    clock = pygame.time.Clock()
+
+    # Font for display
+    font = pygame.font.Font(None, 24)
+
+    running = True
+    total_reward = 0.0
+    step_count = 0
+
+    print("\nControls:")
+    print("  LEFT/RIGHT arrows: Move cart")
+    print("  R: Reset environment")
+    print("  ESC or Q: Quit\n")
+
+    while running:
+        # Handle events
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                running = False
+            elif event.type == pygame.KEYDOWN:
+                if event.key in (pygame.K_ESCAPE, pygame.K_q):
+                    running = False
+                elif event.key == pygame.K_r:
+                    result = env.reset(domain_name="cartpole", task_name=task)
+                    total_reward = 0.0
+                    step_count = 0
+                    print("Environment reset")
+
+        # Check for held keys (for continuous control)
+        keys = pygame.key.get_pressed()
+        if keys[pygame.K_LEFT]:
+            action_value = -1.0
+        elif keys[pygame.K_RIGHT]:
+            action_value = 1.0
+        else:
+            action_value = 0.0
+
+        # Step the environment using OpenEnv pattern
+        action = DMControlAction(values=[action_value])
+        result = env.step(action)
+
+        # Track reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Check if episode is done
+        if result.done:
+            print(
+                f"Episode finished! Steps: {step_count}, "
+                f"Total reward: {total_reward:.2f}"
+            )
+            # Auto-reset on done
+            result = env.reset(domain_name="cartpole", task_name=task)
+            total_reward = 0.0
+            step_count = 0
+
+        # Update display
+        direction = (
+            "<--" if action_value < 0 else ("-->" if action_value > 0 else "---")
+        )
+        screen.fill((30, 30, 30))
+        text = font.render(
+            f"Step: {step_count} | Reward: {total_reward:.1f} | {direction}",
+            True,
+            (255, 255, 255),
+        )
+        screen.blit(text, (10, 40))
+        pygame.display.flip()
+
+        # Print progress periodically
+        if step_count % 200 == 0 and step_count > 0:
+            print(f"Step {step_count}: Total reward: {total_reward:.2f}")
+
+        # Cap at 30 FPS
+        clock.tick(30)
+
+    pygame.quit()
+    print(f"Session ended. Final reward: {total_reward:.2f}")
+
+
+def run_visual(env: DMControlEnv, task: str = "balance"):
+    """Run with pygame visualization showing rendered frames."""
+    import base64
+    import io
+
+    import pygame
+
+    print("\n=== Visual Mode (OpenEnv Step/Observation Pattern) ===")
+
+    # Reset environment with rendering enabled
+    result = env.reset(domain_name="cartpole", task_name=task, render=True)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get first frame to determine window size
+    if result.observation.pixels is None:
+        print("Error: Server did not return rendered pixels.")
+        print("Make sure the server supports render=True")
+        print("\nTry running in interactive mode (default) instead.")
+        sys.exit(1)
+
+    # Decode base64 PNG to pygame surface
+    png_data = base64.b64decode(result.observation.pixels)
+    frame = pygame.image.load(io.BytesIO(png_data))
+    frame_size = frame.get_size()
+
+    # Initialize pygame
+    pygame.init()
+    screen = pygame.display.set_mode(frame_size)
+    pygame.display.set_caption(
+        "Cartpole (OpenEnv) - Arrow Keys to Move, R to Reset, ESC to Quit"
+    )
+    clock = pygame.time.Clock()
+
+    print("Controls:")
+    print("  LEFT/RIGHT arrows: Move cart")
+    print("  R: Reset environment")
+    print("  ESC or Q: Quit")
+
+    running = True
+    total_reward = 0.0
+    step_count = 0
+
+    while running:
+        # Handle events
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                running = False
+            elif event.type == pygame.KEYDOWN:
+                if event.key in (pygame.K_ESCAPE, pygame.K_q):
+                    running = False
+                elif event.key == pygame.K_r:
+                    result = env.reset(
+                        domain_name="cartpole", task_name=task, render=True
+                    )
+                    total_reward = 0.0
+                    step_count = 0
+                    print("Environment reset")
+
+        # Check for held keys (for continuous control)
+        keys = pygame.key.get_pressed()
+        if keys[pygame.K_LEFT]:
+            action_value = -1.0
+        elif keys[pygame.K_RIGHT]:
+            action_value = 1.0
+        else:
+            action_value = 0.0
+
+        # Step the environment using OpenEnv pattern
+        action = DMControlAction(values=[action_value])
+        result = env.step(action, render=True)
+
+        # Track reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Check if episode is done
+        if result.done:
+            print(
+                f"Episode finished! Steps: {step_count}, "
+                f"Total reward: {total_reward:.2f}"
+            )
+            result = env.reset(domain_name="cartpole", task_name=task, render=True)
+            total_reward = 0.0
+            step_count = 0
+
+        # Render the frame from observation pixels
+        if result.observation.pixels:
+            png_data = base64.b64decode(result.observation.pixels)
+            frame = pygame.image.load(io.BytesIO(png_data))
+            screen.blit(frame, (0, 0))
+            pygame.display.flip()
+
+        # Print progress periodically
+        if step_count % 200 == 0 and step_count > 0:
+            print(f"Step {step_count}: Total reward: {total_reward:.2f}")
+
+        # Cap at 30 FPS
+        clock.tick(30)
+
+    pygame.quit()
+    print(f"Session ended. Final reward: {total_reward:.2f}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Interactive cartpole control via OpenEnv"
+    )
+    parser.add_argument(
+        "--visual",
+        action="store_true",
+        help="Enable pygame visualization with rendered frames",
+    )
+    parser.add_argument(
+        "--headless",
+        action="store_true",
+        help="Run in headless mode (no pygame, automated control)",
+    )
+    parser.add_argument(
+        "--max-steps",
+        type=int,
+        default=500,
+        help="Maximum steps for headless mode (default: 500)",
+    )
+    parser.add_argument(
+        "--task",
+        type=str,
+        default="balance",
+        choices=["balance", "balance_sparse", "swingup", "swingup_sparse"],
+        help="Cartpole task (default: balance)",
+    )
+    args = parser.parse_args()
+
+    server_url = "http://localhost:8000"
+    print(f"Connecting to {server_url}...")
+
+    try:
+        with DMControlEnv(base_url=server_url) as env:
+            print("Connected!")
+
+            # Get environment state
+            state = env.state()
+            print(f"Domain: {state.domain_name}, Task: {state.task_name}")
+            print(f"Action spec: {state.action_spec}")
+
+            if args.headless:
+                run_headless(env, task=args.task, max_steps=args.max_steps)
+            elif args.visual:
+                run_visual(env, task=args.task)
+            else:
+                run_interactive(env, task=args.task)
+
+    except ConnectionError as e:
+        print(f"Failed to connect: {e}")
+        print("\nMake sure the server is running:")
+        print("  cd OpenEnv")
+        print(
+            "  PYTHONPATH=src:envs uvicorn envs.dm_control_env.server.app:app --port 8000"
+        )
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

examples/hopper_control.py

@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+"""Interactive hopper control via OpenEnv.
+
+This example demonstrates using the dm_control OpenEnv client with
+the hopper environment. Press SPACE to apply random forces to the joints.
+
+Controls:
+    SPACE: Apply random force to all joints
+    R: Reset environment
+    ESC or Q: Quit
+
+Requirements:
+    pip install pygame
+
+Usage:
+    1. Start the server: uvicorn server.app:app --host 0.0.0.0 --port 8000
+    2. Run this script: python examples/hopper_control.py
+
+    For visual mode (requires working MuJoCo rendering):
+        python examples/hopper_control.py --visual
+"""
+
+import argparse
+import random
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from client import DMControlEnv
+from models import DMControlAction
+
+
+def get_action_dim(env: DMControlEnv) -> int:
+    """Get the action dimension from the environment state."""
+    state = env.state()
+    action_spec = state.action_spec
+    if action_spec and "shape" in action_spec:
+        shape = action_spec["shape"]
+        if isinstance(shape, list) and len(shape) > 0:
+            return shape[0]
+    # Hopper default: 4 actuators (hip, knee, ankle, toe)
+    return 4
+
+
+def generate_random_action(action_dim: int, magnitude: float = 1.0) -> DMControlAction:
+    """Generate a random action with values in [-magnitude, magnitude]."""
+    values = [random.uniform(-magnitude, magnitude) for _ in range(action_dim)]
+    return DMControlAction(values=values)
+
+
+def generate_zero_action(action_dim: int) -> DMControlAction:
+    """Generate a zero action (no force applied)."""
+    return DMControlAction(values=[0.0] * action_dim)
+
+
+def run_headless(env: DMControlEnv, task: str = "hop", max_steps: int = 1000):
+    """Run hopper control in headless mode."""
+    print("\n=== Headless Mode (OpenEnv Step/Observation Pattern) ===")
+    print("This mode demonstrates the OpenEnv API with the hopper.\n")
+
+    # Reset environment using OpenEnv pattern
+    result = env.reset(domain_name="hopper", task_name=task)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get action dimension
+    action_dim = get_action_dim(env)
+    print(f"Action dimension: {action_dim}")
+
+    total_reward = 0.0
+    step_count = 0
+
+    print("\nRunning with periodic random forces...")
+    print("Every 30 steps, a random force burst is applied.\n")
+
+    while not result.done and step_count < max_steps:
+        # Apply random force every 30 steps, otherwise zero action
+        if step_count % 30 < 5:
+            # Random force burst for 5 steps
+            action = generate_random_action(action_dim, magnitude=0.8)
+        else:
+            # No force
+            action = generate_zero_action(action_dim)
+
+        # Step the environment using OpenEnv pattern
+        result = env.step(action)
+
+        # Access observation and reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Print progress periodically
+        if step_count % 100 == 0:
+            # Get some observation values
+            position = result.observation.observations.get("position", [])
+            velocity = result.observation.observations.get("velocity", [])
+            print(
+                f"Step {step_count}: reward={result.reward:.3f}, "
+                f"total={total_reward:.2f}, done={result.done}"
+            )
+            if position:
+                print(f"  position: {position[:3]}")
+            if velocity:
+                print(f"  velocity: {velocity[:3]}")
+
+    print(f"\nEpisode finished: {step_count} steps, total reward: {total_reward:.2f}")
+
+
+def run_interactive(env: DMControlEnv, task: str = "hop"):
+    """Run interactive control with keyboard input via pygame."""
+    import pygame
+
+    print("\n=== Interactive Mode (OpenEnv Step/Observation Pattern) ===")
+    print("Press SPACE to apply random force, R to reset, ESC to quit.\n")
+
+    # Reset environment using OpenEnv pattern
+    result = env.reset(domain_name="hopper", task_name=task)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get action dimension
+    action_dim = get_action_dim(env)
+    print(f"Action dimension: {action_dim}")
+
+    # Initialize pygame for keyboard input (minimal window)
+    pygame.init()
+    screen = pygame.display.set_mode((400, 100))
+    pygame.display.set_caption("Hopper Control - SPACE for random force, R to reset")
+    clock = pygame.time.Clock()
+
+    # Font for display
+    font = pygame.font.Font(None, 24)
+
+    running = True
+    total_reward = 0.0
+    step_count = 0
+    apply_random_force = False
+
+    print("\nControls:")
+    print("  SPACE: Apply random force to joints")
+    print("  R: Reset environment")
+    print("  ESC or Q: Quit\n")
+
+    while running:
+        # Handle events
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                running = False
+            elif event.type == pygame.KEYDOWN:
+                if event.key in (pygame.K_ESCAPE, pygame.K_q):
+                    running = False
+                elif event.key == pygame.K_r:
+                    result = env.reset(domain_name="hopper", task_name=task)
+                    total_reward = 0.0
+                    step_count = 0
+                    print("Environment reset")
+
+        # Check for held keys
+        keys = pygame.key.get_pressed()
+        apply_random_force = keys[pygame.K_SPACE]
+
+        # Generate action based on input
+        if apply_random_force:
+            action = generate_random_action(action_dim, magnitude=2.0)
+        else:
+            action = generate_zero_action(action_dim)
+
+        # Step the environment using OpenEnv pattern
+        result = env.step(action)
+
+        # Track reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Check if episode is done
+        if result.done:
+            print(
+                f"Episode finished! Steps: {step_count}, "
+                f"Total reward: {total_reward:.2f}"
+            )
+            # Auto-reset on done
+            result = env.reset(domain_name="hopper", task_name=task)
+            total_reward = 0.0
+            step_count = 0
+
+        # Update display
+        screen.fill((30, 30, 30))
+        status = "FORCE!" if apply_random_force else "idle"
+        text = font.render(
+            f"Step: {step_count} | Reward: {total_reward:.1f} | {status}",
+            True,
+            (255, 255, 255),
+        )
+        screen.blit(text, (10, 40))
+        pygame.display.flip()
+
+        # Print progress periodically
+        if step_count % 200 == 0 and step_count > 0:
+            print(f"Step {step_count}: Total reward: {total_reward:.2f}")
+
+        # Cap at 30 FPS
+        clock.tick(30)
+
+    pygame.quit()
+    print(f"Session ended. Final reward: {total_reward:.2f}")
+
+
+def run_visual(env: DMControlEnv, task: str = "hop"):
+    """Run with pygame visualization showing rendered frames."""
+    import base64
+    import io
+
+    import pygame
+
+    print("\n=== Visual Mode (OpenEnv Step/Observation Pattern) ===")
+
+    # Reset environment with rendering enabled
+    result = env.reset(domain_name="hopper", task_name=task, render=True)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get action dimension
+    action_dim = get_action_dim(env)
+    print(f"Action dimension: {action_dim}")
+
+    # Get first frame to determine window size
+    if result.observation.pixels is None:
+        print("Error: Server did not return rendered pixels.")
+        print("Make sure the server supports render=True")
+        print("\nTry running in interactive mode (default) instead.")
+        sys.exit(1)
+
+    # Decode base64 PNG to pygame surface
+    png_data = base64.b64decode(result.observation.pixels)
+    frame = pygame.image.load(io.BytesIO(png_data))
+    frame_size = frame.get_size()
+
+    # Initialize pygame
+    pygame.init()
+    screen = pygame.display.set_mode(frame_size)
+    pygame.display.set_caption(
+        "Hopper (OpenEnv) - SPACE for random force, R to Reset, ESC to Quit"
+    )
+    clock = pygame.time.Clock()
+
+    print("Controls:")
+    print("  SPACE: Apply random force to joints")
+    print("  R: Reset environment")
+    print("  ESC or Q: Quit")
+
+    running = True
+    total_reward = 0.0
+    step_count = 0
+
+    while running:
+        # Handle events
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                running = False
+            elif event.type == pygame.KEYDOWN:
+                if event.key in (pygame.K_ESCAPE, pygame.K_q):
+                    running = False
+                elif event.key == pygame.K_r:
+                    result = env.reset(
+                        domain_name="hopper", task_name=task, render=True
+                    )
+                    total_reward = 0.0
+                    step_count = 0
+                    print("Environment reset")
+
+        # Check for held keys
+        keys = pygame.key.get_pressed()
+        apply_random_force = keys[pygame.K_SPACE]
+
+        # Generate action based on input
+        if apply_random_force:
+            action = generate_random_action(action_dim, magnitude=2.0)
+        else:
+            action = generate_zero_action(action_dim)
+
+        # Step the environment using OpenEnv pattern
+        result = env.step(action, render=True)
+
+        # Track reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Check if episode is done
+        if result.done:
+            print(
+                f"Episode finished! Steps: {step_count}, "
+                f"Total reward: {total_reward:.2f}"
+            )
+            result = env.reset(domain_name="hopper", task_name=task, render=True)
+            total_reward = 0.0
+            step_count = 0
+
+        # Render the frame from observation pixels
+        if result.observation.pixels:
+            png_data = base64.b64decode(result.observation.pixels)
+            frame = pygame.image.load(io.BytesIO(png_data))
+            screen.blit(frame, (0, 0))
+            pygame.display.flip()
+
+        # Print progress periodically
+        if step_count % 200 == 0 and step_count > 0:
+            print(f"Step {step_count}: Total reward: {total_reward:.2f}")
+
+        # Cap at 30 FPS
+        clock.tick(30)
+
+    pygame.quit()
+    print(f"Session ended. Final reward: {total_reward:.2f}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Interactive hopper control via OpenEnv"
+    )
+    parser.add_argument(
+        "--visual",
+        action="store_true",
+        help="Enable pygame visualization with rendered frames",
+    )
+    parser.add_argument(
+        "--headless",
+        action="store_true",
+        help="Run in headless mode (no pygame, automated control)",
+    )
+    parser.add_argument(
+        "--max-steps",
+        type=int,
+        default=1000,
+        help="Maximum steps for headless mode (default: 1000)",
+    )
+    parser.add_argument(
+        "--task",
+        type=str,
+        default="hop",
+        choices=["stand", "hop"],
+        help="Hopper task (default: hop)",
+    )
+    args = parser.parse_args()
+
+    server_url = "http://localhost:8000"
+    print(f"Connecting to {server_url}...")
+
+    try:
+        with DMControlEnv(base_url=server_url) as env:
+            print("Connected!")
+
+            # Get environment state
+            state = env.state()
+            print(f"Domain: {state.domain_name}, Task: {state.task_name}")
+            print(f"Action spec: {state.action_spec}")
+
+            if args.headless:
+                run_headless(env, task=args.task, max_steps=args.max_steps)
+            elif args.visual:
+                run_visual(env, task=args.task)
+            else:
+                run_interactive(env, task=args.task)
+
+    except ConnectionError as e:
+        print(f"Failed to connect: {e}")
+        print("\nMake sure the server is running:")
+        print("  cd OpenEnv")
+        print(
+            "  PYTHONPATH=src:envs uvicorn envs.dm_control_env.server.app:app --port 8000"
+        )
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

examples/list_environments.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""List all available dm_control.suite environments.
+
+This utility prints all available domain/task combinations from dm_control.suite.
+"""
+
+from dm_control import suite
+
+
+def main():
+    print("Available dm_control.suite environments:")
+    print("=" * 50)
+
+    # Group by domain
+    domains = {}
+    for domain, task in suite.BENCHMARKING:
+        if domain not in domains:
+            domains[domain] = []
+        domains[domain].append(task)
+
+    for domain in sorted(domains.keys()):
+        tasks = sorted(domains[domain])
+        print(f"\n{domain}:")
+        for task in tasks:
+            # Load env to get action spec
+            try:
+                env = suite.load(domain_name=domain, task_name=task)
+                action_spec = env.action_spec()
+                action_dim = action_spec.shape[0]
+                obs_keys = list(env.observation_spec().keys())
+                env.close()
+                print(f"  - {task:20s} (action_dim={action_dim}, obs={obs_keys})")
+            except Exception as e:
+                print(f"  - {task:20s} (error: {e})")
+
+    print("\n" + "=" * 50)
+    print(f"Total: {len(suite.BENCHMARKING)} environments")
+
+
+if __name__ == "__main__":
+    main()

examples/quadruped_control.py

@@ -0,0 +1,373 @@
+#!/usr/bin/env python3
+"""Interactive quadruped control via OpenEnv.
+
+This example demonstrates using the dm_control OpenEnv client with
+the quadruped environment. Press SPACE to apply random forces to the joints.
+
+Controls:
+    SPACE: Apply random force to all joints
+    R: Reset environment
+    ESC or Q: Quit
+
+Requirements:
+    pip install pygame
+
+Usage:
+    1. Start the server: uvicorn server.app:app --host 0.0.0.0 --port 8000
+    2. Run this script: python examples/quadruped_control.py
+
+    For visual mode (requires working MuJoCo rendering):
+        python examples/quadruped_control.py --visual
+"""
+
+import argparse
+import random
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from client import DMControlEnv
+from models import DMControlAction
+
+
+def get_action_dim(env: DMControlEnv) -> int:
+    """Get the action dimension from the environment state."""
+    state = env.state()
+    action_spec = state.action_spec
+    if action_spec and "shape" in action_spec:
+        shape = action_spec["shape"]
+        if isinstance(shape, list) and len(shape) > 0:
+            return shape[0]
+    # Quadruped default: 12 actuators (3 per leg x 4 legs)
+    return 12
+
+
+def generate_random_action(action_dim: int, magnitude: float = 1.0) -> DMControlAction:
+    """Generate a random action with values in [-magnitude, magnitude]."""
+    values = [random.uniform(-magnitude, magnitude) for _ in range(action_dim)]
+    return DMControlAction(values=values)
+
+
+def generate_zero_action(action_dim: int) -> DMControlAction:
+    """Generate a zero action (no force applied)."""
+    return DMControlAction(values=[0.0] * action_dim)
+
+
+def run_headless(env: DMControlEnv, max_steps: int = 1000):
+    """Run quadruped control in headless mode."""
+    print("\n=== Headless Mode (OpenEnv Step/Observation Pattern) ===")
+    print("This mode demonstrates the OpenEnv API with the quadruped.\n")
+
+    # Reset environment using OpenEnv pattern
+    result = env.reset(domain_name="quadruped", task_name="walk")
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get action dimension
+    action_dim = get_action_dim(env)
+    print(f"Action dimension: {action_dim}")
+
+    total_reward = 0.0
+    step_count = 0
+
+    print("\nRunning with periodic random forces...")
+    print("Every 50 steps, a random force burst is applied.\n")
+
+    while not result.done and step_count < max_steps:
+        # Apply random force every 50 steps, otherwise zero action
+        if step_count % 50 < 10:
+            # Random force burst for 10 steps
+            action = generate_random_action(action_dim, magnitude=0.5)
+        else:
+            # No force
+            action = generate_zero_action(action_dim)
+
+        # Step the environment using OpenEnv pattern
+        result = env.step(action)
+
+        # Access observation and reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Print progress periodically
+        if step_count % 100 == 0:
+            # Get some observation values
+            egocentric_state = result.observation.observations.get(
+                "egocentric_state", []
+            )
+            print(
+                f"Step {step_count}: reward={result.reward:.3f}, "
+                f"total={total_reward:.2f}, done={result.done}"
+            )
+            if egocentric_state:
+                print(f"  egocentric_state (first 5): {egocentric_state[:5]}")
+
+    print(f"\nEpisode finished: {step_count} steps, total reward: {total_reward:.2f}")
+
+
+def run_interactive(env: DMControlEnv):
+    """Run interactive control with keyboard input via pygame."""
+    import pygame
+
+    print("\n=== Interactive Mode (OpenEnv Step/Observation Pattern) ===")
+    print("Press SPACE to apply random force, R to reset, ESC to quit.\n")
+
+    # Reset environment using OpenEnv pattern
+    result = env.reset(domain_name="quadruped", task_name="walk")
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get action dimension
+    action_dim = get_action_dim(env)
+    print(f"Action dimension: {action_dim}")
+
+    # Initialize pygame for keyboard input (minimal window)
+    pygame.init()
+    screen = pygame.display.set_mode((400, 100))
+    pygame.display.set_caption("Quadruped Control - SPACE for random force, R to reset")
+    clock = pygame.time.Clock()
+
+    # Draw instructions on the window
+    font = pygame.font.Font(None, 24)
+
+    running = True
+    total_reward = 0.0
+    step_count = 0
+    apply_random_force = False
+
+    print("\nControls:")
+    print("  SPACE: Apply random force to joints")
+    print("  R: Reset environment")
+    print("  ESC or Q: Quit\n")
+
+    while running:
+        # Handle events
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                running = False
+            elif event.type == pygame.KEYDOWN:
+                if event.key in (pygame.K_ESCAPE, pygame.K_q):
+                    running = False
+                elif event.key == pygame.K_r:
+                    result = env.reset(domain_name="quadruped", task_name="walk")
+                    total_reward = 0.0
+                    step_count = 0
+                    print("Environment reset")
+
+        # Check for held keys
+        keys = pygame.key.get_pressed()
+        apply_random_force = keys[pygame.K_SPACE]
+
+        # Generate action based on input
+        if apply_random_force:
+            action = generate_random_action(action_dim, magnitude=2.0)
+        else:
+            action = generate_zero_action(action_dim)
+
+        # Step the environment using OpenEnv pattern
+        result = env.step(action)
+
+        # Track reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Check if episode is done
+        if result.done:
+            print(
+                f"Episode finished! Steps: {step_count}, "
+                f"Total reward: {total_reward:.2f}"
+            )
+            # Auto-reset on done
+            result = env.reset(domain_name="quadruped", task_name="walk")
+            total_reward = 0.0
+            step_count = 0
+
+        # Update display
+        screen.fill((30, 30, 30))
+        status = "FORCE!" if apply_random_force else "idle"
+        text = font.render(
+            f"Step: {step_count} | Reward: {total_reward:.1f} | {status}",
+            True,
+            (255, 255, 255),
+        )
+        screen.blit(text, (10, 40))
+        pygame.display.flip()
+
+        # Print progress periodically
+        if step_count % 200 == 0 and step_count > 0:
+            print(f"Step {step_count}: Total reward: {total_reward:.2f}")
+
+        # Cap at 30 FPS
+        clock.tick(30)
+
+    pygame.quit()
+    print(f"Session ended. Final reward: {total_reward:.2f}")
+
+
+def run_visual(env: DMControlEnv):
+    """Run with pygame visualization showing rendered frames."""
+    import base64
+    import io
+
+    import pygame
+
+    print("\n=== Visual Mode (OpenEnv Step/Observation Pattern) ===")
+
+    # Reset environment with rendering enabled
+    result = env.reset(domain_name="quadruped", task_name="walk", render=True)
+    print(f"Initial observations: {list(result.observation.observations.keys())}")
+
+    # Get action dimension
+    action_dim = get_action_dim(env)
+    print(f"Action dimension: {action_dim}")
+
+    # Get first frame to determine window size
+    if result.observation.pixels is None:
+        print("Error: Server did not return rendered pixels.")
+        print("Make sure the server supports render=True")
+        print("\nTry running in interactive mode (default) instead.")
+        sys.exit(1)
+
+    # Decode base64 PNG to pygame surface
+    png_data = base64.b64decode(result.observation.pixels)
+    frame = pygame.image.load(io.BytesIO(png_data))
+    frame_size = frame.get_size()
+
+    # Initialize pygame
+    pygame.init()
+    screen = pygame.display.set_mode(frame_size)
+    pygame.display.set_caption(
+        "Quadruped (OpenEnv) - SPACE for random force, R to Reset, ESC to Quit"
+    )
+    clock = pygame.time.Clock()
+
+    print("Controls:")
+    print("  SPACE: Apply random force to joints")
+    print("  R: Reset environment")
+    print("  ESC or Q: Quit")
+
+    running = True
+    total_reward = 0.0
+    step_count = 0
+
+    while running:
+        # Handle events
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                running = False
+            elif event.type == pygame.KEYDOWN:
+                if event.key in (pygame.K_ESCAPE, pygame.K_q):
+                    running = False
+                elif event.key == pygame.K_r:
+                    result = env.reset(
+                        domain_name="quadruped", task_name="walk", render=True
+                    )
+                    total_reward = 0.0
+                    step_count = 0
+                    print("Environment reset")
+
+        # Check for held keys
+        keys = pygame.key.get_pressed()
+        apply_random_force = keys[pygame.K_SPACE]
+
+        # Generate action based on input
+        if apply_random_force:
+            action = generate_random_action(action_dim, magnitude=2.0)
+        else:
+            action = generate_zero_action(action_dim)
+
+        # Step the environment using OpenEnv pattern
+        result = env.step(action, render=True)
+
+        # Track reward from result
+        total_reward += result.reward or 0.0
+        step_count += 1
+
+        # Check if episode is done
+        if result.done:
+            print(
+                f"Episode finished! Steps: {step_count}, "
+                f"Total reward: {total_reward:.2f}"
+            )
+            result = env.reset(domain_name="quadruped", task_name="walk", render=True)
+            total_reward = 0.0
+            step_count = 0
+
+        # Render the frame from observation pixels
+        if result.observation.pixels:
+            png_data = base64.b64decode(result.observation.pixels)
+            frame = pygame.image.load(io.BytesIO(png_data))
+            screen.blit(frame, (0, 0))
+            pygame.display.flip()
+
+        # Print progress periodically
+        if step_count % 200 == 0 and step_count > 0:
+            print(f"Step {step_count}: Total reward: {total_reward:.2f}")
+
+        # Cap at 30 FPS
+        clock.tick(30)
+
+    pygame.quit()
+    print(f"Session ended. Final reward: {total_reward:.2f}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Interactive quadruped control via OpenEnv"
+    )
+    parser.add_argument(
+        "--visual",
+        action="store_true",
+        help="Enable pygame visualization with rendered frames",
+    )
+    parser.add_argument(
+        "--headless",
+        action="store_true",
+        help="Run in headless mode (no pygame, automated control)",
+    )
+    parser.add_argument(
+        "--max-steps",
+        type=int,
+        default=1000,
+        help="Maximum steps for headless mode (default: 1000)",
+    )
+    parser.add_argument(
+        "--task",
+        type=str,
+        default="walk",
+        choices=["walk", "run", "escape", "fetch"],
+        help="Quadruped task (default: walk)",
+    )
+    args = parser.parse_args()
+
+    server_url = "http://localhost:8000"
+    print(f"Connecting to {server_url}...")
+
+    try:
+        with DMControlEnv(base_url=server_url) as env:
+            print("Connected!")
+
+            # Get environment state
+            state = env.state()
+            print(f"Domain: {state.domain_name}, Task: {state.task_name}")
+            print(f"Action spec: {state.action_spec}")
+
+            if args.headless:
+                run_headless(env, max_steps=args.max_steps)
+            elif args.visual:
+                run_visual(env)
+            else:
+                run_interactive(env)
+
+    except ConnectionError as e:
+        print(f"Failed to connect: {e}")
+        print("\nMake sure the server is running:")
+        print("  cd OpenEnv")
+        print(
+            "  PYTHONPATH=src:envs uvicorn envs.dm_control_env.server.app:app --port 8000"
+        )
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,186 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Data models for the dm_control OpenEnv Environment.
+
+This environment wraps dm_control.suite, providing access to all MuJoCo-based
+continuous control tasks (cartpole, walker, humanoid, cheetah, etc.).
+"""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import Field
+
+try:
+    from openenv.core.env_server.types import Action, Observation, State
+except ImportError:
+    from openenv.core.env_server.types import Action, Observation, State
+
+
+class DMControlAction(Action):
+    """
+    Action for dm_control environments.
+
+    All dm_control.suite environments use continuous actions represented as
+    a list of float values. The size and bounds depend on the specific
+    domain/task combination.
+
+    Example (cartpole - 1D action):
+        >>> action = DMControlAction(values=[0.5])  # Push cart right
+
+    Example (walker - 6D action):
+        >>> action = DMControlAction(values=[0.1, -0.2, 0.3, 0.0, -0.1, 0.2])
+
+    Attributes:
+        values: List of continuous action values. Shape and bounds depend on
+            the loaded environment's action_spec.
+    """
+
+    values: List[float] = Field(
+        default_factory=list,
+        description="Continuous action values matching the environment's action_spec",
+    )
+
+
+class DMControlObservation(Observation):
+    """
+    Observation from dm_control environments.
+
+    dm_control environments return observations as a dictionary of named arrays.
+    Common observation keys include 'position', 'velocity', 'orientations', etc.
+    The exact keys depend on the domain/task combination.
+
+    Example observation keys by domain:
+        - cartpole: 'position' (cos/sin of angle), 'velocity'
+        - walker: 'orientations', 'height', 'velocity'
+        - humanoid: 'joint_angles', 'head_height', 'extremities', 'torso_vertical', 'com_velocity'
+
+    Attributes:
+        observations: Dictionary mapping observation names to their values.
+            Each value is a flattened list of floats.
+        pixels: Optional base64-encoded PNG image of the rendered scene.
+            Only included when render=True is passed to reset/step.
+    """
+
+    observations: Dict[str, List[float]] = Field(
+        default_factory=dict,
+        description="Named observation arrays from the environment",
+    )
+    pixels: Optional[str] = Field(
+        default=None,
+        description="Base64-encoded PNG image (when render=True)",
+    )
+
+
+class DMControlState(State):
+    """
+    Extended state for dm_control environments.
+
+    Provides metadata about the currently loaded environment including
+    the domain/task names and action/observation specifications.
+
+    Attributes:
+        episode_id: Unique identifier for the current episode.
+        step_count: Number of steps taken in the current episode.
+        domain_name: The dm_control domain (e.g., 'cartpole', 'walker').
+        task_name: The specific task (e.g., 'balance', 'walk').
+        action_spec: Specification of the action space including shape and bounds.
+        observation_spec: Specification of the observation space.
+        physics_timestep: The physics simulation timestep in seconds.
+        control_timestep: The control timestep (time between actions) in seconds.
+    """
+
+    domain_name: str = Field(
+        default="cartpole",
+        description="The dm_control domain name",
+    )
+    task_name: str = Field(
+        default="balance",
+        description="The task name within the domain",
+    )
+    action_spec: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Specification of the action space (shape, dtype, bounds)",
+    )
+    observation_spec: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Specification of the observation space",
+    )
+    physics_timestep: float = Field(
+        default=0.002,
+        description="Physics simulation timestep in seconds",
+    )
+    control_timestep: float = Field(
+        default=0.02,
+        description="Control timestep (time between actions) in seconds",
+    )
+
+
+# Available dm_control.suite environments
+# Format: (domain_name, task_name)
+AVAILABLE_ENVIRONMENTS = [
+    # Cartpole
+    ("cartpole", "balance"),
+    ("cartpole", "balance_sparse"),
+    ("cartpole", "swingup"),
+    ("cartpole", "swingup_sparse"),
+    # Pendulum
+    ("pendulum", "swingup"),
+    # Point mass
+    ("point_mass", "easy"),
+    ("point_mass", "hard"),
+    # Reacher
+    ("reacher", "easy"),
+    ("reacher", "hard"),
+    # Ball in cup
+    ("ball_in_cup", "catch"),
+    # Finger
+    ("finger", "spin"),
+    ("finger", "turn_easy"),
+    ("finger", "turn_hard"),
+    # Fish
+    ("fish", "upright"),
+    ("fish", "swim"),
+    # Cheetah
+    ("cheetah", "run"),
+    # Walker
+    ("walker", "stand"),
+    ("walker", "walk"),
+    ("walker", "run"),
+    # Hopper
+    ("hopper", "stand"),
+    ("hopper", "hop"),
+    # Swimmer
+    ("swimmer", "swimmer6"),
+    ("swimmer", "swimmer15"),
+    # Humanoid
+    ("humanoid", "stand"),
+    ("humanoid", "walk"),
+    ("humanoid", "run"),
+    # Manipulator
+    ("manipulator", "bring_ball"),
+    ("manipulator", "bring_peg"),
+    ("manipulator", "insert_ball"),
+    ("manipulator", "insert_peg"),
+    # Acrobot
+    ("acrobot", "swingup"),
+    ("acrobot", "swingup_sparse"),
+    # Stacker
+    ("stacker", "stack_2"),
+    ("stacker", "stack_4"),
+    # Dog
+    ("dog", "stand"),
+    ("dog", "walk"),
+    ("dog", "trot"),
+    ("dog", "run"),
+    ("dog", "fetch"),
+    # Quadruped
+    ("quadruped", "walk"),
+    ("quadruped", "run"),
+    ("quadruped", "escape"),
+    ("quadruped", "fetch"),
+]

openenv.yaml

@@ -0,0 +1,6 @@
+spec_version: 1
+name: dm_control_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000

pyproject.toml

@@ -0,0 +1,48 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-dmcontrol-env"
+version = "0.1.0"
+description = "dm_control Environment for OpenEnv - wraps MuJoCo-based continuous control tasks (cartpole, walker, humanoid, etc.)"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv dependencies
+    "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git@v2.1.0",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0.0",
+    "uvicorn>=0.24.0",
+    "requests>=2.31.0",
+    # dm_control dependencies
+    "mujoco>=3.0.0",
+    "dm_control>=1.0.0",
+    "numpy>=1.20.0",
+    # Optional: for pixel observations
+    "pillow>=9.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+interactive = [
+    # For interactive examples with keyboard control
+    "pygame>=2.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+server = "dm_control_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["dm_control_env", "dm_control_env.server"]
+package-dir = { "dm_control_env" = ".", "dm_control_env.server" = "server" }

server/Dockerfile

@@ -0,0 +1,73 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build for dm_control environment
+# Uses pip for package installation
+
+FROM python:3.11-slim AS builder
+
+WORKDIR /app
+
+# Install build dependencies including OpenGL for MuJoCo
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    git \
+    libgl1 \
+    libglx-mesa0 \
+    libglew-dev \
+    libosmesa6-dev \
+    libgl1-mesa-dev \
+    libglfw3 \
+    patchelf \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy environment code
+COPY . /app/env
+
+WORKDIR /app/env
+
+# Install dependencies using pip
+RUN pip install --upgrade pip && \
+    pip install --no-cache-dir -e .
+
+# Final runtime stage
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install runtime dependencies (OpenGL for MuJoCo rendering, curl for healthcheck)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    libgl1 \
+    libglx-mesa0 \
+    libglew-dev \
+    libosmesa6-dev \
+    libglfw3 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy installed packages from builder
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy the environment code
+COPY . /app/env
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env"
+
+# Set MuJoCo to use OSMesa for headless rendering
+ENV MUJOCO_GL="osmesa"
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# Use exec to replace the shell with uvicorn so it receives SIGINT/SIGTERM directly
+CMD ["sh", "-c", "cd /app/env && exec uvicorn server.app:app --host 0.0.0.0 --port 8000"]

server/__init__.py

@@ -0,0 +1,5 @@
+"""dm_control OpenEnv server module."""
+
+from .dm_control_environment import DMControlEnvironment
+
+__all__ = ["DMControlEnvironment"]

server/app.py

@@ -0,0 +1,78 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the dm_control Environment.
+
+This module creates an HTTP server that exposes dm_control.suite environments
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+
+    from ..models import DMControlAction, DMControlObservation
+    from .dm_control_environment import DMControlEnvironment
+except ImportError:
+    from openenv.core.env_server.http_server import create_app
+
+    try:
+        import sys
+        from pathlib import Path
+
+        _parent = str(Path(__file__).parent.parent)
+        if _parent not in sys.path:
+            sys.path.insert(0, _parent)
+        from models import DMControlAction, DMControlObservation
+        from server.dm_control_environment import DMControlEnvironment
+    except ImportError:
+        try:
+            from dm_control_env.models import DMControlAction, DMControlObservation
+            from dm_control_env.server.dm_control_environment import (
+                DMControlEnvironment,
+            )
+        except ImportError:
+            from envs.dm_control_env.models import DMControlAction, DMControlObservation
+            from envs.dm_control_env.server.dm_control_environment import (
+                DMControlEnvironment,
+            )
+
+# Create the app with web interface
+# Pass the class (factory) for concurrent session support
+app = create_app(
+    DMControlEnvironment,
+    DMControlAction,
+    DMControlObservation,
+    env_name="dm_control_env",
+)
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.dm_control_env.server.app
+        openenv serve dm_control_env
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

server/dm_control_environment.py

@@ -0,0 +1,428 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+dm_control Environment Implementation.
+
+Wraps dm_control.suite environments (cartpole, walker, humanoid, etc.)
+with the OpenEnv interface for standardized reinforcement learning.
+"""
+
+import base64
+import io
+import os
+import sys
+from typing import Any, Dict, Optional
+from uuid import uuid4
+
+# Configure MuJoCo rendering backend before importing dm_control
+# On macOS, we don't set MUJOCO_GL - use default (glfw) which works
+# when running synchronously in the main thread (see reset_async/step_async)
+# On Linux, use egl for headless rendering
+if "MUJOCO_GL" not in os.environ and sys.platform != "darwin":
+    os.environ.setdefault("MUJOCO_GL", "egl")
+
+import numpy as np
+
+try:
+    from openenv.core.env_server.interfaces import Environment
+
+    from ..models import DMControlAction, DMControlObservation, DMControlState
+except ImportError:
+    from openenv.core.env_server.interfaces import Environment
+
+    try:
+        import sys
+        from pathlib import Path
+
+        _parent = str(Path(__file__).parent.parent)
+        if _parent not in sys.path:
+            sys.path.insert(0, _parent)
+        from models import DMControlAction, DMControlObservation, DMControlState
+    except ImportError:
+        try:
+            from dm_control_env.models import (
+                DMControlAction,
+                DMControlObservation,
+                DMControlState,
+            )
+        except ImportError:
+            from envs.dm_control_env.models import (
+                DMControlAction,
+                DMControlObservation,
+                DMControlState,
+            )
+
+
+class DMControlEnvironment(Environment):
+    """
+    Wraps dm_control.suite environments with the OpenEnv interface.
+
+    This environment supports all dm_control.suite domains and tasks including
+    cartpole, walker, humanoid, cheetah, and more.
+
+    Features:
+    - Dynamic environment switching via reset(domain_name="...", task_name="...")
+    - Support for all continuous control tasks
+    - Optional visual observations (base64-encoded images)
+    - Configurable via constructor or environment variables
+
+    Example:
+        >>> env = DMControlEnvironment()
+        >>> obs = env.reset()  # Default: cartpole/balance
+        >>> print(obs.observations)
+        >>>
+        >>> # Take an action
+        >>> obs = env.step(DMControlAction(values=[0.5]))  # Push cart right
+        >>> print(obs.reward)
+
+    Example with different environment:
+        >>> env = DMControlEnvironment(domain_name="walker", task_name="walk")
+        >>> obs = env.reset()
+        >>>
+        >>> # Or switch environment on reset
+        >>> obs = env.reset(domain_name="cheetah", task_name="run")
+    """
+
+    # dm_control environments are isolated and thread-safe
+    SUPPORTS_CONCURRENT_SESSIONS = True
+
+    def __init__(
+        self,
+        domain_name: Optional[str] = None,
+        task_name: Optional[str] = None,
+        render_height: Optional[int] = None,
+        render_width: Optional[int] = None,
+    ):
+        """
+        Initialize the dm_control environment.
+
+        Args:
+            domain_name: The dm_control domain to load.
+                Env var: DMCONTROL_DOMAIN (default: cartpole)
+            task_name: The task within the domain.
+                Env var: DMCONTROL_TASK (default: balance)
+            render_height: Height of rendered images (when render=True).
+                Env var: DMCONTROL_RENDER_HEIGHT (default: 480)
+            render_width: Width of rendered images (when render=True).
+                Env var: DMCONTROL_RENDER_WIDTH (default: 640)
+        """
+        self._env = None
+
+        self._domain_name = domain_name or os.environ.get(
+            "DMCONTROL_DOMAIN", "cartpole"
+        )
+        self._task_name = task_name or os.environ.get("DMCONTROL_TASK", "balance")
+        self._render_height = (
+            render_height
+            if render_height is not None
+            else int(os.environ.get("DMCONTROL_RENDER_HEIGHT", "480"))
+        )
+        self._render_width = (
+            render_width
+            if render_width is not None
+            else int(os.environ.get("DMCONTROL_RENDER_WIDTH", "640"))
+        )
+        self._include_pixels = False
+
+        self._state = DMControlState(
+            episode_id=str(uuid4()),
+            step_count=0,
+            domain_name=self._domain_name,
+            task_name=self._task_name,
+        )
+
+    def _load_environment(self, domain_name: str, task_name: str) -> None:
+        """Load or switch to a dm_control environment."""
+        if self._env is not None:
+            try:
+                self._env.close()
+            except Exception:
+                pass
+
+        try:
+            from dm_control import suite
+        except ImportError as e:
+            raise ImportError(
+                "dm_control is required. Install with: pip install dm_control"
+            ) from e
+        except Exception as e:
+            # MuJoCo/OpenGL initialization can fail on macOS
+            error_msg = str(e)
+            if sys.platform == "darwin":
+                raise RuntimeError(
+                    f"Failed to import dm_control (MuJoCo error): {error_msg}\n\n"
+                    "On macOS, try one of these solutions:\n"
+                    "1. Install osmesa: brew install mesa\n"
+                    "2. Run with MUJOCO_GL=glfw (requires display)\n"
+                    "3. Run with MUJOCO_GL=egl (if EGL is available)"
+                ) from e
+            raise
+
+        try:
+            self._env = suite.load(domain_name=domain_name, task_name=task_name)
+        except Exception as e:
+            error_msg = str(e).lower()
+            # Check for MuJoCo/OpenGL errors
+            if "gl" in error_msg or "render" in error_msg or "display" in error_msg:
+                if sys.platform == "darwin":
+                    raise RuntimeError(
+                        f"MuJoCo initialization failed: {e}\n\n"
+                        "On macOS, try one of these solutions:\n"
+                        "1. Install osmesa: brew install mesa\n"
+                        "2. Run with MUJOCO_GL=glfw (requires display)\n"
+                        "3. Set PYOPENGL_PLATFORM=osmesa"
+                    ) from e
+            # Check if it's an invalid environment error
+            try:
+                available = [(d, t) for d, t in suite.BENCHMARKING]
+                raise ValueError(
+                    f"Failed to load {domain_name}/{task_name}. "
+                    f"Available environments: {available[:10]}... "
+                    f"(use dm_control.suite.BENCHMARKING for full list)"
+                ) from e
+            except Exception:
+                raise
+
+        self._domain_name = domain_name
+        self._task_name = task_name
+
+        self._state.domain_name = domain_name
+        self._state.task_name = task_name
+        self._state.action_spec = self._get_action_spec_info()
+        self._state.observation_spec = self._get_observation_spec_info()
+        self._state.physics_timestep = self._env.physics.timestep()
+        self._state.control_timestep = self._env.control_timestep()
+
+    def _get_action_spec_info(self) -> Dict[str, Any]:
+        """Get information about the action space."""
+        spec = self._env.action_spec()
+        return {
+            "shape": list(spec.shape),
+            "dtype": str(spec.dtype),
+            "minimum": spec.minimum.tolist(),
+            "maximum": spec.maximum.tolist(),
+            "name": spec.name,
+        }
+
+    def _get_observation_spec_info(self) -> Dict[str, Any]:
+        """Get information about the observation space."""
+        specs = self._env.observation_spec()
+        obs_info = {}
+        for name, spec in specs.items():
+            obs_info[name] = {
+                "shape": list(spec.shape),
+                "dtype": str(spec.dtype),
+            }
+        return obs_info
+
+    def _get_observation(
+        self,
+        time_step,
+        include_pixels: bool = False,
+    ) -> DMControlObservation:
+        """Convert dm_control TimeStep to DMControlObservation."""
+        import dm_env
+
+        observations = {}
+        for name, value in time_step.observation.items():
+            observations[name] = np.asarray(value).flatten().tolist()
+
+        pixels = None
+        if include_pixels:
+            try:
+                frame = self._env.physics.render(
+                    height=self._render_height,
+                    width=self._render_width,
+                    camera_id=0,
+                )
+                from PIL import Image
+
+                img = Image.fromarray(frame)
+                buffer = io.BytesIO()
+                img.save(buffer, format="PNG")
+                pixels = base64.b64encode(buffer.getvalue()).decode("utf-8")
+            except Exception:
+                pass
+
+        done = time_step.step_type == dm_env.StepType.LAST
+        reward = float(time_step.reward) if time_step.reward is not None else 0.0
+
+        return DMControlObservation(
+            observations=observations,
+            pixels=pixels,
+            reward=reward,
+            done=done,
+        )
+
+    def reset(
+        self,
+        domain_name: Optional[str] = None,
+        task_name: Optional[str] = None,
+        seed: Optional[int] = None,
+        render: bool = False,
+        **kwargs,
+    ) -> DMControlObservation:
+        """
+        Reset the environment and return initial observation.
+
+        Args:
+            domain_name: Optionally switch to a different domain.
+            task_name: Optionally switch to a different task.
+            seed: Random seed for reproducibility.
+            render: If True, include pixel observations.
+            **kwargs: Additional arguments (ignored).
+
+        Returns:
+            DMControlObservation with initial state.
+        """
+        self._include_pixels = render
+
+        target_domain = domain_name or self._domain_name
+        target_task = task_name or self._task_name
+
+        if (
+            self._env is None
+            or target_domain != self._domain_name
+            or target_task != self._task_name
+        ):
+            self._load_environment(target_domain, target_task)
+
+        if seed is not None:
+            np.random.seed(seed)
+
+        time_step = self._env.reset()
+
+        self._state = DMControlState(
+            episode_id=str(uuid4()),
+            step_count=0,
+            domain_name=self._domain_name,
+            task_name=self._task_name,
+            action_spec=self._state.action_spec,
+            observation_spec=self._state.observation_spec,
+            physics_timestep=self._state.physics_timestep,
+            control_timestep=self._state.control_timestep,
+        )
+
+        return self._get_observation(time_step, include_pixels=render)
+
+    def step(
+        self,
+        action: DMControlAction,
+        render: bool = False,
+        **kwargs,
+    ) -> DMControlObservation:
+        """
+        Execute one step in the environment.
+
+        Args:
+            action: DMControlAction with continuous action values.
+            render: If True, include pixel observations.
+
+        Returns:
+            DMControlObservation with new state, reward, and done flag.
+        """
+        if self._env is None:
+            raise RuntimeError("Environment not initialized. Call reset() first.")
+
+        action_array = np.array(action.values, dtype=np.float64)
+
+        action_spec = self._env.action_spec()
+        expected_shape = action_spec.shape
+        if action_array.shape != expected_shape:
+            if action_array.size == np.prod(expected_shape):
+                action_array = action_array.reshape(expected_shape)
+            else:
+                raise ValueError(
+                    f"Action shape {action_array.shape} doesn't match "
+                    f"expected shape {expected_shape}"
+                )
+
+        action_array = np.clip(action_array, action_spec.minimum, action_spec.maximum)
+
+        time_step = self._env.step(action_array)
+        self._state.step_count += 1
+
+        return self._get_observation(
+            time_step, include_pixels=render or self._include_pixels
+        )
+
+    async def reset_async(
+        self,
+        domain_name: Optional[str] = None,
+        task_name: Optional[str] = None,
+        seed: Optional[int] = None,
+        render: bool = False,
+        **kwargs,
+    ) -> DMControlObservation:
+        """Async version of reset.
+
+        On macOS, runs synchronously to avoid MuJoCo threading crashes.
+        On other platforms, runs in a thread pool.
+        """
+        if sys.platform == "darwin":
+            # On macOS, MuJoCo crashes when run in a background thread
+            # Run synchronously (blocks event loop but avoids crash)
+            return self.reset(
+                domain_name=domain_name,
+                task_name=task_name,
+                seed=seed,
+                render=render,
+                **kwargs,
+            )
+        else:
+            import asyncio
+
+            return await asyncio.to_thread(
+                self.reset,
+                domain_name=domain_name,
+                task_name=task_name,
+                seed=seed,
+                render=render,
+                **kwargs,
+            )
+
+    async def step_async(
+        self,
+        action: DMControlAction,
+        render: bool = False,
+        **kwargs,
+    ) -> DMControlObservation:
+        """Async version of step.
+
+        On macOS, runs synchronously to avoid MuJoCo threading crashes.
+        On other platforms, runs in a thread pool.
+        """
+        if sys.platform == "darwin":
+            # On macOS, MuJoCo crashes when run in a background thread
+            # Run synchronously (blocks event loop but avoids crash)
+            return self.step(action, render=render, **kwargs)
+        else:
+            import asyncio
+
+            return await asyncio.to_thread(self.step, action, render=render, **kwargs)
+
+    @property
+    def state(self) -> DMControlState:
+        """Get the current environment state."""
+        return self._state
+
+    def close(self) -> None:
+        """Close the dm_control environment."""
+        env = getattr(self, "_env", None)
+        if env is not None:
+            try:
+                env.close()
+            except Exception:
+                pass
+            self._env = None
+
+    def __del__(self):
+        """Cleanup on deletion."""
+        try:
+            self.close()
+        except Exception:
+            pass

src/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""EnvTorch: Standardized agentic execution environments."""

src/openenv.egg-info/PKG-INFO

@@ -0,0 +1,337 @@
+Metadata-Version: 2.4
+Name: openenv
+Version: 0.2.0
+Summary: A unified framework for reinforcement learning environments
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: huggingface_hub>=0.20.0
+Requires-Dist: openai>=2.7.2
+Requires-Dist: tomli>=2.3.0
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: websockets>=15.0.1
+Provides-Extra: core
+Requires-Dist: fastapi>=0.104.0; extra == "core"
+Requires-Dist: pydantic>=2.0.0; extra == "core"
+Requires-Dist: uvicorn>=0.24.0; extra == "core"
+Requires-Dist: requests>=2.25.0; extra == "core"
+Requires-Dist: websockets>=15.0.1; extra == "core"
+Provides-Extra: cli
+Requires-Dist: typer>=0.9.0; extra == "cli"
+Requires-Dist: rich>=13.0.0; extra == "cli"
+Requires-Dist: pyyaml>=6.0; extra == "cli"
+Requires-Dist: huggingface_hub>=0.20.0; extra == "cli"
+Requires-Dist: openai>=2.7.2; extra == "cli"
+Requires-Dist: tomli>=2.3.0; extra == "cli"
+Requires-Dist: tomli-w>=1.2.0; extra == "cli"
+Provides-Extra: all
+Requires-Dist: openenv[core]; extra == "all"
+Requires-Dist: openenv[cli]; extra == "all"
+Dynamic: license-file
+
+# <img width="35" height="35" alt="image" src="https://github.com/user-attachments/assets/2700a971-e5d6-4036-b03f-2f89c9791609" /> OpenEnv: Agentic Execution Environments
+
+An e2e framework for creating, deploying and using isolated execution environments for agentic RL training, built using Gymnasium style simple APIs.
+
+[![PyPI](https://img.shields.io/pypi/v/openenv?color=blue)](https://pypi.org/project/openenv/)
+[![Discord](https://img.shields.io/badge/Discord-OpenEnv-7289da?style=flat&logo=discord&logoColor=white)](https://discord.gg/YsTYBh6PD9)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/meta-pytorch/OpenEnv/blob/main/examples/OpenEnv_Tutorial.ipynb)
+[![Docs](https://img.shields.io/badge/Docs-Explore-blue?logo=readthedocs&logoColor=white)](https://meta-pytorch.org/OpenEnv/)
+
+---
+
+**🚀 Featured Example:** Train LLMs to play BlackJack using [torchforge](https://github.com/meta-pytorch/torchforge) (PyTorch's agentic RL framework): [`examples/grpo_blackjack/`](examples/grpo_blackjack/)
+
+## OpenEnv on partner platforms:
+
+- [Lightning AI Studio](https://lightning.ai/environments?section=featured)
+- [TRL example](https://huggingface.co/docs/trl/main/en/openenv)
+- [Unsloth Google Colab](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/OpenEnv_gpt_oss_(20B)_Reinforcement_Learning_2048_Game.ipynb)
+- [ART example](https://art.openpipe.ai/integrations/openenv-integration)
+- [Oumi example](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%20-%20OpenEnv%20GRPO%20with%20trl.ipynb)
+
+## Overview
+
+OpenEnv provides a standard for interacting with agentic execution environments via simple Gymnasium style APIs - `step()`, `reset()`, `state()`. Users of agentic execution environments can interact with the environment during RL training loops using these simple APIs.
+
+In addition to making it easier for researchers and RL framework writers, we also provide tools for environment creators making it easier for them to create richer environments and make them available over familiar protocols like HTTP and packaged using canonical technologies like docker. Environment creators can use the OpenEnv framework to create environments that are isolated, secure, and easy to deploy and use.
+
+The OpenEnv CLI (`openenv`) provides commands to initialize new environments and deploy them to Hugging Face Spaces.
+
+> ⚠️ **Early Development Warning** OpenEnv is currently in an experimental
+> stage. You should expect bugs, incomplete features, and APIs that may change
+> in future versions. The project welcomes bugfixes, but to make sure things are
+> well coordinated you should discuss any significant change before starting the
+> work. It's recommended that you signal your intention to contribute in the
+> issue tracker, either by filing a new issue or by claiming an existing one.
+
+### RFCs
+
+Below is a list of active and historical RFCs for OpenEnv. RFCs are proposals for major changes or features. Please review and contribute!
+
+- [RFC 001: Baseline API and Interface Specifications](https://github.com/meta-pytorch/OpenEnv/pull/26)
+
+## Architecture
+
+### Component Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Client Application                   │
+│  ┌────────────────┐              ┌──────────────────┐   │
+│  │  EchoEnv       │              │  CodingEnv       │   │
+│  │ (HTTPEnvClient)│              ��  (HTTPEnvClient) │   │
+│  └────────┬───────┘              └────────┬─────────┘   │
+└───────────┼───────────────────────────────┼─────────────┘
+            │ HTTP                          │ HTTP
+            │ (reset, step, state)          │
+┌───────────▼───────────────────────────────▼─────────────┐
+│              Docker Containers (Isolated)               │
+│  ┌──────────────────────┐    ┌──────────────────────┐   │
+│  │ FastAPI Server       │    │ FastAPI Server       │   │
+│  │   EchoEnvironment    │    │ PythonCodeActEnv     │   │
+│  │ (Environment base)   │    │ (Environment base)   │   │
+│  └──────────────────────┘    └──────────────────────┘   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Core Components
+
+#### 1. Web Interface
+
+OpenEnv includes a built-in web interface for interactive environment exploration and debugging. The web interface provides:
+
+- **Two-Pane Layout**: HumanAgent interaction on the left, state observation on the right
+- **Real-time Updates**: WebSocket-based live updates without page refresh
+- **Dynamic Forms**: Automatically generated action forms based on environment Action types
+- **Action History**: Complete log of all actions taken and their results
+
+The web interface is **conditionally enabled** based on environment variables:
+
+- **Local Development**: Disabled by default for lightweight development
+- **Manual Override**: Enable with `ENABLE_WEB_INTERFACE=true`
+
+To use the web interface:
+
+```python
+from openenv.core.env_server import create_web_interface_app
+from your_env.models import YourAction, YourObservation
+from your_env.server.your_environment import YourEnvironment
+
+env = YourEnvironment()
+app = create_web_interface_app(env, YourAction, YourObservation)
+```
+
+When enabled, open `http://localhost:8000/web` in your browser to interact with the environment.
+
+#### 2. Environment (Server-Side)
+Base class for implementing environment logic:
+- **`reset()`**: Initialize a new episode, returns initial `Observation`
+- **`step(action)`**: Execute an `Action`, returns resulting `Observation`
+- **`state()`**: Access episode metadata (`State` with episode_id, step_count, etc.)
+
+#### 3. HTTPEnvClient (Client-Side)
+Base class for HTTP communication:
+- Handles HTTP requests to environment server
+- Contains a utility to spin up a docker container locally for the corresponding environment
+- Type-safe action/observation parsing
+
+#### 4. Container Providers
+Manage container deployment:
+- `LocalDockerProvider`: Run containers on local Docker daemon
+- `KubernetesProvider`: Deploy to K8s clusters (future)
+
+#### 5. Models
+Type-safe data structures:
+- `Action`: Base class for environment actions
+- `Observation`: Base class for environment observations
+- `State`: Episode state tracking
+- `StepResult`: Combines observation, reward, done flag
+
+## Project Structure
+
+### For Environment Creators
+
+Use the CLI to quickly scaffold a new environment:
+
+```bash
+openenv init my_env
+```
+
+This creates the following structure:
+
+```
+my_env/
+├── .dockerignore        # Docker build exclusions
+├── __init__.py           # Export YourAction, YourObservation, YourEnv
+├── models.py             # Define Action, Observation, State dataclasses
+├── client.py             # Implement YourEnv(HTTPEnvClient)
+├── README.md             # Document your environment
+├── openenv.yaml          # Environment manifest
+├── pyproject.toml        # Dependencies and package configuration
+├── outputs/              # Runtime outputs (logs, evals) - gitignored
+│   ├── logs/
+│   └── evals/
+└── server/
+    ├── your_environment.py  # Implement YourEnvironment(Environment)
+    ├── app.py               # Create FastAPI app
+    ├── requirements.txt     # Dependencies for Docker (can be generated)
+    └── Dockerfile           # Define container image
+```
+
+#### Dependency Management
+
+OpenEnv uses `pyproject.toml` as the primary dependency specification:
+
+- **Environment-level `pyproject.toml`**: Each environment defines its own dependencies
+- **Root-level `pyproject.toml`**: Contains shared core dependencies (fastapi, pydantic, uvicorn)
+- **Server `requirements.txt`**: Can be auto-generated from `pyproject.toml` for Docker builds
+
+**Development Workflow:**
+
+```bash
+# Install environment in editable mode
+cd my_env
+pip install -e .
+
+# Or using uv (faster)
+uv pip install -e .
+
+# Run server locally without Docker
+uv run server --host 0.0.0.0 --port 8000
+```
+
+**Benefits:**
+- ✅ **Client-side extensions**: Modify client classes locally without repo changes
+- ✅ **Better dependency management**: Clear separation between environments
+- ✅ **Flexible workflows**: Use pip, uv, or Docker for different scenarios
+- ✅ **CI/CD ready**: Automated dependency generation and validation
+
+See [`envs/README.md`](envs/README.md) for a complete guide on building environments.
+
+### For Environment Users
+
+To use an environment:
+1. Import from `envs.your_env`: `from envs.echo_env import EchoAction, EchoEnv`
+2. Create client: `client = EchoEnv.from_docker_image("echo-env:latest")`
+3. Interact: `client.reset()`, `client.step(action)`, `client.state()`
+4. Cleanup: `client.close()`
+
+See example scripts in `examples/` directory.
+
+## CLI Commands
+
+The OpenEnv CLI provides commands to manage environments:
+
+- **`openenv init <env_name>`** - Initialize a new environment from template
+- **`openenv push [--repo-id <repo>] [--private]`** - Deploy environment to Hugging Face Spaces
+
+### Quick Start
+
+```bash
+# Create a new environment
+openenv init my_game_env
+
+# Deploy to Hugging Face (will prompt for login if needed)
+cd my_game_env
+openenv push
+```
+
+For detailed options: `openenv init --help` and `openenv push --help`.
+
+## Design Principles
+
+1. **Separation of Concerns**: Clear client-server boundaries
+2. **Type Safety**: Strongly-typed actions, observations, and state
+3. **Container Isolation**: Each environment runs in its own container
+4. **Simple APIs**: Minimal, intuitive interfaces
+
+## Quick Start
+
+### Using the Echo Environment(Example)
+
+```python
+from envs.echo_env import EchoAction, EchoEnv
+
+# Automatically start container and connect
+client = EchoEnv.from_docker_image("echo-env:latest")
+
+# Reset the environment
+result = client.reset()
+print(result.observation.echoed_message)  # "Echo environment ready!"
+
+# Send messages
+result = client.step(EchoAction(message="Hello, World!"))
+print(result.observation.echoed_message)  # "Hello, World!"
+print(result.reward)  # 1.3 (based on message length)
+
+# Cleanup
+client.close()  # Stops and removes container
+```
+
+## Requirements
+
+- Python 3.11+
+- Docker Desktop or Docker Engine
+- FastAPI >= 0.104.0
+- Uvicorn >= 0.24.0
+- Requests >= 2.25.0
+- smolagents (for coding environment)
+
+## Supported RL Tools
+The goal of this project is to support a broad set of open and closed tools to help standardize the agentic RL community. If you have a project that supports OpenEnv environments, please put up a PR to add your tool name along with a link to your documentation.
+
+### torchforge
+See GRPO BlackJack training example: [`examples/grpo_blackjack/`](examples/grpo_blackjack/)
+
+### TRL
+See the [TRL example](https://huggingface.co/docs/trl/main/en/openenv) on how to integrate OpenEnv environments with GRPO training.
+
+### Unsloth
+See the 2048 game example based on gpt-oss: [Colab notebook](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/OpenEnv_gpt_oss_(20B)_Reinforcement_Learning_2048_Game.ipynb)
+
+### SkyRL
+See the [SkyRL example](https://skyrl.readthedocs.io/en/latest/examples/openenv.html) on how to train on OpenEnv environments with SkyRL.
+
+### ART
+See the [ART example](https://art.openpipe.ai/integrations/openenv-integration) on how OpenEnv environments can be used to train models with ART.
+
+### Oumi
+See the [Oumi example](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%20-%20OpenEnv%20GRPO%20with%20trl.ipynb) on how OpenEnv environments can be used to train models with Oumi.
+
+## Example Environments
+
+### Echo Environment
+A simple environment that echoes back messages with metadata. Perfect for:
+- Testing the HTTP server infrastructure
+- Learning the framework basics
+- Verifying container deployment
+
+See: [`envs/echo_env/README.md`](envs/echo_env/README.md)
+
+### Coding Environment
+Executes arbitrary Python code in a sandboxed environment. Features:
+- Safe code execution using smolagents
+- Capture stdout, stderr, and exit codes
+- Persistent execution context within episodes
+- Error handling with detailed messages
+
+See: [`envs/coding_env/README.md`](envs/coding_env/README.md)
+
+## Community Support & Acknowledgments
+This is an open and community-centric project. If you would like to add your name here, please put up a pull request and tag @jspisak for review. Ty!!
+
+Supporters include: Meta-PyTorch, Hugging Face, [Patronus AI](https://patronus.ai), [Surge AI](https://surgehq.ai), [LastMile AI](https://www.lastmileai.dev), Unsloth AI, Reflection AI, vLLM, SkyRL (UC-Berkeley), LightningAI, Axolotl AI, Stanford Scaling Intelligence Lab, Mithril, [OpenMined](https://openmined.org/), [Fleet AI](https://fleetai.com), [Halluminate](https://halluminate.ai/), [Turing](https://www.turing.com/) ..
+
+And we'd also like to acknowledge the team at Farama Foundation as the OpenEnv API was heavily inspired by the work you all have done on Gymnasium. Cheers!
+
+## License
+
+BSD 3-Clause License (see [LICENSE](./LICENSE) file)

src/openenv.egg-info/SOURCES.txt

@@ -0,0 +1,142 @@
+LICENSE
+README.md
+pyproject.toml
+envs/atari_env/__init__.py
+envs/atari_env/client.py
+envs/atari_env/models.py
+envs/atari_env/server/__init__.py
+envs/atari_env/server/app.py
+envs/atari_env/server/atari_environment.py
+envs/browsergym_env/__init__.py
+envs/browsergym_env/client.py
+envs/browsergym_env/models.py
+envs/browsergym_env/server/__init__.py
+envs/browsergym_env/server/app.py
+envs/browsergym_env/server/browsergym_environment.py
+envs/chat_env/__init__.py
+envs/chat_env/client.py
+envs/chat_env/models.py
+envs/chat_env/server/__init__.py
+envs/chat_env/server/app.py
+envs/chat_env/server/chat_environment.py
+envs/chat_env/server/test_chat_env.py
+envs/coding_env/__init__.py
+envs/coding_env/client.py
+envs/coding_env/models.py
+envs/coding_env/server/__init__.py
+envs/coding_env/server/app.py
+envs/coding_env/server/python_codeact_env.py
+envs/coding_env/server/python_executor.py
+envs/coding_env/server/transforms.py
+envs/connect4_env/__init__.py
+envs/connect4_env/client.py
+envs/connect4_env/models.py
+envs/connect4_env/server/__init__.py
+envs/connect4_env/server/app.py
+envs/connect4_env/server/connect4_environment.py
+envs/dipg_safety_env/__init__.py
+envs/dipg_safety_env/client.py
+envs/dipg_safety_env/models.py
+envs/dipg_safety_env/server/__init__.py
+envs/dipg_safety_env/server/app.py
+envs/dipg_safety_env/server/dipg_environment.py
+envs/echo_env/__init__.py
+envs/echo_env/client.py
+envs/echo_env/models.py
+envs/echo_env/build/lib/server/__init__.py
+envs/echo_env/build/lib/server/app.py
+envs/echo_env/build/lib/server/echo_environment.py
+envs/echo_env/server/__init__.py
+envs/echo_env/server/app.py
+envs/echo_env/server/echo_environment.py
+envs/finrl_env/__init__.py
+envs/finrl_env/client.py
+envs/finrl_env/models.py
+envs/finrl_env/server/__init__.py
+envs/finrl_env/server/app.py
+envs/finrl_env/server/finrl_environment.py
+envs/git_env/__init__.py
+envs/git_env/client.py
+envs/git_env/models.py
+envs/git_env/server/__init__.py
+envs/git_env/server/app.py
+envs/git_env/server/git_task_environment.py
+envs/openspiel_env/__init__.py
+envs/openspiel_env/client.py
+envs/openspiel_env/models.py
+envs/openspiel_env/server/__init__.py
+envs/openspiel_env/server/app.py
+envs/openspiel_env/server/openspiel_environment.py
+envs/openspiel_env/server/opponent_policies.py
+envs/play/build/lib/server/__init__.py
+envs/play/build/lib/server/app.py
+envs/play/build/lib/server/play_environment.py
+envs/sumo_rl_env/__init__.py
+envs/sumo_rl_env/client.py
+envs/sumo_rl_env/models.py
+envs/sumo_rl_env/server/__init__.py
+envs/sumo_rl_env/server/app.py
+envs/sumo_rl_env/server/sumo_environment.py
+envs/textarena_env/__init__.py
+envs/textarena_env/client.py
+envs/textarena_env/models.py
+envs/textarena_env/rewards.py
+envs/textarena_env/build/lib/server/__init__.py
+envs/textarena_env/build/lib/server/app.py
+envs/textarena_env/build/lib/server/environment.py
+envs/textarena_env/server/__init__.py
+envs/textarena_env/server/app.py
+envs/textarena_env/server/environment.py
+src/openenv/__init__.py
+src/openenv.egg-info/PKG-INFO
+src/openenv.egg-info/SOURCES.txt
+src/openenv.egg-info/dependency_links.txt
+src/openenv.egg-info/entry_points.txt
+src/openenv.egg-info/requires.txt
+src/openenv.egg-info/top_level.txt
+src/openenv/cli/__init__.py
+src/openenv/cli/__main__.py
+src/openenv/cli/_cli_utils.py
+src/openenv/cli/_validation.py
+src/openenv/cli/commands/__init__.py
+src/openenv/cli/commands/build.py
+src/openenv/cli/commands/init.py
+src/openenv/cli/commands/push.py
+src/openenv/cli/commands/serve.py
+src/openenv/cli/commands/validate.py
+src/openenv/cli/templates/__init__.py
+src/openenv/cli/templates/__pycache__/__init__.cpython-311.pyc
+src/openenv/cli/templates/__pycache__/__init__.cpython-313.pyc
+src/openenv/cli/templates/openenv_env/README.md
+src/openenv/cli/templates/openenv_env/__init__.py
+src/openenv/cli/templates/openenv_env/client.py
+src/openenv/cli/templates/openenv_env/models.py
+src/openenv/cli/templates/openenv_env/openenv.yaml
+src/openenv/cli/templates/openenv_env/pyproject.toml
+src/openenv/cli/templates/openenv_env/server/Dockerfile
+src/openenv/cli/templates/openenv_env/server/__ENV_NAME___environment.py
+src/openenv/cli/templates/openenv_env/server/__init__.py
+src/openenv/cli/templates/openenv_env/server/app.py
+src/openenv/cli/templates/openenv_env/server/requirements.txt
+src/openenv/core/__init__.py
+src/openenv/core/client_types.py
+src/openenv/core/env_client.py
+src/openenv/core/utils.py
+src/openenv/core/containers/__init__.py
+src/openenv/core/containers/test_local_docker_provider.py
+src/openenv/core/containers/runtime/__init__.py
+src/openenv/core/containers/runtime/providers.py
+src/openenv/core/containers/runtime/uv_provider.py
+src/openenv/core/env_server/__init__.py
+src/openenv/core/env_server/base_transforms.py
+src/openenv/core/env_server/exceptions.py
+src/openenv/core/env_server/http_server.py
+src/openenv/core/env_server/interfaces.py
+src/openenv/core/env_server/route_config.py
+src/openenv/core/env_server/serialization.py
+src/openenv/core/env_server/types.py
+src/openenv/core/env_server/web_interface.py
+src/openenv/core/tools/__init__.py
+src/openenv/core/tools/git_server_client.py
+src/openenv/core/tools/local_python_executor.py
+src/openenv_core/__init__.py

src/openenv.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

src/openenv.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openenv = openenv.cli.__main__:main

src/openenv.egg-info/requires.txt

@@ -0,0 +1,32 @@
+fastapi>=0.104.0
+pydantic>=2.0.0
+uvicorn>=0.24.0
+requests>=2.25.0
+typer>=0.9.0
+rich>=13.0.0
+pyyaml>=6.0
+huggingface_hub>=0.20.0
+openai>=2.7.2
+tomli>=2.3.0
+tomli-w>=1.2.0
+websockets>=15.0.1
+
+[all]
+openenv[core]
+openenv[cli]
+
+[cli]
+typer>=0.9.0
+rich>=13.0.0
+pyyaml>=6.0
+huggingface_hub>=0.20.0
+openai>=2.7.2
+tomli>=2.3.0
+tomli-w>=1.2.0
+
+[core]
+fastapi>=0.104.0
+pydantic>=2.0.0
+uvicorn>=0.24.0
+requests>=2.25.0
+websockets>=15.0.1

src/openenv.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+openenv
+openenv_core

src/openenv/__init__.py

@@ -0,0 +1,23 @@
+"""
+Unified OpenEnv package bundling the CLI and core runtime.
+"""
+
+from importlib import metadata
+
+from .auto import AutoAction, AutoEnv
+from .core import GenericEnvClient, GenericAction, SyncEnvClient
+
+__all__ = [
+    "core",
+    "cli",
+    "AutoEnv",
+    "AutoAction",
+    "GenericEnvClient",
+    "GenericAction",
+    "SyncEnvClient",
+]
+
+try:
+    __version__ = metadata.version("openenv")  # type: ignore[arg-type]
+except metadata.PackageNotFoundError:  # pragma: no cover - local dev
+    __version__ = "0.0.0"

src/openenv/auto/__init__.py

@@ -0,0 +1,39 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+OpenEnv Auto Module
+===================
+
+Provides HuggingFace-style auto-discovery API for OpenEnv environments.
+
+This module enables automatic environment and action class loading without
+manual imports:
+
+    >>> from openenv import AutoEnv, AutoAction
+    >>>
+    >>> # Load environment from installed package or HuggingFace Hub
+    >>> env = AutoEnv.from_name("coding-env")
+    >>>
+    >>> # Get action class
+    >>> CodeAction = AutoAction.from_name("coding")
+    >>> action = CodeAction(code="print('Hello!')")
+
+Classes:
+    AutoEnv: Automatic environment client selection and instantiation
+    AutoAction: Automatic action class selection
+
+The auto-discovery system works by:
+1. Discovering installed openenv-* packages via importlib.metadata
+2. Loading environment manifests (openenv.yaml) from package resources
+3. Supporting HuggingFace Hub repositories for remote environments
+4. Caching discovery results for performance
+"""
+
+from .auto_action import AutoAction
+from .auto_env import AutoEnv
+
+__all__ = ["AutoEnv", "AutoAction"]

src/openenv/auto/_discovery.py

@@ -0,0 +1,584 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Environment Auto-Discovery System
+==================================
+
+This module provides automatic discovery of OpenEnv environments by:
+1. Discovering installed openenv-* packages using importlib.metadata
+2. Loading manifests (openenv.yaml) from package resources
+3. Caching results for performance
+4. Supporting HuggingFace Hub downloads
+
+This enables AutoEnv to work without coupling to src/envs/ directory.
+"""
+
+import importlib
+import importlib.metadata
+import importlib.resources
+import json
+import logging
+import re
+import tempfile
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Dict, Optional, Type, Any
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class EnvironmentInfo:
+    """
+    Rich information about a discovered environment.
+
+    Attributes:
+        env_key: Environment key (e.g., "echo", "coding")
+        name: Full environment name (e.g., "echo_env")
+        package_name: Package name (e.g., "openenv-echo_env")
+        version: Version string
+        description: Human-readable description
+        client_module_path: Full module path to client (e.g., "echo_env.client")
+        client_class_name: Client class name (e.g., "EchoEnv")
+        action_class_name: Action class name (e.g., "EchoAction")
+        observation_class_name: Observation class name (e.g., "EchoObservation")
+        default_image: Default Docker image name (e.g., "echo-env:latest")
+        spec_version: OpenEnv spec version (from openenv.yaml)
+        manifest: Original manifest data
+    """
+
+    env_key: str
+    name: str
+    package_name: str
+    version: str
+    description: str
+    client_module_path: str
+    client_class_name: str
+    action_class_name: str
+    observation_class_name: str
+    default_image: str
+    spec_version: Optional[int] = None
+    manifest: Optional[Dict[str, Any]] = None
+
+    def get_client_class(self) -> Type:
+        """
+        Dynamically import and return the client class.
+
+        Returns:
+            Client class (e.g., EchoEnv)
+
+        Raises:
+            ImportError: If module or class cannot be imported
+        """
+        try:
+            module = importlib.import_module(self.client_module_path)
+            return getattr(module, self.client_class_name)
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import {self.client_class_name} from {self.client_module_path}: {e}\n"
+                f"Make sure the package '{self.package_name}' is installed: "
+                f"pip install {self.package_name}"
+            ) from e
+        except AttributeError as e:
+            raise ImportError(
+                f"Class {self.client_class_name} not found in {self.client_module_path}: {e}"
+            ) from e
+
+    def get_action_class(self) -> Type:
+        """
+        Dynamically import and return the action class.
+
+        Returns:
+            Action class (e.g., EchoAction)
+
+        Raises:
+            ImportError: If module or class cannot be imported
+        """
+        try:
+            module = importlib.import_module(self.client_module_path)
+            return getattr(module, self.action_class_name)
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import {self.action_class_name} from {self.client_module_path}: {e}\n"
+                f"Make sure the package '{self.package_name}' is installed: "
+                f"pip install {self.package_name}"
+            ) from e
+        except AttributeError as e:
+            raise ImportError(
+                f"Class {self.action_class_name} not found in {self.client_module_path}: {e}"
+            ) from e
+
+    def get_observation_class(self) -> Type:
+        """
+        Dynamically import and return the observation class.
+
+        Returns:
+            Observation class (e.g., EchoObservation)
+
+        Raises:
+            ImportError: If module or class cannot be imported
+        """
+        try:
+            module = importlib.import_module(self.client_module_path)
+            return getattr(module, self.observation_class_name)
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import {self.observation_class_name} from {self.client_module_path}: {e}\n"
+                f"Make sure the package '{self.package_name}' is installed: "
+                f"pip install {self.package_name}"
+            ) from e
+        except AttributeError as e:
+            raise ImportError(
+                f"Class {self.observation_class_name} not found in {self.client_module_path}: {e}"
+            ) from e
+
+
+def _normalize_env_name(name: str) -> str:
+    """
+    Normalize environment name to standard format.
+
+    Args:
+        name: Input name (e.g., "echo", "echo-env", "echo_env")
+
+    Returns:
+        Normalized name (e.g., "echo_env")
+
+    Examples:
+        >>> _normalize_env_name("echo")
+        'echo_env'
+        >>> _normalize_env_name("echo-env")
+        'echo_env'
+        >>> _normalize_env_name("echo_env")
+        'echo_env'
+    """
+    # Remove common suffixes
+    name = re.sub(r"[-_]env$", "", name)
+    # Convert hyphens to underscores
+    name = name.replace("-", "_")
+    # Add _env suffix if not present
+    if not name.endswith("_env"):
+        name = f"{name}_env"
+    return name
+
+
+def _is_hub_url(name: str) -> bool:
+    """
+    Check if name is a HuggingFace Hub URL or repo ID.
+
+    Args:
+        name: Input name
+
+    Returns:
+        True if it looks like a Hub URL
+
+    Examples:
+        >>> _is_hub_url("meta-pytorch/echo_env")
+        True
+        >>> _is_hub_url("https://huggingface.co/meta-pytorch/echo_env")
+        True
+        >>> _is_hub_url("echo")
+        False
+    """
+    # Contains org/repo pattern or huggingface.co domain
+    return "/" in name or "huggingface.co" in name
+
+
+def _infer_class_name(env_name: str, class_type: str) -> str:
+    """
+    Infer class name from environment name using simple conventions.
+
+    Args:
+        env_name: Environment name (e.g., "echo_env")
+        class_type: Type of class ("client", "action", "observation")
+
+    Returns:
+        Inferred class name
+
+    Examples:
+        >>> _infer_class_name("echo_env", "client")
+        'EchoEnv'
+        >>> _infer_class_name("echo_env", "action")
+        'EchoAction'
+    """
+    # Remove _env suffix for base name
+    base_name = env_name.replace("_env", "")
+
+    # Convert to PascalCase
+    pascal_name = "".join(word.capitalize() for word in base_name.split("_"))
+
+    # Add suffix based on type
+    if class_type == "client":
+        return f"{pascal_name}Env"
+    elif class_type == "action":
+        return f"{pascal_name}Action"
+    elif class_type == "observation":
+        return f"{pascal_name}Observation"
+    else:
+        raise ValueError(f"Unknown class type: {class_type}")
+
+
+def _load_manifest_from_package(
+    package_name: str, module_name: str
+) -> Optional[Dict[str, Any]]:
+    """
+    Load openenv.yaml manifest from an installed package.
+
+    Args:
+        package_name: Package name (e.g., "openenv-echo_env")
+        module_name: Module name (e.g., "echo_env")
+
+    Returns:
+        Parsed manifest dictionary, or None if not found
+
+    """
+    try:
+        # Try to read openenv.yaml from package
+        if hasattr(importlib.resources, "files"):
+            # Python 3.9+
+            package_files = importlib.resources.files(module_name)
+            if (package_files / "openenv.yaml").is_file():
+                manifest_text = (package_files / "openenv.yaml").read_text()
+                return yaml.safe_load(manifest_text)
+        else:
+            # Python 3.7-3.8 fallback
+            with importlib.resources.open_text(module_name, "openenv.yaml") as f:
+                return yaml.safe_load(f)
+    except (FileNotFoundError, ModuleNotFoundError, AttributeError):
+        logger.debug(f"No openenv.yaml found in {module_name}")
+        return None
+    except Exception as e:
+        logger.warning(f"Failed to load openenv.yaml from {module_name}: {e}")
+        return None
+
+
+def _create_env_info_from_package(
+    package_name: str, module_name: str, version: str
+) -> Optional[EnvironmentInfo]:
+    """
+    Create EnvironmentInfo from an installed package.
+
+    Args:
+        package_name: Package name (e.g., "openenv-echo_env")
+        module_name: Module name (e.g., "echo_env")
+        version: Package version
+
+    Returns:
+        EnvironmentInfo instance, or None if invalid
+    """
+    # Load manifest
+    manifest = _load_manifest_from_package(package_name, module_name)
+
+    # Get environment name
+    if manifest and "name" in manifest:
+        env_name = manifest["name"]
+    else:
+        # Infer from module name
+        env_name = module_name
+
+    # Normalize to ensure _env suffix
+    if not env_name.endswith("_env"):
+        env_name = f"{env_name}_env"
+
+    # Determine env_key (e.g., "echo_env" → "echo")
+    env_key = env_name.replace("_env", "") if env_name.endswith("_env") else env_name
+
+    # Get description
+    description = (
+        manifest.get("description", f"{env_name} environment")
+        if manifest
+        else f"{env_name} environment"
+    )
+
+    # Get spec version
+    spec_version = manifest.get("spec_version") if manifest else None
+
+    # Determine class names
+    # Check if manifest has custom class names (custom format)
+    if manifest and "action" in manifest and "observation" in manifest:
+        # Custom format (like coding_env)
+        client_class_name = _infer_class_name(env_name, "client")
+        action_class_name = manifest.get(
+            "action", _infer_class_name(env_name, "action")
+        )
+        observation_class_name = manifest.get(
+            "observation", _infer_class_name(env_name, "observation")
+        )
+    else:
+        # Use conventions
+        client_class_name = _infer_class_name(env_name, "client")
+        action_class_name = _infer_class_name(env_name, "action")
+        observation_class_name = _infer_class_name(env_name, "observation")
+
+    # Module path is just module_name.client
+    client_module_path = f"{module_name}.client"
+
+    # Determine default Docker image name
+    image_name = env_name.replace("_", "-")
+    default_image = f"{image_name}:latest"
+
+    return EnvironmentInfo(
+        env_key=env_key,
+        name=env_name,
+        package_name=package_name,
+        version=version,
+        description=description,
+        client_module_path=client_module_path,
+        client_class_name=client_class_name,
+        action_class_name=action_class_name,
+        observation_class_name=observation_class_name,
+        default_image=default_image,
+        spec_version=spec_version,
+        manifest=manifest,
+    )
+
+
+class EnvironmentDiscovery:
+    """
+    Auto-discovery system for OpenEnv environments using installed packages.
+
+    This class discovers installed openenv-* packages and loads their metadata.
+    """
+
+    def __init__(self):
+        """Initialize discovery system."""
+        self._cache: Optional[Dict[str, EnvironmentInfo]] = None
+        self._cache_file = Path(tempfile.gettempdir()) / "openenv_discovery_cache.json"
+
+    def _discover_installed_packages(self) -> Dict[str, EnvironmentInfo]:
+        """
+        Discover all installed openenv-* packages.
+
+        Returns:
+            Dictionary mapping env_key to EnvironmentInfo
+        """
+        environments = {}
+
+        # Invalidate import caches to ensure we pick up newly installed packages
+        importlib.invalidate_caches()
+
+        # Get all installed packages
+        try:
+            distributions = importlib.metadata.distributions()
+        except Exception as e:
+            logger.warning(f"Failed to get installed packages: {e}")
+            return environments
+
+        # Filter for openenv-* packages (exclude openenv-core)
+        for dist in distributions:
+            package_name = dist.metadata["Name"]
+
+            if not package_name.startswith("openenv-"):
+                continue
+
+            if package_name == "openenv-core":
+                continue
+
+            # Get module name (e.g., "openenv-echo_env" → "echo_env")
+            module_name = package_name.replace("openenv-", "").replace("-", "_")
+
+            # Get version
+            version = dist.version
+
+            try:
+                # Create environment info
+                env_info = _create_env_info_from_package(
+                    package_name, module_name, version
+                )
+
+                if env_info:
+                    environments[env_info.env_key] = env_info
+                    logger.debug(
+                        f"Discovered environment: {env_info.env_key} ({package_name})"
+                    )
+
+            except Exception as e:
+                logger.warning(f"Failed to load environment from {package_name}: {e}")
+                continue
+
+        return environments
+
+    def _load_cache(self) -> Optional[Dict[str, EnvironmentInfo]]:
+        """
+        Load cached discovery results.
+
+        Returns:
+            Dictionary of env_key -> EnvironmentInfo, or None if cache invalid
+        """
+        if not self._cache_file.exists():
+            return None
+
+        try:
+            with open(self._cache_file, "r") as f:
+                cache_data = json.load(f)
+
+            # Reconstruct EnvironmentInfo objects
+            cache = {}
+            for env_key, env_data in cache_data.items():
+                cache[env_key] = EnvironmentInfo(**env_data)
+
+            return cache
+        except Exception as e:
+            logger.warning(f"Failed to load discovery cache: {e}")
+            return None
+
+    def _save_cache(self, environments: Dict[str, EnvironmentInfo]) -> None:
+        """
+        Save discovery results to cache.
+
+        Args:
+            environments: Dictionary of env_key -> EnvironmentInfo
+        """
+        try:
+            cache_data = {}
+            for env_key, env_info in environments.items():
+                cache_data[env_key] = asdict(env_info)
+
+            with open(self._cache_file, "w") as f:
+                json.dump(cache_data, f, indent=2)
+
+        except Exception as e:
+            logger.warning(f"Failed to save discovery cache: {e}")
+
+    def discover(self, use_cache: bool = True) -> Dict[str, EnvironmentInfo]:
+        """
+        Discover all installed OpenEnv environments.
+
+        Args:
+            use_cache: If True, try to load from cache first
+
+        Returns:
+            Dictionary mapping env_key to EnvironmentInfo
+
+        Examples:
+            >>> discovery = EnvironmentDiscovery()
+            >>> envs = discovery.discover()
+            >>> print(envs.keys())
+            dict_keys(['echo', 'coding', ...])
+        """
+        # Try to load from memory cache first
+        if use_cache and self._cache is not None:
+            return self._cache
+
+        # Try to load from file cache
+        if use_cache:
+            cached = self._load_cache()
+            if cached is not None:
+                self._cache = cached
+                return self._cache
+
+        # Discover from installed packages
+        environments = self._discover_installed_packages()
+
+        # Save to cache
+        self._save_cache(environments)
+        self._cache = environments
+
+        return environments
+
+    def get_environment(self, env_key: str) -> Optional[EnvironmentInfo]:
+        """
+        Get information about a specific environment.
+
+        Args:
+            env_key: Environment key (e.g., "echo", "coding")
+
+        Returns:
+            EnvironmentInfo if found, None otherwise
+
+        Examples:
+            >>> discovery = EnvironmentDiscovery()
+            >>> env = discovery.get_environment("echo")
+            >>> print(env.client_class_name)
+            'EchoEnv'
+        """
+        environments = self.discover()
+        return environments.get(env_key)
+
+    def get_environment_by_name(self, name: str) -> Optional[EnvironmentInfo]:
+        """
+        Get environment info by flexible name matching.
+
+        Args:
+            name: Environment name (e.g., "echo", "echo-env", "echo_env")
+
+        Returns:
+            EnvironmentInfo if found, None otherwise
+        """
+        # Normalize name to env_key
+        normalized = _normalize_env_name(name)
+        env_key = normalized.replace("_env", "")
+
+        return self.get_environment(env_key)
+
+    def list_environments(self) -> None:
+        """
+        Print a formatted list of all discovered environments.
+
+        Examples:
+            >>> discovery = EnvironmentDiscovery()
+            >>> discovery.list_environments()
+            Available OpenEnv Environments:
+            ----------------------------------------------------------------------
+              echo           : Echo Environment (v0.1.0) - openenv-echo_env
+              coding         : Coding Environment (v0.1.0) - openenv-coding_env
+              ...
+        """
+        environments = self.discover()
+
+        print("Available OpenEnv Environments:")
+        print("-" * 70)
+
+        if not environments:
+            print("  No OpenEnv environments found.")
+            print("  Install environments with: pip install openenv-<env-name>")
+        else:
+            for env_key in sorted(environments.keys()):
+                env = environments[env_key]
+                print(f"  {env_key:<15}: {env.description} (v{env.version})")
+                print(f"                   Package: {env.package_name}")
+
+        print("-" * 70)
+        print(f"Total: {len(environments)} environments")
+
+    def clear_cache(self) -> None:
+        """Clear the discovery cache."""
+        if self._cache_file.exists():
+            self._cache_file.unlink()
+        self._cache = None
+
+
+# Global discovery instance
+_global_discovery: Optional[EnvironmentDiscovery] = None
+
+
+def get_discovery() -> EnvironmentDiscovery:
+    """
+    Get or create the global discovery instance.
+
+    Returns:
+        Global EnvironmentDiscovery instance
+
+    Examples:
+        >>> discovery = get_discovery()
+        >>> envs = discovery.discover()
+    """
+    global _global_discovery
+
+    if _global_discovery is None:
+        _global_discovery = EnvironmentDiscovery()
+
+    return _global_discovery
+
+
+def reset_discovery() -> None:
+    """Reset the global discovery instance (useful for testing)."""
+    global _global_discovery
+    if _global_discovery is not None:
+        _global_discovery.clear_cache()
+    _global_discovery = None

src/openenv/auto/auto_action.py

@@ -0,0 +1,276 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+AutoAction - Automatic Action Class Selection
+==============================================
+
+AutoAction provides a HuggingFace-style API for automatically retrieving the
+correct Action class from installed packages or HuggingFace Hub.
+
+This module simplifies working with environment actions by automatically
+detecting and returning the appropriate Action class without requiring
+manual imports.
+
+Example:
+    >>> from openenv import AutoEnv, AutoAction
+    >>>
+    >>> # Get Action class from environment name
+    >>> CodeAction = AutoAction.from_env("coding")
+    >>> action = CodeAction(code="print('Hello!')")
+    >>>
+    >>> # From HuggingFace Hub
+    >>> CodeAction = AutoAction.from_env("meta-pytorch/coding-env")
+    >>>
+    >>> # Use with AutoEnv
+    >>> env = AutoEnv.from_env("coding-env")
+    >>> result = env.step(action)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Type, Dict, Any
+
+from ._discovery import get_discovery, _is_hub_url
+from .auto_env import AutoEnv
+
+logger = logging.getLogger(__name__)
+
+
+class AutoAction:
+    """
+    AutoAction automatically retrieves the correct Action class based on
+    environment names or HuggingFace Hub repositories.
+
+    This class follows the HuggingFace AutoModel pattern, making it easy to
+    get the right Action class without needing to know which module to import.
+
+    The class provides factory methods that look up the Action class and
+    return the class (not an instance) for you to instantiate.
+
+    Example:
+        >>> # From installed package
+        >>> CodeAction = AutoAction.from_env("coding")
+        >>> action = CodeAction(code="print('test')")
+        >>>
+        >>> # From HuggingFace Hub
+        >>> CodeAction = AutoAction.from_env("meta-pytorch/coding-env")
+        >>> action = CodeAction(code="print('test')")
+        >>>
+        >>> # Use with AutoEnv for a complete workflow
+        >>> env = AutoEnv.from_env("coding-env")
+        >>> ActionClass = AutoAction.from_env("coding-env")
+        >>> action = ActionClass(code="print('Hello, AutoAction!')")
+        >>> result = env.step(action)
+
+    Note:
+        AutoAction is not meant to be instantiated directly. Use the class
+        method from_env() instead.
+    """
+
+    def __init__(self):
+        """AutoAction should not be instantiated directly. Use class methods instead."""
+        raise TypeError(
+            "AutoAction is a factory class and should not be instantiated directly. "
+            "Use AutoAction.from_hub() or AutoAction.from_env() instead."
+        )
+
+    @classmethod
+    def from_env(cls, name: str, skip_install: bool = False) -> Type:
+        """
+        Get the Action class from environment name or HuggingFace Hub repository.
+
+        This method automatically:
+        1. Checks if the name is a HuggingFace Hub URL/repo ID
+        2. If Hub: downloads and installs the environment package
+        3. If local: looks up the installed openenv-* package
+        4. Imports and returns the Action class
+
+        Args:
+            name: Environment name or HuggingFace Hub repo ID
+                  Examples:
+                  - "coding" / "coding-env" / "coding_env"
+                  - "meta-pytorch/coding-env" (Hub repo ID)
+                  - "https://huggingface.co/meta-pytorch/coding-env" (Hub URL)
+            skip_install: If True, skip package installation and return
+                GenericAction class instead. Use this when working with
+                GenericEnvClient to avoid installing remote packages.
+
+        Returns:
+            Action class (not an instance!). Returns GenericAction when
+            skip_install=True.
+
+        Raises:
+            ValueError: If environment not found (only when skip_install=False)
+            ImportError: If environment package is not installed (only when skip_install=False)
+
+        Examples:
+            >>> # From installed package
+            >>> CodeAction = AutoAction.from_env("coding-env")
+            >>> action = CodeAction(code="print('Hello!')")
+            >>>
+            >>> # From HuggingFace Hub
+            >>> CodeAction = AutoAction.from_env("meta-pytorch/coding-env")
+            >>> action = CodeAction(code="print('Hello!')")
+            >>>
+            >>> # Skip installation, use GenericAction (for GenericEnvClient)
+            >>> ActionClass = AutoAction.from_env("user/repo", skip_install=True)
+            >>> action = ActionClass(code="print('Hello!')")  # Returns GenericAction
+            >>>
+            >>> # Different name formats
+            >>> EchoAction = AutoAction.from_env("echo")
+            >>> EchoAction = AutoAction.from_env("echo-env")
+            >>> EchoAction = AutoAction.from_env("echo_env")
+        """
+        # If skip_install is True, return GenericAction without any package lookup
+        if skip_install:
+            from openenv.core.generic_client import GenericAction
+
+            logger.info(
+                f"Returning GenericAction for '{name}' (skip_install=True). "
+                f"Use keyword arguments to create actions: GenericAction(code='...')"
+            )
+            return GenericAction
+
+        # Check if it's a HuggingFace Hub URL or repo ID
+        if _is_hub_url(name):
+            # Ensure package is installed (reuse AutoEnv logic, downloads only if needed)
+            env_name = AutoEnv._ensure_package_from_hub(name)
+        else:
+            env_name = name
+
+        # Get environment info from discovery
+        discovery = get_discovery()
+        env_info = discovery.get_environment_by_name(env_name)
+
+        if not env_info:
+            # Environment not found - provide helpful error message
+            available_envs = discovery.discover()
+
+            if not available_envs:
+                raise ValueError(
+                    "No OpenEnv environments found.\n"
+                    "Install an environment with: pip install openenv-<env-name>\n"
+                    "Or specify a HuggingFace Hub repository: AutoAction.from_env('openenv/echo_env')"
+                )
+
+            # Try to suggest similar environment names
+            from difflib import get_close_matches
+
+            env_keys = list(available_envs.keys())
+            suggestions = get_close_matches(env_name, env_keys, n=3, cutoff=0.6)
+
+            error_msg = f"Unknown environment '{env_name}'.\n"
+            if suggestions:
+                error_msg += f"Did you mean: {', '.join(suggestions)}?\n"
+            error_msg += f"Available environments: {', '.join(sorted(env_keys))}"
+
+            raise ValueError(error_msg)
+
+        # Get the action class
+        try:
+            action_class = env_info.get_action_class()
+            return action_class
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import action class for '{env_name}'.\n"
+                f"Package '{env_info.package_name}' appears to be installed but the module cannot be imported.\n"
+                f"Try reinstalling: pip install --force-reinstall {env_info.package_name}\n"
+                f"Original error: {e}"
+            ) from e
+
+    @classmethod
+    def from_hub(cls, env_name: str, skip_install: bool = False) -> Type:
+        """
+        Get the Action class from environment name.
+
+        This is an alias for from_env() for backward compatibility and clarity.
+
+        Args:
+            env_name: Environment name (e.g., "coding", "echo")
+            skip_install: If True, skip package installation and return
+                GenericAction class instead.
+
+        Returns:
+            Action class (not an instance!)
+
+        Examples:
+            >>> CodeAction = AutoAction.from_hub("coding")
+            >>> action = CodeAction(code="print('Hello!')")
+        """
+        return cls.from_env(env_name, skip_install=skip_install)
+
+    @classmethod
+    def get_action_info(cls, name: str) -> Dict[str, Any]:
+        """
+        Get detailed information about an action class.
+
+        Args:
+            name: Environment name
+
+        Returns:
+            Dictionary with action class metadata
+
+        Raises:
+            ValueError: If environment not found
+
+        Examples:
+            >>> info = AutoAction.get_action_info("coding")
+            >>> print(info['action_class'])
+            'CodingAction'
+            >>> print(info['module'])
+            'coding_env.client'
+        """
+        discovery = get_discovery()
+        env_info = discovery.get_environment_by_name(name)
+
+        if not env_info:
+            raise ValueError(f"Unknown environment: {name}")
+
+        return {
+            "env_key": env_info.env_key,
+            "env_name": env_info.name,
+            "package": env_info.package_name,
+            "action_class": env_info.action_class_name,
+            "observation_class": env_info.observation_class_name,
+            "module": env_info.client_module_path,
+        }
+
+    @classmethod
+    def list_actions(cls) -> None:
+        """
+        Print a formatted list of all available action classes.
+
+        This discovers all installed openenv-* packages and displays
+        their action class information in a user-friendly format.
+
+        Examples:
+            >>> AutoAction.list_actions()
+            Available Action Classes:
+            ----------------------------------------------------------------------
+              echo           : EchoAction (from openenv-echo-env)
+              coding         : CodingAction (from openenv-coding_env)
+            ----------------------------------------------------------------------
+            Total: 2 action classes
+        """
+        discovery = get_discovery()
+        environments = discovery.discover()
+
+        print("Available Action Classes:")
+        print("-" * 70)
+
+        if not environments:
+            print("  No OpenEnv environments found.")
+            print("  Install environments with: pip install openenv-<env-name>")
+        else:
+            for env_key in sorted(environments.keys()):
+                env = environments[env_key]
+                print(f"  {env_key:<15}: {env.action_class_name}")
+                print(f"                   Package: {env.package_name}")
+
+        print("-" * 70)
+        print(f"Total: {len(environments)} action classes")

src/openenv/auto/auto_env.py

@@ -0,0 +1,896 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+AutoEnv - Automatic Environment Selection
+==========================================
+
+AutoEnv provides a HuggingFace-style API for automatically selecting and
+instantiating the correct environment client from installed packages or
+HuggingFace Hub.
+
+This module simplifies environment creation by automatically detecting the
+environment type from the name and instantiating the appropriate client class.
+
+Example:
+    >>> from openenv import AutoEnv, AutoAction
+    >>>
+    >>> # From installed package
+    >>> env = AutoEnv.from_env("coding-env")
+    >>>
+    >>> # From HuggingFace Hub
+    >>> env = AutoEnv.from_env("meta-pytorch/coding-env")
+    >>>
+    >>> # With configuration
+    >>> env = AutoEnv.from_env("coding", env_vars={"DEBUG": "1"})
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+import shutil
+import subprocess
+import sys
+import requests
+from typing import Any, Optional, TYPE_CHECKING, Dict
+
+from ._discovery import get_discovery, _is_hub_url
+from openenv.core.utils import run_async_safely
+
+
+if TYPE_CHECKING:
+    from openenv.core.containers.runtime import ContainerProvider
+    from openenv.core.env_client import EnvClient
+
+logger = logging.getLogger(__name__)
+
+# Cache for repo ID → env_name mapping to avoid redundant downloads
+_hub_env_name_cache: Dict[str, str] = {}
+
+# Environment variable to skip user confirmation for remote installs
+OPENENV_TRUST_REMOTE_CODE = "OPENENV_TRUST_REMOTE_CODE"
+
+
+def _has_uv() -> bool:
+    """Check if uv is available in the system."""
+    return shutil.which("uv") is not None
+
+
+def _get_pip_command() -> list[str]:
+    """
+    Get the appropriate pip command (uv pip or pip).
+
+    Returns:
+        List of command parts for pip installation
+    """
+    if _has_uv():
+        return ["uv", "pip"]
+    return [sys.executable, "-m", "pip"]
+
+
+def _confirm_remote_install(repo_id: str) -> bool:
+    """
+    Ask user for confirmation before installing remote code.
+
+    This is a security measure since we're executing code from the internet.
+
+    Args:
+        repo_id: The HuggingFace repo ID being installed
+
+    Returns:
+        True if user confirms, False otherwise
+    """
+    # Check environment variable for automated/CI environments
+    if os.environ.get(OPENENV_TRUST_REMOTE_CODE, "").lower() in ("1", "true", "yes"):
+        logger.info("Skipping confirmation (OPENENV_TRUST_REMOTE_CODE is set)")
+        return True
+
+    # Check if we're in an interactive terminal
+    if not sys.stdin.isatty():
+        logger.warning(
+            "Cannot prompt for confirmation in non-interactive mode. "
+            "Set OPENENV_TRUST_REMOTE_CODE=1 to allow remote installs."
+        )
+        return False
+
+    print(f"\n{'=' * 60}")
+    print("⚠️  SECURITY WARNING: Remote Code Installation")
+    print(f"{'=' * 60}")
+    print("You are about to install code from a remote repository:")
+    print(f"  Repository: {repo_id}")
+    print(f"  Source: https://huggingface.co/spaces/{repo_id}")
+    print("\nThis will execute code from the internet on your machine.")
+    print("Only proceed if you trust the source.")
+    print(f"{'=' * 60}\n")
+
+    try:
+        response = input("Do you want to proceed? [y/N]: ").strip().lower()
+        return response in ("y", "yes")
+    except (EOFError, KeyboardInterrupt):
+        print("\nInstallation cancelled.")
+        return False
+
+
+class AutoEnv:
+    """
+    AutoEnv automatically selects and instantiates the correct environment client
+    based on environment names or HuggingFace Hub repositories.
+
+    This class follows the HuggingFace AutoModel pattern, making it easy to work
+    with different environments without needing to import specific client classes.
+
+    The class provides factory methods that:
+    1. Check if name is a HuggingFace Hub URL/repo ID
+    2. If Hub: download and install the environment package
+    3. If local: look up the installed openenv-* package
+    4. Import and instantiate the client class
+
+    Example:
+        >>> # From installed package
+        >>> env = AutoEnv.from_env("coding-env")
+        >>>
+        >>> # From HuggingFace Hub
+        >>> env = AutoEnv.from_env("meta-pytorch/coding-env")
+        >>>
+        >>> # List available environments
+        >>> AutoEnv.list_environments()
+
+    Note:
+        AutoEnv is not meant to be instantiated directly. Use the class method
+        from_env() instead.
+    """
+
+    def __init__(self):
+        """AutoEnv should not be instantiated directly. Use class methods instead."""
+        raise TypeError(
+            "AutoEnv is a factory class and should not be instantiated directly. "
+            "Use AutoEnv.from_hub() or AutoEnv.from_env() instead."
+        )
+
+    @classmethod
+    def _resolve_space_url(cls, repo_id: str) -> str:
+        """
+        Resolve HuggingFace Space repo ID to Space URL.
+
+        Args:
+            repo_id: HuggingFace repo ID (e.g., "wukaixingxp/coding-env-test")
+
+        Returns:
+            Space URL (e.g., "https://wukaixingxp-coding-env-test.hf.space")
+
+        Examples:
+            >>> AutoEnv._resolve_space_url("wukaixingxp/coding-env-test")
+            'https://wukaixingxp-coding-env-test.hf.space'
+        """
+        # Clean up repo_id if it's a full URL
+        if "huggingface.co" in repo_id:
+            # Extract org/repo from URL
+            # https://huggingface.co/wukaixingxp/coding-env-test -> wukaixingxp/coding-env-test
+            parts = repo_id.split("/")
+            if len(parts) >= 2:
+                repo_id = f"{parts[-2]}/{parts[-1]}"
+
+        # Convert user/space-name to user-space-name.hf.space
+        space_slug = repo_id.replace("/", "-")
+        return f"https://{space_slug}.hf.space"
+
+    @classmethod
+    def _is_local_url(cls, url: str) -> bool:
+        """
+        Check if a URL points to a local server.
+
+        Args:
+            url: URL to check
+
+        Returns:
+            True if URL is localhost or 127.0.0.1, False otherwise
+
+        Examples:
+            >>> AutoEnv._is_local_url("http://localhost:8000")
+            True
+            >>> AutoEnv._is_local_url("http://127.0.0.1:8000")
+            True
+            >>> AutoEnv._is_local_url("https://example.com")
+            False
+        """
+        url_lower = url.lower()
+        return "localhost" in url_lower or "127.0.0.1" in url_lower
+
+    @classmethod
+    def _check_server_availability(cls, base_url: str, timeout: float = 2.0) -> bool:
+        """
+        Check if a server at the given URL is running and accessible.
+
+        Args:
+            base_url: Server base URL to check
+            timeout: Request timeout in seconds
+
+        Returns:
+            True if server is accessible, False otherwise
+
+        Examples:
+            >>> AutoEnv._check_server_availability("http://localhost:8000")
+            True  # if server is running
+        """
+        try:
+            # Bypass proxy for localhost to avoid proxy issues
+            proxies = None
+            if cls._is_local_url(base_url):
+                proxies = {"http": None, "https": None}
+
+            # Try to access the health endpoint
+            response = requests.get(
+                f"{base_url}/health", timeout=timeout, proxies=proxies
+            )
+            if response.status_code == 200:
+                return True
+
+            # If health endpoint doesn't exist, try root endpoint
+            response = requests.get(base_url, timeout=timeout, proxies=proxies)
+            return response.status_code == 200
+        except (requests.RequestException, Exception) as e:
+            logger.debug(f"Server {base_url} not accessible: {e}")
+            return False
+
+    @classmethod
+    def _check_space_availability(cls, space_url: str, timeout: float = 5.0) -> bool:
+        """
+        Check if HuggingFace Space is running and accessible.
+
+        Args:
+            space_url: Space URL to check
+            timeout: Request timeout in seconds
+
+        Returns:
+            True if Space is accessible, False otherwise
+
+        Examples:
+            >>> AutoEnv._check_space_availability("https://wukaixingxp-coding-env-test.hf.space")
+            True
+        """
+        try:
+            # Try to access the health endpoint
+            response = requests.get(f"{space_url}/health", timeout=timeout)
+            if response.status_code == 200:
+                return True
+
+            # If health endpoint doesn't exist, try root endpoint
+            response = requests.get(space_url, timeout=timeout)
+            return response.status_code == 200
+        except (requests.RequestException, Exception) as e:
+            logger.debug(f"Space {space_url} not accessible: {e}")
+            return False
+
+    @classmethod
+    def _get_hub_git_url(cls, repo_id: str) -> str:
+        """
+        Get the git URL for a HuggingFace Space.
+
+        Args:
+            repo_id: HuggingFace repo ID (e.g., "wukaixingxp/coding-env-test")
+
+        Returns:
+            Git URL for pip installation (e.g., "git+https://huggingface.co/spaces/wukaixingxp/coding-env-test")
+        """
+        # Clean up repo_id if it's a full URL
+        if "huggingface.co" in repo_id:
+            parts = repo_id.split("/")
+            if len(parts) >= 2:
+                repo_id = f"{parts[-2]}/{parts[-1]}"
+
+        return f"git+https://huggingface.co/spaces/{repo_id}"
+
+    @classmethod
+    def _install_from_hub(cls, repo_id: str, trust_remote_code: bool = False) -> str:
+        """
+        Install environment package directly from HuggingFace Hub using git+.
+
+        This is the preferred method as it avoids downloading the entire repo
+        and uses pip/uv's native git support.
+
+        Args:
+            repo_id: HuggingFace repo ID (e.g., "wukaixingxp/coding-env-test")
+            trust_remote_code: If True, skip user confirmation
+
+        Returns:
+            Package name that was installed
+
+        Raises:
+            ValueError: If installation fails or user declines
+        """
+        # Security check - confirm with user before installing remote code
+        if not trust_remote_code and not _confirm_remote_install(repo_id):
+            raise ValueError(
+                "Installation cancelled by user.\n"
+                "To allow remote installs without prompting, set OPENENV_TRUST_REMOTE_CODE=1"
+            )
+
+        git_url = cls._get_hub_git_url(repo_id)
+        pip_cmd = _get_pip_command()
+        pip_name = "uv pip" if pip_cmd[0] == "uv" else "pip"
+
+        logger.info(f"Installing from HuggingFace Space using {pip_name}: {repo_id}")
+        logger.info(f"Command: {' '.join(pip_cmd)} install {git_url}")
+
+        try:
+            result = subprocess.run(
+                [*pip_cmd, "install", git_url],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+
+            # Try to extract package name from pip output
+            # Look for "Successfully installed <package-name>-<version>"
+            for line in result.stdout.split("\n"):
+                if "Successfully installed" in line:
+                    # Parse package name from the line
+                    parts = line.replace("Successfully installed", "").strip().split()
+                    for part in parts:
+                        if part.startswith("openenv-"):
+                            # Remove version suffix (e.g., "openenv-coding_env-0.1.0" -> "openenv-coding_env")
+                            # Check if last segment looks like a version number
+                            last_segment = part.rsplit("-", 1)[-1]
+                            if last_segment.replace(".", "").isdigit():
+                                package_name = "-".join(part.rsplit("-", 1)[:-1])
+                            else:
+                                package_name = part
+                            logger.info(f"Successfully installed: {package_name}")
+                            return package_name
+
+            # Fallback: try to determine package name from repo_id
+            # Convention: repo name like "coding-env-test" -> package "openenv-coding_env"
+            env_name = repo_id.split("/")[-1]  # Get repo name from "user/repo"
+            env_name = env_name.replace("-", "_")
+            if not env_name.endswith("_env"):
+                env_name = f"{env_name}_env"
+            package_name = f"openenv-{env_name}"
+
+            logger.info(f"Installed (inferred package name): {package_name}")
+            return package_name
+
+        except subprocess.CalledProcessError as e:
+            error_msg = e.stderr or e.stdout or str(e)
+            raise ValueError(
+                f"Failed to install environment from HuggingFace Space: {repo_id}\n"
+                f"Command: {' '.join(pip_cmd)} install {git_url}\n"
+                f"Error: {error_msg}\n"
+                f"Make sure the repository exists and contains a valid Python package."
+            ) from e
+
+    @classmethod
+    def _is_package_installed(cls, package_name: str) -> bool:
+        """
+        Check if a package is already installed.
+
+        Args:
+            package_name: Package name (e.g., "openenv-coding_env")
+
+        Returns:
+            True if installed, False otherwise
+        """
+        try:
+            import importlib.metadata
+
+            importlib.metadata.distribution(package_name)
+            return True
+        except importlib.metadata.PackageNotFoundError:
+            return False
+
+    @classmethod
+    def _ensure_package_from_hub(
+        cls, name: str, trust_remote_code: bool = False
+    ) -> str:
+        """
+        Ensure package from HuggingFace Hub is installed.
+
+        Uses git+ URLs for direct installation without downloading the entire repo.
+        Prompts user for confirmation before installing remote code.
+
+        Args:
+            name: HuggingFace repo ID (e.g., "wukaixingxp/coding-env-test")
+            trust_remote_code: If True, skip user confirmation
+
+        Returns:
+            Environment name (e.g., "coding_env")
+        """
+        global _hub_env_name_cache
+
+        # Check if we already resolved this repo ID
+        if name in _hub_env_name_cache:
+            env_name = _hub_env_name_cache[name]
+            logger.debug(f"Using cached env name for {name}: {env_name}")
+            return env_name
+
+        # Try to infer expected package name from repo ID
+        # Convention: repo "user/coding-env" -> package "openenv-coding_env"
+        repo_name = name.split("/")[-1] if "/" in name else name
+        expected_env_name = repo_name.replace("-", "_")
+        if not expected_env_name.endswith("_env"):
+            expected_env_name = f"{expected_env_name}_env"
+        expected_package_name = f"openenv-{expected_env_name}"
+
+        # Check if already installed
+        if cls._is_package_installed(expected_package_name):
+            logger.info(f"Package already installed: {expected_package_name}")
+            # Clear and refresh discovery cache to make sure it's detected
+            get_discovery().clear_cache()
+            get_discovery().discover(use_cache=False)
+            # Cache the result
+            _hub_env_name_cache[name] = expected_env_name
+            return expected_env_name
+
+        # Not installed, install using git+ URL
+        logger.info(f"Package not found locally, installing from Hub: {name}")
+
+        # Track existing packages before installation
+        get_discovery().clear_cache()
+        existing_envs = set(get_discovery().discover(use_cache=False).keys())
+
+        # Install the package
+        cls._install_from_hub(name, trust_remote_code=trust_remote_code)
+
+        # Clear discovery cache to pick up the newly installed package
+        try:
+            importlib.invalidate_caches()
+        except Exception:
+            pass
+        get_discovery().clear_cache()
+        discovered_envs = get_discovery().discover(use_cache=False)
+
+        # Find the newly installed environment by comparing before/after
+        new_envs = set(discovered_envs.keys()) - existing_envs
+
+        if new_envs:
+            # Use the first newly discovered environment
+            env_name = next(iter(new_envs))
+            logger.info(f"Found newly installed environment: '{env_name}'")
+        else:
+            # Fallback: try to find by matching module patterns
+            # Look for any env that might match the repo name pattern
+            repo_name = name.split("/")[-1] if "/" in name else name
+            repo_base = (
+                repo_name.replace("-", "_").replace("_env", "").replace("_test", "")
+            )
+
+            env_name = None
+            for env_key, env_info in discovered_envs.items():
+                # Check if env_key is a prefix/substring match
+                if env_key in repo_base or repo_base.startswith(env_key):
+                    env_name = env_key
+                    logger.info(
+                        f"Found matching environment '{env_name}' for repo '{name}'"
+                    )
+                    break
+
+            if env_name is None:
+                # Last resort: use inferred name from repo
+                env_name = repo_name.replace("-", "_")
+                if not env_name.endswith("_env"):
+                    env_name = f"{env_name}_env"
+                # Strip to get env_key
+                env_name = env_name.replace("_env", "")
+                logger.warning(
+                    f"Could not find newly installed environment for repo '{name}', "
+                    f"using inferred name: {env_name}"
+                )
+
+        # Cache the result to avoid redundant installs
+        _hub_env_name_cache[name] = env_name
+
+        return env_name
+
+    @classmethod
+    def from_env(
+        cls,
+        name: str,
+        base_url: Optional[str] = None,
+        docker_image: Optional[str] = None,
+        container_provider: Optional[ContainerProvider] = None,
+        wait_timeout: float = 30.0,
+        env_vars: Optional[Dict[str, str]] = None,
+        trust_remote_code: bool = False,
+        skip_install: bool = False,
+        **kwargs: Any,
+    ) -> "EnvClient":
+        """
+        Create an environment client from a name or HuggingFace Hub repository.
+
+        This method automatically:
+        1. Checks if the name is a HuggingFace Hub URL/repo ID
+        2. If Hub: installs the environment package using git+ URL
+        3. If local: looks up the installed openenv-* package
+        4. Imports the client class and instantiates it
+
+        Args:
+            name: Environment name or HuggingFace Hub repo ID
+                  Examples:
+                  - "coding" / "coding-env" / "coding_env"
+                  - "meta-pytorch/coding-env" (Hub repo ID)
+                  - "https://huggingface.co/meta-pytorch/coding-env" (Hub URL)
+            base_url: Optional base URL for HTTP connection
+            docker_image: Optional Docker image name (overrides default)
+            container_provider: Optional container provider
+            wait_timeout: Timeout for container startup (seconds)
+            env_vars: Optional environment variables for the container
+            trust_remote_code: If True, skip user confirmation when installing
+                from HuggingFace Hub. Can also be set via OPENENV_TRUST_REMOTE_CODE
+                environment variable.
+            skip_install: If True, skip package installation and return a
+                GenericEnvClient for remote environments. Useful when you only
+                want to connect to a running server without installing any
+                remote code. When True:
+                - If base_url is provided: connects directly using GenericEnvClient
+                - If HF Space is running: connects to Space using GenericEnvClient
+                - If HF Space is not running: uses Docker from HF registry
+            **kwargs: Additional arguments passed to the client class
+
+        Returns:
+            Instance of the environment client class
+
+        Raises:
+            ValueError: If environment not found or cannot be loaded
+            ImportError: If environment package is not installed
+
+        Examples:
+            >>> # From installed package
+            >>> env = AutoEnv.from_env("coding-env")
+            >>>
+            >>> # From HuggingFace Hub
+            >>> env = AutoEnv.from_env("meta-pytorch/coding-env")
+            >>>
+            >>> # With custom Docker image
+            >>> env = AutoEnv.from_env("coding", docker_image="my-coding-env:v2")
+            >>>
+            >>> # With environment variables
+            >>> env = AutoEnv.from_env(
+            ...     "dipg",
+            ...     env_vars={"DIPG_DATASET_PATH": "/data/dipg"}
+            ... )
+            >>>
+            >>> # Skip package installation, use GenericEnvClient
+            >>> env = AutoEnv.from_env(
+            ...     "user/my-env",
+            ...     skip_install=True
+            ... )
+        """
+        from openenv.core import GenericEnvClient
+
+        # Handle skip_install mode - return GenericEnvClient without package installation
+        if skip_install:
+            # If base_url is provided, connect directly
+            if base_url:
+                if cls._check_server_availability(base_url):
+                    logger.info(
+                        f"Using GenericEnvClient for {base_url} (skip_install=True)"
+                    )
+                    return GenericEnvClient(base_url=base_url, **kwargs)
+                else:
+                    raise ConnectionError(
+                        f"Server not available at {base_url}. "
+                        f"Please ensure the server is running."
+                    )
+
+            # If it's a Hub URL, try to connect to Space or use Docker
+            if _is_hub_url(name):
+                space_url = cls._resolve_space_url(name)
+                logger.info(f"Checking if HuggingFace Space is accessible: {space_url}")
+
+                if cls._check_space_availability(space_url):
+                    logger.info(
+                        f"Using GenericEnvClient for Space {space_url} (skip_install=True)"
+                    )
+                    return GenericEnvClient(base_url=space_url, **kwargs)
+                else:
+                    # Space not running, use Docker from HF registry
+                    logger.info(
+                        f"Space not running at {space_url}, "
+                        f"using GenericEnvClient with HF Docker registry"
+                    )
+                    return run_async_safely(
+                        GenericEnvClient.from_env(
+                            name,
+                            use_docker=True,
+                            provider=container_provider,
+                            env_vars=env_vars or {},
+                            **kwargs,
+                        )
+                    )
+
+            # For local environments with skip_install, we need docker_image
+            if docker_image:
+                logger.info(
+                    f"Using GenericEnvClient with Docker image {docker_image} "
+                    f"(skip_install=True)"
+                )
+                return run_async_safely(
+                    GenericEnvClient.from_docker_image(
+                        image=docker_image,
+                        provider=container_provider,
+                        wait_timeout=wait_timeout,
+                        env_vars=env_vars or {},
+                        **kwargs,
+                    )
+                )
+            else:
+                raise ValueError(
+                    f"Cannot use skip_install=True for local environment '{name}' "
+                    f"without providing base_url or docker_image. "
+                    f"For local environments, either:\n"
+                    f"  1. Provide base_url to connect to a running server\n"
+                    f"  2. Provide docker_image to start a container\n"
+                    f"  3. Set skip_install=False to use the installed package"
+                )
+
+        # Check if it's a HuggingFace Hub URL or repo ID
+        if _is_hub_url(name):
+            # Try to connect to Space directly first
+            space_url = cls._resolve_space_url(name)
+            logger.info(f"Checking if HuggingFace Space is accessible: {space_url}")
+
+            space_is_available = cls._check_space_availability(space_url)
+
+            if space_is_available and base_url is None:
+                # Space is accessible! We'll connect directly without Docker
+                logger.info(f"Space is accessible at: {space_url}")
+                logger.info("Installing package for client code (no Docker needed)...")
+
+                # Ensure package is installed (uses git+ URL)
+                env_name = cls._ensure_package_from_hub(
+                    name, trust_remote_code=trust_remote_code
+                )
+
+                # Set base_url to connect to remote Space
+                base_url = space_url
+                logger.info("Will connect to remote Space (no local Docker)")
+            else:
+                # Space not accessible or user provided explicit base_url
+                if not space_is_available:
+                    logger.info(f"Space not accessible at {space_url}")
+                    logger.info("Falling back to local Docker mode...")
+
+                # Ensure package is installed (uses git+ URL)
+                env_name = cls._ensure_package_from_hub(
+                    name, trust_remote_code=trust_remote_code
+                )
+        else:
+            env_name = name
+
+        # Get environment info from discovery
+        discovery = get_discovery()
+        env_info = discovery.get_environment_by_name(env_name)
+
+        if not env_info:
+            # Environment not found - provide helpful error message
+            available_envs = discovery.discover()
+
+            if not available_envs:
+                raise ValueError(
+                    "No OpenEnv environments found.\n"
+                    "Install an environment with: pip install openenv-<env-name>\n"
+                    "Or specify a HuggingFace Hub repository: AutoEnv.from_env('openenv/echo_env')"
+                )
+
+            # Try to suggest similar environment names
+            from difflib import get_close_matches
+
+            env_keys = list(available_envs.keys())
+            suggestions = get_close_matches(env_name, env_keys, n=3, cutoff=0.6)
+
+            error_msg = f"Unknown environment '{env_name}'.\n"
+            if suggestions:
+                error_msg += f"Did you mean: {', '.join(suggestions)}?\n"
+            error_msg += f"Available environments: {', '.join(sorted(env_keys))}"
+
+            raise ValueError(error_msg)
+
+        # Get the client class
+        try:
+            client_class = env_info.get_client_class()
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import environment client for '{env_name}'.\n"
+                f"Package '{env_info.package_name}' appears to be installed but the module cannot be imported.\n"
+                f"Try reinstalling: pip install --force-reinstall {env_info.package_name}\n"
+                f"Original error: {e}"
+            ) from e
+
+        # Determine Docker image to use
+        if docker_image is None:
+            docker_image = env_info.default_image
+
+        # Create client instance
+        try:
+            if base_url:
+                # Check if the server at base_url is available
+                is_local = cls._is_local_url(base_url)
+                server_available = cls._check_server_availability(base_url)
+
+                if server_available:
+                    # Server is running, connect directly
+                    logger.info(
+                        f"✅ Server available at {base_url}, connecting directly"
+                    )
+                    return client_class(base_url=base_url, provider=None, **kwargs)
+                elif is_local:
+                    # Local server not running, auto-start Docker container
+                    logger.info(f"❌ Server not available at {base_url}")
+                    logger.info(f"🐳 Auto-starting Docker container: {docker_image}")
+                    return run_async_safely(
+                        client_class.from_docker_image(
+                            image=docker_image,
+                            provider=container_provider,
+                            wait_timeout=wait_timeout,
+                            env_vars=env_vars or {},
+                            **kwargs,
+                        )
+                    )
+                else:
+                    # Remote server not available, cannot auto-start
+                    raise ConnectionError(
+                        f"Remote server not available at {base_url}. "
+                        f"Please ensure the server is running."
+                    )
+            else:
+                # No base_url provided, start new Docker container
+                return run_async_safely(
+                    client_class.from_docker_image(
+                        image=docker_image,
+                        provider=container_provider,
+                        wait_timeout=wait_timeout,
+                        env_vars=env_vars or {},
+                        **kwargs,
+                    )
+                )
+        except Exception as e:
+            raise ValueError(
+                f"Failed to create environment client for '{env_name}'.\n"
+                f"Client class: {client_class.__name__}\n"
+                f"Docker image: {docker_image}\n"
+                f"Error: {e}"
+            ) from e
+
+    @classmethod
+    def from_hub(
+        cls,
+        name: str,
+        base_url: Optional[str] = None,
+        docker_image: Optional[str] = None,
+        container_provider: Optional["ContainerProvider"] = None,
+        wait_timeout: float = 30.0,
+        env_vars: Optional[Dict[str, str]] = None,
+        trust_remote_code: bool = False,
+        skip_install: bool = False,
+        **kwargs: Any,
+    ) -> "EnvClient":
+        """
+        Create an environment client from a name or HuggingFace Hub repository.
+
+        This is an alias for from_env() for backward compatibility.
+
+        Args:
+            name: Environment name or HuggingFace Hub repo ID
+            base_url: Optional base URL for HTTP connection
+            docker_image: Optional Docker image name (overrides default)
+            container_provider: Optional container provider
+            wait_timeout: Timeout for container startup (seconds)
+            env_vars: Optional environment variables for the container
+            trust_remote_code: If True, skip user confirmation when installing
+                from HuggingFace Hub
+            skip_install: If True, skip package installation and return a
+                GenericEnvClient for remote environments
+            **kwargs: Additional arguments passed to the client class
+
+        Returns:
+            Instance of the environment client class
+
+        Examples:
+            >>> env = AutoEnv.from_hub("coding-env")
+            >>> env = AutoEnv.from_hub("meta-pytorch/coding-env")
+        """
+        return cls.from_env(
+            name=name,
+            base_url=base_url,
+            docker_image=docker_image,
+            container_provider=container_provider,
+            wait_timeout=wait_timeout,
+            env_vars=env_vars,
+            trust_remote_code=trust_remote_code,
+            skip_install=skip_install,
+            **kwargs,
+        )
+
+    @classmethod
+    def get_env_class(cls, name: str):
+        """
+        Get the environment client class without instantiating it.
+
+        Args:
+            name: Environment name
+
+        Returns:
+            The environment client class
+
+        Raises:
+            ValueError: If environment not found
+
+        Examples:
+            >>> CodingEnv = AutoEnv.get_env_class("coding")
+            >>> # Now you can instantiate it yourself
+            >>> env = CodingEnv(base_url="http://localhost:8000")
+        """
+        discovery = get_discovery()
+        env_info = discovery.get_environment_by_name(name)
+
+        if not env_info:
+            raise ValueError(f"Unknown environment: {name}")
+
+        return env_info.get_client_class()
+
+    @classmethod
+    def get_env_info(cls, name: str) -> Dict[str, Any]:
+        """
+        Get detailed information about an environment.
+
+        Args:
+            name: Environment name
+
+        Returns:
+            Dictionary with environment metadata
+
+        Raises:
+            ValueError: If environment not found
+
+        Examples:
+            >>> info = AutoEnv.get_env_info("coding")
+            >>> print(info['description'])
+            'Coding environment for OpenEnv'
+            >>> print(info['default_image'])
+            'coding-env:latest'
+        """
+        discovery = get_discovery()
+        env_info = discovery.get_environment_by_name(name)
+
+        if not env_info:
+            raise ValueError(f"Unknown environment: {name}")
+
+        return {
+            "env_key": env_info.env_key,
+            "name": env_info.name,
+            "package": env_info.package_name,
+            "version": env_info.version,
+            "description": env_info.description,
+            "env_class": env_info.client_class_name,
+            "action_class": env_info.action_class_name,
+            "observation_class": env_info.observation_class_name,
+            "module": env_info.client_module_path,
+            "default_image": env_info.default_image,
+            "spec_version": env_info.spec_version,
+        }
+
+    @classmethod
+    def list_environments(cls) -> None:
+        """
+        Print a formatted list of all available environments.
+
+        This discovers all installed openenv-* packages and displays
+        their metadata in a user-friendly format.
+
+        Examples:
+            >>> AutoEnv.list_environments()
+            Available OpenEnv Environments:
+            ----------------------------------------------------------------------
+              echo           : Echo Environment (v0.1.0)
+                               Package: openenv-echo-env
+              coding         : Coding Environment (v0.1.0)
+                               Package: openenv-coding_env
+            ----------------------------------------------------------------------
+            Total: 2 environments
+        """
+        discovery = get_discovery()
+        discovery.list_environments()

src/openenv/cli/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""OpenEnv CLI package."""
+
+__version__ = "0.1.0"

src/openenv/cli/__main__.py

@@ -0,0 +1,62 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+OpenEnv CLI entry point.
+
+This module provides the main entry point for the OpenEnv command-line interface,
+following the Hugging Face CLI pattern.
+"""
+
+import sys
+
+import typer
+
+from openenv.cli.commands import build, fork, init, push, serve, validate
+
+# Create the main CLI app
+app = typer.Typer(
+    name="openenv",
+    help="OpenEnv - An e2e framework for creating, deploying and using isolated execution environments for agentic RL training",
+    no_args_is_help=True,
+)
+
+# Register commands
+app.command(name="init", help="Initialize a new OpenEnv environment")(init.init)
+app.command(name="build", help="Build Docker images for OpenEnv environments")(
+    build.build
+)
+app.command(
+    name="validate", help="Validate environment structure and deployment readiness"
+)(validate.validate)
+app.command(
+    name="push",
+    help="Push an OpenEnv environment to Hugging Face Spaces or custom registry",
+)(push.push)
+app.command(name="serve", help="Serve environments locally (TODO: Phase 4)")(
+    serve.serve
+)
+app.command(
+    name="fork",
+    help="Fork (duplicate) a Hugging Face Space to your account",
+)(fork.fork)
+
+
+# Entry point for setuptools
+def main() -> None:
+    """Main entry point for the CLI."""
+    try:
+        app()
+    except KeyboardInterrupt:
+        print("\nOperation cancelled by user.")
+        sys.exit(130)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()