Upload folder using huggingface_hub

Dockerfile

@@ -1,20 +1,39 @@
-# Copyright (c) Meta Platforms, Inc. and affiliates.
-# All rights reserved.
+# Dockerfile for Atari Environment
+# This image provides Atari 2600 games via the Arcade Learning Environment (ALE)
+
+# Configurable base image - defaults to local build, can be overridden for CI/CD
+# Base image provides: fastapi, uvicorn, requests, curl, PYTHONPATH=/app/src
+#
+# Local build: docker build -t envtorch-base:latest -f src/core/containers/images/Dockerfile .
+#              docker build -f envs/atari_env/server/Dockerfile -t atari-env:latest .
 #
-# This source code is licensed under the BSD-style license found in the
-# LICENSE file in the root directory of this source tree.
-
-# Use the specified openenv-base image
-FROM ghcr.io/meta-pytorch/openenv-base:sha-7dd8148
-# Install ALE-specific dependencies
-RUN pip install --no-cache-dir \
-    gymnasium>=0.29.0 \
-    ale-py>=0.8.0 \
-    numpy>=1.24.0
-
-# Copy only what's needed for this environment
+# CI/CD build: docker build --build-arg BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest \
+#              -f envs/atari_env/server/Dockerfile -t atari-env:latest .
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ghcr.io/meta-pytorch/openenv-base:latest
+
+# Install dependencies
+COPY envs/atari_env/server/requirements.txt /tmp/requirements.txt
+RUN pip install --no-cache-dir -r /tmp/requirements.txt && rm /tmp/requirements.txt
+
+# Copy OpenEnv core (base image already set WORKDIR=/app)
 COPY src/core/ /app/src/core/
-COPY src/envs/atari_env/ /app/src/envs/atari_env/
+
+# Copy Atari environment code
+COPY envs/atari_env/ /app/envs/atari_env/
+
+# Copy README for web interface documentation
+COPY envs/atari_env/README.md /app/README.md
+
+# Atari-specific environment variables (can be overridden at runtime)
+ENV ATARI_GAME=pong
+ENV ATARI_OBS_TYPE=rgb
+ENV ATARI_FULL_ACTION_SPACE=false
+ENV ATARI_REPEAT_ACTION_PROB=0.0
+ENV ATARI_FRAMESKIP=4
+
+# Expose port
+EXPOSE 8000
 
 # Health check
 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
@@ -22,4 +41,6 @@ HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
 
 # Run the FastAPI server
 CMD ["uvicorn", "envs.atari_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]
+ENV PYTHONPATH=/app/src/core:/app/src:${PYTHONPATH}
+
 ENV ENABLE_WEB_INTERFACE=true

README.md

@@ -1,51 +1,425 @@
 ---
-title: atari_env
+title: Atari Environment Server
 emoji: 🕹️
-colorFrom: red
-colorTo: yellow
+colorFrom: blue
+colorTo: green
 sdk: docker
 pinned: false
 app_port: 8000
 base_path: /web
 tags:
+  - openenv-main
   - openenv
 ---
 
-# Atari_env Environment Server
+## Hugging Face Space Deployment
 
-FastAPI server for atari_env environment powered by Meta's OpenEnv.
+This Space is built from OpenEnv environment `atari_env`.
 
-## About
+- Space URL: `https://huggingface.co/spaces/openenv/atari_env`
+- OpenEnv pinned ref: `main`
+- Hub tag: `openenv`
 
-This Space provides a containerized environment for atari_env interactions.
-Built with FastAPI and OpenEnv framework.
+### Connecting from Code
 
-## Web Interface
+```python
+from envs.atari_env import AtariEnv
 
-This deployment includes an interactive web interface for exploring the environment:
-- **HumanAgent Interface**: Interact with the environment using a web form
-- **State Observer**: Real-time view of environment state and action history
-- **Live Updates**: WebSocket-based real-time updates
+env = AtariEnv(base_url="https://huggingface.co/spaces/openenv/atari_env")
+```
 
-Access the web interface at: `/web`
+# Atari Environment
 
-## Atari Environment
+Integration of Atari 2600 games with the OpenEnv framework via the Arcade Learning Environment (ALE). ALE provides access to 100+ classic Atari games for RL research.
 
-Provides Atari 2600 games via the Arcade Learning Environment (ALE).
+## Supported Games
 
-### Usage
-Send a POST request to `/step` with:
-```json
-{
-  "action_id": 0,
-  "game_name": "pong"
-}
+ALE supports 100+ Atari 2600 games including:
+
+### Popular Games
+- **Pong** - Classic two-player tennis
+- **Breakout** - Break bricks with a ball
+- **Space Invaders** - Shoot descending aliens
+- **Pac-Man / Ms. Pac-Man** - Navigate mazes and eat pellets
+- **Asteroids** - Destroy asteroids in space
+- **Defender** - Side-scrolling space shooter
+- **Centipede** - Shoot segmented centipede
+- **Donkey Kong** - Jump over barrels to save princess
+- **Frogger** - Cross road and river safely
+- **Q*bert** - Jump on pyramid cubes
+
+And many more! For a complete list, see [ALE documentation](https://ale.farama.org/environments/complete_list/).
+
+## Architecture
+
+```
+┌────────────────────────────────────┐
+│ RL Training Code (Client)          │
+│   AtariEnv.step(action)            │
+└──────────────┬─────────────────────┘
+               │ HTTP
+┌──────────────▼─────────────────────┐
+│ FastAPI Server (Docker)            │
+│   AtariEnvironment                 │
+│     ├─ Wraps ALEInterface          │
+│     ├─ Handles observations        │
+│     └─ Action execution            │
+└────────────────────────────────────┘
+```
+
+## Installation & Usage
+
+### Option 1: Local Development (without Docker)
+
+**Requirements:**
+- Python 3.11+
+- ale-py installed: `pip install ale-py`
+
+The client is **async by default**:
+
+```python
+import asyncio
+from atari_env import AtariEnv, AtariAction
+
+async def main():
+    # Start local server manually: python -m atari_env.server.app
+    async with AtariEnv(base_url="http://localhost:8000") as env:
+        # Reset environment
+        result = await env.reset()
+        print(f"Screen shape: {result.observation.screen_shape}")
+        print(f"Legal actions: {result.observation.legal_actions}")
+
+        # Take actions
+        for _ in range(10):
+            result = await env.step(AtariAction(action_id=2, game_name="pong"))
+            print(f"Reward: {result.reward}, Done: {result.done}")
+            if result.done:
+                break
+
+asyncio.run(main())
+```
+
+For **synchronous usage**, use the `.sync()` wrapper:
+
+```python
+from atari_env import AtariEnv, AtariAction
+
+with AtariEnv(base_url="http://localhost:8000").sync() as env:
+    result = env.reset()
+    result = env.step(AtariAction(action_id=2, game_name="pong"))
+    print(f"Reward: {result.reward}")
 ```
 
-## API Documentation
+### Option 2: Docker (Recommended)
+
+**Build Atari image:**
+
+```bash
+cd OpenEnv
+
+# Build the image
+docker build \
+  -f envs/atari_env/server/Dockerfile \
+  -t atari-env:latest \
+  .
+```
+
+**Run specific games:**
+
+```bash
+# Pong (default)
+docker run -p 8000:8000 atari-env:latest
 
-Visit `/docs` for interactive API documentation.
+# Breakout
+docker run -p 8000:8000 -e ATARI_GAME=breakout atari-env:latest
 
-## Health Check
+# Space Invaders with grayscale observation
+docker run -p 8000:8000 \
+  -e ATARI_GAME=space_invaders \
+  -e ATARI_OBS_TYPE=grayscale \
+  atari-env:latest
 
-The environment provides a health check endpoint at `/health`.
+# Ms. Pac-Man with full action space
+docker run -p 8000:8000 \
+  -e ATARI_GAME=ms_pacman \
+  -e ATARI_FULL_ACTION_SPACE=true \
+  atari-env:latest
+```
+
+**Use with from_docker_image():**
+
+```python
+import asyncio
+import numpy as np
+from atari_env import AtariEnv, AtariAction
+
+async def main():
+    # Automatically starts container
+    client = await AtariEnv.from_docker_image("atari-env:latest")
+
+    async with client:
+        result = await client.reset()
+        result = await client.step(AtariAction(action_id=2))  # UP
+
+        # Reshape screen for visualization
+        screen = np.array(result.observation.screen).reshape(result.observation.screen_shape)
+        print(f"Screen shape: {screen.shape}")  # (210, 160, 3) for RGB
+
+asyncio.run(main())
+```
+
+## Observation Types
+
+### 1. RGB (Default)
+- **Shape**: [210, 160, 3]
+- **Description**: Full-color screen observation
+- **Usage**: Most realistic, good for vision-based learning
+
+```python
+docker run -p 8000:8000 -e ATARI_OBS_TYPE=rgb atari-env:latest
+```
+
+### 2. Grayscale
+- **Shape**: [210, 160]
+- **Description**: Grayscale screen observation
+- **Usage**: Reduced dimensionality, faster processing
+
+```python
+docker run -p 8000:8000 -e ATARI_OBS_TYPE=grayscale atari-env:latest
+```
+
+### 3. RAM
+- **Shape**: [128]
+- **Description**: Raw 128-byte Atari 2600 RAM contents
+- **Usage**: Compact representation, useful for specific research
+
+```python
+docker run -p 8000:8000 -e ATARI_OBS_TYPE=ram atari-env:latest
+```
+
+## Action Spaces
+
+### Minimal Action Set (Default)
+Game-specific minimal actions (typically 4-9 actions).
+- Pong: 6 actions (NOOP, FIRE, UP, DOWN, etc.)
+- Breakout: 4 actions (NOOP, FIRE, LEFT, RIGHT)
+
+```python
+docker run -p 8000:8000 -e ATARI_FULL_ACTION_SPACE=false atari-env:latest
+```
+
+### Full Action Set
+All 18 possible Atari 2600 actions:
+0. NOOP
+1. FIRE
+2. UP
+3. RIGHT
+4. LEFT
+5. DOWN
+6. UPRIGHT
+7. UPLEFT
+8. DOWNRIGHT
+9. DOWNLEFT
+10. UPFIRE
+11. RIGHTFIRE
+12. LEFTFIRE
+13. DOWNFIRE
+14. UPRIGHTFIRE
+15. UPLEFTFIRE
+16. DOWNRIGHTFIRE
+17. DOWNLEFTFIRE
+
+```python
+docker run -p 8000:8000 -e ATARI_FULL_ACTION_SPACE=true atari-env:latest
+```
+
+## Configuration
+
+### Environment Variables
+
+- `ATARI_GAME`: Game name (default: "pong")
+- `ATARI_OBS_TYPE`: Observation type - "rgb", "grayscale", "ram" (default: "rgb")
+- `ATARI_FULL_ACTION_SPACE`: Use full action space - "true"/"false" (default: "false")
+- `ATARI_MODE`: Game mode (optional, game-specific)
+- `ATARI_DIFFICULTY`: Game difficulty (optional, game-specific)
+- `ATARI_REPEAT_ACTION_PROB`: Sticky action probability 0.0-1.0 (default: "0.0")
+- `ATARI_FRAMESKIP`: Frames to skip per action (default: "4")
+
+### Example: Breakout with Custom Settings
+
+```bash
+docker run -p 8000:8000 \
+  -e ATARI_GAME=breakout \
+  -e ATARI_OBS_TYPE=grayscale \
+  -e ATARI_FULL_ACTION_SPACE=true \
+  -e ATARI_REPEAT_ACTION_PROB=0.25 \
+  -e ATARI_FRAMESKIP=4 \
+  atari-env:latest
+```
+
+## API Reference
+
+### AtariAction
+
+```python
+@dataclass
+class AtariAction(Action):
+    action_id: int                  # Action index to execute
+    game_name: str = "pong"         # Game name
+    obs_type: str = "rgb"           # Observation type
+    full_action_space: bool = False # Full or minimal action space
+```
+
+### AtariObservation
+
+```python
+@dataclass
+class AtariObservation(Observation):
+    screen: List[int]               # Flattened screen pixels
+    screen_shape: List[int]         # Original screen shape
+    legal_actions: List[int]        # Legal action indices
+    lives: int                      # Lives remaining
+    episode_frame_number: int       # Frame # in episode
+    frame_number: int               # Total frame #
+    done: bool                      # Episode finished
+    reward: Optional[float]         # Reward from last action
+```
+
+### AtariState
+
+```python
+@dataclass
+class AtariState(State):
+    episode_id: str                      # Unique episode ID
+    step_count: int                      # Number of steps
+    game_name: str                       # Game name
+    obs_type: str                        # Observation type
+    full_action_space: bool              # Action space type
+    mode: Optional[int]                  # Game mode
+    difficulty: Optional[int]            # Game difficulty
+    repeat_action_probability: float     # Sticky action prob
+    frameskip: int                       # Frameskip setting
+```
+
+## Example Script
+
+```python
+#!/usr/bin/env python3
+"""Example training loop with Atari environment."""
+
+import asyncio
+import numpy as np
+from atari_env import AtariEnv, AtariAction
+
+async def train():
+    # Start environment
+    client = await AtariEnv.from_docker_image("atari-env:latest")
+
+    async with client:
+        # Training loop
+        for episode in range(10):
+            result = await client.reset()
+            episode_reward = 0
+            steps = 0
+
+            while not result.done:
+                # Random policy (replace with your RL agent)
+                action_id = np.random.choice(result.observation.legal_actions)
+
+                # Take action
+                result = await client.step(AtariAction(action_id=action_id))
+
+                episode_reward += result.reward or 0
+                steps += 1
+
+                # Reshape screen for processing
+                screen = np.array(result.observation.screen).reshape(
+                    result.observation.screen_shape
+                )
+
+                # Your RL training code here
+                # ...
+
+            print(f"Episode {episode}: reward={episode_reward:.2f}, steps={steps}")
+
+asyncio.run(train())
+```
+
+## Testing
+
+### Local Testing
+
+```bash
+# Install dependencies
+pip install ale-py fastapi uvicorn requests
+
+# Start server
+export PYTHONPATH=src:envs
+python -m atari_env.server.app
+
+# Test from another terminal (using sync wrapper for simplicity)
+python -c "
+from atari_env import AtariEnv, AtariAction
+with AtariEnv(base_url='http://localhost:8000').sync() as env:
+    result = env.reset()
+    print(f'Initial obs: {result.observation.screen_shape}')
+    result = env.step(AtariAction(action_id=2))
+    print(f'After step: reward={result.reward}, done={result.done}')
+"
+```
+
+### Docker Testing
+
+```bash
+# Build and run
+docker build -f envs/atari_env/server/Dockerfile -t atari-env:latest .
+docker run -p 8000:8000 atari-env:latest
+
+# Test in another terminal
+curl http://localhost:8000/health
+curl -X POST http://localhost:8000/reset
+```
+
+## Popular Games and Their Characteristics
+
+| Game | Minimal Actions | Lives | Difficulty | Notes |
+|------|----------------|-------|-----------|-------|
+| Pong | 6 | 1 | Low | Good for learning basics |
+| Breakout | 4 | 5 | Medium | Classic RL benchmark |
+| Space Invaders | 6 | 3 | Medium | Shooting game |
+| Ms. Pac-Man | 9 | 3 | High | Complex navigation |
+| Asteroids | 14 | 3 | Medium | Continuous shooting |
+| Montezuma's Revenge | 18 | 5 | Very High | Exploration challenge |
+| Pitfall | 18 | 1 | High | Platformer |
+| Seaquest | 18 | 3 | High | Submarine rescue |
+
+## Limitations & Notes
+
+- **Frame perfect timing**: Some games require precise timing
+- **Exploration**: Games like Montezuma's Revenge are notoriously difficult
+- **Observation delay**: HTTP adds minimal latency vs local gym
+- **Determinism**: Set `ATARI_REPEAT_ACTION_PROB=0.0` for deterministic behavior
+- **ROMs**: All ROMs are bundled with ale-py package
+
+## References
+
+- [Arcade Learning Environment Paper (2013)](https://jair.org/index.php/jair/article/view/10819)
+- [ALE GitHub](https://github.com/Farama-Foundation/Arcade-Learning-Environment)
+- [ALE Documentation](https://ale.farama.org/)
+- [Gymnasium Atari Environments](https://gymnasium.farama.org/environments/atari/)
+
+## Citation
+
+If you use ALE in your research, please cite:
+
+```bibtex
+@Article{bellemare13arcade,
+    author = {{Bellemare}, M.~G. and {Naddaf}, Y. and {Veness}, J. and {Bowling}, M.},
+    title = {The Arcade Learning Environment: An Evaluation Platform for General Agents},
+    journal = {Journal of Artificial Intelligence Research},
+    year = "2013",
+    month = "jun",
+    volume = "47",
+    pages = "253--279",
+}
+```

__init__.py

@@ -0,0 +1,31 @@
+# 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.
+
+"""
+Atari Environment for OpenEnv.
+
+This module provides OpenEnv integration for Atari 2600 games via the
+Arcade Learning Environment (ALE).
+
+Example:
+    >>> from envs.atari_env import AtariEnv, AtariAction
+    >>>
+    >>> # Connect to a running server or start via Docker
+    >>> env = AtariEnv.from_docker_image("atari-env:latest")
+    >>>
+    >>> # Reset and interact
+    >>> result = env.reset()
+    >>> result = env.step(AtariAction(action_id=2))  # UP
+    >>> print(result.reward, result.done)
+    >>>
+    >>> # Cleanup
+    >>> env.close()
+"""
+
+from .client import AtariEnv
+from .models import AtariAction, AtariObservation, AtariState
+
+__all__ = ["AtariEnv", "AtariAction", "AtariObservation", "AtariState"]

client.py

@@ -0,0 +1,120 @@
+# 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.
+
+"""
+Atari Environment Client.
+
+This module provides the client for connecting to an Atari Environment server
+via WebSocket for persistent sessions.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, TYPE_CHECKING
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_client import EnvClient
+
+from .models import AtariAction, AtariObservation, AtariState
+
+if TYPE_CHECKING:
+    from openenv.core.containers.runtime import ContainerProvider
+
+
+class AtariEnv(EnvClient[AtariAction, AtariObservation, AtariState]):
+    """
+    Client for Atari Environment.
+
+    This client maintains a persistent WebSocket connection to the environment
+    server, enabling efficient multi-step interactions with lower latency.
+
+    Example:
+        >>> # Connect to a running server
+        >>> with AtariEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.screen_shape)
+        ...
+        ...     result = client.step(AtariAction(action_id=2))  # UP
+        ...     print(result.reward, result.done)
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = AtariEnv.from_docker_image("atari-env:latest")
+        >>> try:
+        ...     result = client.reset()
+        ...     result = client.step(AtariAction(action_id=0))  # NOOP
+        ... finally:
+        ...     client.close()
+    """
+
+    def _step_payload(self, action: AtariAction) -> Dict[str, Any]:
+        """
+        Convert AtariAction to JSON payload for step request.
+
+        Args:
+            action: AtariAction instance.
+
+        Returns:
+            Dictionary representation suitable for JSON encoding.
+        """
+        return {
+            "action_id": action.action_id,
+            "game_name": action.game_name,
+            "obs_type": action.obs_type,
+            "full_action_space": action.full_action_space,
+        }
+
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[AtariObservation]:
+        """
+        Parse server response into StepResult[AtariObservation].
+
+        Args:
+            payload: JSON response from server.
+
+        Returns:
+            StepResult with AtariObservation.
+        """
+        obs_data = payload.get("observation", {})
+
+        observation = AtariObservation(
+            screen=obs_data.get("screen", []),
+            screen_shape=obs_data.get("screen_shape", []),
+            legal_actions=obs_data.get("legal_actions", []),
+            lives=obs_data.get("lives", 0),
+            episode_frame_number=obs_data.get("episode_frame_number", 0),
+            frame_number=obs_data.get("frame_number", 0),
+            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[str, Any]) -> AtariState:
+        """
+        Parse server response into AtariState object.
+
+        Args:
+            payload: JSON response from /state endpoint.
+
+        Returns:
+            AtariState object with environment state information.
+        """
+        return AtariState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            game_name=payload.get("game_name", "unknown"),
+            obs_type=payload.get("obs_type", "rgb"),
+            full_action_space=payload.get("full_action_space", False),
+            mode=payload.get("mode"),
+            difficulty=payload.get("difficulty"),
+            repeat_action_probability=payload.get("repeat_action_probability", 0.0),
+            frameskip=payload.get("frameskip", 4),
+        )

envs/atari_env/README.md

@@ -0,0 +1,408 @@
+---
+title: Atari Environment Server
+emoji: 🕹️
+colorFrom: '#FF6200'
+colorTo: '#D4151B'
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# Atari Environment
+
+Integration of Atari 2600 games with the OpenEnv framework via the Arcade Learning Environment (ALE). ALE provides access to 100+ classic Atari games for RL research.
+
+## Supported Games
+
+ALE supports 100+ Atari 2600 games including:
+
+### Popular Games
+- **Pong** - Classic two-player tennis
+- **Breakout** - Break bricks with a ball
+- **Space Invaders** - Shoot descending aliens
+- **Pac-Man / Ms. Pac-Man** - Navigate mazes and eat pellets
+- **Asteroids** - Destroy asteroids in space
+- **Defender** - Side-scrolling space shooter
+- **Centipede** - Shoot segmented centipede
+- **Donkey Kong** - Jump over barrels to save princess
+- **Frogger** - Cross road and river safely
+- **Q*bert** - Jump on pyramid cubes
+
+And many more! For a complete list, see [ALE documentation](https://ale.farama.org/environments/complete_list/).
+
+## Architecture
+
+```
+┌────────────────────────────────────┐
+│ RL Training Code (Client)          │
+│   AtariEnv.step(action)            │
+└──────────────┬─────────────────────┘
+               │ HTTP
+┌──────────────▼─────────────────────┐
+│ FastAPI Server (Docker)            │
+│   AtariEnvironment                 │
+│     ├─ Wraps ALEInterface          │
+│     ├─ Handles observations        │
+│     └─ Action execution            │
+└────────────────────────────────────┘
+```
+
+## Installation & Usage
+
+### Option 1: Local Development (without Docker)
+
+**Requirements:**
+- Python 3.11+
+- ale-py installed: `pip install ale-py`
+
+The client is **async by default**:
+
+```python
+import asyncio
+from atari_env import AtariEnv, AtariAction
+
+async def main():
+    # Start local server manually: python -m atari_env.server.app
+    async with AtariEnv(base_url="http://localhost:8000") as env:
+        # Reset environment
+        result = await env.reset()
+        print(f"Screen shape: {result.observation.screen_shape}")
+        print(f"Legal actions: {result.observation.legal_actions}")
+
+        # Take actions
+        for _ in range(10):
+            result = await env.step(AtariAction(action_id=2, game_name="pong"))
+            print(f"Reward: {result.reward}, Done: {result.done}")
+            if result.done:
+                break
+
+asyncio.run(main())
+```
+
+For **synchronous usage**, use the `.sync()` wrapper:
+
+```python
+from atari_env import AtariEnv, AtariAction
+
+with AtariEnv(base_url="http://localhost:8000").sync() as env:
+    result = env.reset()
+    result = env.step(AtariAction(action_id=2, game_name="pong"))
+    print(f"Reward: {result.reward}")
+```
+
+### Option 2: Docker (Recommended)
+
+**Build Atari image:**
+
+```bash
+cd OpenEnv
+
+# Build the image
+docker build \
+  -f envs/atari_env/server/Dockerfile \
+  -t atari-env:latest \
+  .
+```
+
+**Run specific games:**
+
+```bash
+# Pong (default)
+docker run -p 8000:8000 atari-env:latest
+
+# Breakout
+docker run -p 8000:8000 -e ATARI_GAME=breakout atari-env:latest
+
+# Space Invaders with grayscale observation
+docker run -p 8000:8000 \
+  -e ATARI_GAME=space_invaders \
+  -e ATARI_OBS_TYPE=grayscale \
+  atari-env:latest
+
+# Ms. Pac-Man with full action space
+docker run -p 8000:8000 \
+  -e ATARI_GAME=ms_pacman \
+  -e ATARI_FULL_ACTION_SPACE=true \
+  atari-env:latest
+```
+
+**Use with from_docker_image():**
+
+```python
+import asyncio
+import numpy as np
+from atari_env import AtariEnv, AtariAction
+
+async def main():
+    # Automatically starts container
+    client = await AtariEnv.from_docker_image("atari-env:latest")
+
+    async with client:
+        result = await client.reset()
+        result = await client.step(AtariAction(action_id=2))  # UP
+
+        # Reshape screen for visualization
+        screen = np.array(result.observation.screen).reshape(result.observation.screen_shape)
+        print(f"Screen shape: {screen.shape}")  # (210, 160, 3) for RGB
+
+asyncio.run(main())
+```
+
+## Observation Types
+
+### 1. RGB (Default)
+- **Shape**: [210, 160, 3]
+- **Description**: Full-color screen observation
+- **Usage**: Most realistic, good for vision-based learning
+
+```python
+docker run -p 8000:8000 -e ATARI_OBS_TYPE=rgb atari-env:latest
+```
+
+### 2. Grayscale
+- **Shape**: [210, 160]
+- **Description**: Grayscale screen observation
+- **Usage**: Reduced dimensionality, faster processing
+
+```python
+docker run -p 8000:8000 -e ATARI_OBS_TYPE=grayscale atari-env:latest
+```
+
+### 3. RAM
+- **Shape**: [128]
+- **Description**: Raw 128-byte Atari 2600 RAM contents
+- **Usage**: Compact representation, useful for specific research
+
+```python
+docker run -p 8000:8000 -e ATARI_OBS_TYPE=ram atari-env:latest
+```
+
+## Action Spaces
+
+### Minimal Action Set (Default)
+Game-specific minimal actions (typically 4-9 actions).
+- Pong: 6 actions (NOOP, FIRE, UP, DOWN, etc.)
+- Breakout: 4 actions (NOOP, FIRE, LEFT, RIGHT)
+
+```python
+docker run -p 8000:8000 -e ATARI_FULL_ACTION_SPACE=false atari-env:latest
+```
+
+### Full Action Set
+All 18 possible Atari 2600 actions:
+0. NOOP
+1. FIRE
+2. UP
+3. RIGHT
+4. LEFT
+5. DOWN
+6. UPRIGHT
+7. UPLEFT
+8. DOWNRIGHT
+9. DOWNLEFT
+10. UPFIRE
+11. RIGHTFIRE
+12. LEFTFIRE
+13. DOWNFIRE
+14. UPRIGHTFIRE
+15. UPLEFTFIRE
+16. DOWNRIGHTFIRE
+17. DOWNLEFTFIRE
+
+```python
+docker run -p 8000:8000 -e ATARI_FULL_ACTION_SPACE=true atari-env:latest
+```
+
+## Configuration
+
+### Environment Variables
+
+- `ATARI_GAME`: Game name (default: "pong")
+- `ATARI_OBS_TYPE`: Observation type - "rgb", "grayscale", "ram" (default: "rgb")
+- `ATARI_FULL_ACTION_SPACE`: Use full action space - "true"/"false" (default: "false")
+- `ATARI_MODE`: Game mode (optional, game-specific)
+- `ATARI_DIFFICULTY`: Game difficulty (optional, game-specific)
+- `ATARI_REPEAT_ACTION_PROB`: Sticky action probability 0.0-1.0 (default: "0.0")
+- `ATARI_FRAMESKIP`: Frames to skip per action (default: "4")
+
+### Example: Breakout with Custom Settings
+
+```bash
+docker run -p 8000:8000 \
+  -e ATARI_GAME=breakout \
+  -e ATARI_OBS_TYPE=grayscale \
+  -e ATARI_FULL_ACTION_SPACE=true \
+  -e ATARI_REPEAT_ACTION_PROB=0.25 \
+  -e ATARI_FRAMESKIP=4 \
+  atari-env:latest
+```
+
+## API Reference
+
+### AtariAction
+
+```python
+@dataclass
+class AtariAction(Action):
+    action_id: int                  # Action index to execute
+    game_name: str = "pong"         # Game name
+    obs_type: str = "rgb"           # Observation type
+    full_action_space: bool = False # Full or minimal action space
+```
+
+### AtariObservation
+
+```python
+@dataclass
+class AtariObservation(Observation):
+    screen: List[int]               # Flattened screen pixels
+    screen_shape: List[int]         # Original screen shape
+    legal_actions: List[int]        # Legal action indices
+    lives: int                      # Lives remaining
+    episode_frame_number: int       # Frame # in episode
+    frame_number: int               # Total frame #
+    done: bool                      # Episode finished
+    reward: Optional[float]         # Reward from last action
+```
+
+### AtariState
+
+```python
+@dataclass
+class AtariState(State):
+    episode_id: str                      # Unique episode ID
+    step_count: int                      # Number of steps
+    game_name: str                       # Game name
+    obs_type: str                        # Observation type
+    full_action_space: bool              # Action space type
+    mode: Optional[int]                  # Game mode
+    difficulty: Optional[int]            # Game difficulty
+    repeat_action_probability: float     # Sticky action prob
+    frameskip: int                       # Frameskip setting
+```
+
+## Example Script
+
+```python
+#!/usr/bin/env python3
+"""Example training loop with Atari environment."""
+
+import asyncio
+import numpy as np
+from atari_env import AtariEnv, AtariAction
+
+async def train():
+    # Start environment
+    client = await AtariEnv.from_docker_image("atari-env:latest")
+
+    async with client:
+        # Training loop
+        for episode in range(10):
+            result = await client.reset()
+            episode_reward = 0
+            steps = 0
+
+            while not result.done:
+                # Random policy (replace with your RL agent)
+                action_id = np.random.choice(result.observation.legal_actions)
+
+                # Take action
+                result = await client.step(AtariAction(action_id=action_id))
+
+                episode_reward += result.reward or 0
+                steps += 1
+
+                # Reshape screen for processing
+                screen = np.array(result.observation.screen).reshape(
+                    result.observation.screen_shape
+                )
+
+                # Your RL training code here
+                # ...
+
+            print(f"Episode {episode}: reward={episode_reward:.2f}, steps={steps}")
+
+asyncio.run(train())
+```
+
+## Testing
+
+### Local Testing
+
+```bash
+# Install dependencies
+pip install ale-py fastapi uvicorn requests
+
+# Start server
+export PYTHONPATH=src:envs
+python -m atari_env.server.app
+
+# Test from another terminal (using sync wrapper for simplicity)
+python -c "
+from atari_env import AtariEnv, AtariAction
+with AtariEnv(base_url='http://localhost:8000').sync() as env:
+    result = env.reset()
+    print(f'Initial obs: {result.observation.screen_shape}')
+    result = env.step(AtariAction(action_id=2))
+    print(f'After step: reward={result.reward}, done={result.done}')
+"
+```
+
+### Docker Testing
+
+```bash
+# Build and run
+docker build -f envs/atari_env/server/Dockerfile -t atari-env:latest .
+docker run -p 8000:8000 atari-env:latest
+
+# Test in another terminal
+curl http://localhost:8000/health
+curl -X POST http://localhost:8000/reset
+```
+
+## Popular Games and Their Characteristics
+
+| Game | Minimal Actions | Lives | Difficulty | Notes |
+|------|----------------|-------|-----------|-------|
+| Pong | 6 | 1 | Low | Good for learning basics |
+| Breakout | 4 | 5 | Medium | Classic RL benchmark |
+| Space Invaders | 6 | 3 | Medium | Shooting game |
+| Ms. Pac-Man | 9 | 3 | High | Complex navigation |
+| Asteroids | 14 | 3 | Medium | Continuous shooting |
+| Montezuma's Revenge | 18 | 5 | Very High | Exploration challenge |
+| Pitfall | 18 | 1 | High | Platformer |
+| Seaquest | 18 | 3 | High | Submarine rescue |
+
+## Limitations & Notes
+
+- **Frame perfect timing**: Some games require precise timing
+- **Exploration**: Games like Montezuma's Revenge are notoriously difficult
+- **Observation delay**: HTTP adds minimal latency vs local gym
+- **Determinism**: Set `ATARI_REPEAT_ACTION_PROB=0.0` for deterministic behavior
+- **ROMs**: All ROMs are bundled with ale-py package
+
+## References
+
+- [Arcade Learning Environment Paper (2013)](https://jair.org/index.php/jair/article/view/10819)
+- [ALE GitHub](https://github.com/Farama-Foundation/Arcade-Learning-Environment)
+- [ALE Documentation](https://ale.farama.org/)
+- [Gymnasium Atari Environments](https://gymnasium.farama.org/environments/atari/)
+
+## Citation
+
+If you use ALE in your research, please cite:
+
+```bibtex
+@Article{bellemare13arcade,
+    author = {{Bellemare}, M.~G. and {Naddaf}, Y. and {Veness}, J. and {Bowling}, M.},
+    title = {The Arcade Learning Environment: An Evaluation Platform for General Agents},
+    journal = {Journal of Artificial Intelligence Research},
+    year = "2013",
+    month = "jun",
+    volume = "47",
+    pages = "253--279",
+}
+```

envs/atari_env/__init__.py

@@ -0,0 +1,31 @@
+# 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.
+
+"""
+Atari Environment for OpenEnv.
+
+This module provides OpenEnv integration for Atari 2600 games via the
+Arcade Learning Environment (ALE).
+
+Example:
+    >>> from envs.atari_env import AtariEnv, AtariAction
+    >>>
+    >>> # Connect to a running server or start via Docker
+    >>> env = AtariEnv.from_docker_image("atari-env:latest")
+    >>>
+    >>> # Reset and interact
+    >>> result = env.reset()
+    >>> result = env.step(AtariAction(action_id=2))  # UP
+    >>> print(result.reward, result.done)
+    >>>
+    >>> # Cleanup
+    >>> env.close()
+"""
+
+from .client import AtariEnv
+from .models import AtariAction, AtariObservation, AtariState
+
+__all__ = ["AtariEnv", "AtariAction", "AtariObservation", "AtariState"]

envs/atari_env/client.py

@@ -0,0 +1,120 @@
+# 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.
+
+"""
+Atari Environment Client.
+
+This module provides the client for connecting to an Atari Environment server
+via WebSocket for persistent sessions.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, TYPE_CHECKING
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_client import EnvClient
+
+from .models import AtariAction, AtariObservation, AtariState
+
+if TYPE_CHECKING:
+    from openenv.core.containers.runtime import ContainerProvider
+
+
+class AtariEnv(EnvClient[AtariAction, AtariObservation, AtariState]):
+    """
+    Client for Atari Environment.
+
+    This client maintains a persistent WebSocket connection to the environment
+    server, enabling efficient multi-step interactions with lower latency.
+
+    Example:
+        >>> # Connect to a running server
+        >>> with AtariEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.screen_shape)
+        ...
+        ...     result = client.step(AtariAction(action_id=2))  # UP
+        ...     print(result.reward, result.done)
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = AtariEnv.from_docker_image("atari-env:latest")
+        >>> try:
+        ...     result = client.reset()
+        ...     result = client.step(AtariAction(action_id=0))  # NOOP
+        ... finally:
+        ...     client.close()
+    """
+
+    def _step_payload(self, action: AtariAction) -> Dict[str, Any]:
+        """
+        Convert AtariAction to JSON payload for step request.
+
+        Args:
+            action: AtariAction instance.
+
+        Returns:
+            Dictionary representation suitable for JSON encoding.
+        """
+        return {
+            "action_id": action.action_id,
+            "game_name": action.game_name,
+            "obs_type": action.obs_type,
+            "full_action_space": action.full_action_space,
+        }
+
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[AtariObservation]:
+        """
+        Parse server response into StepResult[AtariObservation].
+
+        Args:
+            payload: JSON response from server.
+
+        Returns:
+            StepResult with AtariObservation.
+        """
+        obs_data = payload.get("observation", {})
+
+        observation = AtariObservation(
+            screen=obs_data.get("screen", []),
+            screen_shape=obs_data.get("screen_shape", []),
+            legal_actions=obs_data.get("legal_actions", []),
+            lives=obs_data.get("lives", 0),
+            episode_frame_number=obs_data.get("episode_frame_number", 0),
+            frame_number=obs_data.get("frame_number", 0),
+            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[str, Any]) -> AtariState:
+        """
+        Parse server response into AtariState object.
+
+        Args:
+            payload: JSON response from /state endpoint.
+
+        Returns:
+            AtariState object with environment state information.
+        """
+        return AtariState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            game_name=payload.get("game_name", "unknown"),
+            obs_type=payload.get("obs_type", "rgb"),
+            full_action_space=payload.get("full_action_space", False),
+            mode=payload.get("mode"),
+            difficulty=payload.get("difficulty"),
+            repeat_action_probability=payload.get("repeat_action_probability", 0.0),
+            frameskip=payload.get("frameskip", 4),
+        )

envs/atari_env/models.py

@@ -0,0 +1,85 @@
+# 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 Atari Environment.
+
+This module defines the Action, Observation, and State types for Atari games
+via the Arcade Learning Environment (ALE).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional
+
+from openenv.core.env_server import Action, Observation, State
+
+
+class AtariAction(Action):
+    """
+    Action for Atari environments.
+
+    Attributes:
+        action_id: The integer action ID to take (from legal_actions).
+        game_name: Name of the Atari game (e.g., "pong", "breakout", "space_invaders").
+        obs_type: Observation type ("rgb", "grayscale", or "ram").
+        full_action_space: Whether to use full (18 actions) or minimal action space.
+    """
+
+    action_id: int
+    game_name: str = "pong"
+    obs_type: Literal["rgb", "grayscale", "ram"] = "rgb"
+    full_action_space: bool = False
+
+
+class AtariObservation(Observation):
+    """
+    Observation from Atari environment.
+
+    This represents what the agent sees after taking an action.
+
+    Attributes:
+        screen: Screen observation as a flattened list of pixels.
+                Shape depends on obs_type:
+                - rgb: [210, 160, 3] flattened
+                - grayscale: [210, 160] flattened
+                - ram: [128] (RAM contents)
+        screen_shape: Original shape of the screen before flattening.
+        legal_actions: List of legal action IDs the agent can take.
+        lives: Number of lives remaining.
+        episode_frame_number: Frame number within current episode.
+        frame_number: Total frame number since environment creation.
+    """
+
+    screen: List[int]
+    screen_shape: List[int]
+    legal_actions: List[int]
+    lives: int = 0
+    episode_frame_number: int = 0
+    frame_number: int = 0
+
+
+class AtariState(State):
+    """
+    State for Atari environment.
+
+    Attributes:
+        game_name: Name of the Atari game.
+        obs_type: Observation type ("rgb", "grayscale", or "ram").
+        full_action_space: Whether using full or minimal action space.
+        mode: Game mode (if applicable).
+        difficulty: Game difficulty (if applicable).
+        repeat_action_probability: Probability of repeating previous action (sticky actions).
+        frameskip: Number of frames to skip per action.
+    """
+
+    game_name: str = "pong"
+    obs_type: Literal["rgb", "grayscale", "ram"] = "rgb"
+    full_action_space: bool = False
+    mode: Optional[int] = None
+    difficulty: Optional[int] = None
+    repeat_action_probability: float = 0.0
+    frameskip: int = 4

envs/atari_env/server/Dockerfile

@@ -0,0 +1,43 @@
+# Dockerfile for Atari Environment
+# This image provides Atari 2600 games via the Arcade Learning Environment (ALE)
+
+# Configurable base image - defaults to local build, can be overridden for CI/CD
+# Base image provides: fastapi, uvicorn, requests, curl, PYTHONPATH=/app/src
+#
+# Local build: docker build -t envtorch-base:latest -f src/core/containers/images/Dockerfile .
+#              docker build -f envs/atari_env/server/Dockerfile -t atari-env:latest .
+#
+# CI/CD build: docker build --build-arg BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest \
+#              -f envs/atari_env/server/Dockerfile -t atari-env:latest .
+ARG BASE_IMAGE=openenv-base:latest
+FROM ${BASE_IMAGE}
+
+# Install dependencies
+COPY envs/atari_env/server/requirements.txt /tmp/requirements.txt
+RUN pip install --no-cache-dir -r /tmp/requirements.txt && rm /tmp/requirements.txt
+
+# Copy OpenEnv core (base image already set WORKDIR=/app)
+COPY src/core/ /app/src/core/
+
+# Copy Atari environment code
+COPY envs/atari_env/ /app/envs/atari_env/
+
+# Copy README for web interface documentation
+COPY envs/atari_env/README.md /app/README.md
+
+# Atari-specific environment variables (can be overridden at runtime)
+ENV ATARI_GAME=pong
+ENV ATARI_OBS_TYPE=rgb
+ENV ATARI_FULL_ACTION_SPACE=false
+ENV ATARI_REPEAT_ACTION_PROB=0.0
+ENV ATARI_FRAMESKIP=4
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+CMD ["uvicorn", "envs.atari_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

envs/atari_env/server/__init__.py

@@ -0,0 +1,15 @@
+# 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.
+
+"""
+Atari Environment Server.
+
+Server-side implementation of Atari environment for OpenEnv.
+"""
+
+from .atari_environment import AtariEnvironment
+
+__all__ = ["AtariEnvironment"]

envs/atari_env/server/app.py

@@ -0,0 +1,80 @@
+# 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 Atari Environment.
+
+This module creates an HTTP server that exposes Atari games
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn envs.atari_env.server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn envs.atari_env.server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    python -m envs.atari_env.server.app
+
+Environment variables:
+    ATARI_GAME: Game name to serve (default: "pong")
+    ATARI_OBS_TYPE: Observation type (default: "rgb")
+    ATARI_FULL_ACTION_SPACE: Use full action space (default: "false")
+    ATARI_MODE: Game mode (optional)
+    ATARI_DIFFICULTY: Game difficulty (optional)
+    ATARI_REPEAT_ACTION_PROB: Sticky action probability (default: "0.0")
+    ATARI_FRAMESKIP: Frameskip (default: "4")
+"""
+
+import os
+
+from openenv.core.env_server import create_app
+
+from ..models import AtariAction, AtariObservation
+from .atari_environment import AtariEnvironment
+
+# Get configuration from environment variables
+game_name = os.getenv("ATARI_GAME", "pong")
+obs_type = os.getenv("ATARI_OBS_TYPE", "rgb")
+full_action_space = os.getenv("ATARI_FULL_ACTION_SPACE", "false").lower() == "true"
+repeat_action_prob = float(os.getenv("ATARI_REPEAT_ACTION_PROB", "0.0"))
+frameskip = int(os.getenv("ATARI_FRAMESKIP", "4"))
+
+# Optional parameters
+mode = os.getenv("ATARI_MODE")
+difficulty = os.getenv("ATARI_DIFFICULTY")
+
+# Convert to int if specified
+mode = int(mode) if mode is not None else None
+difficulty = int(difficulty) if difficulty is not None else None
+
+
+# Factory function to create AtariEnvironment instances
+def create_atari_environment():
+    """Factory function that creates AtariEnvironment with config."""
+    return AtariEnvironment(
+        game_name=game_name,
+        obs_type=obs_type,
+        full_action_space=full_action_space,
+        mode=mode,
+        difficulty=difficulty,
+        repeat_action_probability=repeat_action_prob,
+        frameskip=frameskip,
+    )
+
+
+# Create the FastAPI app with web interface and README integration
+# Pass the factory function instead of an instance for WebSocket session support
+app = create_app(
+    create_atari_environment, AtariAction, AtariObservation, env_name="atari_env"
+)
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)

envs/atari_env/server/atari_environment.py

@@ -0,0 +1,246 @@
+# 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.
+
+"""
+Atari Environment Server Implementation.
+
+This module wraps ALE's ALEInterface and exposes it
+via the OpenEnv Environment interface.
+"""
+
+import uuid
+from typing import Any, Dict, Literal, Optional
+
+from openenv.core.env_server import Action, Environment, Observation
+
+from ..models import AtariAction, AtariObservation, AtariState
+
+# Import ALE
+try:
+    import numpy as np
+    from ale_py import ALEInterface, roms
+except ImportError as e:
+    raise ImportError(
+        "ALE (Arcade Learning Environment) is not installed. "
+        "Please install it with: pip install ale-py"
+    ) from e
+
+
+class AtariEnvironment(Environment):
+    """
+    Atari Environment wrapper for OpenEnv.
+
+    This environment wraps Atari 2600 games via the Arcade Learning Environment (ALE)
+    and provides a clean interface for RL training.
+
+    Supported games include: pong, breakout, space_invaders, and 100+ others.
+
+    Args:
+        game_name: Name of the Atari game (e.g., "pong", "breakout").
+        obs_type: Observation type - "rgb", "grayscale", or "ram".
+        full_action_space: Use full action space (18 actions) vs minimal.
+        mode: Game mode (if applicable).
+        difficulty: Game difficulty (if applicable).
+        repeat_action_probability: Sticky action probability (default 0.0).
+        frameskip: Number of frames to skip per action (default 4).
+
+    Example:
+        >>> env = AtariEnvironment("pong")
+        >>> obs = env.reset()
+        >>> print(obs.screen_shape)  # [210, 160, 3]
+        >>> obs = env.step(AtariAction(action_id=2))  # UP
+        >>> print(obs.reward, obs.done)
+    """
+
+    def __init__(
+        self,
+        game_name: str = "pong",
+        obs_type: Literal["rgb", "grayscale", "ram"] = "rgb",
+        full_action_space: bool = False,
+        mode: Optional[int] = None,
+        difficulty: Optional[int] = None,
+        repeat_action_probability: float = 0.0,
+        frameskip: int = 4,
+    ):
+        """Initialize Atari environment."""
+        super().__init__()
+
+        self.game_name = game_name
+        self.obs_type = obs_type
+        self.full_action_space = full_action_space
+        self.mode = mode
+        self.difficulty = difficulty
+        self.repeat_action_probability = repeat_action_probability
+        self.frameskip = frameskip
+
+        # Create ALE interface
+        self.ale = ALEInterface()
+
+        # Configure ALE
+        from ale_py import LoggerMode
+
+        self.ale.setLoggerMode(LoggerMode.Error)  # Error mode only
+        self.ale.setFloat("repeat_action_probability", repeat_action_probability)
+
+        # Load ROM
+        try:
+            rom_path = roms.get_rom_path(game_name)
+            self.ale.loadROM(rom_path)
+        except Exception as e:
+            raise ValueError(
+                f"Failed to load Atari game '{game_name}': {e}\n"
+                f"Available games can be found via: ale_py.roms.list_roms()"
+            ) from e
+
+        # Set mode and difficulty if specified
+        if mode is not None:
+            self.ale.setMode(mode)
+        if difficulty is not None:
+            self.ale.setDifficulty(difficulty)
+
+        # Get action set
+        if full_action_space:
+            self._action_set = self.ale.getLegalActionSet()
+        else:
+            self._action_set = self.ale.getMinimalActionSet()
+
+        # Get screen dimensions for observation space
+        self.screen_height, self.screen_width = self.ale.getScreenDims()
+        if obs_type == "rgb":
+            self.screen_shape = [self.screen_height, self.screen_width, 3]
+        elif obs_type == "grayscale":
+            self.screen_shape = [self.screen_height, self.screen_width]
+        elif obs_type == "ram":
+            self.screen_shape = [self.ale.getRAMSize()]
+        else:
+            raise ValueError(f"Invalid obs_type: {obs_type}")
+
+        # Initialize state
+        self._state = AtariState(
+            game_name=game_name,
+            obs_type=obs_type,
+            full_action_space=full_action_space,
+            mode=mode,
+            difficulty=difficulty,
+            repeat_action_probability=repeat_action_probability,
+            frameskip=frameskip,
+        )
+
+    def reset(self) -> Observation:
+        """
+        Reset the environment and return initial observation.
+
+        Returns:
+            Initial observation for the agent.
+        """
+        # Reset ALE
+        self.ale.reset_game()
+
+        # Reset state tracking
+        self._state.episode_id = str(uuid.uuid4())
+        self._state.step_count = 0
+
+        # Get initial observation
+        return self._make_observation()
+
+    def step(self, action: Action) -> Observation:
+        """
+        Execute agent's action and return resulting observation.
+
+        Args:
+            action: AtariAction containing the action_id to execute.
+
+        Returns:
+            Observation after action execution.
+
+        Raises:
+            ValueError: If action is not an AtariAction.
+        """
+        if not isinstance(action, AtariAction):
+            raise ValueError(f"Expected AtariAction, got {type(action)}")
+
+        # Validate action_id
+        if action.action_id < 0 or action.action_id >= len(self._action_set):
+            raise ValueError(
+                f"Invalid action_id: {action.action_id}. "
+                f"Valid range: [0, {len(self._action_set) - 1}]"
+            )
+
+        # Get actual ALE action
+        ale_action = self._action_set[action.action_id]
+
+        # Execute action with frameskip
+        total_reward = 0.0
+        for _ in range(self.frameskip):
+            total_reward += self.ale.act(ale_action)
+            if self.ale.game_over():
+                break
+
+        self._state.step_count += 1
+
+        # Get observation
+        obs = self._make_observation()
+        obs.reward = total_reward
+
+        return obs
+
+    @property
+    def state(self) -> AtariState:
+        """Get current environment state."""
+        return self._state
+
+    def _make_observation(self) -> AtariObservation:
+        """
+        Create an AtariObservation from current ALE state.
+
+        Returns:
+            AtariObservation for the agent.
+        """
+        # Get screen observation
+        if self.obs_type == "rgb":
+            screen = self.ale.getScreenRGB()
+        elif self.obs_type == "grayscale":
+            screen = self.ale.getScreenGrayscale()
+        elif self.obs_type == "ram":
+            screen = self.ale.getRAM()
+        else:
+            raise ValueError(f"Invalid obs_type: {self.obs_type}")
+
+        # Flatten screen for JSON serialization
+        # Handle both numpy arrays and lists
+        if hasattr(screen, "flatten"):
+            screen_flat = screen.flatten().tolist()
+        elif hasattr(screen, "tolist"):
+            screen_flat = screen.tolist()
+        else:
+            screen_flat = list(screen)
+
+        # Get game info
+        lives = self.ale.lives()
+        episode_frame_number = self.ale.getEpisodeFrameNumber()
+        frame_number = self.ale.getFrameNumber()
+        done = self.ale.game_over()
+
+        # Create legal actions list (indices into action_set)
+        legal_actions = list(range(len(self._action_set)))
+
+        # Create observation
+        obs = AtariObservation(
+            screen=screen_flat,
+            screen_shape=self.screen_shape,
+            legal_actions=legal_actions,
+            lives=lives,
+            episode_frame_number=episode_frame_number,
+            frame_number=frame_number,
+            done=done,
+            reward=0.0,  # Will be filled in by step()
+            metadata={
+                "game_name": self.game_name,
+                "action_meanings": [str(a) for a in self._action_set],
+            },
+        )
+
+        return obs

envs/atari_env/server/requirements.txt

@@ -0,0 +1,3 @@
+gymnasium>=0.29.0
+ale-py>=0.8.0
+numpy>=1.24.0

envs/atari_env/test_atari_docker.sh

@@ -0,0 +1,333 @@
+#!/bin/bash
+# Comprehensive Docker test for Atari environment
+# Tests: Build, Start, Health, Reset, Step, State, Cleanup
+
+set -e  # Exit on error
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+IMAGE_NAME="atari-env"
+IMAGE_TAG="test"
+CONTAINER_NAME="atari-env-test"
+PORT="8765"  # Use non-standard port to avoid conflicts
+HEALTH_RETRIES=30
+HEALTH_DELAY=2
+
+# Cleanup function
+cleanup() {
+    echo -e "\n${BLUE}Cleaning up...${NC}"
+    docker stop ${CONTAINER_NAME} 2>/dev/null || true
+    docker rm ${CONTAINER_NAME} 2>/dev/null || true
+    echo -e "${GREEN}✓${NC} Cleanup complete"
+}
+
+# Set trap to cleanup on exit
+trap cleanup EXIT
+
+# Header
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  ATARI ENVIRONMENT DOCKER TEST"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Check prerequisites
+echo -e "${BLUE}Checking prerequisites...${NC}"
+if ! command -v docker &> /dev/null; then
+    echo -e "${RED}✗${NC} Docker is not installed"
+    exit 1
+fi
+echo -e "${GREEN}✓${NC} Docker is installed"
+
+if ! command -v curl &> /dev/null; then
+    echo -e "${RED}✗${NC} curl is not installed"
+    exit 1
+fi
+echo -e "${GREEN}✓${NC} curl is installed"
+
+# Check if we're in the right directory
+if [ ! -f "envs/atari_env/server/Dockerfile" ]; then
+    echo -e "${RED}✗${NC} Must run from OpenEnv root directory"
+    exit 1
+fi
+echo -e "${GREEN}✓${NC} In correct directory"
+
+# Step 1: Build Docker image
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}STEP 1: Building Docker Image${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+echo "Building ${IMAGE_NAME}:${IMAGE_TAG}..."
+if docker build -f envs/atari_env/server/Dockerfile -t ${IMAGE_NAME}:${IMAGE_TAG} . 2>&1 | tee /tmp/atari_build.log | tail -n 20; then
+    echo -e "${GREEN}✓${NC} Docker image built successfully"
+else
+    echo -e "${RED}✗${NC} Docker build failed"
+    echo "See /tmp/atari_build.log for full output"
+    exit 1
+fi
+
+# Check image exists
+if docker image inspect ${IMAGE_NAME}:${IMAGE_TAG} &> /dev/null; then
+    IMAGE_SIZE=$(docker image inspect ${IMAGE_NAME}:${IMAGE_TAG} --format='{{.Size}}' | awk '{print $1/1024/1024}')
+    echo -e "${GREEN}✓${NC} Image size: ${IMAGE_SIZE} MB"
+else
+    echo -e "${RED}✗${NC} Image not found after build"
+    exit 1
+fi
+
+# Step 2: Start container
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}STEP 2: Starting Container${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+# Clean up any existing container
+docker rm -f ${CONTAINER_NAME} 2>/dev/null || true
+
+echo "Starting container on port ${PORT}..."
+docker run -d \
+    --name ${CONTAINER_NAME} \
+    -p ${PORT}:8000 \
+    -e ATARI_GAME=pong \
+    -e ATARI_OBS_TYPE=ram \
+    -e ATARI_FRAMESKIP=4 \
+    ${IMAGE_NAME}:${IMAGE_TAG}
+
+if [ $? -eq 0 ]; then
+    echo -e "${GREEN}✓${NC} Container started: ${CONTAINER_NAME}"
+else
+    echo -e "${RED}✗${NC} Failed to start container"
+    exit 1
+fi
+
+# Wait for container to be running
+sleep 2
+if docker ps | grep -q ${CONTAINER_NAME}; then
+    echo -e "${GREEN}✓${NC} Container is running"
+else
+    echo -e "${RED}✗${NC} Container is not running"
+    docker logs ${CONTAINER_NAME}
+    exit 1
+fi
+
+# Step 3: Wait for health check
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}STEP 3: Waiting for Server${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+echo "Waiting for server to be ready (timeout: ${HEALTH_RETRIES}s)..."
+for i in $(seq 1 ${HEALTH_RETRIES}); do
+    if curl -s http://localhost:${PORT}/health > /dev/null 2>&1; then
+        echo -e "${GREEN}✓${NC} Server is ready (${i}s)"
+        break
+    fi
+
+    if [ $i -eq ${HEALTH_RETRIES} ]; then
+        echo -e "${RED}✗${NC} Server did not become ready in time"
+        echo "Container logs:"
+        docker logs ${CONTAINER_NAME}
+        exit 1
+    fi
+
+    echo -n "."
+    sleep ${HEALTH_DELAY}
+done
+
+# Step 4: Test health endpoint
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}STEP 4: Testing Health Endpoint${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+HEALTH_RESPONSE=$(curl -s http://localhost:${PORT}/health)
+echo "Response: ${HEALTH_RESPONSE}"
+
+if echo "${HEALTH_RESPONSE}" | grep -q "healthy"; then
+    echo -e "${GREEN}✓${NC} Health endpoint working"
+else
+    echo -e "${RED}✗${NC} Health endpoint failed"
+    exit 1
+fi
+
+# Step 5: Test reset endpoint
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}STEP 5: Testing Reset Endpoint${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+RESET_RESPONSE=$(curl -s -X POST http://localhost:${PORT}/reset -H "Content-Type: application/json" -d '{}')
+
+if [ -z "${RESET_RESPONSE}" ]; then
+    echo -e "${RED}✗${NC} Reset endpoint returned empty response"
+    docker logs ${CONTAINER_NAME} | tail -20
+    exit 1
+fi
+
+echo "Response (first 200 chars): ${RESET_RESPONSE:0:200}..."
+
+# Check if response contains expected fields
+if echo "${RESET_RESPONSE}" | grep -q "observation" && \
+   echo "${RESET_RESPONSE}" | grep -q "screen" && \
+   echo "${RESET_RESPONSE}" | grep -q "legal_actions"; then
+    echo -e "${GREEN}✓${NC} Reset endpoint working"
+
+    # Extract some info
+    SCREEN_LEN=$(echo "${RESET_RESPONSE}" | grep -o '"screen":\[[^]]*\]' | wc -c)
+    echo "  Screen data length: ${SCREEN_LEN} chars"
+else
+    echo -e "${RED}✗${NC} Reset response missing required fields"
+    echo "Full response: ${RESET_RESPONSE}"
+    exit 1
+fi
+
+# Step 6: Test step endpoint
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}STEP 6: Testing Step Endpoint${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+STEP_PAYLOAD='{"action": {"action_id": 0, "game_name": "pong"}}'
+STEP_RESPONSE=$(curl -s -X POST http://localhost:${PORT}/step -H "Content-Type: application/json" -d "${STEP_PAYLOAD}")
+
+if [ -z "${STEP_RESPONSE}" ]; then
+    echo -e "${RED}✗${NC} Step endpoint returned empty response"
+    docker logs ${CONTAINER_NAME} | tail -20
+    exit 1
+fi
+
+echo "Response (first 200 chars): ${STEP_RESPONSE:0:200}..."
+
+# Check if response contains expected fields
+if echo "${STEP_RESPONSE}" | grep -q "observation" && \
+   echo "${STEP_RESPONSE}" | grep -q "reward" && \
+   echo "${STEP_RESPONSE}" | grep -q "done"; then
+    echo -e "${GREEN}✓${NC} Step endpoint working"
+
+    # Extract reward and done
+    REWARD=$(echo "${STEP_RESPONSE}" | grep -o '"reward":[^,}]*' | cut -d: -f2)
+    DONE=$(echo "${STEP_RESPONSE}" | grep -o '"done":[^,}]*' | cut -d: -f2)
+    echo "  Reward: ${REWARD}"
+    echo "  Done: ${DONE}"
+else
+    echo -e "${RED}✗${NC} Step response missing required fields"
+    echo "Full response: ${STEP_RESPONSE}"
+    exit 1
+fi
+
+# Step 7: Test state endpoint
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}STEP 7: Testing State Endpoint${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+STATE_RESPONSE=$(curl -s http://localhost:${PORT}/state)
+
+if [ -z "${STATE_RESPONSE}" ]; then
+    echo -e "${RED}✗${NC} State endpoint returned empty response"
+    docker logs ${CONTAINER_NAME} | tail -20
+    exit 1
+fi
+
+echo "Response: ${STATE_RESPONSE}"
+
+# Check if response contains expected fields
+if echo "${STATE_RESPONSE}" | grep -q "episode_id" && \
+   echo "${STATE_RESPONSE}" | grep -q "step_count" && \
+   echo "${STATE_RESPONSE}" | grep -q "game_name"; then
+    echo -e "${GREEN}✓${NC} State endpoint working"
+
+    # Extract info
+    GAME_NAME=$(echo "${STATE_RESPONSE}" | grep -o '"game_name":"[^"]*"' | cut -d'"' -f4)
+    STEP_COUNT=$(echo "${STATE_RESPONSE}" | grep -o '"step_count":[^,}]*' | cut -d: -f2)
+    echo "  Game: ${GAME_NAME}"
+    echo "  Steps: ${STEP_COUNT}"
+else
+    echo -e "${RED}✗${NC} State response missing required fields"
+    echo "Full response: ${STATE_RESPONSE}"
+    exit 1
+fi
+
+# Step 8: Test multiple steps
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}STEP 8: Testing Multiple Steps${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+echo "Taking 10 steps..."
+TOTAL_REWARD=0
+for i in {1..10}; do
+    ACTION_ID=$((RANDOM % 3))  # Random action 0-2
+    STEP_PAYLOAD="{\"action\": {\"action_id\": ${ACTION_ID}, \"game_name\": \"pong\"}}"
+    STEP_RESPONSE=$(curl -s -X POST http://localhost:${PORT}/step -H "Content-Type: application/json" -d "${STEP_PAYLOAD}")
+
+    if ! echo "${STEP_RESPONSE}" | grep -q "observation"; then
+        echo -e "${RED}✗${NC} Step ${i} failed"
+        exit 1
+    fi
+
+    REWARD=$(echo "${STEP_RESPONSE}" | grep -o '"reward":[^,}]*' | cut -d: -f2 | sed 's/null/0/')
+    DONE=$(echo "${STEP_RESPONSE}" | grep -o '"done":[^,}]*' | cut -d: -f2)
+
+    echo "  Step ${i}: action=${ACTION_ID}, reward=${REWARD}, done=${DONE}"
+
+    if [ "${DONE}" = "true" ]; then
+        echo "  Episode completed early at step ${i}"
+        break
+    fi
+done
+
+echo -e "${GREEN}✓${NC} Multiple steps completed successfully"
+
+# Step 9: Check container logs for errors
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}STEP 9: Checking Container Logs${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+LOGS=$(docker logs ${CONTAINER_NAME} 2>&1)
+
+if echo "${LOGS}" | grep -i "error" | grep -v "LoggerMode.Error"; then
+    echo -e "${YELLOW}⚠${NC}  Found errors in logs:"
+    echo "${LOGS}" | grep -i "error" | head -5
+else
+    echo -e "${GREEN}✓${NC} No errors in container logs"
+fi
+
+if echo "${LOGS}" | grep -i "exception"; then
+    echo -e "${RED}✗${NC} Found exceptions in logs:"
+    echo "${LOGS}" | grep -i "exception" | head -5
+    exit 1
+else
+    echo -e "${GREEN}✓${NC} No exceptions in container logs"
+fi
+
+# Final Summary
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo -e "${GREEN}✅ ALL DOCKER TESTS PASSED${NC}"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "Summary:"
+echo "  ✓ Docker image built successfully"
+echo "  ✓ Container started and ran"
+echo "  ✓ Health endpoint working"
+echo "  ✓ Reset endpoint working"
+echo "  ✓ Step endpoint working"
+echo "  ✓ State endpoint working"
+echo "  ✓ Multiple steps working"
+echo "  ✓ No errors or exceptions"
+echo ""
+echo "Image: ${IMAGE_NAME}:${IMAGE_TAG}"
+echo "Container: ${CONTAINER_NAME}"
+echo "Port: ${PORT}"
+echo ""
+echo "To keep container running: docker start ${CONTAINER_NAME}"
+echo "To view logs: docker logs ${CONTAINER_NAME}"
+echo ""

models.py

@@ -0,0 +1,85 @@
+# 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 Atari Environment.
+
+This module defines the Action, Observation, and State types for Atari games
+via the Arcade Learning Environment (ALE).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional
+
+from openenv.core.env_server import Action, Observation, State
+
+
+class AtariAction(Action):
+    """
+    Action for Atari environments.
+
+    Attributes:
+        action_id: The integer action ID to take (from legal_actions).
+        game_name: Name of the Atari game (e.g., "pong", "breakout", "space_invaders").
+        obs_type: Observation type ("rgb", "grayscale", or "ram").
+        full_action_space: Whether to use full (18 actions) or minimal action space.
+    """
+
+    action_id: int
+    game_name: str = "pong"
+    obs_type: Literal["rgb", "grayscale", "ram"] = "rgb"
+    full_action_space: bool = False
+
+
+class AtariObservation(Observation):
+    """
+    Observation from Atari environment.
+
+    This represents what the agent sees after taking an action.
+
+    Attributes:
+        screen: Screen observation as a flattened list of pixels.
+                Shape depends on obs_type:
+                - rgb: [210, 160, 3] flattened
+                - grayscale: [210, 160] flattened
+                - ram: [128] (RAM contents)
+        screen_shape: Original shape of the screen before flattening.
+        legal_actions: List of legal action IDs the agent can take.
+        lives: Number of lives remaining.
+        episode_frame_number: Frame number within current episode.
+        frame_number: Total frame number since environment creation.
+    """
+
+    screen: List[int]
+    screen_shape: List[int]
+    legal_actions: List[int]
+    lives: int = 0
+    episode_frame_number: int = 0
+    frame_number: int = 0
+
+
+class AtariState(State):
+    """
+    State for Atari environment.
+
+    Attributes:
+        game_name: Name of the Atari game.
+        obs_type: Observation type ("rgb", "grayscale", or "ram").
+        full_action_space: Whether using full or minimal action space.
+        mode: Game mode (if applicable).
+        difficulty: Game difficulty (if applicable).
+        repeat_action_probability: Probability of repeating previous action (sticky actions).
+        frameskip: Number of frames to skip per action.
+    """
+
+    game_name: str = "pong"
+    obs_type: Literal["rgb", "grayscale", "ram"] = "rgb"
+    full_action_space: bool = False
+    mode: Optional[int] = None
+    difficulty: Optional[int] = None
+    repeat_action_probability: float = 0.0
+    frameskip: int = 4

pyproject.toml

@@ -0,0 +1,147 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-core"
+version = "0.2.2.dev0"
+description = "A unified framework for reinforcement learning environments"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    # Core shared dependencies - minimal set required for all environments
+    # Heavy dependencies (torch, numpy, smolagents, etc.) should be in
+    # individual environment pyproject.toml files
+    "fastapi>=0.104.0",
+    "pydantic>=2.0.0",
+    "uvicorn>=0.24.0",
+    "requests>=2.25.0",
+    # CLI dependencies
+    "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",
+    # MCP support
+    "fastmcp>=3.0.0",
+    # Web UI dependencies
+    "gradio>=4.0.0",
+]
+
+[project.optional-dependencies]
+core = [
+    "fastapi>=0.104.0",
+    "pydantic>=2.0.0",
+    "uvicorn>=0.24.0",
+    "requests>=2.25.0",
+    "websockets>=15.0.1",
+]
+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",
+]
+docs = [
+    "sphinx==7.2.6",
+    "pytorch-sphinx-theme2",
+    "sphinxcontrib.katex==0.9.10",
+    "docutils>=0.18.1,<0.21",
+    "sphinx-design==0.6.1",
+    "sphinxcontrib-mermaid==1.0.0",
+    "myst-parser",
+    "sphinxext-opengraph",
+    "sphinx-sitemap==2.7.1",
+    "sphinx-gallery>=0.14.0",
+    "matplotlib",
+    "nest-asyncio",
+    "smolagents",
+]
+all = [
+    "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git@main",
+    "openenv-core[cli]",
+]
+daytona = [
+    "daytona>=0.136.0",
+    "pyyaml>=6.0",
+]
+inspect = [
+    "inspect-ai>=0.3.0",
+]
+
+[project.scripts]
+openenv = "openenv.cli.__main__:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.package-data]
+"openenv.cli" = ["templates/**/*"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.coverage.run]
+omit = [
+    "openenv/cli/templates/**",
+    "**/templates/**",
+    "openenv/cli/__main__.py",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+markers = [
+    "docker: Tests that require Docker to be running",
+    "network: Tests that require network access (HuggingFace, etc.)",
+    "integration: Integration tests with external resources",
+]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.14.0",
+    "usort>=1.1.0",
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]
+
+[tool.usort]
+# Disable first_party auto-detection so all non-stdlib imports land in
+# the same "third_party" bucket (the default_category). This matches
+# pyfmt's usort behavior inside arc f, which groups openenv.* and env
+# package imports together without blank-line separators.
+first_party_detection = false
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "W"]
+ignore = [
+    "E402",  # Module level import not at top of file (needed for pytest.importorskip patterns)
+    "E501",  # Line too long (not enforced previously, would require large refactor)
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Context manager variables that are intentionally unused
+"tests/envs/test_websockets.py" = ["F841"]
+"tests/test_cli/test_push.py" = ["F841"]
+# Compatibility shim module
+"src/openenv_core/__init__.py" = ["F401"]

server/Dockerfile

@@ -0,0 +1,43 @@
+# Dockerfile for Atari Environment
+# This image provides Atari 2600 games via the Arcade Learning Environment (ALE)
+
+# Configurable base image - defaults to local build, can be overridden for CI/CD
+# Base image provides: fastapi, uvicorn, requests, curl, PYTHONPATH=/app/src
+#
+# Local build: docker build -t envtorch-base:latest -f src/core/containers/images/Dockerfile .
+#              docker build -f envs/atari_env/server/Dockerfile -t atari-env:latest .
+#
+# CI/CD build: docker build --build-arg BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest \
+#              -f envs/atari_env/server/Dockerfile -t atari-env:latest .
+ARG BASE_IMAGE=openenv-base:latest
+FROM ${BASE_IMAGE}
+
+# Install dependencies
+COPY envs/atari_env/server/requirements.txt /tmp/requirements.txt
+RUN pip install --no-cache-dir -r /tmp/requirements.txt && rm /tmp/requirements.txt
+
+# Copy OpenEnv core (base image already set WORKDIR=/app)
+COPY src/core/ /app/src/core/
+
+# Copy Atari environment code
+COPY envs/atari_env/ /app/envs/atari_env/
+
+# Copy README for web interface documentation
+COPY envs/atari_env/README.md /app/README.md
+
+# Atari-specific environment variables (can be overridden at runtime)
+ENV ATARI_GAME=pong
+ENV ATARI_OBS_TYPE=rgb
+ENV ATARI_FULL_ACTION_SPACE=false
+ENV ATARI_REPEAT_ACTION_PROB=0.0
+ENV ATARI_FRAMESKIP=4
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+CMD ["uvicorn", "envs.atari_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

server/__init__.py

@@ -0,0 +1,15 @@
+# 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.
+
+"""
+Atari Environment Server.
+
+Server-side implementation of Atari environment for OpenEnv.
+"""
+
+from .atari_environment import AtariEnvironment
+
+__all__ = ["AtariEnvironment"]

server/app.py

@@ -0,0 +1,80 @@
+# 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 Atari Environment.
+
+This module creates an HTTP server that exposes Atari games
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn envs.atari_env.server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn envs.atari_env.server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    python -m envs.atari_env.server.app
+
+Environment variables:
+    ATARI_GAME: Game name to serve (default: "pong")
+    ATARI_OBS_TYPE: Observation type (default: "rgb")
+    ATARI_FULL_ACTION_SPACE: Use full action space (default: "false")
+    ATARI_MODE: Game mode (optional)
+    ATARI_DIFFICULTY: Game difficulty (optional)
+    ATARI_REPEAT_ACTION_PROB: Sticky action probability (default: "0.0")
+    ATARI_FRAMESKIP: Frameskip (default: "4")
+"""
+
+import os
+
+from openenv.core.env_server import create_app
+
+from ..models import AtariAction, AtariObservation
+from .atari_environment import AtariEnvironment
+
+# Get configuration from environment variables
+game_name = os.getenv("ATARI_GAME", "pong")
+obs_type = os.getenv("ATARI_OBS_TYPE", "rgb")
+full_action_space = os.getenv("ATARI_FULL_ACTION_SPACE", "false").lower() == "true"
+repeat_action_prob = float(os.getenv("ATARI_REPEAT_ACTION_PROB", "0.0"))
+frameskip = int(os.getenv("ATARI_FRAMESKIP", "4"))
+
+# Optional parameters
+mode = os.getenv("ATARI_MODE")
+difficulty = os.getenv("ATARI_DIFFICULTY")
+
+# Convert to int if specified
+mode = int(mode) if mode is not None else None
+difficulty = int(difficulty) if difficulty is not None else None
+
+
+# Factory function to create AtariEnvironment instances
+def create_atari_environment():
+    """Factory function that creates AtariEnvironment with config."""
+    return AtariEnvironment(
+        game_name=game_name,
+        obs_type=obs_type,
+        full_action_space=full_action_space,
+        mode=mode,
+        difficulty=difficulty,
+        repeat_action_probability=repeat_action_prob,
+        frameskip=frameskip,
+    )
+
+
+# Create the FastAPI app with web interface and README integration
+# Pass the factory function instead of an instance for WebSocket session support
+app = create_app(
+    create_atari_environment, AtariAction, AtariObservation, env_name="atari_env"
+)
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)

server/atari_environment.py

@@ -0,0 +1,246 @@
+# 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.
+
+"""
+Atari Environment Server Implementation.
+
+This module wraps ALE's ALEInterface and exposes it
+via the OpenEnv Environment interface.
+"""
+
+import uuid
+from typing import Any, Dict, Literal, Optional
+
+from openenv.core.env_server import Action, Environment, Observation
+
+from ..models import AtariAction, AtariObservation, AtariState
+
+# Import ALE
+try:
+    import numpy as np
+    from ale_py import ALEInterface, roms
+except ImportError as e:
+    raise ImportError(
+        "ALE (Arcade Learning Environment) is not installed. "
+        "Please install it with: pip install ale-py"
+    ) from e
+
+
+class AtariEnvironment(Environment):
+    """
+    Atari Environment wrapper for OpenEnv.
+
+    This environment wraps Atari 2600 games via the Arcade Learning Environment (ALE)
+    and provides a clean interface for RL training.
+
+    Supported games include: pong, breakout, space_invaders, and 100+ others.
+
+    Args:
+        game_name: Name of the Atari game (e.g., "pong", "breakout").
+        obs_type: Observation type - "rgb", "grayscale", or "ram".
+        full_action_space: Use full action space (18 actions) vs minimal.
+        mode: Game mode (if applicable).
+        difficulty: Game difficulty (if applicable).
+        repeat_action_probability: Sticky action probability (default 0.0).
+        frameskip: Number of frames to skip per action (default 4).
+
+    Example:
+        >>> env = AtariEnvironment("pong")
+        >>> obs = env.reset()
+        >>> print(obs.screen_shape)  # [210, 160, 3]
+        >>> obs = env.step(AtariAction(action_id=2))  # UP
+        >>> print(obs.reward, obs.done)
+    """
+
+    def __init__(
+        self,
+        game_name: str = "pong",
+        obs_type: Literal["rgb", "grayscale", "ram"] = "rgb",
+        full_action_space: bool = False,
+        mode: Optional[int] = None,
+        difficulty: Optional[int] = None,
+        repeat_action_probability: float = 0.0,
+        frameskip: int = 4,
+    ):
+        """Initialize Atari environment."""
+        super().__init__()
+
+        self.game_name = game_name
+        self.obs_type = obs_type
+        self.full_action_space = full_action_space
+        self.mode = mode
+        self.difficulty = difficulty
+        self.repeat_action_probability = repeat_action_probability
+        self.frameskip = frameskip
+
+        # Create ALE interface
+        self.ale = ALEInterface()
+
+        # Configure ALE
+        from ale_py import LoggerMode
+
+        self.ale.setLoggerMode(LoggerMode.Error)  # Error mode only
+        self.ale.setFloat("repeat_action_probability", repeat_action_probability)
+
+        # Load ROM
+        try:
+            rom_path = roms.get_rom_path(game_name)
+            self.ale.loadROM(rom_path)
+        except Exception as e:
+            raise ValueError(
+                f"Failed to load Atari game '{game_name}': {e}\n"
+                f"Available games can be found via: ale_py.roms.list_roms()"
+            ) from e
+
+        # Set mode and difficulty if specified
+        if mode is not None:
+            self.ale.setMode(mode)
+        if difficulty is not None:
+            self.ale.setDifficulty(difficulty)
+
+        # Get action set
+        if full_action_space:
+            self._action_set = self.ale.getLegalActionSet()
+        else:
+            self._action_set = self.ale.getMinimalActionSet()
+
+        # Get screen dimensions for observation space
+        self.screen_height, self.screen_width = self.ale.getScreenDims()
+        if obs_type == "rgb":
+            self.screen_shape = [self.screen_height, self.screen_width, 3]
+        elif obs_type == "grayscale":
+            self.screen_shape = [self.screen_height, self.screen_width]
+        elif obs_type == "ram":
+            self.screen_shape = [self.ale.getRAMSize()]
+        else:
+            raise ValueError(f"Invalid obs_type: {obs_type}")
+
+        # Initialize state
+        self._state = AtariState(
+            game_name=game_name,
+            obs_type=obs_type,
+            full_action_space=full_action_space,
+            mode=mode,
+            difficulty=difficulty,
+            repeat_action_probability=repeat_action_probability,
+            frameskip=frameskip,
+        )
+
+    def reset(self) -> Observation:
+        """
+        Reset the environment and return initial observation.
+
+        Returns:
+            Initial observation for the agent.
+        """
+        # Reset ALE
+        self.ale.reset_game()
+
+        # Reset state tracking
+        self._state.episode_id = str(uuid.uuid4())
+        self._state.step_count = 0
+
+        # Get initial observation
+        return self._make_observation()
+
+    def step(self, action: Action) -> Observation:
+        """
+        Execute agent's action and return resulting observation.
+
+        Args:
+            action: AtariAction containing the action_id to execute.
+
+        Returns:
+            Observation after action execution.
+
+        Raises:
+            ValueError: If action is not an AtariAction.
+        """
+        if not isinstance(action, AtariAction):
+            raise ValueError(f"Expected AtariAction, got {type(action)}")
+
+        # Validate action_id
+        if action.action_id < 0 or action.action_id >= len(self._action_set):
+            raise ValueError(
+                f"Invalid action_id: {action.action_id}. "
+                f"Valid range: [0, {len(self._action_set) - 1}]"
+            )
+
+        # Get actual ALE action
+        ale_action = self._action_set[action.action_id]
+
+        # Execute action with frameskip
+        total_reward = 0.0
+        for _ in range(self.frameskip):
+            total_reward += self.ale.act(ale_action)
+            if self.ale.game_over():
+                break
+
+        self._state.step_count += 1
+
+        # Get observation
+        obs = self._make_observation()
+        obs.reward = total_reward
+
+        return obs
+
+    @property
+    def state(self) -> AtariState:
+        """Get current environment state."""
+        return self._state
+
+    def _make_observation(self) -> AtariObservation:
+        """
+        Create an AtariObservation from current ALE state.
+
+        Returns:
+            AtariObservation for the agent.
+        """
+        # Get screen observation
+        if self.obs_type == "rgb":
+            screen = self.ale.getScreenRGB()
+        elif self.obs_type == "grayscale":
+            screen = self.ale.getScreenGrayscale()
+        elif self.obs_type == "ram":
+            screen = self.ale.getRAM()
+        else:
+            raise ValueError(f"Invalid obs_type: {self.obs_type}")
+
+        # Flatten screen for JSON serialization
+        # Handle both numpy arrays and lists
+        if hasattr(screen, "flatten"):
+            screen_flat = screen.flatten().tolist()
+        elif hasattr(screen, "tolist"):
+            screen_flat = screen.tolist()
+        else:
+            screen_flat = list(screen)
+
+        # Get game info
+        lives = self.ale.lives()
+        episode_frame_number = self.ale.getEpisodeFrameNumber()
+        frame_number = self.ale.getFrameNumber()
+        done = self.ale.game_over()
+
+        # Create legal actions list (indices into action_set)
+        legal_actions = list(range(len(self._action_set)))
+
+        # Create observation
+        obs = AtariObservation(
+            screen=screen_flat,
+            screen_shape=self.screen_shape,
+            legal_actions=legal_actions,
+            lives=lives,
+            episode_frame_number=episode_frame_number,
+            frame_number=frame_number,
+            done=done,
+            reward=0.0,  # Will be filled in by step()
+            metadata={
+                "game_name": self.game_name,
+                "action_meanings": [str(a) for a in self._action_set],
+            },
+        )
+
+        return obs

server/requirements.txt

@@ -0,0 +1,3 @@
+gymnasium>=0.29.0
+ale-py>=0.8.0
+numpy>=1.24.0

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/core/README.md

@@ -0,0 +1,212 @@
+# <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. 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.
+
+
+## Overview
+`openenv.core` provides the foundational building blocks for creating and interacting with containerized environments over HTTP. It enables you to build agent environments that can be deployed as Docker containers and accessed via a simple HTTP API.
+
+> ⚠️ **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.
+
+
+# OpenEnv Core
+
+Core components for OpenEnv - a framework for building HTTP-based agentic environments.
+
+## Features
+
+- **EnvClient**: Async-first client for interacting with remote environments
+- **SyncEnvClient**: Synchronous wrapper via `.sync()` for sync codebases
+- **HTTPEnvServer**: FastAPI-based server wrapper for exposing environments over HTTP/WebSocket
+- **Container Providers**: Pluggable architecture for running containers (Docker, Kubernetes, etc.)
+- **Type System**: Strongly-typed Action/Observation/State interfaces
+- **Web Interface**: Optional web UI for interacting with environments
+
+## Installation
+
+```bash
+pip install "openenv[core]"
+```
+
+For development:
+```bash
+pip install "openenv[core]"
+```
+
+## Quick Start
+
+### Creating an Environment Client
+
+EnvClient is **async by default**. Use `async with` and `await` for all operations:
+
+```python
+import asyncio
+from openenv.core import EnvClient, StepResult
+from dataclasses import dataclass
+from typing import Any
+
+@dataclass
+class MyAction:
+    text: str
+
+@dataclass
+class MyObservation:
+    response: str
+
+class MyEnvClient(EnvClient[MyAction, MyObservation, Any]):
+    def _step_payload(self, action: MyAction) -> dict:
+        return {"text": action.text}
+
+    def _parse_result(self, payload: dict) -> StepResult[MyObservation]:
+        obs_data = payload["observation"]
+        return StepResult(
+            observation=MyObservation(**obs_data),
+            reward=payload.get("reward"),
+            done=payload.get("done", False)
+        )
+
+    def _parse_state(self, payload: dict) -> Any:
+        return payload
+
+# Async usage (recommended)
+async def main():
+    client = await MyEnvClient.from_docker_image("my-env:latest")
+    async with client:
+        result = await client.reset()
+        step_result = await client.step(MyAction(text="hello"))
+
+asyncio.run(main())
+
+# Sync usage (via .sync() wrapper)
+with MyEnvClient(base_url="http://localhost:8000").sync() as client:
+    result = client.reset()
+    step_result = client.step(MyAction(text="hello"))
+```
+
+### Creating an Environment Server
+
+```python
+from openenv.core.env_server import Environment, HTTPEnvServer, create_app
+from dataclasses import dataclass
+
+@dataclass
+class MyAction:
+    text: str
+
+@dataclass
+class MyObservation:
+    response: str
+    reward: float = 0.0
+    done: bool = False
+
+class MyEnvironment(Environment):
+    def reset(self) -> MyObservation:
+        return MyObservation(response="Ready")
+
+    def step(self, action: MyAction) -> MyObservation:
+        return MyObservation(
+            response=f"Echo: {action.text}",
+            reward=1.0,
+            done=False
+        )
+
+# Create FastAPI app
+env = MyEnvironment()
+app = create_app(env, MyAction, MyObservation)
+
+# Run with: uvicorn module:app --host 0.0.0.0 --port 8000
+```
+
+## Container Providers
+
+OpenEnv Core supports multiple container providers:
+
+### Local Docker Provider
+
+```python
+from openenv.core.containers.runtime import LocalDockerProvider
+
+provider = LocalDockerProvider()
+base_url = provider.start_container("my-env:latest")
+provider.wait_for_ready(base_url)
+# Use environment...
+provider.stop_container()
+```
+
+### Kubernetes Provider (Coming Soon)
+
+```python
+from openenv.core.containers.runtime import KubernetesProvider
+
+provider = KubernetesProvider(namespace="envs")
+base_url = provider.start_container("my-env:latest")
+# Use environment...
+provider.stop_container()
+```
+
+
+## API Reference
+
+### EnvClient
+
+Async base class for environment clients. Key methods:
+
+- `async connect()`: Establish WebSocket connection
+- `async reset(**kwargs)`: Reset environment
+- `async step(action)`: Execute action
+- `async state()`: Get current state
+- `async close()`: Close connection and cleanup
+- `sync()`: Return a SyncEnvClient wrapper for synchronous usage
+
+Abstract methods to implement:
+- `_step_payload(action)`: Convert action to JSON
+- `_parse_result(payload)`: Parse response to StepResult
+- `_parse_state(payload)`: Parse state response
+
+### SyncEnvClient
+
+Synchronous wrapper around EnvClient. Use `client.sync()` to get one:
+
+```python
+sync_client = async_client.sync()
+with sync_client:
+    result = sync_client.reset()
+    result = sync_client.step(action)
+```
+
+### HTTPEnvServer
+
+Server wrapper with these methods:
+
+- `register_routes(app)`: Register endpoints on FastAPI app
+- `_deserialize_action(data)`: Convert JSON to Action
+- `_serialize_observation(obs)`: Convert Observation to JSON
+
+### Environment Interface
+
+Base interface for environment implementations:
+
+- `reset()`: Reset environment and return initial observation
+- `step(action)`: Execute action and return observation
+- `state`: Property returning current environment state
+
+## License
+
+This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please see the main OpenEnv repository for contribution guidelines.
+
+## Links
+
+- **Homepage**: https://github.com/meta-pytorch/OpenEnv
+- **Documentation**: https://github.com/meta-pytorch/OpenEnv/blob/main/README.md
+- **Bug Tracker**: https://github.com/meta-pytorch/OpenEnv/issues

src/core/__init__.py

@@ -6,14 +6,76 @@
 
 """Core components for agentic environments."""
 
-# Re-export main components from submodules for convenience
-from .env_server import *
-from .http_env_client import HTTPEnvClient
-from .types import StepResult
+from __future__ import annotations
 
-# Note: MCP module doesn't export anything yet
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+from . import env_server
+from .env_server import *  # noqa: F403
+
+if TYPE_CHECKING:
+    from .env_client import EnvClient
+    from .generic_client import GenericAction, GenericEnvClient
+    from .llm_client import (
+        AnthropicClient,
+        create_llm_client,
+        LLMClient,
+        LLMResponse,
+        OpenAIClient,
+        ToolCall,
+    )
+    from .mcp_client import MCPClientBase, MCPToolClient
+    from .sync_client import SyncEnvClient
 
 __all__ = [
-    "HTTPEnvClient",
-    "StepResult",
-]
+    "EnvClient",
+    "SyncEnvClient",
+    "GenericEnvClient",
+    "GenericAction",
+    "MCPClientBase",
+    "MCPToolClient",
+    "AnthropicClient",
+    "LLMClient",
+    "LLMResponse",
+    "OpenAIClient",
+    "ToolCall",
+    "create_llm_client",
+] + env_server.__all__  # type: ignore
+
+
+_LAZY_ATTRS = {
+    "EnvClient": (".env_client", "EnvClient"),
+    "SyncEnvClient": (".sync_client", "SyncEnvClient"),
+    "GenericEnvClient": (".generic_client", "GenericEnvClient"),
+    "GenericAction": (".generic_client", "GenericAction"),
+    "MCPClientBase": (".mcp_client", "MCPClientBase"),
+    "MCPToolClient": (".mcp_client", "MCPToolClient"),
+    "AnthropicClient": (".llm_client", "AnthropicClient"),
+    "LLMClient": (".llm_client", "LLMClient"),
+    "LLMResponse": (".llm_client", "LLMResponse"),
+    "OpenAIClient": (".llm_client", "OpenAIClient"),
+    "ToolCall": (".llm_client", "ToolCall"),
+    "create_llm_client": (".llm_client", "create_llm_client"),
+}
+
+
+def __getattr__(name: str):
+    if name in _LAZY_ATTRS:
+        module_path, attr_name = _LAZY_ATTRS[name]
+        module = import_module(module_path, __name__)
+        value = getattr(module, attr_name)
+        globals()[name] = value
+        return value
+
+    try:
+        value = getattr(env_server, name)
+    except AttributeError as exc:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from exc
+
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals().keys()) | set(__all__))

src/core/client_types.py

@@ -0,0 +1,23 @@
+# Type definitions for EnvTorch
+from dataclasses import dataclass
+from typing import Generic, Optional, TypeVar
+
+# Generic type for observations
+ObsT = TypeVar("ObsT")
+StateT = TypeVar("StateT")
+
+
+@dataclass
+class StepResult(Generic[ObsT]):
+    """
+    Represents the result of one environment step.
+
+    Attributes:
+        observation: The environment's observation after the action.
+        reward: Scalar reward for this step (optional).
+        done: Whether the episode is finished.
+    """
+
+    observation: ObsT
+    reward: Optional[float] = None
+    done: bool = False

src/core/containers/__init__.py

@@ -4,4 +4,4 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
-"""Container management for environment servers."""
+"""Container management for environment servers."""

src/core/containers/images/Dockerfile

@@ -8,30 +8,47 @@
 # OpenEnv Base Image
 #
 # This is the standard base image for all OpenEnv environment servers.
-# It includes the minimal dependencies needed to run HTTP environment servers.
+# It includes the minimal dependencies needed to run HTTP environment servers
+# and uv for fast dependency management.
 #
-# Build: docker build -t openenv-base:latest -f src/core/containers/images/Dockerfile .
-# Tag:   docker tag openenv-base:latest openenv-base:0.1.0
+# Build from repo root: docker build -t openenv-base:latest -f src/openenv/core/containers/images/Dockerfile .
+# Tag:   docker tag openenv-base:latest openenv-base:0.2.0
 #
 
+FROM ghcr.io/astral-sh/uv:0.5.27-python3.11-bookworm-slim AS builder
+
+# Set working directory
+WORKDIR /app
+
+# Copy core pyproject.toml and lockfile for dependency installation
+COPY pyproject.toml uv.lock* ./
+
+# Install core dependencies using uv with cache mount
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv pip install --system -r pyproject.toml
+
+# Final runtime stage
 FROM python:3.11-slim
 
 # Set metadata
 LABEL maintainer="OpenEnv Team"
-LABEL description="Base image for OpenEnv based environment servers"
-LABEL version="0.1.0"
+LABEL description="Base image for OpenEnv based environment servers with uv"
+LABEL version="0.2.0"
 
 # Install system dependencies
 RUN apt-get update && apt-get install -y --no-install-recommends \
     curl \
+    ca-certificates \
     && rm -rf /var/lib/apt/lists/*
 
-# Install Python dependencies that all environments need
-RUN pip install --no-cache-dir \
-    fastapi>=0.104.0 \
-    "uvicorn[standard]>=0.24.0" \
-    requests>=2.25.0 \
-    wsproto>=1.0.0
+# Copy uv from builder
+COPY --from=builder /usr/local/bin/uv /usr/local/bin/uvx /usr/local/bin/
+
+# Copy installed Python packages from builder
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+
+# Copy console scripts installed by pip (uvicorn, fastapi, etc.)
+COPY --from=builder /usr/local/bin/uvicorn /usr/local/bin/fastapi /usr/local/bin/
 
 # Set working directory
 WORKDIR /app
@@ -39,6 +56,7 @@ WORKDIR /app
 # Default environment variables
 ENV PYTHONPATH=/app/src
 ENV PYTHONUNBUFFERED=1
+ENV UV_SYSTEM_PYTHON=1
 
 # Default expose port (can be overridden)
 EXPOSE 8000

src/core/containers/images/README.md

@@ -36,7 +36,7 @@ Total: 465 MB (base shared, minimal duplication)
 
 ```bash
 # From project root
-docker build -t openenv-base:latest -f src/core/containers/images/Dockerfile .
+docker build -t openenv-base:latest -f src/openenv/core/containers/images/Dockerfile .
 ```
 
 ## Usage in Environment Dockerfiles
@@ -47,8 +47,8 @@ Each environment Dockerfile should start with:
 FROM openenv-base:latest
 
 # Copy only environment-specific files
-COPY src/core/ /app/src/core/
-COPY src/envs/my_env/ /app/src/envs/my_env/
+COPY src/openenv/core/ /app/src/openenv/core/
+COPY envs/my_env/ /app/envs/my_env/
 
 # Run the server
 CMD ["uvicorn", "envs.my_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]
@@ -66,10 +66,10 @@ CMD ["uvicorn", "envs.my_env.server.app:app", "--host", "0.0.0.0", "--port", "80
 
 ```bash
 # Step 1: Build base image (do this once)
-docker build -t openenv-base:latest -f src/core/containers/images/Dockerfile .
+docker build -t openenv-base:latest -f src/openenv/core/containers/images/Dockerfile .
 
 # Step 2: Build echo environment (uses base)
-docker build -t echo-env:latest -f src/envs/echo_env/server/Dockerfile .
+docker build -t echo-env:latest -f envs/echo_env/server/Dockerfile .
 
 # Step 3: Run echo environment
 docker run -p 8000:8000 echo-env:latest
@@ -79,14 +79,14 @@ docker run -p 8000:8000 echo-env:latest
 
 When dependencies need updating:
 
-1. Update `src/core/containers/images/Dockerfile`
+1. Update `src/openenv/core/containers/images/Dockerfile`
 2. Rebuild base image
 3. Rebuild all environment images (they'll use new base)
 
 ```bash
 # Update base
-docker build -t openenv-base:latest -f src/core/containers/images/Dockerfile .
+docker build -t openenv-base:latest -f src/openenv/core/containers/images/Dockerfile .
 
 # Rebuild environments (they automatically use new base)
-docker build -t echo-env:latest -f src/envs/echo_env/server/Dockerfile .
+docker build -t echo-env:latest -f envs/echo_env/server/Dockerfile .
 ```

src/core/containers/runtime/__init__.py

@@ -6,10 +6,20 @@
 
 """Container runtime providers."""
 
-from .providers import ContainerProvider, KubernetesProvider, LocalDockerProvider
+from .providers import (
+    ContainerProvider,
+    DockerSwarmProvider,
+    KubernetesProvider,
+    LocalDockerProvider,
+    RuntimeProvider,
+)
+from .uv_provider import UVProvider
 
 __all__ = [
     "ContainerProvider",
+    "DockerSwarmProvider",
     "LocalDockerProvider",
     "KubernetesProvider",
-]
+    "RuntimeProvider",
+    "UVProvider",
+]

src/core/containers/runtime/daytona_provider.py

@@ -0,0 +1,572 @@
+# 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.
+
+"""
+Daytona container provider for running OpenEnv environments in Daytona cloud sandboxes.
+
+Requires the ``daytona`` SDK: ``pip install daytona>=0.10``
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import time
+from typing import Any, Callable, Dict, Optional
+
+import yaml
+
+from .providers import ContainerProvider
+
+
+class DaytonaProvider(ContainerProvider):
+    """
+    Container provider that runs environments in Daytona cloud sandboxes.
+
+    Example:
+        >>> provider = DaytonaProvider(api_key="your-key")
+        >>> image = DaytonaProvider.image_from_dockerfile("envs/echo_env/server/Dockerfile")
+        >>> base_url = provider.start_container(image)
+        >>> provider.wait_for_ready(base_url)
+        >>> provider.stop_container()
+    """
+
+    _dockerfile_registry: Dict[str, Dict[str, Any]] = {}
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        public: bool = False,
+        resources: Optional[Any] = None,
+        auto_stop_interval: int = 15,
+        target: Optional[str] = None,
+        on_snapshot_create_logs: Optional[Callable[[str], None]] = None,
+        cmd: Optional[str] = None,
+        create_timeout: float = 300,
+    ):
+        """
+        Args:
+            api_key: Daytona API key. Falls back to ``DAYTONA_API_KEY`` env var.
+            public: If True, the sandbox preview is publicly accessible.
+            resources: Optional ``daytona.Resources`` instance for CPU/memory.
+            auto_stop_interval: Minutes of inactivity before auto-stop (0 disables).
+            target: Daytona target region (e.g. "us").
+            on_snapshot_create_logs: Callback for snapshot build log lines.
+            cmd: Shell command to start the server inside the sandbox.
+            create_timeout: Seconds to wait for sandbox creation (default 300).
+                Heavy images (e.g. with Playwright/Chromium) may need more.
+        """
+        from daytona import Daytona, DaytonaConfig
+
+        config_kwargs: Dict[str, Any] = {}
+        resolved_key = api_key or os.environ.get("DAYTONA_API_KEY")
+        if resolved_key:
+            config_kwargs["api_key"] = resolved_key
+        if target:
+            config_kwargs["target"] = target
+
+        self._daytona = Daytona(DaytonaConfig(**config_kwargs))
+        self._public = public
+        self._resources = resources
+        self._auto_stop_interval = auto_stop_interval
+        self._on_snapshot_create_logs = on_snapshot_create_logs
+        self._cmd = cmd
+        self._create_timeout = create_timeout
+        self._sandbox: Any = None
+        self._preview_url: Optional[str] = None
+
+    def _discover_server_cmd(self, sandbox: Any, port: int = 8000) -> str:
+        """Discover the server command from ``openenv.yaml`` inside *sandbox*.
+
+        Finds the file, reads the ``app`` field, and constructs a command
+        of the form ``cd <env_root> && python -m uvicorn <app> --host 0.0.0.0 --port <port>``.
+
+        Raises:
+            ValueError: If ``openenv.yaml`` is not found or lacks an ``app`` field.
+        """
+        yaml_path = self._find_openenv_yaml(sandbox)
+        if yaml_path is None:
+            raise ValueError(
+                "Could not find openenv.yaml inside the sandbox. "
+                "Pass an explicit cmd= to DaytonaProvider or start_container()."
+            )
+
+        cat_resp = sandbox.process.exec(f"cat {shlex.quote(yaml_path)}", timeout=10)
+        content = cat_resp.result if hasattr(cat_resp, "result") else str(cat_resp)
+        app = self._parse_app_field(content)
+        if app is None:
+            raise ValueError(
+                f"openenv.yaml at {yaml_path} does not contain an 'app' field. "
+                "Pass an explicit cmd= to DaytonaProvider or start_container()."
+            )
+
+        # The directory containing openenv.yaml is the env root
+        env_root = yaml_path.rsplit("/", 1)[0]
+        return (
+            f"cd {shlex.quote(env_root)} && "
+            f"python -m uvicorn {shlex.quote(app)} --host 0.0.0.0 --port {port}"
+        )
+
+    def _find_openenv_yaml(self, sandbox: Any) -> Optional[str]:
+        """Locate ``openenv.yaml`` inside the sandbox.
+
+        Tries the modern layout path ``/app/env/openenv.yaml`` first,
+        then falls back to a ``find`` command for the old layout.
+        """
+        # Fast path: modern Dockerfile layout
+        resp = sandbox.process.exec(
+            "test -f /app/env/openenv.yaml && echo found", timeout=10
+        )
+        out = resp.result if hasattr(resp, "result") else str(resp)
+        if "found" in (out or ""):
+            return "/app/env/openenv.yaml"
+
+        # Fallback: search for it (redirect stderr so error messages
+        # like "No such file or directory" don't get mistaken for paths).
+        resp = sandbox.process.exec(
+            "find /app -maxdepth 4 -name openenv.yaml -print -quit 2>/dev/null",
+            timeout=10,
+        )
+        path = (resp.result if hasattr(resp, "result") else str(resp) or "").strip()
+        if path and path.startswith("/"):
+            return path
+
+        return None
+
+    @staticmethod
+    def _parse_app_field(yaml_content: str) -> Optional[str]:
+        """Extract the ``app`` value from raw openenv.yaml content.
+
+        Uses PyYAML to handle comments, quotes, and nested keys correctly.
+        """
+        try:
+            data = yaml.safe_load(yaml_content) or {}
+        except Exception:
+            return None
+
+        if not isinstance(data, dict):
+            return None
+
+        value = data.get("app")
+        if isinstance(value, str):
+            value = value.strip()
+            return value if value else None
+        return None
+
+    @staticmethod
+    def _parse_dockerfile_cmd(dockerfile_content: str) -> Optional[str]:
+        """Extract the server command from the last ``CMD`` in a Dockerfile.
+
+        Handles exec form (``CMD ["prog", "arg"]``) and shell form
+        (``CMD prog arg``).  When a Dockerfile has multiple ``CMD``
+        instructions (e.g. multi-stage builds), the last one wins - same
+        semantics as Docker itself.  Lines where ``CMD`` appears inside a
+        comment are ignored.
+
+        Returns:
+            The command as a single string, or ``None`` if no ``CMD`` found.
+        """
+        import re
+
+        last_cmd: Optional[str] = None
+        for line in dockerfile_content.splitlines():
+            stripped = line.strip()
+            # Skip comments
+            if stripped.startswith("#"):
+                continue
+            match = re.match(r"CMD\s+(.+)", stripped, flags=re.IGNORECASE)
+            if match:
+                last_cmd = match.group(1).strip()
+
+        if last_cmd is None:
+            return None
+
+        # Exec form: CMD ["executable", "param1", ...]
+        if last_cmd.startswith("["):
+            try:
+                parts = json.loads(last_cmd)
+                if isinstance(parts, list) and all(isinstance(p, str) for p in parts):
+                    return " ".join(parts)
+            except (json.JSONDecodeError, TypeError):
+                pass
+
+        # Shell form: CMD executable param1 ...
+        return last_cmd if last_cmd else None
+
+    @staticmethod
+    def strip_buildkit_syntax(dockerfile_content: str) -> str:
+        """Remove BuildKit ``--mount=...`` flags from ``RUN`` instructions.
+
+        Handles single-line flags, multi-line continuations, and multiple
+        ``--mount`` flags spread across continuation lines. Only leading
+        ``--mount`` flags are removed (before the actual command starts).
+
+        Daytona's ``Image.from_dockerfile`` does not support BuildKit
+        ``--mount`` syntax.  This helper strips the flags so that standard
+        Dockerfiles (like the ones generated by ``openenv build``) can
+        be used directly.
+        """
+        import re
+
+        def strip_leading_mounts(text: str) -> str:
+            remaining = text
+            while True:
+                match = re.match(r"\s*--mount=\S+\s*", remaining)
+                if not match:
+                    return remaining
+                remaining = remaining[match.end() :]
+
+        lines = dockerfile_content.split("\n")
+        result: list[str] = []
+        in_run = False
+        in_mount_prefix = False
+
+        for line in lines:
+            line_out = line
+            run_start = False
+            if re.match(r"\s*RUN(\s+|$)", line, flags=re.IGNORECASE):
+                in_run = True
+                in_mount_prefix = True
+                run_start = True
+
+            if in_run and in_mount_prefix:
+                original_ends_with_slash = line_out.rstrip().endswith("\\")
+                if run_start:
+                    match = re.match(r"(\s*RUN\s+)(.*)$", line_out, flags=re.IGNORECASE)
+                    if match:
+                        run_prefix, remainder = match.group(1), match.group(2)
+                    else:
+                        run_prefix, remainder = line_out, ""
+                    new_remainder = strip_leading_mounts(remainder)
+                    line_out = run_prefix + new_remainder
+                    content_for_check = new_remainder
+                else:
+                    new_remainder = strip_leading_mounts(line_out)
+                    line_out = new_remainder
+                    content_for_check = new_remainder
+
+                if original_ends_with_slash and not line_out.rstrip().endswith("\\"):
+                    line_out = line_out.rstrip() + " \\"
+
+                if content_for_check.strip() not in ("", "\\"):
+                    in_mount_prefix = False
+
+            if in_run and not line_out.rstrip().endswith("\\"):
+                in_run = False
+                in_mount_prefix = False
+
+            result.append(line_out)
+
+        return "\n".join(result)
+
+    @classmethod
+    def image_from_dockerfile(
+        cls,
+        dockerfile_path: str,
+        context_dir: str | None = None,
+    ) -> str:
+        """Validate a Dockerfile and return a ``dockerfile:`` URI for
+        :meth:`start_container`.
+
+        Eagerly validates the Dockerfile (existence, COPY sources,
+        BuildKit stripping) and stores the processed content in an
+        internal registry.  The actual ``daytona.Image`` is created
+        later inside ``start_container``.
+
+        Args:
+            dockerfile_path: Path to the Dockerfile on disk.
+            context_dir: Build context directory.  Defaults to the
+                Dockerfile's grandparent directory, matching the
+                ``openenv init`` convention where Dockerfiles live in
+                ``<env>/server/Dockerfile`` and the build context is
+                ``<env>/``.  Pass explicitly for non-standard layouts
+                (e.g. ``context_dir="."`` for repo-root contexts).
+
+        Returns:
+            A ``"dockerfile:<abs_path>"`` string to pass to
+            ``start_container``.
+
+        Raises:
+            FileNotFoundError: If *dockerfile_path* does not exist.
+            ValueError: If *context_dir* is given but does not exist,
+                or if COPY sources in the Dockerfile cannot be found
+                under the resolved context directory.
+        """
+        import pathlib
+        import re
+
+        src = pathlib.Path(dockerfile_path).resolve()
+        if not src.is_file():
+            raise FileNotFoundError(f"Dockerfile not found: {dockerfile_path}")
+
+        if context_dir is not None:
+            ctx = pathlib.Path(context_dir)
+            if not ctx.is_dir():
+                raise ValueError(f"context_dir does not exist: {context_dir}")
+        else:
+            # Default: grandparent of the Dockerfile, matching the
+            # openenv init layout (<env>/server/Dockerfile -> <env>/).
+            ctx = src.parent.parent
+
+        content = src.read_text()
+        stripped = cls.strip_buildkit_syntax(content)
+
+        # Validate that COPY sources exist under the context directory.
+        # This catches mismatches early (e.g. a Dockerfile expecting repo
+        # root as context when we defaulted to the env directory).
+        for line in stripped.splitlines():
+            m = re.match(r"^\s*COPY\s+(?!--from=)(\S+)\s+", line, re.IGNORECASE)
+            if not m:
+                continue
+            copy_src = m.group(1)
+            if copy_src.startswith("/"):
+                continue
+            resolved = ctx / copy_src
+            if not resolved.exists() and not any(ctx.glob(copy_src)):
+                raise ValueError(
+                    f"Dockerfile COPY source '{copy_src}' not found "
+                    f"under context_dir '{ctx}'. This Dockerfile may "
+                    f"expect a different build context (e.g. the repo "
+                    f"root). Pass context_dir explicitly."
+                )
+
+        # Parse CMD from the original Dockerfile so start_container can
+        # use it as a fallback when openenv.yaml is unavailable.
+        parsed_cmd = cls._parse_dockerfile_cmd(content)
+
+        cls._dockerfile_registry[str(src)] = {
+            "stripped_content": stripped,
+            "context_dir": str(ctx),
+            "server_cmd": parsed_cmd,
+        }
+
+        return f"dockerfile:{src}"
+
+    def start_container(
+        self,
+        image: str,
+        port: Optional[int] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> str:
+        """
+        Create a Daytona sandbox from a Docker image or snapshot.
+
+        Daytona does not execute the image's CMD (known bug — ENTRYPOINT
+        runs, CMD does not).  The server command is resolved in order:
+
+        1. Explicit ``cmd`` passed to the constructor.
+        2. ``cmd`` key in ``**kwargs`` (popped before forwarding).
+        3. Auto-discovered from ``openenv.yaml`` inside the sandbox.
+        4. ``CMD`` parsed from the Dockerfile (when *image* came from
+           ``image_from_dockerfile``).
+
+        Args:
+            image: Docker image name (e.g. ``"echo-env:latest"``),
+                   ``"snapshot:<name>"`` to create from a pre-built snapshot,
+                   or ``"dockerfile:<path>"`` returned by
+                   :meth:`image_from_dockerfile`.
+            port: Must be ``None`` or ``8000``. Daytona exposes port 8000
+                  via its preview proxy; other ports raise ``ValueError``.
+            env_vars: Environment variables forwarded to the sandbox.
+            **kwargs: ``cmd`` (str) to override the server command;
+                remaining kwargs passed through to ``Daytona.create()``.
+
+        Returns:
+            HTTPS preview URL for the sandbox (base_url).
+        """
+        if port is not None and port != 8000:
+            raise ValueError(
+                f"DaytonaProvider only supports port 8000 (got {port}). "
+                "The Daytona preview proxy routes to port 8000 inside the sandbox."
+            )
+
+        # Resolve the server command (may be None; discovery happens after
+        # sandbox creation when we can inspect the filesystem).
+        cmd = kwargs.pop("cmd", None) or self._cmd
+
+        # CMD parsed from Dockerfile (populated for "dockerfile:" images).
+        parsed_cmd: Optional[str] = None
+
+        # Build creation params
+        create_kwargs: Dict[str, Any] = {}
+        if env_vars:
+            create_kwargs["env_vars"] = env_vars
+        if self._public:
+            create_kwargs["public"] = True
+        if self._auto_stop_interval != 15:
+            create_kwargs["auto_stop_interval"] = self._auto_stop_interval
+
+        if image.startswith("snapshot:"):
+            from daytona import CreateSandboxFromSnapshotParams
+
+            snapshot_name = image[len("snapshot:") :]
+            params = CreateSandboxFromSnapshotParams(
+                snapshot=snapshot_name, **create_kwargs
+            )
+        elif image.startswith("dockerfile:"):
+            from daytona import CreateSandboxFromImageParams, Image
+
+            dockerfile_path = image[len("dockerfile:") :]
+            meta = self._dockerfile_registry.get(dockerfile_path)
+            if meta is None:
+                raise ValueError(
+                    f"No registered Dockerfile metadata for {dockerfile_path}. "
+                    "Call DaytonaProvider.image_from_dockerfile() first."
+                )
+
+            parsed_cmd = meta.get("server_cmd")
+
+            # Build the daytona Image from the pre-stripped content.
+            import pathlib
+            import uuid
+
+            ctx = pathlib.Path(meta["context_dir"])
+            tmp_name = f".daytona-{uuid.uuid4().hex[:8]}.dockerfile"
+            tmp_path = ctx / tmp_name
+            try:
+                tmp_path.write_text(meta["stripped_content"])
+                daytona_image = Image.from_dockerfile(str(tmp_path))
+            finally:
+                tmp_path.unlink(missing_ok=True)
+
+            img_kwargs: Dict[str, Any] = {
+                "image": daytona_image,
+                **create_kwargs,
+            }
+            if self._resources is not None:
+                img_kwargs["resources"] = self._resources
+            params = CreateSandboxFromImageParams(**img_kwargs)
+        else:
+            from daytona import CreateSandboxFromImageParams
+
+            img_kwargs = {"image": image, **create_kwargs}
+            if self._resources is not None:
+                img_kwargs["resources"] = self._resources
+            params = CreateSandboxFromImageParams(**img_kwargs)
+
+        # Create sandbox
+        extra: Dict[str, Any] = dict(kwargs)
+        if self._on_snapshot_create_logs is not None:
+            extra["on_snapshot_create_logs"] = self._on_snapshot_create_logs
+
+        self._sandbox = self._daytona.create(
+            params, timeout=self._create_timeout, **extra
+        )
+
+        try:
+            # Discover server command from openenv.yaml if not explicitly set.
+            if cmd is None:
+                try:
+                    cmd = self._discover_server_cmd(self._sandbox)
+                except ValueError:
+                    # Fall back to CMD parsed from Dockerfile (if available).
+                    if parsed_cmd:
+                        cmd = parsed_cmd
+                    else:
+                        raise
+
+            # Wrap in bash -c so compound commands (cd ... && uvicorn ...)
+            # are handled correctly by nohup.  Write PID so we can check
+            # if the process crashed later in wait_for_ready().
+            escaped_cmd = shlex.quote(cmd)
+            self._sandbox.process.exec(
+                f"nohup bash -c {escaped_cmd} > /tmp/openenv-server.log 2>&1 &"
+                " echo $! > /tmp/openenv-server.pid",
+                timeout=10,
+            )
+
+            # Get a signed preview URL for port 8000.  The token is
+            # embedded in the URL itself so no extra headers are needed.
+            signed = self._sandbox.create_signed_preview_url(
+                8000, expires_in_seconds=86400
+            )
+            self._preview_url = signed.url
+        except Exception:
+            self.stop_container()
+            raise
+
+        return self._preview_url
+
+    def refresh_preview_url(self) -> str:
+        """Get a fresh signed preview URL (valid for 24h).
+
+        Daytona signed URLs expire after at most 24 hours.  Call this to
+        get a new one for long-running sessions.  The returned URL points
+        to the same sandbox — clients will need to reconnect using it.
+        """
+        if self._sandbox is None:
+            raise RuntimeError("No active sandbox to refresh URL for.")
+        signed = self._sandbox.create_signed_preview_url(8000, expires_in_seconds=86400)
+        self._preview_url = signed.url
+        return self._preview_url
+
+    def stop_container(self) -> None:
+        """Delete the Daytona sandbox."""
+        if self._sandbox is None:
+            return
+
+        try:
+            self._daytona.delete(self._sandbox)
+        finally:
+            self._sandbox = None
+            self._preview_url = None
+
+    def wait_for_ready(self, base_url: str, timeout_s: float = 120.0) -> None:
+        """
+        Poll the /health endpoint until the sandbox is ready.
+
+        Uses a longer default timeout (120s) than Docker providers because
+        Daytona sandboxes may have cold-start latency.
+
+        Args:
+            base_url: Preview URL returned by ``start_container()``.
+            timeout_s: Maximum seconds to wait.
+
+        Raises:
+            TimeoutError: If the sandbox doesn't become ready in time.
+            RuntimeError: If the server process died (detected via PID check).
+        """
+        import requests
+
+        health_url = f"{base_url}/health"
+
+        deadline = time.time() + timeout_s
+        while time.time() < deadline:
+            try:
+                response = requests.get(health_url, timeout=5.0)
+                if response.status_code == 200:
+                    return
+            except requests.RequestException:
+                pass
+
+            # Early exit: if the server process died, raise immediately
+            # instead of waiting for the full health-check timeout.
+            if self._sandbox is not None:
+                resp = self._sandbox.process.exec(
+                    "kill -0 $(cat /tmp/openenv-server.pid) 2>/dev/null"
+                    " && echo RUNNING || echo DEAD",
+                    timeout=10,
+                )
+                out = resp.result if hasattr(resp, "result") else str(resp)
+                if "DEAD" in (out or ""):
+                    log_resp = self._sandbox.process.exec(
+                        "cat /tmp/openenv-server.log 2>/dev/null", timeout=10
+                    )
+                    log = (
+                        log_resp.result
+                        if hasattr(log_resp, "result")
+                        else str(log_resp)
+                    )
+                    raise RuntimeError(f"Server process died.\nLog:\n{log}")
+
+            time.sleep(1.0)
+
+        raise TimeoutError(
+            f"Daytona sandbox at {base_url} did not become ready within {timeout_s}s"
+        )

src/core/containers/runtime/providers.py

@@ -8,13 +8,13 @@
 Container provider abstractions for running environment servers.
 
 This module provides a pluggable architecture for different container providers
-(local Docker, Kubernetes, cloud providers, etc.) to be used with HTTPEnvClient.
+(local Docker, Kubernetes, cloud providers, etc.) to be used with EnvClient.
 """
 
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, Sequence
 
 
 class ContainerProvider(ABC):
@@ -118,7 +118,11 @@ class LocalDockerProvider(ContainerProvider):
                 capture_output=True,
                 timeout=5,
             )
-        except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+        except (
+            subprocess.CalledProcessError,
+            FileNotFoundError,
+            subprocess.TimeoutExpired,
+        ):
             raise RuntimeError(
                 "Docker is not available. Please install Docker Desktop or Docker Engine."
             )
@@ -154,10 +158,13 @@ class LocalDockerProvider(ContainerProvider):
 
         # Build docker run command
         cmd = [
-            "docker", "run",
+            "docker",
+            "run",
             "-d",  # Detached
-            "--name", self._container_name,
-            "-p", f"{port}:8000",  # Map port
+            "--name",
+            self._container_name,
+            "-p",
+            f"{port}:8000",  # Map port
         ]
 
         # Add environment variables
@@ -169,8 +176,12 @@ class LocalDockerProvider(ContainerProvider):
         cmd.append(image)
 
         # Run container
-        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
-        self._container_id = result.stdout.strip()
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+            self._container_id = result.stdout.strip()
+        except subprocess.CalledProcessError as e:
+            error_msg = f"Failed to start Docker container.\nCommand: {' '.join(cmd)}\nExit code: {e.returncode}\nStderr: {e.stderr}\nStdout: {e.stdout}"
+            raise RuntimeError(error_msg) from e
 
         # Wait a moment for container to start
         time.sleep(1)
@@ -222,14 +233,18 @@ class LocalDockerProvider(ContainerProvider):
             TimeoutError: If container doesn't become ready
         """
         import time
+
         import requests
 
         start_time = time.time()
         health_url = f"{base_url}/health"
 
+        # Bypass proxy for localhost to avoid proxy issues
+        proxies = {"http": None, "https": None}
+
         while time.time() - start_time < timeout_s:
             try:
-                response = requests.get(health_url, timeout=2.0)
+                response = requests.get(health_url, timeout=2.0, proxies=proxies)
                 if response.status_code == 200:
                     return
             except requests.RequestException:
@@ -273,6 +288,308 @@ class LocalDockerProvider(ContainerProvider):
         return f"{clean_image}-{timestamp}"
 
 
+class DockerSwarmProvider(ContainerProvider):
+    """
+    Container provider that uses Docker Swarm services for local concurrency.
+
+    This provider creates a replicated Swarm service backed by the local Docker
+    engine. The built-in load-balancer fans requests across the replicas,
+    allowing multiple container instances to run concurrently on the developer
+    workstation (mirroring the workflow described in the Docker stack docs).
+    """
+
+    def __init__(
+        self,
+        *,
+        auto_init_swarm: bool = True,
+        overlay_network: Optional[str] = None,
+    ):
+        """
+        Args:
+            auto_init_swarm: Whether to call ``docker swarm init`` when Swarm
+                is not active. Otherwise, user must manually initialize Swarm.
+            overlay_network: Optional overlay network name for the service.
+                When provided, the network is created with
+                ``docker network create --driver overlay --attachable`` if it
+                does not already exist.
+        """
+        self._service_name: Optional[str] = None
+        self._service_id: Optional[str] = None
+        self._published_port: Optional[int] = None
+        self._overlay_network = overlay_network
+        self._auto_init_swarm = auto_init_swarm
+
+        self._ensure_docker_available()
+        self._ensure_swarm_initialized()
+        if self._overlay_network:
+            self._ensure_overlay_network(self._overlay_network)
+
+    def start_container(
+        self,
+        image: str,
+        port: Optional[int] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> str:
+        """
+        Start (or scale) a Swarm service for the given image.
+
+        Supported kwargs:
+            replicas (int): Number of container replicas (default: 2).
+            cpu_limit (float | str): CPU limit passed to ``--limit-cpu``.
+            memory_limit (str): Memory limit passed to ``--limit-memory``.
+            constraints (Sequence[str]): Placement constraints.
+            labels (Dict[str, str]): Service labels.
+            command (Sequence[str] | str): Override container command.
+        """
+        import shlex
+        import subprocess
+        import time
+
+        allowed_kwargs = {
+            "replicas",
+            "cpu_limit",
+            "memory_limit",
+            "constraints",
+            "labels",
+            "command",
+        }
+        unknown = set(kwargs) - allowed_kwargs
+        if unknown:
+            raise ValueError(f"Unsupported kwargs for DockerSwarmProvider: {unknown}")
+
+        replicas = int(kwargs.get("replicas", 2))
+        cpu_limit = kwargs.get("cpu_limit")
+        memory_limit = kwargs.get("memory_limit")
+        constraints: Optional[Sequence[str]] = kwargs.get("constraints")
+        labels: Optional[Dict[str, str]] = kwargs.get("labels")
+        command_override = kwargs.get("command")
+
+        if port is None:
+            port = self._find_available_port()
+
+        self._service_name = self._generate_service_name(image)
+        self._published_port = port
+
+        cmd = [
+            "docker",
+            "service",
+            "create",
+            "--detach",
+            "--name",
+            self._service_name,
+            "--replicas",
+            str(max(1, replicas)),
+            "--publish",
+            f"{port}:8000",
+        ]
+
+        if self._overlay_network:
+            cmd.extend(["--network", self._overlay_network])
+
+        if env_vars:
+            for key, value in env_vars.items():
+                cmd.extend(["--env", f"{key}={value}"])
+
+        if cpu_limit is not None:
+            cmd.extend(["--limit-cpu", str(cpu_limit)])
+
+        if memory_limit is not None:
+            cmd.extend(["--limit-memory", str(memory_limit)])
+
+        if constraints:
+            for constraint in constraints:
+                cmd.extend(["--constraint", constraint])
+
+        if labels:
+            for key, value in labels.items():
+                cmd.extend(["--label", f"{key}={value}"])
+
+        cmd.append(image)
+
+        if command_override:
+            if isinstance(command_override, str):
+                cmd.extend(shlex.split(command_override))
+            else:
+                cmd.extend(command_override)
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            self._service_id = result.stdout.strip()
+        except subprocess.CalledProcessError as e:
+            error_msg = (
+                "Failed to start Docker Swarm service.\n"
+                f"Command: {' '.join(cmd)}\n"
+                f"Exit code: {e.returncode}\n"
+                f"Stdout: {e.stdout}\n"
+                f"Stderr: {e.stderr}"
+            )
+            raise RuntimeError(error_msg) from e
+
+        # Give Swarm a brief moment to schedule the tasks.
+        time.sleep(1.0)
+
+        return f"http://localhost:{port}"
+
+    def stop_container(self) -> None:
+        """
+        Remove the Swarm service (and keep the Swarm manager running).
+        """
+        if not self._service_name:
+            return
+
+        import subprocess
+
+        try:
+            subprocess.run(
+                ["docker", "service", "rm", self._service_name],
+                capture_output=True,
+                check=True,
+                timeout=10,
+            )
+        except subprocess.CalledProcessError:
+            # Service may already be gone; ignore.
+            pass
+        finally:
+            self._service_name = None
+            self._service_id = None
+            self._published_port = None
+
+    def wait_for_ready(self, base_url: str, timeout_s: float = 30.0) -> None:
+        """
+        Wait for at least one replica to become healthy by polling /health.
+
+        Note: With Swarm's load balancer, requests round-robin across replicas,
+        so this only verifies that at least one replica is responding. Some
+        replicas may still be starting when this returns.
+        """
+        import time
+
+        import requests
+
+        deadline = time.time() + timeout_s
+        health_url = f"{base_url}/health"
+
+        # Bypass proxy for localhost to avoid proxy issues
+        proxies = {"http": None, "https": None}
+
+        while time.time() < deadline:
+            try:
+                response = requests.get(health_url, timeout=2.0, proxies=proxies)
+                if response.status_code == 200:
+                    return
+            except requests.RequestException:
+                pass
+
+            time.sleep(0.5)
+
+        raise TimeoutError(
+            f"Swarm service at {base_url} did not become ready within {timeout_s}s"
+        )
+
+    def _ensure_docker_available(self) -> None:
+        import subprocess
+
+        try:
+            subprocess.run(
+                ["docker", "version"],
+                check=True,
+                capture_output=True,
+                timeout=5,
+            )
+        except (
+            subprocess.CalledProcessError,
+            FileNotFoundError,
+            subprocess.TimeoutExpired,
+        ) as exc:
+            raise RuntimeError(
+                "Docker is not available. Please install Docker Desktop or Docker Engine."
+            ) from exc
+
+    def _ensure_swarm_initialized(self) -> None:
+        import subprocess
+
+        try:
+            result = subprocess.run(
+                ["docker", "info", "--format", "{{.Swarm.LocalNodeState}}"],
+                capture_output=True,
+                text=True,
+                check=True,
+                timeout=5,
+            )
+            state = result.stdout.strip().lower()
+            if state == "active":
+                return
+        except subprocess.CalledProcessError:
+            state = "unknown"
+
+        if not self._auto_init_swarm:
+            raise RuntimeError(
+                f"Docker Swarm is not active (state={state}). Enable Swarm manually or pass auto_init_swarm=True."
+            )
+
+        try:
+            subprocess.run(
+                ["docker", "swarm", "init"],
+                check=True,
+                capture_output=True,
+                timeout=10,
+            )
+        except subprocess.CalledProcessError as e:
+            raise RuntimeError("Failed to initialize Docker Swarm") from e
+
+    def _ensure_overlay_network(self, network: str) -> None:
+        import subprocess
+
+        inspect = subprocess.run(
+            ["docker", "network", "inspect", network],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if inspect.returncode == 0:
+            return
+
+        try:
+            subprocess.run(
+                [
+                    "docker",
+                    "network",
+                    "create",
+                    "--driver",
+                    "overlay",
+                    "--attachable",
+                    network,
+                ],
+                check=True,
+                capture_output=True,
+                timeout=10,
+            )
+        except subprocess.CalledProcessError as e:
+            raise RuntimeError(f"Failed to create overlay network '{network}'") from e
+
+    def _find_available_port(self) -> int:
+        import socket
+
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(("", 0))
+            s.listen(1)
+            port = s.getsockname()[1]
+        return port
+
+    def _generate_service_name(self, image: str) -> str:
+        import time
+
+        clean_image = image.split("/")[-1].split(":")[0]
+        timestamp = int(time.time() * 1000)
+        return f"{clean_image}-swarm-{timestamp}"
+
+
 class KubernetesProvider(ContainerProvider):
     """
     Container provider for Kubernetes clusters.
@@ -286,4 +603,67 @@ class KubernetesProvider(ContainerProvider):
         >>> # Pod running in k8s, accessible via service or port-forward
         >>> provider.stop_container()
     """
+
     pass
+
+
+class RuntimeProvider(ABC):
+    """
+    Abstract base class for runtime providers that are not container providers.
+    Providers implement this interface to support different runtime platforms:
+    - UVProvider: Runs environments via `uv run`
+
+    The provider manages a single runtime lifecycle and provides the base URL
+    for connecting to it.
+
+    Example:
+        >>> provider = UVProvider(project_path="/path/to/env")
+        >>> base_url = provider.start()
+        >>> print(base_url)  # http://localhost:8000
+        >>> provider.stop()
+    """
+
+    @abstractmethod
+    def start(
+        self,
+        port: Optional[int] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> str:
+        """
+        Start a runtime from the specified image.
+
+        Args:
+            image: Runtime image name
+            port: Port to expose (if None, provider chooses)
+            env_vars: Environment variables for the runtime
+            **kwargs: Additional runtime options
+        """
+
+    @abstractmethod
+    def stop(self) -> None:
+        """
+        Stop the runtime.
+        """
+        pass
+
+    @abstractmethod
+    def wait_for_ready(self, timeout_s: float = 30.0) -> None:
+        """
+        Wait for the runtime to be ready to accept requests.
+        """
+        pass
+
+    def __enter__(self) -> "RuntimeProvider":
+        """
+        Enter the runtime provider.
+        """
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        """
+        Exit the runtime provider.
+        """
+        self.stop()
+        return False

src/core/containers/runtime/uv_provider.py

@@ -0,0 +1,224 @@
+"""Providers for launching ASGI applications via ``uv run``."""
+
+from __future__ import annotations
+
+import os
+import socket
+import subprocess
+import time
+from typing import Dict, Optional
+
+import requests
+
+from .providers import RuntimeProvider
+
+
+def _check_uv_installed() -> None:
+    try:
+        subprocess.check_output(["uv", "--version"])
+    except FileNotFoundError as exc:
+        raise RuntimeError(
+            "`uv` executable not found. Install uv from https://docs.astral.sh and ensure it is on PATH."
+        ) from exc
+
+
+def _find_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("", 0))
+        sock.listen(1)
+        return sock.getsockname()[1]
+
+
+def _create_uv_command(
+    *,
+    host: str,
+    port: int,
+    reload: bool,
+    workers: int,
+    app: str,
+    project_path: str,
+) -> list[str]:
+    command: list[str] = ["uv", "run", "--isolated", "--project", project_path]
+
+    command.append("--")
+    command.extend(
+        [
+            "uvicorn",
+            app,
+            "--host",
+            host,
+            "--port",
+            str(port),
+            "--workers",
+            str(workers),
+        ]
+    )
+
+    if reload:
+        command.append("--reload")
+
+    return command
+
+
+def _poll_health(health_url: str, timeout_s: float) -> None:
+    """Poll a health endpoint until it returns HTTP 200 or times out."""
+
+    deadline = time.time() + timeout_s
+    while time.time() < deadline:
+        try:
+            timeout = max(0.0001, min(deadline - time.time(), 2.0))
+            response = requests.get(health_url, timeout=timeout)
+            if response.status_code == 200:
+                return
+        except requests.RequestException:
+            continue
+
+        time.sleep(0.5)
+
+    raise TimeoutError(f"Server did not become ready within {timeout_s:.1f} seconds")
+
+
+class UVProvider(RuntimeProvider):
+    """
+    RuntimeProvider implementation backed by ``uv run``.
+
+    Args:
+        project_path: Local path to a uv project (passed to ``uv run --project``)
+        app: ASGI application path for uvicorn (defaults to ``server.app:app``)
+        host: Host interface to bind to (defaults to ``0.0.0.0``)
+        reload: Whether to enable uvicorn's reload mode
+        env_vars: Environment variables to pass through to the spawned process
+        context_timeout_s: How long to wait for the environment to become ready
+
+    Example:
+        >>> provider = UVProvider(project_path="/path/to/env")
+        >>> base_url = provider.start()
+        >>> print(base_url)  # http://localhost:8000
+        >>> # Use the environment via base_url
+        >>> provider.stop()
+    """
+
+    def __init__(
+        self,
+        *,
+        project_path: str,
+        app: str = "server.app:app",
+        host: str = "0.0.0.0",
+        reload: bool = False,
+        env_vars: Optional[Dict[str, str]] = None,
+        context_timeout_s: float = 60.0,
+    ):
+        """Initialize the UVProvider."""
+        self.project_path = os.path.abspath(project_path)
+        self.app = app
+        self.host = host
+        self.reload = reload
+        self.env_vars = env_vars
+        self.context_timeout_s = context_timeout_s
+        _check_uv_installed()
+        self._process = None
+        self._base_url = None
+
+    def start(
+        self,
+        port: Optional[int] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        workers: int = 1,
+        **_: Dict[str, str],
+    ) -> str:
+        """
+        Start the environment via `uv run`.
+
+        Args:
+            port: The port to bind the environment to
+            env_vars: Environment variables to pass to the environment
+            workers: The number of workers to use
+
+        Returns:
+            The base URL of the environment
+
+        Raises:
+            RuntimeError: If the environment is already running
+        """
+        if self._process is not None and self._process.poll() is None:
+            raise RuntimeError("UVProvider is already running")
+
+        bind_port = port or _find_free_port()
+
+        command = _create_uv_command(
+            host=self.host,
+            port=bind_port,
+            reload=self.reload,
+            workers=workers,
+            app=self.app,
+            project_path=self.project_path,
+        )
+
+        env = os.environ.copy()
+
+        if self.env_vars:
+            env.update(self.env_vars)
+        if env_vars:
+            env.update(env_vars)
+
+        try:
+            self._process = subprocess.Popen(command, env=env)
+        except OSError as exc:
+            raise RuntimeError(f"Failed to launch `uv run`: {exc}") from exc
+
+        client_host = "127.0.0.1" if self.host in {"0.0.0.0", "::"} else self.host
+        self._base_url = f"http://{client_host}:{bind_port}"
+        return self._base_url
+
+    def wait_for_ready(self, timeout_s: float = 60.0) -> None:
+        """
+        Wait for the environment to become ready.
+
+        Args:
+            timeout_s: The timeout to wait for the environment to become ready
+
+        Raises:
+            RuntimeError: If the environment is not running
+            TimeoutError: If the environment does not become ready within the timeout
+        """
+        if self._process and self._process.poll() is not None:
+            code = self._process.returncode
+            raise RuntimeError(f"uv process exited prematurely with code {code}")
+
+        _poll_health(f"{self._base_url}/health", timeout_s=timeout_s)
+
+    def stop(self) -> None:
+        """
+        Stop the environment.
+
+        Raises:
+            RuntimeError: If the environment is not running
+        """
+        if self._process is None:
+            return
+
+        if self._process.poll() is None:
+            self._process.terminate()
+            try:
+                self._process.wait(timeout=10.0)
+            except subprocess.TimeoutExpired:
+                self._process.kill()
+                self._process.wait(timeout=5.0)
+
+        self._process = None
+        self._base_url = None
+
+    @property
+    def base_url(self) -> str:
+        """
+        The base URL of the environment.
+
+        Returns:
+            The base URL of the environment
+
+        Raises:
+            RuntimeError: If the environment is not running
+        """
+        if self._base_url is None:
+            raise RuntimeError("UVProvider has not been started")
+        return self._base_url

src/core/containers/test_local_docker_provider.py

@@ -16,8 +16,8 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent.parent.parent))
 
 import requests
+from openenv.core.containers.runtime import LocalDockerProvider
 
-from core.containers.runtime import LocalDockerProvider
 
 # TODO: Remove this test or make it a functional test sicne this will be tested in e2e test for echo env
 def test_local_docker_provider():
@@ -87,7 +87,9 @@ def test_local_docker_provider():
         print(f"  Length: {data['observation']['message_length']}")
         print(f"  Reward: {data['reward']}")
         assert response.status_code == 200
-        assert data["observation"]["echoed_message"] == "Hello from LocalDockerProvider!"
+        assert (
+            data["observation"]["echoed_message"] == "Hello from LocalDockerProvider!"
+        )
         assert data["observation"]["message_length"] == 31
         print("✓ Step test passed\n")
 
@@ -107,11 +109,11 @@ def test_local_docker_provider():
         for i in range(3):
             response = requests.post(
                 f"{base_url}/step",
-                json={"action": {"message": f"Message {i+1}"}},
+                json={"action": {"message": f"Message {i + 1}"}},
                 headers={"Content-Type": "application/json"},
             )
             assert response.status_code == 200
-            print(f"  Step {i+1}: ✓")
+            print(f"  Step {i + 1}: ✓")
 
         # Check state updated
         response = requests.get(f"{base_url}/state")
@@ -130,6 +132,7 @@ def test_local_docker_provider():
     except Exception as e:
         print(f"\n❌ Test failed: {e}")
         import traceback
+
         traceback.print_exc()
         return False
 
@@ -197,8 +200,7 @@ def test_provider_with_env_vars():
 
         print("Starting container with environment variables...")
         base_url = provider.start_container(
-            "echo-env:latest",
-            env_vars={"DEBUG": "true", "LOG_LEVEL": "info"}
+            "echo-env:latest", env_vars={"DEBUG": "true", "LOG_LEVEL": "info"}
         )
         print(f"✓ Started at: {base_url}")
 

src/core/env_client.py

@@ -0,0 +1,484 @@
+# 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 client for persistent sessions.
+
+This module provides a WebSocket-based client that maintains a persistent connection
+to an environment server, enabling efficient multi-step interactions without
+the overhead of HTTP request/response cycles.
+
+The client is async by default. For synchronous usage, use the `.sync()` method
+to get a `SyncEnvClient` wrapper.
+
+Example (async):
+    >>> async with GenericEnvClient(base_url="ws://localhost:8000") as env:
+    ...     result = await env.reset()
+    ...     result = await env.step({"code": "print('hello')"})
+
+Example (sync wrapper):
+    >>> env = GenericEnvClient(base_url="ws://localhost:8000").sync()
+    >>> with env:
+    ...     result = env.reset()
+    ...     result = env.step({"code": "print('hello')"})
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Generic, Optional, Type, TYPE_CHECKING, TypeVar
+
+from .client_types import StateT, StepResult
+from .containers.runtime import LocalDockerProvider, UVProvider
+from .utils import convert_to_ws_url
+
+if TYPE_CHECKING:
+    from websockets.asyncio.client import ClientConnection
+
+    from .containers.runtime import ContainerProvider, RuntimeProvider
+    from .sync_client import SyncEnvClient
+
+from websockets.asyncio.client import connect as ws_connect
+
+ActT = TypeVar("ActT")
+ObsT = TypeVar("ObsT")
+EnvClientT = TypeVar("EnvClientT", bound="EnvClient")
+
+
+class EnvClient(ABC, Generic[ActT, ObsT, StateT]):
+    """
+    Async environment client for persistent sessions.
+
+    This client maintains a persistent WebSocket connection to an environment
+    server, enabling efficient multi-step interactions. Each client instance
+    corresponds to a dedicated environment session on the server.
+
+    The client is async by default. For synchronous usage, use the `.sync()`
+    method to get a `SyncEnvClient` wrapper.
+
+    Features:
+    - Lower latency for sequential interactions
+    - Session state is maintained server-side
+    - Better suited for long-running episodes
+    - Async by default for modern Python async/await patterns
+
+    Example (async):
+        >>> from envs.coding_env.client import CodingEnv
+        >>>
+        >>> # Connect to a server using async context manager
+        >>> async with CodingEnv(base_url="ws://localhost:8000") as env:
+        ...     result = await env.reset(seed=42)
+        ...     while not result.done:
+        ...         action = agent.predict(result.observation)
+        ...         result = await env.step(action)
+
+    Example (sync wrapper):
+        >>> env = CodingEnv(base_url="ws://localhost:8000").sync()
+        >>> with env:
+        ...     result = env.reset(seed=42)
+        ...     result = env.step(action)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        connect_timeout_s: float = 10.0,
+        message_timeout_s: float = 60.0,
+        max_message_size_mb: float = 100.0,
+        provider: Optional["ContainerProvider | RuntimeProvider"] = None,
+        mode: Optional[str] = None,
+    ):
+        """
+        Initialize environment client.
+
+        Args:
+            base_url: Base URL of the environment server (http:// or ws://).
+                     Will be converted to ws:// if http:// is provided.
+            connect_timeout_s: Timeout for establishing WebSocket connection
+            message_timeout_s: Timeout for receiving responses to messages
+            max_message_size_mb: Maximum WebSocket message size in megabytes.
+                                Default 100MB to handle large observations (screenshots, DOM, etc.)
+            provider: Optional container/runtime provider for lifecycle management.
+                     Can be a ContainerProvider (Docker) or RuntimeProvider (UV).
+            mode: Communication mode: 'simulation' for Gym-style API (default) or
+                 'production' for MCP JSON-RPC protocol. Can also be set via the
+                 OPENENV_CLIENT_MODE environment variable. Constructor parameter
+                 takes precedence over environment variable. Case-insensitive.
+        """
+        # Determine mode (constructor > env var > default)
+        if mode is None:
+            mode = os.environ.get("OPENENV_CLIENT_MODE", "simulation")
+
+        # Normalize and validate mode
+        mode = mode.lower()
+        if mode not in ("simulation", "production"):
+            raise ValueError(
+                f"Invalid mode: '{mode}'. Must be 'simulation' or 'production'. "
+                f"Set via constructor parameter or OPENENV_CLIENT_MODE environment variable."
+            )
+
+        # Store mode (use object.__setattr__ to bypass immutability)
+        object.__setattr__(self, "_mode", mode)
+
+        # Convert HTTP URL to WebSocket URL
+        ws_url = convert_to_ws_url(base_url)
+
+        self._ws_url = f"{ws_url}/ws"
+        self._connect_timeout = connect_timeout_s
+        self._message_timeout = message_timeout_s
+        self._max_message_size = int(
+            max_message_size_mb * 1024 * 1024
+        )  # Convert MB to bytes
+        self._provider = provider
+        self._ws: Optional[ClientConnection] = None
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Prevent modification of _mode after initialization."""
+        if name == "_mode" and hasattr(self, "_mode"):
+            raise AttributeError("Cannot modify mode after initialization")
+        super().__setattr__(name, value)
+
+    async def connect(self) -> "EnvClient":
+        """
+        Establish WebSocket connection to the server.
+
+        Returns:
+            self for method chaining
+
+        Raises:
+            ConnectionError: If connection cannot be established
+        """
+        if self._ws is not None:
+            return self
+
+        # Bypass proxy for localhost connections
+        ws_url_lower = self._ws_url.lower()
+        is_localhost = "localhost" in ws_url_lower or "127.0.0.1" in ws_url_lower
+
+        old_no_proxy = os.environ.get("NO_PROXY")
+        if is_localhost:
+            # Set NO_PROXY to bypass proxy for localhost
+            current_no_proxy = old_no_proxy or ""
+            if "localhost" not in current_no_proxy.lower():
+                os.environ["NO_PROXY"] = (
+                    f"{current_no_proxy},localhost,127.0.0.1"
+                    if current_no_proxy
+                    else "localhost,127.0.0.1"
+                )
+
+        try:
+            self._ws = await ws_connect(
+                self._ws_url,
+                open_timeout=self._connect_timeout,
+                max_size=self._max_message_size,
+            )
+        except Exception as e:
+            raise ConnectionError(f"Failed to connect to {self._ws_url}: {e}") from e
+        finally:
+            # Restore original NO_PROXY value
+            if is_localhost:
+                if old_no_proxy is None:
+                    os.environ.pop("NO_PROXY", None)
+                else:
+                    os.environ["NO_PROXY"] = old_no_proxy
+
+        return self
+
+    async def disconnect(self) -> None:
+        """Close the WebSocket connection."""
+        if self._ws is not None:
+            try:
+                # Send close message
+                await self._send({"type": "close"})
+            except Exception:
+                pass  # Best effort
+            try:
+                await self._ws.close()
+            except Exception:
+                pass
+            self._ws = None
+
+    async def _ensure_connected(self) -> None:
+        """Ensure WebSocket connection is established."""
+        if self._ws is None:
+            await self.connect()
+
+    async def _send(self, message: Dict[str, Any]) -> None:
+        """Send a message over the WebSocket."""
+        await self._ensure_connected()
+        assert self._ws is not None
+        await self._ws.send(json.dumps(message))
+
+    async def _receive(self) -> Dict[str, Any]:
+        """Receive and parse a message from the WebSocket."""
+        assert self._ws is not None
+        raw = await asyncio.wait_for(self._ws.recv(), timeout=self._message_timeout)
+        return json.loads(raw)
+
+    async def _send_and_receive(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Send a message and wait for response."""
+        await self._send(message)
+        response = await self._receive()
+
+        # Check for error response
+        if response.get("type") == "error":
+            error_data = response.get("data", {})
+            raise RuntimeError(
+                f"Server error: {error_data.get('message', 'Unknown error')} "
+                f"(code: {error_data.get('code', 'UNKNOWN')})"
+            )
+
+        return response
+
+    @classmethod
+    async def from_docker_image(
+        cls: Type[EnvClientT],
+        image: str,
+        provider: Optional["ContainerProvider"] = None,
+        **kwargs: Any,
+    ) -> EnvClientT:
+        """
+        Create an environment client by spinning up a Docker container.
+
+        Args:
+            image: Docker image name to run (e.g., "coding-env:latest")
+            provider: Container provider to use (defaults to LocalDockerProvider)
+            **kwargs: Additional arguments to pass to provider.start_container()
+
+        Returns:
+            Connected client instance
+        """
+        if provider is None:
+            provider = LocalDockerProvider()
+
+        # Start container
+        base_url = provider.start_container(image, **kwargs)
+
+        # Wait for server to be ready
+        provider.wait_for_ready(base_url)
+
+        # Create and connect client
+        client = cls(base_url=base_url, provider=provider)
+        await client.connect()
+
+        return client
+
+    @classmethod
+    async def from_env(
+        cls: Type[EnvClientT],
+        repo_id: str,
+        *,
+        use_docker: bool = True,
+        provider: Optional["ContainerProvider | RuntimeProvider"] = None,
+        **provider_kwargs: Any,
+    ) -> EnvClientT:
+        """
+        Create a client from a Hugging Face Space.
+
+        Args:
+            repo_id: Hugging Face space identifier ``{org}/{space}``.
+            use_docker: When ``True`` (default) pull from the HF registry and
+                launch via :class:`LocalDockerProvider`. When ``False`` run the
+                space locally with :class:`UVProvider`.
+            provider: Optional provider instance to reuse. Must be a
+                :class:`ContainerProvider` when ``use_docker=True`` and a
+                :class:`RuntimeProvider` otherwise.
+            provider_kwargs: Additional keyword arguments forwarded to
+                either the container provider's ``start_container`` (docker)
+                or to the ``UVProvider`` constructor/start (uv). When
+                ``use_docker=False``, the ``project_path`` argument can be
+                used to override the default git URL
+                (``git+https://huggingface.co/spaces/{repo_id}``).
+
+        Returns:
+            Connected client instance
+
+        Examples:
+            >>> # Pull and run from HF Docker registry
+            >>> env = await MyEnv.from_env("openenv/echo-env")
+            >>>
+            >>> # Run locally with UV (clones the space)
+            >>> env = await MyEnv.from_env("openenv/echo-env", use_docker=False)
+            >>>
+            >>> # Run from a local checkout
+            >>> env = await MyEnv.from_env(
+            ...     "openenv/echo-env",
+            ...     use_docker=False,
+            ...     project_path="/path/to/local/checkout"
+            ... )
+        """
+        # Extract start args that apply to both providers
+        start_args = {}
+        for key in ("port", "env_vars", "workers"):
+            if key in provider_kwargs:
+                start_args[key] = provider_kwargs.pop(key)
+
+        if use_docker:
+            # Docker mode: pull from HF registry
+            docker_provider = provider or LocalDockerProvider()
+            tag = provider_kwargs.pop("tag", "latest")
+            image = f"registry.hf.space/{repo_id.replace('/', '-')}:{tag}"
+            base_url = docker_provider.start_container(
+                image, **start_args, **provider_kwargs
+            )
+            docker_provider.wait_for_ready(base_url)
+
+            client = cls(base_url=base_url, provider=docker_provider)
+            await client.connect()
+            return client
+        else:
+            # UV mode: clone and run with uv
+            if provider is None:
+                uv_kwargs = dict(provider_kwargs)
+                project_path = uv_kwargs.pop("project_path", None)
+                if project_path is None:
+                    project_path = f"git+https://huggingface.co/spaces/{repo_id}"
+
+                provider = UVProvider(project_path=project_path, **uv_kwargs)
+            else:
+                if provider_kwargs:
+                    raise ValueError(
+                        "provider_kwargs cannot be used when supplying a provider instance"
+                    )
+
+            base_url = provider.start(**start_args)
+            provider.wait_for_ready()
+
+            client = cls(base_url=base_url, provider=provider)
+            await client.connect()
+            return client
+
+    @abstractmethod
+    def _step_payload(self, action: ActT) -> Dict[str, Any]:
+        """Convert an Action object to the JSON data expected by the env server."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[ObsT]:
+        """Convert a JSON response from the env server to StepResult[ObsT]."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def _parse_state(self, payload: Dict[str, Any]) -> StateT:
+        """Convert a JSON response from the state endpoint to a State object."""
+        raise NotImplementedError
+
+    async def reset(self, **kwargs: Any) -> StepResult[ObsT]:
+        """
+        Reset the environment with optional parameters.
+
+        Args:
+            **kwargs: Optional parameters passed to the environment's reset method.
+                     Common parameters include:
+                     - seed: Random seed for reproducibility
+                     - episode_id: Custom episode identifier
+
+        Returns:
+            StepResult containing initial observation
+        """
+        message = {
+            "type": "reset",
+            "data": kwargs,
+        }
+        response = await self._send_and_receive(message)
+        return self._parse_result(response.get("data", {}))
+
+    async def step(self, action: ActT, **kwargs: Any) -> StepResult[ObsT]:
+        """
+        Execute an action in the environment.
+
+        Args:
+            action: The action to execute
+            **kwargs: Optional parameters (currently ignored)
+
+        Returns:
+            StepResult containing observation, reward, and done status
+        """
+        message = {
+            "type": "step",
+            "data": self._step_payload(action),
+        }
+        response = await self._send_and_receive(message)
+        return self._parse_result(response.get("data", {}))
+
+    async def state(self) -> StateT:
+        """
+        Get the current environment state from the server.
+
+        Returns:
+            State object with environment state information
+        """
+        message = {"type": "state"}
+        response = await self._send_and_receive(message)
+        return self._parse_state(response.get("data", {}))
+
+    async def close(self) -> None:
+        """
+        Close the WebSocket connection and clean up resources.
+
+        If this client was created via from_docker_image() or from_env(),
+        this will also stop and remove the associated container/process.
+        """
+        await self.disconnect()
+
+        if self._provider is not None:
+            # Handle both ContainerProvider and RuntimeProvider
+            if hasattr(self._provider, "stop_container"):
+                self._provider.stop_container()
+            elif hasattr(self._provider, "stop"):
+                self._provider.stop()
+
+    async def __aenter__(self) -> "EnvClient":
+        """Enter async context manager, ensuring connection is established."""
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit async context manager, closing connection."""
+        await self.close()
+
+    def __enter__(self) -> "EnvClient":
+        """Sync context manager entry - raises error suggesting async usage."""
+        raise TypeError(
+            "EnvClient is async by default. Use 'async with' instead of 'with', "
+            "or call .sync() to get a synchronous wrapper:\n"
+            "  async with client:  # async usage\n"
+            "  with client.sync():  # sync wrapper"
+        )
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Sync context manager exit - should not be reached."""
+        pass  # pragma: no cover
+
+    def sync(self) -> "SyncEnvClient":
+        """
+        Return a synchronous wrapper around this async client.
+
+        Use this method when you need synchronous access to the environment
+        without async/await syntax. This is useful for:
+        - Integration with synchronous codebases
+        - Interactive/REPL usage
+        - Stopping async from "infecting" the call stack
+
+        Returns:
+            SyncEnvClient wrapper that provides synchronous methods
+
+        Example:
+            >>> # Create async client and get sync wrapper
+            >>> async_client = GenericEnvClient(base_url="http://localhost:8000")
+            >>> sync_client = async_client.sync()
+            >>>
+            >>> # Use synchronous API
+            >>> with sync_client:
+            ...     result = sync_client.reset()
+            ...     result = sync_client.step({"code": "print('hello')"})
+        """
+        from .sync_client import SyncEnvClient
+
+        return SyncEnvClient(self)

src/core/env_server/__init__.py

@@ -7,10 +7,74 @@
 """Core environment interfaces and types."""
 
 from .base_transforms import CompositeTransform, NullTransform
-from .http_server import HTTPEnvServer, create_app, create_fastapi_app
+from .exceptions import (
+    ConcurrencyConfigurationError,
+    EnvironmentFactoryError,
+    OpenEnvError,
+    SessionCapacityError,
+    SessionCreationError,
+    SessionNotFoundError,
+)
+from .http_server import create_app, create_fastapi_app, HTTPEnvServer
 from .interfaces import Environment, Message, ModelTokenizer, Transform
-from .types import Action, Observation, State
-from .web_interface import create_web_interface_app, WebInterfaceManager
+
+try:
+    from .mcp_environment import MCPEnvironment
+except ModuleNotFoundError:
+    MCPEnvironment = None  # type: ignore[assignment]
+
+from .mcp_types import (
+    CallToolAction,
+    CallToolObservation,
+    JsonRpcError,
+    # JSON-RPC types
+    JsonRpcErrorCode,
+    JsonRpcRequest,
+    JsonRpcResponse,
+    ListToolsAction,
+    ListToolsObservation,
+    McpMethod,
+    RESERVED_TOOL_NAMES,
+    Tool,
+    ToolError,
+    ToolErrorType,
+    WSMCPMessage,
+    WSMCPResponse,
+)
+from .route_config import GetEndpointConfig
+from .serialization import (
+    deserialize_action,
+    deserialize_action_with_preprocessing,
+    serialize_observation,
+)
+from .types import (
+    Action,
+    BaseMessage,
+    ConcurrencyConfig,
+    HealthResponse,
+    HealthStatus,
+    Observation,
+    SchemaResponse,
+    ServerCapacityStatus,
+    ServerMode,
+    SessionInfo,
+    State,
+    WSCloseMessage,
+    WSErrorCode,
+    WSErrorResponse,
+    WSIncomingMessage,
+    WSObservationResponse,
+    WSResetMessage,
+    WSStateMessage,
+    WSStateResponse,
+    WSStepMessage,
+)
+
+try:
+    from .web_interface import create_web_interface_app, WebInterfaceManager
+except ModuleNotFoundError:
+    create_web_interface_app = None  # type: ignore[assignment]
+    WebInterfaceManager = None  # type: ignore[assignment]
 
 __all__ = [
     # Core interfaces
@@ -22,6 +86,33 @@ __all__ = [
     "Action",
     "Observation",
     "State",
+    "SchemaResponse",
+    "HealthResponse",
+    # Enums
+    "HealthStatus",
+    "ServerMode",
+    "WSErrorCode",
+    # WebSocket message types
+    "BaseMessage",
+    "WSIncomingMessage",
+    "WSResetMessage",
+    "WSStepMessage",
+    "WSStateMessage",
+    "WSCloseMessage",
+    "WSObservationResponse",
+    "WSStateResponse",
+    "WSErrorResponse",
+    # Concurrency types
+    "ConcurrencyConfig",
+    "ServerCapacityStatus",
+    "SessionInfo",
+    # Exceptions
+    "OpenEnvError",
+    "ConcurrencyConfigurationError",
+    "SessionCapacityError",
+    "SessionNotFoundError",
+    "SessionCreationError",
+    "EnvironmentFactoryError",
     # Base transforms
     "CompositeTransform",
     "NullTransform",
@@ -32,4 +123,28 @@ __all__ = [
     # Web Interface
     "create_web_interface_app",
     "WebInterfaceManager",
+    # Serialization utilities
+    "deserialize_action",
+    "deserialize_action_with_preprocessing",
+    "serialize_observation",
+    # Route configuration
+    "GetEndpointConfig",
+    # MCP types
+    "Tool",
+    "ToolError",
+    "ToolErrorType",
+    "ListToolsAction",
+    "CallToolAction",
+    "ListToolsObservation",
+    "CallToolObservation",
+    "WSMCPMessage",
+    "WSMCPResponse",
+    "RESERVED_TOOL_NAMES",
+    "MCPEnvironment",
+    # JSON-RPC types
+    "JsonRpcErrorCode",
+    "JsonRpcError",
+    "JsonRpcRequest",
+    "JsonRpcResponse",
+    "McpMethod",
 ]

src/core/env_server/base_transforms.py

@@ -26,4 +26,4 @@ class NullTransform(Transform):
     """Default transform that passes through unchanged."""
 
     def __call__(self, observation: Observation) -> Observation:
-        return observation
+        return observation

src/core/env_server/exceptions.py

@@ -0,0 +1,105 @@
+# 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.
+
+"""Custom exceptions for environment server operations."""
+
+from typing import Optional
+
+
+class OpenEnvError(Exception):
+    """Base exception for all OpenEnv errors."""
+
+    pass
+
+
+class ConcurrencyConfigurationError(OpenEnvError):
+    """
+    Raised when an environment is misconfigured for concurrent sessions.
+
+    This error is raised during server startup when max_concurrent_envs > 1
+    is specified for an environment that is not marked as SUPPORTS_CONCURRENT_SESSIONS.
+    """
+
+    def __init__(
+        self,
+        environment_name: str,
+        max_concurrent_envs: int,
+        message: Optional[str] = None,
+    ):
+        self.environment_name = environment_name
+        self.max_concurrent_envs = max_concurrent_envs
+
+        if message is None:
+            message = (
+                f"Environment '{environment_name}' is not marked as SUPPORTS_CONCURRENT_SESSIONS. "
+                f"Cannot run with max_concurrent_envs={max_concurrent_envs}. "
+                f"Either set max_concurrent_envs=1 or ensure the environment "
+                f"properly isolates session state and set SUPPORTS_CONCURRENT_SESSIONS=True."
+            )
+
+        super().__init__(message)
+
+
+class SessionCapacityError(OpenEnvError):
+    """
+    Raised when the server cannot accept new sessions due to capacity limits.
+
+    This error is raised when a new WebSocket connection is attempted but
+    the server has already reached max_concurrent_envs active sessions.
+    """
+
+    def __init__(
+        self,
+        active_sessions: int,
+        max_sessions: int,
+        message: Optional[str] = None,
+    ):
+        self.active_sessions = active_sessions
+        self.max_sessions = max_sessions
+
+        if message is None:
+            message = (
+                f"Server at capacity: {active_sessions}/{max_sessions} sessions active. "
+                f"Cannot accept new connections."
+            )
+
+        super().__init__(message)
+
+
+class SessionNotFoundError(OpenEnvError):
+    """Raised when attempting to access a session that does not exist."""
+
+    def __init__(self, session_id: str, message: Optional[str] = None):
+        self.session_id = session_id
+
+        if message is None:
+            message = f"Session '{session_id}' not found."
+
+        super().__init__(message)
+
+
+class SessionCreationError(OpenEnvError):
+    """Raised when a session cannot be created."""
+
+    def __init__(self, reason: str, message: Optional[str] = None):
+        self.reason = reason
+
+        if message is None:
+            message = f"Failed to create session: {reason}"
+
+        super().__init__(message)
+
+
+class EnvironmentFactoryError(OpenEnvError):
+    """Raised when the environment factory fails to create an instance."""
+
+    def __init__(self, factory_name: str, message: Optional[str] = None):
+        self.factory_name = factory_name
+
+        if message is None:
+            message = f"Environment factory '{factory_name}' failed to create instance."
+
+        super().__init__(message)

src/core/env_server/gradio_theme.py

@@ -0,0 +1,128 @@
+# 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.
+
+"""Unified terminal-style theme for OpenEnv Gradio UI (light/dark)."""
+
+from __future__ import annotations
+
+import gradio as gr
+
+_MONO_FONTS = (
+    "JetBrains Mono",
+    "Fira Code",
+    "Cascadia Code",
+    "Consolas",
+    "ui-monospace",
+    "monospace",
+)
+
+_CORE_FONT = (
+    "Lato",
+    "Inter",
+    "Arial",
+    "Helvetica",
+    "sans-serif",
+)
+
+_ZERO_RADIUS = gr.themes.Size(
+    xxs="0px",
+    xs="0px",
+    sm="0px",
+    md="0px",
+    lg="0px",
+    xl="0px",
+    xxl="0px",
+)
+
+_GREEN_HUE = gr.themes.Color(
+    c50="#e6f4ea",
+    c100="#ceead6",
+    c200="#a8dab5",
+    c300="#6fcc8b",
+    c400="#3fb950",
+    c500="#238636",
+    c600="#1a7f37",
+    c700="#116329",
+    c800="#0a4620",
+    c900="#033a16",
+    c950="#04200d",
+)
+
+_NEUTRAL_HUE = gr.themes.Color(
+    c50="#f6f8fa",
+    c100="#eaeef2",
+    c200="#d0d7de",
+    c300="#afb8c1",
+    c400="#8c959f",
+    c500="#6e7781",
+    c600="#57606a",
+    c700="#424a53",
+    c800="#32383f",
+    c900="#24292f",
+    c950="#1b1f24",
+)
+
+OPENENV_GRADIO_THEME = gr.themes.Base(
+    primary_hue=_GREEN_HUE,
+    secondary_hue=_NEUTRAL_HUE,
+    neutral_hue=_NEUTRAL_HUE,
+    font=_CORE_FONT,
+    font_mono=_MONO_FONTS,
+    radius_size=_ZERO_RADIUS,
+).set(
+    body_background_fill="#ffffff",
+    background_fill_primary="#ffffff",
+    background_fill_secondary="#f6f8fa",
+    block_background_fill="#ffffff",
+    block_border_color="#ffffff",
+    block_label_text_color="#57606a",
+    block_title_text_color="#24292f",
+    border_color_primary="#d0d7de",
+    input_background_fill="#ffffff",
+    input_border_color="#d0d7de",
+    button_primary_background_fill="#1a7f37",
+    button_primary_background_fill_hover="#116329",
+    button_primary_text_color="#ffffff",
+    button_secondary_background_fill="#f6f8fa",
+    button_secondary_background_fill_hover="#eaeef2",
+    button_secondary_text_color="#24292f",
+    button_secondary_border_color="#d0d7de",
+    body_background_fill_dark="#0d1117",
+    background_fill_primary_dark="#0d1117",
+    background_fill_secondary_dark="#0d1117",
+    block_background_fill_dark="#0d1117",
+    block_border_color_dark="#0d1117",
+    block_label_text_color_dark="#8b949e",
+    block_title_text_color_dark="#c9d1d9",
+    border_color_primary_dark="#30363d",
+    input_background_fill_dark="#0d1117",
+    input_border_color_dark="#30363d",
+    button_primary_background_fill_dark="#30363d",
+    button_primary_background_fill_hover_dark="#484f58",
+    button_primary_text_color_dark="#c9d1d9",
+    button_secondary_background_fill_dark="#21262d",
+    button_secondary_background_fill_hover_dark="#30363d",
+    button_secondary_text_color_dark="#c9d1d9",
+    button_secondary_border_color_dark="#30363d",
+)
+
+OPENENV_GRADIO_CSS = """
+* { border-radius: 0 !important; }
+.col-left { padding: 16px !important; }
+.col-right { padding: 16px !important; }
+.prose, .markdown-text, .md,
+.prose > *, .markdown-text > * {
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+}
+.dark .col-left {
+    border-left-color: rgba(139, 148, 158, 0.4) !important;
+}
+.dark .col-right {
+    border-left-color: rgba(201, 209, 217, 0.3) !important;
+}
+"""

src/core/env_server/gradio_ui.py

@@ -0,0 +1,240 @@
+# 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.
+
+"""
+Gradio-based web UI for OpenEnv environments.
+
+Replaces the legacy HTML/JavaScript interface when ENABLE_WEB_INTERFACE is set.
+Mount at /web via gr.mount_gradio_app() from create_web_interface_app().
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Dict, List, Optional
+
+import gradio as gr
+
+from .types import EnvironmentMetadata
+
+
+def _escape_md(text: str) -> str:
+    """Escape Markdown special characters in user-controlled content."""
+    return re.sub(r"([\\`*_\{\}\[\]()#+\-.!|~>])", r"\\\1", str(text))
+
+
+def _format_observation(data: Dict[str, Any]) -> str:
+    """Format reset/step response for Markdown display."""
+    lines: List[str] = []
+    obs = data.get("observation", {})
+    if isinstance(obs, dict):
+        if obs.get("prompt"):
+            lines.append(f"**Prompt:**\n\n{_escape_md(obs['prompt'])}\n")
+        messages = obs.get("messages", [])
+        if messages:
+            lines.append("**Messages:**\n")
+            for msg in messages:
+                sender = _escape_md(str(msg.get("sender_id", "?")))
+                content = _escape_md(str(msg.get("content", "")))
+                cat = _escape_md(str(msg.get("category", "")))
+                lines.append(f"- `[{cat}]` Player {sender}: {content}")
+            lines.append("")
+    reward = data.get("reward")
+    done = data.get("done")
+    if reward is not None:
+        lines.append(f"**Reward:** `{reward}`")
+    if done is not None:
+        lines.append(f"**Done:** `{done}`")
+    return "\n".join(lines) if lines else "*No observation data*"
+
+
+def _readme_section(metadata: Optional[EnvironmentMetadata]) -> str:
+    """README content for the left panel."""
+    if not metadata or not metadata.readme_content:
+        return "*No README available.*"
+    return metadata.readme_content
+
+
+def get_gradio_display_title(
+    metadata: Optional[EnvironmentMetadata],
+    fallback: str = "OpenEnv Environment",
+) -> str:
+    """Return the title used for the Gradio app (browser tab and Blocks)."""
+    name = metadata.name if metadata else fallback
+    return f"OpenEnv Agentic Environment: {name}"
+
+
+def build_gradio_app(
+    web_manager: Any,
+    action_fields: List[Dict[str, Any]],
+    metadata: Optional[EnvironmentMetadata],
+    is_chat_env: bool,
+    title: str = "OpenEnv Environment",
+    quick_start_md: Optional[str] = None,
+) -> gr.Blocks:
+    """
+    Build a Gradio Blocks app for the OpenEnv web interface.
+
+    Args:
+        web_manager: WebInterfaceManager (reset/step_environment, get_state).
+        action_fields: Field dicts from _extract_action_fields(action_cls).
+        metadata: Environment metadata for README/name.
+        is_chat_env: If True, single message textbox; else form from action_fields.
+        title: App title (overridden by metadata.name when present; see get_gradio_display_title).
+        quick_start_md: Optional Quick Start markdown (class names already replaced).
+
+    Returns:
+        gr.Blocks to mount with gr.mount_gradio_app(app, blocks, path="/web").
+    """
+    readme_content = _readme_section(metadata)
+    display_title = get_gradio_display_title(metadata, fallback=title)
+
+    async def reset_env():
+        try:
+            data = await web_manager.reset_environment()
+            obs_md = _format_observation(data)
+            return (
+                obs_md,
+                json.dumps(data, indent=2),
+                "Environment reset successfully.",
+            )
+        except Exception as e:
+            return ("", "", f"Error: {e}")
+
+    def _step_with_action(action_data: Dict[str, Any]):
+        async def _run():
+            try:
+                data = await web_manager.step_environment(action_data)
+                obs_md = _format_observation(data)
+                return (
+                    obs_md,
+                    json.dumps(data, indent=2),
+                    "Step complete.",
+                )
+            except Exception as e:
+                return ("", "", f"Error: {e}")
+
+        return _run
+
+    async def step_chat(message: str):
+        if not (message or str(message).strip()):
+            return ("", "", "Please enter an action message.")
+        action = {"message": str(message).strip()}
+        return await _step_with_action(action)()
+
+    def get_state_sync():
+        try:
+            data = web_manager.get_state()
+            return json.dumps(data, indent=2)
+        except Exception as e:
+            return f"Error: {e}"
+
+    with gr.Blocks(title=display_title) as demo:
+        with gr.Row():
+            with gr.Column(scale=1, elem_classes="col-left"):
+                if quick_start_md:
+                    with gr.Accordion("Quick Start", open=True):
+                        gr.Markdown(quick_start_md)
+                with gr.Accordion("README", open=False):
+                    gr.Markdown(readme_content)
+
+            with gr.Column(scale=2, elem_classes="col-right"):
+                obs_display = gr.Markdown(
+                    value=("# Playground\n\nClick **Reset** to start a new episode."),
+                )
+                with gr.Group():
+                    if is_chat_env:
+                        action_input = gr.Textbox(
+                            label="Action message",
+                            placeholder="e.g. Enter your message...",
+                        )
+                        step_inputs = [action_input]
+                        step_fn = step_chat
+                    else:
+                        step_inputs = []
+                        for field in action_fields:
+                            name = field["name"]
+                            field_type = field.get("type", "text")
+                            label = name.replace("_", " ").title()
+                            placeholder = field.get("placeholder", "")
+                            if field_type == "checkbox":
+                                inp = gr.Checkbox(label=label)
+                            elif field_type == "number":
+                                inp = gr.Number(label=label)
+                            elif field_type == "select":
+                                choices = field.get("choices") or []
+                                inp = gr.Dropdown(
+                                    choices=choices,
+                                    label=label,
+                                    allow_custom_value=False,
+                                )
+                            elif field_type in ("textarea", "tensor"):
+                                inp = gr.Textbox(
+                                    label=label,
+                                    placeholder=placeholder,
+                                    lines=3,
+                                )
+                            else:
+                                inp = gr.Textbox(
+                                    label=label,
+                                    placeholder=placeholder,
+                                )
+                            step_inputs.append(inp)
+
+                        async def step_form(*values):
+                            if not action_fields:
+                                return await _step_with_action({})()
+                            action_data = {}
+                            for i, field in enumerate(action_fields):
+                                if i >= len(values):
+                                    break
+                                name = field["name"]
+                                val = values[i]
+                                if field.get("type") == "checkbox":
+                                    action_data[name] = bool(val)
+                                elif val is not None and val != "":
+                                    action_data[name] = val
+                            return await _step_with_action(action_data)()
+
+                        step_fn = step_form
+
+                    with gr.Row():
+                        step_btn = gr.Button("Step", variant="primary")
+                        reset_btn = gr.Button("Reset", variant="secondary")
+                        state_btn = gr.Button("Get state", variant="secondary")
+                    with gr.Row():
+                        status = gr.Textbox(
+                            label="Status",
+                            interactive=False,
+                        )
+                    raw_json = gr.Code(
+                        label="Raw JSON response",
+                        language="json",
+                        interactive=False,
+                    )
+
+        reset_btn.click(
+            fn=reset_env,
+            outputs=[obs_display, raw_json, status],
+        )
+        step_btn.click(
+            fn=step_fn,
+            inputs=step_inputs,
+            outputs=[obs_display, raw_json, status],
+        )
+        if is_chat_env:
+            action_input.submit(
+                fn=step_fn,
+                inputs=step_inputs,
+                outputs=[obs_display, raw_json, status],
+            )
+        state_btn.click(
+            fn=get_state_sync,
+            outputs=[raw_json],
+        )
+
+    return demo

src/core/env_server/http_server.py

@@ -8,25 +8,113 @@
 HTTP server wrapper for Environment instances.
 
 This module provides utilities to wrap any Environment subclass and expose it
-over HTTP endpoints that HTTPEnvClient can consume.
+over HTTP and WebSocket endpoints that EnvClient can consume.
 """
 
 from __future__ import annotations
 
+import asyncio
+import inspect
+import json
 import os
-from dataclasses import asdict
-from typing import Any, Dict, Type
+import time
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Dict, Optional, Type
+
+from fastapi import (
+    Body,
+    FastAPI,
+    HTTPException,
+    Request,
+    status,
+    WebSocket,
+    WebSocketDisconnect,
+)
+from pydantic import ValidationError
 
 from .interfaces import Environment
-from .types import Action, Observation
-from fastapi import Body, FastAPI
+from .mcp_environment import get_server_tools
+from .mcp_types import (
+    JsonRpcErrorCode,
+    JsonRpcRequest,
+    JsonRpcResponse,
+    McpMethod,
+    WSMCPMessage,
+    WSMCPResponse,
+)
+from .route_config import GetEndpointConfig, register_get_endpoints
+from .serialization import deserialize_action, serialize_observation
+from .types import (
+    Action,
+    ConcurrencyConfig,
+    EnvironmentMetadata,
+    HealthResponse,
+    HealthStatus,
+    Observation,
+    ResetRequest,
+    ResetResponse,
+    SchemaResponse,
+    ServerCapacityStatus,
+    ServerMode,
+    SessionInfo,
+    State,
+    StepRequest,
+    StepResponse,
+    WSCloseMessage,
+    WSErrorCode,
+    WSErrorResponse,
+    WSObservationResponse,
+    WSResetMessage,
+    WSStateMessage,
+    WSStateResponse,
+    WSStepMessage,
+)
+
+
+def _make_json_serializable(obj: Any) -> Any:
+    """
+    Convert an object to a JSON-serializable form.
+
+    Handles Pydantic models, dataclasses, and other common types.
+
+    Args:
+        obj: The object to convert
+
+    Returns:
+        A JSON-serializable representation of the object
+    """
+    if obj is None:
+        return None
+    if isinstance(obj, (str, int, float, bool)):
+        return obj
+    if isinstance(obj, (list, tuple)):
+        return [_make_json_serializable(item) for item in obj]
+    if isinstance(obj, dict):
+        return {k: _make_json_serializable(v) for k, v in obj.items()}
+    if hasattr(obj, "model_dump"):
+        # Pydantic model
+        return obj.model_dump()
+    if hasattr(obj, "__dict__"):
+        # Object with __dict__
+        return {k: _make_json_serializable(v) for k, v in obj.__dict__.items()}
+    # Fallback to string representation
+    return str(obj)
+
+
+from .exceptions import (
+    ConcurrencyConfigurationError,
+    EnvironmentFactoryError,
+    SessionCapacityError,
+)
+
 
 class HTTPEnvServer:
     """
     HTTP server wrapper for Environment instances.
 
     This class wraps an Environment and exposes its reset(), step(), and state
-    methods as HTTP endpoints compatible with HTTPEnvClient.
+    methods as HTTP and WebSocket endpoints compatible with EnvClient.
 
     The server expects:
     - Action deserialization: Converts JSON dict to Action subclass
@@ -35,9 +123,15 @@ class HTTPEnvServer:
     Example:
         >>> from core.env_server import HTTPEnvServer
         >>> from envs.coding_env.server import CodeExecutionEnvironment
+        >>> from envs.coding_env.models import CodeAction, CodeObservation
         >>>
-        >>> env = CodeExecutionEnvironment()
-        >>> server = HTTPEnvServer(env)
+        >>> # Pass environment class (factory pattern)
+        >>> server = HTTPEnvServer(
+        ...     env=CodeExecutionEnvironment,
+        ...     action_cls=CodeAction,
+        ...     observation_cls=CodeObservation,
+        ...     max_concurrent_envs=4,
+        ... )
         >>>
         >>> # Register routes with FastAPI
         >>> from fastapi import FastAPI
@@ -47,178 +141,1177 @@ class HTTPEnvServer:
 
     def __init__(
         self,
-        env: Environment,
+        env: Callable[[], Environment],
         action_cls: Type[Action],
         observation_cls: Type[Observation],
+        max_concurrent_envs: Optional[int] = None,
+        concurrency_config: Optional[ConcurrencyConfig] = None,
     ):
         """
         Initialize HTTP server wrapper.
 
         Args:
-            env: The Environment instance to wrap
+            env: Environment factory (callable) that creates new instances.
+                 Will be called to create a new environment for each WebSocket session.
             action_cls: The Action subclass this environment expects
             observation_cls: The Observation subclass this environment returns
+            max_concurrent_envs: Maximum number of concurrent WebSocket sessions.
+                                 Mutually exclusive with concurrency_config.
+            concurrency_config: Optional ConcurrencyConfig for advanced concurrency settings.
+                                Mutually exclusive with max_concurrent_envs.
+
+        Raises:
+            ValueError: If both max_concurrent_envs and concurrency_config are provided.
+            ConcurrencyConfigurationError: If max_concurrent_envs > 1 for an
+                environment that is not marked as SUPPORTS_CONCURRENT_SESSIONS.
         """
-        self.env = env
+        # Validate that env is callable
+        if not callable(env):
+            raise TypeError(
+                f"env must be a callable (class or factory function), got {type(env)}. "
+                f"Pass the environment class (e.g., MyEnvironment) not an instance (e.g., MyEnvironment())."
+            )
+
+        self._env_factory: Callable[[], Environment] = env
+
+        # Handle concurrency configuration
+        if max_concurrent_envs is not None and concurrency_config is not None:
+            raise ValueError(
+                "Cannot specify both 'max_concurrent_envs' and 'concurrency_config'. "
+                "Please use only one method to configure concurrency."
+            )
+
+        if concurrency_config is not None:
+            self._concurrency_config = concurrency_config
+        elif max_concurrent_envs is not None:
+            self._concurrency_config = ConcurrencyConfig(
+                max_concurrent_envs=max_concurrent_envs,
+                session_timeout=None,
+            )
+        else:
+            # Default configuration
+            self._concurrency_config = ConcurrencyConfig(
+                max_concurrent_envs=1,
+                session_timeout=None,
+            )
+
+        self._max_concurrent_envs = self._concurrency_config.max_concurrent_envs
+
+        # Validate concurrency configuration
+        self._validate_concurrency_safety()
+
         self.action_cls = action_cls
         self.observation_cls = observation_cls
 
-    def register_routes(self, app: Any) -> None:
+        # Session management for WebSocket connections
+        self._sessions: Dict[str, Environment] = {}
+        self._session_executors: Dict[str, ThreadPoolExecutor] = {}
+        self._session_info: Dict[str, SessionInfo] = {}
+        self._session_lock = asyncio.Lock()
+
+        # Create thread pool for running sync code in async context
+        # This is needed for environments using sync libraries (e.g., Playwright)
+        self._executor = ThreadPoolExecutor(max_workers=32)
+
+    def _validate_concurrency_safety(self) -> None:
         """
-        Register HTTP routes on a FastAPI application.
+        Validate that the environment supports the configured concurrency level.
 
-        Args:
-            app: FastAPI application instance
+        Raises:
+            ConcurrencyConfigurationError: If max_concurrent_envs > 1 for an
+                environment that is not marked as SUPPORTS_CONCURRENT_SESSIONS.
         """
+        if self._max_concurrent_envs <= 1:
+            return
 
-        if not isinstance(app, FastAPI):
-            raise TypeError("app must be a FastAPI instance")
+        if inspect.isclass(self._env_factory):
+            env_cls = self._env_factory
+        else:
+            _temp_env = self._env_factory()
+            env_cls = type(_temp_env)
+            _temp_env.close()
+            del _temp_env
 
-        @app.post("/reset")
-        async def reset(request: Dict[str, Any] = Body(default={})) -> Dict[str, Any]:
-            """Reset endpoint - returns initial observation."""
-            # TODO: Handle seed, episode_id from request if provided
-            observation = self.env.reset()
-            return self._serialize_observation(observation)
+        if not getattr(env_cls, "SUPPORTS_CONCURRENT_SESSIONS", False):
+            raise ConcurrencyConfigurationError(
+                environment_name=env_cls.__name__,
+                max_concurrent_envs=self._max_concurrent_envs,
+            )
 
-        @app.post("/step")
-        async def step(request: Dict[str, Any]) -> Dict[str, Any]:
-            """Step endpoint - executes action and returns observation."""
-            action_data = request.get("action", {})
-            # TODO: Handle timeout_s, request_id, episode_id from request if provided
+    def get_capacity_status(self) -> ServerCapacityStatus:
+        """
+        Get the current capacity status of the server.
+
+        Returns:
+            ServerCapacityStatus with current session counts and availability.
+        """
+        return ServerCapacityStatus.from_counts(
+            active=len(self._sessions),
+            max_sessions=self._max_concurrent_envs,
+        )
+
+    async def _run_sync_in_thread_pool(
+        self, func: Callable[..., Observation], *args, **kwargs
+    ) -> Observation:
+        """Run a synchronous function in the thread pool executor."""
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(self._executor, lambda: func(*args, **kwargs))
+
+    def _get_valid_kwargs(
+        self,
+        sig: inspect.Signature,
+        kwargs: Dict[str, Any],
+        skip_params: Optional[set[str]] = None,
+    ) -> Dict[str, Any]:
+        """Filter kwargs to only include parameters accepted by the function signature."""
+        if skip_params is None:
+            skip_params = set()
+
+        valid_kwargs = {}
+
+        has_kwargs = any(
+            p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+        )
+
+        for k, v in kwargs.items():
+            if k in sig.parameters or has_kwargs:
+                if k not in skip_params:
+                    valid_kwargs[k] = v
+
+        return valid_kwargs
+
+    async def _create_session(self) -> tuple[str, Environment]:
+        """
+        Create a new WebSocket session with its own environment instance.
+
+        Returns:
+            Tuple of (session_id, environment)
 
-            # Deserialize action
-            action = self._deserialize_action(action_data)
+        Raises:
+            SessionCapacityError: If max concurrent sessions reached
+            EnvironmentFactoryError: If the factory fails to create an environment
+        """
+        async with self._session_lock:
+            if len(self._sessions) >= self._max_concurrent_envs:
+                raise SessionCapacityError(
+                    active_sessions=len(self._sessions),
+                    max_sessions=self._max_concurrent_envs,
+                )
 
-            # Execute step
-            observation = self.env.step(action)
+            session_id = str(uuid.uuid4())
+            current_time = time.time()
 
-            # Return serialized observation
-            return self._serialize_observation(observation)
+            # Create executor and reserve slot so capacity is not exceeded while
+            # we create the env outside the lock (avoids blocking other sessions)
+            executor = ThreadPoolExecutor(max_workers=1)
+            self._session_executors[session_id] = executor
+            self._sessions[session_id] = None  # placeholder until env is ready
 
-        @app.get("/state")
-        async def get_state() -> Dict[str, Any]:
-            """State endpoint - returns current environment state."""
-            state = self.env.state
-            return asdict(state)
+        try:
+            # Create environment in the executor thread (outside lock)
+            loop = asyncio.get_event_loop()
+            env = await loop.run_in_executor(executor, self._env_factory)
+        except Exception as e:
+            async with self._session_lock:
+                executor.shutdown(wait=False)
+                self._session_executors.pop(session_id, None)
+                self._sessions.pop(session_id, None)
+            factory_name = getattr(
+                self._env_factory, "__name__", str(self._env_factory)
+            )
+            raise EnvironmentFactoryError(factory_name) from e
 
-        @app.get("/health")
-        async def health() -> Dict[str, str]:
-            """Health check endpoint."""
-            return {"status": "healthy"}
+        async with self._session_lock:
+            self._sessions[session_id] = env
+            self._session_info[session_id] = SessionInfo(
+                session_id=session_id,
+                created_at=current_time,
+                last_activity_at=current_time,
+                step_count=0,
+                environment_type=type(env).__name__,
+            )
 
+        return session_id, env
 
-    def _deserialize_action(self, action_data: Dict[str, Any]) -> Action:
+    async def _destroy_session(self, session_id: str) -> None:
         """
-        Convert JSON dict to Action instance.
+        Destroy a WebSocket session and cleanup resources.
 
         Args:
-            action_data: Dictionary containing action data
+            session_id: The session ID to destroy
+        """
+        async with self._session_lock:
+            env = self._sessions.pop(session_id, None)
+            executor = self._session_executors.pop(session_id, None)
+            self._session_info.pop(session_id, None)
 
-        Returns:
-            Action instance
+        # Run close() in the same executor where the env was created
+        # This is required for thread-sensitive libraries like Playwright/greenlet
+        if env is not None:
+            if executor is not None:
+                try:
+                    loop = asyncio.get_event_loop()
+                    await loop.run_in_executor(executor, env.close)
+                except Exception:
+                    # If executor close fails, try direct close as fallback
+                    try:
+                        env.close()
+                    except Exception:
+                        pass  # Best effort cleanup
+            else:
+                try:
+                    env.close()
+                except Exception:
+                    pass  # Best effort cleanup
+
+        # Shutdown executor after close is done
+        if executor is not None:
+            executor.shutdown(wait=False)
+
+    def _update_session_activity(
+        self, session_id: str, increment_step: bool = False
+    ) -> None:
+        """
+        Update session activity timestamp and optionally increment step count.
 
-        Note:
-            This is a simple implementation. Subclasses may need to override
-            for more complex deserialization logic.
+        Args:
+            session_id: The session ID to update
+            increment_step: If True, increment the step count
         """
-        # Remove metadata if present (it will be set via kw_only field)
-        metadata = action_data.pop("metadata", {})
-        action = self.action_cls(**action_data)
-        action.metadata = metadata
-        return action
+        if session_id in self._session_info:
+            self._session_info[session_id].last_activity_at = time.time()
+            if increment_step:
+                self._session_info[session_id].step_count += 1
 
-    def _serialize_observation(self, observation: Observation) -> Dict[str, Any]:
+    def get_session_info(self, session_id: str) -> Optional[SessionInfo]:
         """
-        Convert Observation instance to JSON-compatible dict.
+        Get information about a specific session.
 
         Args:
-            observation: Observation instance
+            session_id: The session ID to query
 
         Returns:
-            Dictionary compatible with HTTPEnvClient._parse_result()
+            SessionInfo if the session exists, None otherwise
+        """
+        return self._session_info.get(session_id)
+
+    async def _run_in_session_executor(
+        self, session_id: str, func: Callable[..., Observation], *args, **kwargs
+    ) -> Observation:
+        """Run a synchronous function in the session's thread pool executor."""
+        executor = self._session_executors.get(session_id, self._executor)
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(executor, lambda: func(*args, **kwargs))
+
+    @property
+    def active_sessions(self) -> int:
+        """Return the number of active WebSocket sessions."""
+        return len(self._sessions)
+
+    @property
+    def max_concurrent_envs(self) -> int:
+        """Return the maximum number of concurrent environments."""
+        return self._max_concurrent_envs
+
+    @property
+    def is_concurrency_safe(self) -> bool:
+        """Return whether the environment is marked as concurrency safe."""
+        import inspect
 
-        The format matches what HTTPEnvClient expects:
-        {
-            "observation": {...},  # Observation fields
-            "reward": float | None,
-            "done": bool,
-        }
+        if inspect.isclass(self._env_factory):
+            return getattr(self._env_factory, "SUPPORTS_CONCURRENT_SESSIONS", False)
+        else:
+            _temp_env = self._env_factory()
+            result = getattr(_temp_env, "SUPPORTS_CONCURRENT_SESSIONS", False)
+            _temp_env.close()
+            del _temp_env
+            return result
+
+    @property
+    def concurrency_config(self) -> ConcurrencyConfig:
+        """Return the concurrency configuration."""
+        return self._concurrency_config
+
+    def register_routes(
+        self, app: FastAPI, mode: ServerMode | str = ServerMode.SIMULATION
+    ) -> None:
         """
-        obs_dict = asdict(observation)
+        Register HTTP routes on a FastAPI application.
+
+        Args:
+            app: FastAPI application instance
+            mode: Server mode - either SIMULATION or PRODUCTION (or string equivalents).
+                  In production mode, simulation control endpoints (/reset, /step, /state)
+                  are NOT registered. Only safe endpoints (/health, /schema, /metadata, /ws)
+                  are available. Defaults to SIMULATION for backwards compatibility.
+
+        Raises:
+            ValueError: If mode is not a valid ServerMode or string equivalent.
+        """
+        # Convert string to ServerMode enum for backwards compatibility
+        if isinstance(mode, str):
+            try:
+                mode = ServerMode(mode.lower())
+            except ValueError:
+                valid_modes = [m.value for m in ServerMode]
+                raise ValueError(
+                    f"Invalid mode: '{mode}'. Must be one of: {valid_modes}"
+                )
+
+        # Helper function to handle reset endpoint
+        async def reset_handler(
+            request: ResetRequest = Body(default_factory=ResetRequest),
+        ) -> ResetResponse:
+            """Reset endpoint - returns initial observation."""
+            _env = self._env_factory()
+
+            try:
+                kwargs = request.model_dump(exclude_unset=True)
+
+                is_async = _env.reset_async.__func__ is not Environment.reset_async
+
+                if is_async:
+                    sig = inspect.signature(_env.reset_async)
+                else:
+                    sig = inspect.signature(_env.reset)
+                valid_kwargs = self._get_valid_kwargs(sig, kwargs)
+
+                if is_async:
+                    observation = await _env.reset_async(**valid_kwargs)
+                else:
+                    observation = await self._run_sync_in_thread_pool(
+                        _env.reset, **valid_kwargs
+                    )
+                return ResetResponse(**serialize_observation(observation))
+            finally:
+                _env.close()
+
+        # Helper function to handle step endpoint
+        async def step_handler(request: StepRequest) -> StepResponse:
+            """Step endpoint - executes action and returns observation."""
+            action_data = request.action
+
+            try:
+                action = deserialize_action(action_data, self.action_cls)
+            except ValidationError as e:
+                raise HTTPException(
+                    status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=e.errors()
+                )
+
+            _env = self._env_factory()
+
+            try:
+                kwargs = request.model_dump(exclude_unset=True, exclude={"action"})
+
+                is_async = _env.step_async.__func__ is not Environment.step_async
+
+                if is_async:
+                    sig = inspect.signature(_env.step_async)
+                else:
+                    sig = inspect.signature(_env.step)
+                valid_kwargs = self._get_valid_kwargs(
+                    sig, kwargs, skip_params={"action"}
+                )
+
+                if is_async:
+                    observation = await _env.step_async(action, **valid_kwargs)
+                else:
+                    observation = await self._run_sync_in_thread_pool(
+                        _env.step, action, **valid_kwargs
+                    )
+
+                return StepResponse(**serialize_observation(observation))
+            finally:
+                _env.close()
+
+        # Helper function to handle MCP endpoint
+        async def mcp_handler(
+            request: JsonRpcRequest, session_env: Optional[Environment] = None
+        ) -> JsonRpcResponse:
+            """
+            Handle MCP JSON-RPC requests.
+
+            Supports tools/list and tools/call methods in JSON-RPC 2.0 format.
+            """
+            method = request.method
+            request_id = request.id
+
+            # Use provided session environment or create temporary one
+            if session_env is not None:
+                _env = session_env
+                should_close = False
+            else:
+                _env = self._env_factory()
+                should_close = True
+            try:
+                if method == McpMethod.TOOLS_LIST:
+                    # Check if environment is MCP-enabled
+                    if not hasattr(_env, "mcp_client"):
+                        return JsonRpcResponse.error_response(
+                            JsonRpcErrorCode.INTERNAL_ERROR,
+                            "Environment does not support MCP",
+                            request_id=request_id,
+                        )
+
+                    # Use async context manager for MCP client
+                    async with _env.mcp_client:
+                        tools = await _env.mcp_client.list_tools()
+
+                    return JsonRpcResponse.success(
+                        result={
+                            "tools": [
+                                t.model_dump() if hasattr(t, "model_dump") else dict(t)
+                                for t in tools
+                            ]
+                        },
+                        request_id=request_id,
+                    )
+
+                elif method == McpMethod.TOOLS_CALL:
+                    params = request.params
+                    tool_name = params.get("name")
+                    arguments = params.get("arguments", {})
+
+                    if not hasattr(_env, "mcp_client"):
+                        return JsonRpcResponse.error_response(
+                            JsonRpcErrorCode.INTERNAL_ERROR,
+                            "Environment does not support MCP",
+                            request_id=request_id,
+                        )
+
+                    if not tool_name:
+                        return JsonRpcResponse.error_response(
+                            JsonRpcErrorCode.INVALID_REQUEST,
+                            "Missing 'name' in params",
+                            request_id=request_id,
+                        )
+
+                    # Use async context manager for MCP client
+                    async with _env.mcp_client:
+                        result = await _env.mcp_client.call_tool(
+                            name=tool_name, arguments=arguments
+                        )
+
+                    # Ensure result is JSON serializable
+                    serializable_result = _make_json_serializable(result)
 
-        # Extract reward and done (these are part of StepResult on client side)
-        reward = obs_dict.pop("reward", None)
-        done = obs_dict.pop("done", False)
-        obs_dict.pop("metadata", None)  # Remove metadata from observation
+                    return JsonRpcResponse.success(
+                        result=serializable_result,
+                        request_id=request_id,
+                    )
+
+                else:
+                    return JsonRpcResponse.error_response(
+                        JsonRpcErrorCode.METHOD_NOT_FOUND,
+                        f"Method not found: {method}",
+                        request_id=request_id,
+                    )
+
+            except Exception as e:
+                return JsonRpcResponse.error_response(
+                    JsonRpcErrorCode.INTERNAL_ERROR,
+                    str(e),
+                    request_id=request_id,
+                )
+            finally:
+                if should_close:
+                    _env.close()
+
+        # Register MCP WebSocket endpoint (available in both production and simulation modes)
+        @app.websocket("/mcp")
+        async def mcp_websocket_endpoint(websocket: WebSocket):
+            """
+            WebSocket endpoint for MCP JSON-RPC requests.
+
+            Each WebSocket connection gets its own environment instance for MCP operations.
+
+            Message Protocol:
+            - Client sends: JSON-RPC 2.0 request (tools/list, tools/call)
+            - Server responds: JSON-RPC 2.0 response (result or error)
+            """
+            await websocket.accept()
+
+            session_id = None
+            session_env = None
+
+            try:
+                # Create session with dedicated environment
+                session_id, session_env = await self._create_session()
+
+                while True:
+                    # Receive message from client
+                    raw_message = await websocket.receive_text()
+
+                    try:
+                        jsonrpc_dict = json.loads(raw_message)
+                        jsonrpc_request = JsonRpcRequest(**jsonrpc_dict)
+                    except json.JSONDecodeError as e:
+                        error_resp = JsonRpcResponse.error_response(
+                            JsonRpcErrorCode.PARSE_ERROR,
+                            f"Parse error: {e}",
+                        )
+                        await websocket.send_text(error_resp.model_dump_json())
+                        continue
+                    except ValidationError as e:
+                        error_resp = JsonRpcResponse.error_response(
+                            JsonRpcErrorCode.INVALID_REQUEST,
+                            f"Invalid request: {e}",
+                        )
+                        await websocket.send_text(error_resp.model_dump_json())
+                        continue
+
+                    try:
+                        # Call mcp_handler with session environment
+                        response = await mcp_handler(
+                            jsonrpc_request, session_env=session_env
+                        )
+                        await websocket.send_text(response.model_dump_json())
+                    except Exception as e:
+                        error_resp = JsonRpcResponse.error_response(
+                            JsonRpcErrorCode.INTERNAL_ERROR,
+                            str(e),
+                            request_id=jsonrpc_request.id,
+                        )
+                        await websocket.send_text(error_resp.model_dump_json())
+
+            except WebSocketDisconnect:
+                pass
+            except SessionCapacityError as e:
+                error_resp = JsonRpcResponse.error_response(
+                    JsonRpcErrorCode.SERVER_ERROR,
+                    str(e),
+                    data={
+                        "active_sessions": e.active_sessions,
+                        "max_sessions": e.max_sessions,
+                    },
+                )
+                await websocket.send_text(error_resp.model_dump_json())
+            except EnvironmentFactoryError as e:
+                error_resp = JsonRpcResponse.error_response(
+                    JsonRpcErrorCode.SERVER_ERROR,
+                    str(e),
+                    data={"factory_name": e.factory_name},
+                )
+                await websocket.send_text(error_resp.model_dump_json())
+            except Exception as e:
+                error_resp = JsonRpcResponse.error_response(
+                    JsonRpcErrorCode.SERVER_ERROR,
+                    str(e),
+                )
+                await websocket.send_text(error_resp.model_dump_json())
+            finally:
+                if session_id:
+                    await self._destroy_session(session_id)
+                try:
+                    await websocket.close()
+                except RuntimeError:
+                    pass
+
+        # Register simulation control routes only in simulation mode
+        if mode == ServerMode.SIMULATION:
+
+            @app.post(
+                "/reset",
+                response_model=ResetResponse,
+                tags=["Environment Control"],
+                summary="Reset the environment",
+                description="""
+Reset the environment to its initial state and return the first observation.
+
+You can optionally provide a seed for reproducibility and an episode_id for tracking.
+                """,
+                responses={
+                    200: {
+                        "description": "Environment reset successfully",
+                        "content": {
+                            "application/json": {
+                                "example": {
+                                    "observation": {"status": "ready", "data": {}},
+                                    "reward": None,
+                                    "done": False,
+                                }
+                            }
+                        },
+                    }
+                },
+            )
+            async def reset(
+                request: ResetRequest = Body(default_factory=ResetRequest),
+            ) -> ResetResponse:
+                return await reset_handler(request)
+
+            @app.post(
+                "/step",
+                response_model=StepResponse,
+                tags=["Environment Control"],
+                summary="Execute an action in the environment",
+                description="""
+Execute an action in the environment and receive the resulting observation.
+
+The action must conform to the environment's action schema, which can be
+retrieved from the `/schema` endpoint. If the action is invalid,
+the endpoint will return HTTP 422 with detailed validation errors.
+
+The response includes:
+- **observation**: The environment's response to the action
+- **reward**: Optional reward signal (float or None)
+- **done**: Boolean indicating if the episode has terminated
+                """,
+                responses={
+                    200: {
+                        "description": "Action executed successfully",
+                        "content": {
+                            "application/json": {
+                                "example": {
+                                    "observation": {"status": "success", "data": {}},
+                                    "reward": 1.0,
+                                    "done": False,
+                                }
+                            }
+                        },
+                    },
+                    422: {
+                        "description": "Validation error - invalid action format or values",
+                        "content": {
+                            "application/json": {
+                                "example": {
+                                    "detail": [
+                                        {
+                                            "type": "string_too_short",
+                                            "loc": ["body", "action", "message"],
+                                            "msg": "String should have at least 1 character",
+                                            "input": "",
+                                        }
+                                    ]
+                                }
+                            }
+                        },
+                    },
+                    500: {
+                        "description": "Internal server error during action execution"
+                    },
+                },
+            )
+            async def step(request: StepRequest) -> StepResponse:
+                return await step_handler(request)
+
+        def get_state_handler() -> State:
+            _env = self._env_factory()
+            try:
+                return _env.state
+            finally:
+                _env.close()
+
+        def get_metadata_handler() -> EnvironmentMetadata:
+            _env = self._env_factory()
+            try:
+                return _env.get_metadata()
+            finally:
+                _env.close()
+
+        # Build list of GET endpoints based on mode
+        get_endpoints = [
+            GetEndpointConfig(
+                path="/metadata",
+                handler=get_metadata_handler,
+                response_model=EnvironmentMetadata,
+                tag="Environment Info",
+                summary="Get environment metadata",
+                description="""
+Get metadata about this environment.
+
+Returns information about the environment including name, description,
+version, author, and documentation links.
+                """,
+            ),
+            GetEndpointConfig(
+                path="/health",
+                handler=lambda: HealthResponse(status=HealthStatus.HEALTHY),
+                response_model=HealthResponse,
+                tag="Health",
+                summary="Health check",
+                description="Check if the environment server is running and healthy.",
+            ),
+        ]
+
+        # Only register /state endpoint in simulation mode
+        if mode == ServerMode.SIMULATION:
+            get_endpoints.insert(
+                0,
+                GetEndpointConfig(
+                    path="/state",
+                    handler=get_state_handler,
+                    response_model=State,
+                    tag="State Management",
+                    summary="Get current environment state",
+                    description="""
+Retrieve the current internal state of the environment.
+
+The structure of the state object is defined by the environment's State model.
+                    """,
+                ),
+            )
+
+        register_get_endpoints(app, get_endpoints)
+
+        # Register combined schema endpoint
+        @app.get(
+            "/schema",
+            response_model=SchemaResponse,
+            tags=["Schema"],
+            summary="Get all JSON schemas",
+            description="""
+Get JSON schemas for actions, observations, and state in a single response.
+
+Returns a combined schema object containing:
+- **action**: JSON schema for actions accepted by this environment
+- **observation**: JSON schema for observations returned by this environment
+- **state**: JSON schema for environment state objects
+
+This is more efficient than calling individual schema endpoints and provides
+all schema information needed to interact with the environment.
+            """,
+            responses={
+                200: {
+                    "description": "Combined schemas retrieved successfully",
+                    "content": {
+                        "application/json": {
+                            "example": {
+                                "action": {
+                                    "type": "object",
+                                    "properties": {"message": {"type": "string"}},
+                                },
+                                "observation": {
+                                    "type": "object",
+                                    "properties": {"response": {"type": "string"}},
+                                },
+                                "state": {
+                                    "type": "object",
+                                    "properties": {"step_count": {"type": "integer"}},
+                                },
+                            }
+                        }
+                    },
+                }
+            },
+        )
+        async def get_schemas() -> SchemaResponse:
+            """Return all schemas in one response."""
+            return SchemaResponse(
+                action=self.action_cls.model_json_schema(),
+                observation=self.observation_cls.model_json_schema(),
+                state=State.model_json_schema(),
+            )
+
+        # Register MCP endpoint for production mode (direct MCP access)
+        @app.post("/mcp")
+        async def mcp_endpoint(request_raw: Request) -> Dict[str, Any]:
+            """
+            MCP JSON-RPC endpoint for production mode.
+
+            Bypasses step() overhead and provides direct access to MCP tools.
+            Supports tools/list and tools/call methods.
+            """
+            # Parse JSON manually to handle parse errors gracefully
+            try:
+                body = await request_raw.body()
+                request_dict = json.loads(body)
+                request = JsonRpcRequest(**request_dict)
+            except json.JSONDecodeError:
+                return JsonRpcResponse.error_response(
+                    JsonRpcErrorCode.PARSE_ERROR
+                ).model_dump()
+            except ValidationError as e:
+                return JsonRpcResponse.error_response(
+                    JsonRpcErrorCode.INVALID_REQUEST,
+                    f"Invalid request: {e}",
+                ).model_dump()
+            except Exception:
+                return JsonRpcResponse.error_response(
+                    JsonRpcErrorCode.PARSE_ERROR
+                ).model_dump()
+
+            method = request.method
+            params = request.params
+            request_id = request.id
+
+            # Create a temporary environment for MCP access
+            _env = self._env_factory()
+
+            try:
+                # Check if environment supports MCP
+                if not hasattr(_env, "mcp_client") and not hasattr(_env, "mcp_server"):
+                    return JsonRpcResponse.error_response(
+                        JsonRpcErrorCode.INTERNAL_ERROR,
+                        "Environment does not support MCP",
+                        request_id=request_id,
+                    ).model_dump()
+
+                if method == McpMethod.TOOLS_LIST:
+                    # List tools from MCP server
+                    if hasattr(_env, "mcp_client") and _env.mcp_client:
+                        async with _env.mcp_client:
+                            tools = await _env.mcp_client.list_tools()
+                        return JsonRpcResponse.success(
+                            result={
+                                "tools": [
+                                    t.model_dump()
+                                    if hasattr(t, "model_dump")
+                                    else dict(t)
+                                    for t in tools
+                                ]
+                            },
+                            request_id=request_id,
+                        ).model_dump()
+                    elif hasattr(_env, "mcp_server") and _env.mcp_server:
+                        # Use server directly
+                        tools = []
+                        for tool_name, tool in get_server_tools(
+                            _env.mcp_server
+                        ).items():
+                            tool_dict = {
+                                "name": tool.name,
+                                "description": tool.description or "",
+                                "inputSchema": tool.parameters or {},
+                            }
+                            tools.append(tool_dict)
+                        return JsonRpcResponse.success(
+                            result={"tools": tools},
+                            request_id=request_id,
+                        ).model_dump()
+                    else:
+                        return JsonRpcResponse.error_response(
+                            JsonRpcErrorCode.INTERNAL_ERROR,
+                            "MCP server not available",
+                            request_id=request_id,
+                        ).model_dump()
+
+                elif method == McpMethod.TOOLS_CALL:
+                    tool_name = params.get("name")
+                    arguments = params.get("arguments", {})
+
+                    if not tool_name:
+                        return JsonRpcResponse.error_response(
+                            JsonRpcErrorCode.INVALID_PARAMS,
+                            "Invalid params - 'name' is required",
+                            request_id=request_id,
+                        ).model_dump()
+
+                    # Call tool via MCP
+                    if hasattr(_env, "mcp_client") and _env.mcp_client:
+                        async with _env.mcp_client:
+                            result = await _env.mcp_client.call_tool(
+                                name=tool_name, arguments=arguments
+                            )
+                    elif hasattr(_env, "mcp_server") and _env.mcp_server:
+                        # Call tool directly on FastMCP server
+                        server_tools = get_server_tools(_env.mcp_server)
+                        if tool_name in server_tools:
+                            tool = server_tools[tool_name]
+                            result = tool.fn(**arguments)
+                        else:
+                            return JsonRpcResponse.error_response(
+                                JsonRpcErrorCode.INVALID_PARAMS,
+                                f"Tool not found: {tool_name}",
+                                request_id=request_id,
+                            ).model_dump()
+                    else:
+                        return JsonRpcResponse.error_response(
+                            JsonRpcErrorCode.INTERNAL_ERROR,
+                            "MCP server not available",
+                            request_id=request_id,
+                        ).model_dump()
+
+                    # Make result JSON serializable
+                    serializable_result = _make_json_serializable(result)
+
+                    return JsonRpcResponse.success(
+                        result=serializable_result,
+                        request_id=request_id,
+                    ).model_dump()
+
+                else:
+                    return JsonRpcResponse.error_response(
+                        JsonRpcErrorCode.METHOD_NOT_FOUND,
+                        f"Method not found: {method}",
+                        request_id=request_id,
+                    ).model_dump()
+
+            except Exception as e:
+                return JsonRpcResponse.error_response(
+                    JsonRpcErrorCode.INTERNAL_ERROR,
+                    str(e),
+                    request_id=request_id,
+                ).model_dump()
+            finally:
+                _env.close()
+
+        # Register WebSocket endpoint for persistent sessions
+        @app.websocket("/ws")
+        async def websocket_endpoint(websocket: WebSocket):
+            """
+            WebSocket endpoint for persistent environment sessions.
+
+            Each WebSocket connection gets its own environment instance.
+
+            Message Protocol:
+            - Client sends: WSResetMessage | WSStepMessage | WSStateMessage | WSCloseMessage
+            - Server responds: WSObservationResponse | WSStateResponse | WSErrorResponse
+            """
+            await websocket.accept()
+
+            session_id = None
+            session_env = None
+
+            try:
+                # Create session with dedicated environment
+                session_id, session_env = await self._create_session()
+
+                while True:
+                    # Receive message from client
+                    raw_message = await websocket.receive_text()
+
+                    try:
+                        message_dict = json.loads(raw_message)
+                    except json.JSONDecodeError as e:
+                        error_resp = WSErrorResponse(
+                            data={
+                                "message": f"Invalid JSON: {e}",
+                                "code": WSErrorCode.INVALID_JSON,
+                            }
+                        )
+                        await websocket.send_text(error_resp.model_dump_json())
+                        continue
+
+                    msg_type = message_dict.get("type", "")
+
+                    try:
+                        match msg_type:
+                            case "reset":
+                                msg = WSResetMessage(**message_dict)
+
+                                is_async = (
+                                    session_env.reset_async.__func__
+                                    is not Environment.reset_async
+                                )
+
+                                if is_async:
+                                    sig = inspect.signature(session_env.reset_async)
+                                    valid_kwargs = self._get_valid_kwargs(sig, msg.data)
+                                    observation = await session_env.reset_async(
+                                        **valid_kwargs
+                                    )
+                                else:
+                                    sig = inspect.signature(session_env.reset)
+                                    valid_kwargs = self._get_valid_kwargs(sig, msg.data)
+                                    observation = await self._run_in_session_executor(
+                                        session_id, session_env.reset, **valid_kwargs
+                                    )
+
+                                self._update_session_activity(session_id)
+
+                                response = WSObservationResponse(
+                                    data=serialize_observation(observation),
+                                )
+
+                            case "step":
+                                msg = WSStepMessage(**message_dict)
+                                action = deserialize_action(msg.data, self.action_cls)
+
+                                is_async = (
+                                    session_env.step_async.__func__
+                                    is not Environment.step_async
+                                )
+
+                                if is_async:
+                                    observation = await session_env.step_async(action)
+                                else:
+                                    observation = await self._run_in_session_executor(
+                                        session_id, session_env.step, action
+                                    )
+
+                                self._update_session_activity(
+                                    session_id, increment_step=True
+                                )
+
+                                response = WSObservationResponse(
+                                    data=serialize_observation(observation)
+                                )
+
+                            case "state":
+                                msg = WSStateMessage(**message_dict)
+                                state = session_env.state
+                                if hasattr(state, "model_dump"):
+                                    state_data = state.model_dump()
+                                else:
+                                    state_data = dict(state) if state else {}
+
+                                response = WSStateResponse(data=state_data)
+
+                            case "close":
+                                msg = WSCloseMessage(**message_dict)
+                                break
+
+                            case "mcp":
+                                msg = WSMCPMessage(**message_dict)
+                                try:
+                                    rpc_request = JsonRpcRequest(**msg.data)
+                                except (ValidationError, Exception) as e:
+                                    rpc_response = JsonRpcResponse.error_response(
+                                        JsonRpcErrorCode.INVALID_REQUEST,
+                                        f"Invalid request: {e}",
+                                    )
+                                else:
+                                    rpc_response = await mcp_handler(
+                                        rpc_request,
+                                        session_env=session_env,
+                                    )
+                                response = WSMCPResponse(data=rpc_response.model_dump())
+
+                            case _:
+                                response = WSErrorResponse(
+                                    data={
+                                        "message": f"Unknown message type: {msg_type}",
+                                        "code": WSErrorCode.UNKNOWN_TYPE,
+                                    }
+                                )
+
+                        await websocket.send_text(response.model_dump_json())
+
+                    except ValidationError as e:
+                        error_resp = WSErrorResponse(
+                            data={
+                                "message": "Invalid message",
+                                "code": WSErrorCode.VALIDATION_ERROR,
+                                "errors": e.errors(),
+                            }
+                        )
+                        await websocket.send_text(error_resp.model_dump_json())
+                    except Exception as e:
+                        error_resp = WSErrorResponse(
+                            data={
+                                "message": str(e),
+                                "code": WSErrorCode.EXECUTION_ERROR,
+                            }
+                        )
+                        await websocket.send_text(error_resp.model_dump_json())
+
+            except WebSocketDisconnect:
+                pass
+            except SessionCapacityError as e:
+                error_resp = WSErrorResponse(
+                    data={
+                        "message": str(e),
+                        "code": WSErrorCode.CAPACITY_REACHED,
+                        "active_sessions": e.active_sessions,
+                        "max_sessions": e.max_sessions,
+                    }
+                )
+                await websocket.send_text(error_resp.model_dump_json())
+            except EnvironmentFactoryError as e:
+                error_resp = WSErrorResponse(
+                    data={
+                        "message": str(e),
+                        "code": WSErrorCode.FACTORY_ERROR,
+                        "factory_name": e.factory_name,
+                    }
+                )
+                await websocket.send_text(error_resp.model_dump_json())
+            except Exception as e:
+                error_resp = WSErrorResponse(
+                    data={"message": str(e), "code": WSErrorCode.SESSION_ERROR}
+                )
+                await websocket.send_text(error_resp.model_dump_json())
+            finally:
+                if session_id:
+                    await self._destroy_session(session_id)
+                try:
+                    await websocket.close()
+                except RuntimeError:
+                    pass
 
-        # Return in HTTPEnvClient expected format
-        return {
-            "observation": obs_dict,
-            "reward": reward,
-            "done": done,
-        }
 
 def create_app(
-    env: Environment,
+    env: Callable[[], Environment],
     action_cls: Type[Action],
     observation_cls: Type[Observation],
     env_name: Optional[str] = None,
-) -> Any:
+    max_concurrent_envs: Optional[int] = None,
+    concurrency_config: Optional[ConcurrencyConfig] = None,
+    gradio_builder: Optional[Callable[..., Any]] = None,
+) -> FastAPI:
     """
     Create a FastAPI application with or without web interface.
-    
+
     This function creates a FastAPI app with the web interface enabled by default,
     including README integration for better user experience.
-    
+
     Args:
-        env: The Environment instance to serve
+        env: Environment factory (callable) that creates new instances
         action_cls: The Action subclass this environment expects
         observation_cls: The Observation subclass this environment returns
         env_name: Optional environment name for README loading
-        
+        max_concurrent_envs: Maximum concurrent WebSocket sessions.
+                             Mutually exclusive with concurrency_config.
+        concurrency_config: Optional ConcurrencyConfig for advanced concurrency settings.
+                            Mutually exclusive with max_concurrent_envs.
+        gradio_builder: Optional callable to build a custom Gradio UI at /web.
+            Signature: (web_manager, action_fields, metadata, is_chat_env, title,
+            quick_start_md) -> gr.Blocks. When None, the default Gradio app is used.
+            See docs/customizing-web-ui.md.
+
     Returns:
         FastAPI application instance with or without web interface and README integration
     """
     # Check if web interface should be enabled
     # This can be controlled via environment variable or build argument
-    enable_web = (
-        os.getenv("ENABLE_WEB_INTERFACE", "false").lower() in ("true", "1", "yes")
+    enable_web = os.getenv("ENABLE_WEB_INTERFACE", "false").lower() in (
+        "true",
+        "1",
+        "yes",
     )
 
     if enable_web:
-        # Import web interface only when needed
+        # Gradio-based web UI (gradio is a core dependency)
         from .web_interface import create_web_interface_app
-        return create_web_interface_app(env, action_cls, observation_cls, env_name)
+
+        return create_web_interface_app(
+            env,
+            action_cls,
+            observation_cls,
+            env_name,
+            max_concurrent_envs,
+            concurrency_config,
+            gradio_builder=gradio_builder,
+        )
     else:
         # Use standard FastAPI app without web interface
-        return create_fastapi_app(env, action_cls, observation_cls)
-    
+        return create_fastapi_app(
+            env, action_cls, observation_cls, max_concurrent_envs, concurrency_config
+        )
+
 
 def create_fastapi_app(
-    env: Environment,
+    env: Callable[[], Environment],
     action_cls: Type[Action],
     observation_cls: Type[Observation],
-) -> Any:
+    max_concurrent_envs: Optional[int] = None,
+    concurrency_config: Optional[ConcurrencyConfig] = None,
+) -> FastAPI:
     """
-    Create a FastAPI application with routes for the given environment.
+    Create a FastAPI application with comprehensive documentation.
 
     Args:
-        env: The Environment instance to serve
+        env: Environment factory (callable) that creates new instances
         action_cls: The Action subclass this environment expects
         observation_cls: The Observation subclass this environment returns
+        max_concurrent_envs: Maximum concurrent WebSocket sessions.
+                             Mutually exclusive with concurrency_config.
+        concurrency_config: Optional ConcurrencyConfig for advanced concurrency settings.
+                            Mutually exclusive with max_concurrent_envs.
 
     Returns:
-        FastAPI application instance with routes registered
-
-    Example:
-        >>> from envs.coding_env.server import CodeExecutionEnvironment
-        >>> from envs.coding_env.models import CodeAction, CodeObservation
-        >>>
-        >>> env = CodeExecutionEnvironment()
-        >>> app = create_fastapi_app(env, CodeAction, CodeObservation)
-        >>>
-        >>> # Run with: uvicorn module:app --host 0.0.0.0 --port 8000
+        FastAPI application instance
     """
     try:
         from fastapi import FastAPI
@@ -227,7 +1320,72 @@ def create_fastapi_app(
             "FastAPI is required. Install with: pip install fastapi uvicorn"
         )
 
-    app = FastAPI(title="Environment HTTP Server")
-    server = HTTPEnvServer(env, action_cls, observation_cls)
+    app = FastAPI(
+        title="OpenEnv Environment HTTP API",
+        version="1.0.0",
+        description="""
+# OpenEnv Environment HTTP API
+
+HTTP API for interacting with OpenEnv environments through a standardized interface.
+
+## Features
+
+* **Environment Reset**: Initialize or restart episodes
+* **Action Execution**: Send actions and receive observations
+* **State Inspection**: Query current environment state
+* **Schema Access**: Retrieve JSON schemas for actions and observations
+
+## Workflow
+
+1. Call `/reset` to start a new episode and get initial observation
+2. Call `/step` repeatedly with actions to interact with environment
+3. Episode ends when observation returns `done: true`
+4. Call `/state` anytime to inspect current environment state
+
+## Documentation
+
+* **Swagger UI**: Available at `/docs`
+* **ReDoc**: Available at `/redoc`
+* **OpenAPI Schema**: Available at `/openapi.json`
+        """,
+        openapi_tags=[
+            {
+                "name": "Environment Control",
+                "description": "Core operations for environment interaction (reset, step)",
+            },
+            {
+                "name": "State Management",
+                "description": "Operations for inspecting environment state",
+            },
+            {
+                "name": "Environment Info",
+                "description": "Information about the environment",
+            },
+            {
+                "name": "Schema",
+                "description": "JSON Schema endpoints for actions, observations, and state",
+            },
+            {"name": "Health", "description": "Service health and status checks"},
+        ],
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/openapi.json",
+        contact={
+            "name": "OpenEnv Team",
+            "url": "https://github.com/meta-pytorch/OpenEnv",
+        },
+        license_info={
+            "name": "BSD-3-Clause",
+            "url": "https://github.com/meta-pytorch/OpenEnv/blob/main/LICENSE",
+        },
+    )
+
+    server = HTTPEnvServer(
+        env,
+        action_cls,
+        observation_cls,
+        max_concurrent_envs,
+        concurrency_config=concurrency_config,
+    )
     server.register_routes(app)
     return app

src/core/env_server/interfaces.py

@@ -4,10 +4,20 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
+import inspect
 from abc import ABC, abstractmethod
-from typing import Any, Protocol, TypedDict
+from typing import Any, Generic, Optional, Protocol, TYPE_CHECKING, TypeVar
 
-from .types import Action, Observation, State
+from typing_extensions import TypedDict
+
+from .types import Action, EnvironmentMetadata, Observation, State
+
+if TYPE_CHECKING:
+    from openenv.core.rubrics import Rubric
+
+ActT = TypeVar("ActT", bound=Action)
+ObsT = TypeVar("ObsT", bound=Observation)
+StateT = TypeVar("StateT", bound=State)
 
 
 class Message(TypedDict):
@@ -64,7 +74,7 @@ class ModelTokenizer(Protocol):
         ...
 
 
-class Transform(ABC):
+class Transform(ABC, Generic[ObsT]):
     """Transform observations to add rewards, metrics, or other modifications.
 
     Transforms follow the TorchRL pattern where they take an observation
@@ -73,7 +83,7 @@ class Transform(ABC):
     """
 
     @abstractmethod
-    def __call__(self, observation: Observation) -> Observation:
+    def __call__(self, observation: ObsT) -> ObsT:
         """Transform an observation.
 
         Args:
@@ -85,34 +95,203 @@ class Transform(ABC):
         pass
 
 
-class Environment(ABC):
+class Environment(ABC, Generic[ActT, ObsT, StateT]):
     """Base class for all environment servers following Gym/Gymnasium API.
 
     Args:
         transform: Optional transform to apply to observations
+        rubric: Optional rubric for reward computation. When provided, the
+            rubric's output can be used to set the observation's reward in step().
+
+    Class Attributes:
+        SUPPORTS_CONCURRENT_SESSIONS: Whether this environment supports concurrent sessions.
+            When True, multiple WebSocket connections can each have their own
+            environment instance (up to max_concurrent_envs). When False (default),
+            the environment should only be used with a single session at a time.
+
+            Set this to True in your Environment subclass if:
+            - The environment uses proper session isolation (e.g., unique working dirs)
+            - No shared mutable state exists between instances
+            - External resources (databases, APIs) can handle concurrent access
+
+    Attributes:
+        rubric: Optional rubric for computing rewards. Environments can set this
+            in __init__ and use it in step() to compute observation rewards.
+            Training infrastructure can access it for introspection:
+                for name, r in env.rubric.named_rubrics():
+                    print(f"{name}: {r.last_score}")
+
+    See RFC 004 for rubric design: rfcs/004-rubrics.md
     """
 
-    def __init__(self, transform: Transform | None = None):
+    # Class-level flag indicating whether this environment supports concurrent sessions
+    SUPPORTS_CONCURRENT_SESSIONS: bool = False
+
+    # Optional rubric for reward computation
+    rubric: Optional["Rubric"]
+
+    def __init__(
+        self,
+        transform: Optional[Transform[ObsT]] = None,
+        rubric: Optional["Rubric"] = None,
+    ):
         self.transform = transform
+        self.rubric = rubric
 
     @abstractmethod
-    def reset(self) -> Observation:
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> ObsT:
         """Reset the environment and return initial observation."""
         pass
 
+    async def reset_async(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> ObsT:
+        """Async version of reset. Default implementation calls sync reset.
+
+        Override to provide true async implementation.
+        """
+        return self.reset(seed=seed, episode_id=episode_id, **kwargs)
+
     @abstractmethod
-    def step(self, action: Action) -> Observation:
+    def step(
+        self,
+        action: ActT,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> ObsT:
         """Take a step in the environment."""
         pass
 
+    async def step_async(
+        self,
+        action: ActT,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> ObsT:
+        """Async version of step. Default implementation calls sync step.
+
+        Override to provide true async implementation.
+        """
+        return self.step(action, timeout_s=timeout_s, **kwargs)
+
     @property
     @abstractmethod
-    def state(self) -> State:
+    def state(self) -> StateT:
         """Get the current environment state."""
         pass
 
-    def _apply_transform(self, observation: Observation) -> Observation:
+    def get_metadata(self) -> EnvironmentMetadata:
+        """
+        Get metadata about this environment.
+
+        Override this method to provide custom metadata for the environment.
+        Default implementation returns basic metadata derived from class name.
+
+        Returns:
+            EnvironmentMetadata with environment information
+        """
+        return EnvironmentMetadata(
+            name=self.__class__.__name__,
+            description=f"{self.__class__.__name__} environment",
+            version="1.0.0",
+        )
+
+    def _apply_transform(self, observation: ObsT) -> ObsT:
         """Apply transform if one is provided."""
         if self.transform is not None:
             return self.transform(observation)
         return observation
+
+    def _apply_rubric(self, action: ActT, observation: ObsT) -> float:
+        """Apply rubric if one is provided.
+
+        Args:
+            action: The action taken by the agent.
+            observation: The resulting observation.
+
+        Returns:
+            Reward value from the rubric, or 0.0 if no rubric is set.
+
+        Usage in step():
+            def step(self, action: MyAction, ...) -> MyObservation:
+                # ... execute action and create observation ...
+                observation.reward = self._apply_rubric(action, observation)
+                return observation
+        """
+        if self.rubric is not None:
+            return self.rubric(action, observation)
+        return 0.0
+
+    async def _apply_rubric_async(self, action: ActT, observation: ObsT) -> float:
+        """Apply rubric asynchronously if one is provided.
+
+        Args:
+            action: The action taken by the agent.
+            observation: The resulting observation.
+
+        Returns:
+            Reward value from the rubric, or 0.0 if no rubric is set.
+
+        Usage in step_async():
+            async def step_async(self, action: MyAction, ...) -> MyObservation:
+                # ... execute action and create observation ...
+                observation.reward = await self._apply_rubric_async(action, observation)
+                return observation
+        """
+        if self.rubric is not None:
+            result = self.rubric(action, observation)
+            # If rubric returns a coroutine, await it
+            if inspect.iscoroutine(result):
+                return await result
+            return result
+        return 0.0
+
+    def _reset_rubric(self) -> None:
+        """Reset the rubric state if one is provided.
+
+        Call this in reset() to clear any trajectory state in the rubric.
+
+        Usage in reset():
+            def reset(self, ...) -> MyObservation:
+                self._reset_rubric()
+                # ... create initial observation ...
+                return observation
+        """
+        if self.rubric is not None:
+            self.rubric.reset()
+
+    async def _reset_rubric_async(self) -> None:
+        """Reset the rubric state asynchronously if one is provided.
+
+        Call this in reset_async() to clear any trajectory state in the rubric.
+
+        Usage in reset_async():
+            async def reset_async(self, ...) -> MyObservation:
+                await self._reset_rubric_async()
+                # ... create initial observation ...
+                return observation
+        """
+        if self.rubric is not None:
+            # Check if rubric has async reset method
+            if hasattr(self.rubric, "reset_async"):
+                result = self.rubric.reset_async()
+                if inspect.iscoroutine(result):
+                    await result
+            else:
+                self.rubric.reset()
+
+    def close(self) -> None:
+        """Clean up resources used by the environment.
+
+        Override this method to implement custom cleanup logic.
+        Called when the environment is being destroyed or reset.
+        """
+        pass

src/core/env_server/mcp_environment.py

@@ -0,0 +1,624 @@
+# 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.
+
+"""
+MCP Environment base class for OpenEnv.
+
+This module provides the MCPEnvironment base class that integrates FastMCP servers
+with OpenEnv's Gym-style Environment interface. It handles MCP tool discovery
+and invocation through the step() API, following RFC 003.
+
+Key features:
+- Automatic routing of ListToolsAction and CallToolAction to MCP server
+- Reserved tool name validation (reset, step, state, close are protected)
+- Timeout handling for tool calls
+- Proper error categorization (tool not found, execution errors, timeouts)
+- Mode-aware tool registration (production vs simulation)
+- Code mode support via get_callables() and execute_code()
+
+Usage:
+    from fastmcp import FastMCP
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+
+    class MyMCPEnv(MCPEnvironment):
+        def __init__(self):
+            mcp = FastMCP("my-server")
+
+            # Register mode-specific tools
+            @self.tool(mode="production")
+            def my_tool(arg: str) -> str:
+                return f"Production: {arg}"
+
+            @self.tool(mode="simulation")
+            def my_tool(arg: str) -> str:
+                return f"Simulation: {arg}"
+
+            super().__init__(mcp)
+
+        def reset(self, seed=None, episode_id=None, **kwargs):
+            # Reset logic here
+            ...
+
+        def _step_impl(self, action):
+            # Handle non-MCP actions
+            ...
+
+        @property
+        def state(self):
+            # Return current state
+            ...
+"""
+
+import asyncio
+import inspect
+from abc import abstractmethod
+from collections import defaultdict
+from typing import Any, Callable, Dict, Optional
+
+from fastmcp import Client
+from fastmcp.client.client import CallToolResult
+from mcp.types import TextContent
+
+from ..utils import run_async_safely
+from .interfaces import Environment
+from .mcp_types import (
+    CallToolAction,
+    CallToolObservation,
+    ListToolsAction,
+    ListToolsObservation,
+    RESERVED_TOOL_NAMES,
+    Tool,
+    ToolError,
+    ToolErrorType,
+)
+from .types import Action, Observation
+
+
+# Default timeout for MCP tool calls in seconds
+MCP_TOOL_CALL_TIMEOUT = 30.0
+
+# Valid modes for tool registration
+VALID_MODES = {"production", "simulation"}
+
+
+def get_server_tools(mcp_server: Any) -> Dict[str, Any]:
+    """
+    Get tools from a FastMCP server, compatible with both 2.x and 3.x.
+
+    Returns:
+        Dictionary mapping tool names to tool objects.
+    """
+    # FastMCP 2.x: get_tools() returns dict {name: Tool}
+    if hasattr(mcp_server, "get_tools"):
+        result = run_async_safely(mcp_server.get_tools())
+        if isinstance(result, dict):
+            return result
+    # FastMCP 3.x: list_tools() returns list of Tool objects
+    if hasattr(mcp_server, "list_tools"):
+        tools_list = run_async_safely(mcp_server.list_tools())
+        return {t.name: t for t in tools_list}
+    return {}
+
+
+class MCPEnvironment(Environment):
+    """
+    Base class for environments that expose tools via MCP (Model Context Protocol).
+
+    MCPEnvironment bridges FastMCP servers with OpenEnv's Gym-style API, allowing
+    agents to discover and invoke MCP tools through the standard step() interface.
+
+    The class automatically handles:
+    - ListToolsAction: Returns available tools from the MCP server
+    - CallToolAction: Invokes a specific tool with arguments
+
+    All other actions are delegated to the abstract _step_impl() method,
+    which subclasses must implement.
+
+    Args:
+        mcp_server: A FastMCP server instance containing tool definitions.
+            The server's tools will be validated against reserved names.
+        transform: Optional transform to apply to observations (inherited from Environment).
+
+    Raises:
+        ValueError: If any tool in the MCP server uses a reserved name
+            (reset, step, state, close).
+
+    Example:
+        >>> from fastmcp import FastMCP
+        >>> mcp = FastMCP("calculator")
+        >>> @mcp.tool()
+        ... def add(a: int, b: int) -> int:
+        ...     return a + b
+        >>> env = MyMCPEnvironment(mcp)
+        >>> obs = env.step(ListToolsAction())
+        >>> obs.tools[0].name
+        'add'
+    """
+
+    def __init__(self, mcp_server: Any, transform: Optional[Any] = None) -> None:
+        """
+        Initialize the MCP environment.
+
+        Args:
+            mcp_server: A FastMCP server instance with tool definitions.
+            transform: Optional transform to apply to observations.
+
+        Raises:
+            ValueError: If any tool uses a reserved name (reset, step, state, close).
+        """
+        super().__init__(transform=transform)
+
+        # Validate tool names before storing
+        self._validate_tool_names(mcp_server)
+
+        self.mcp_server = mcp_server
+        self.mcp_client = Client(mcp_server)
+
+        # Track mode-specific tools: {tool_name: {mode: func}}
+        # mode can be "production", "simulation", or None (available in all modes)
+        self._mode_tools = defaultdict(dict)
+
+        # Track tool schemas for list_tools: {tool_name: {mode: schema}}
+        self._mode_tool_schemas = defaultdict(dict)
+
+    @property
+    def supports_code_mode(self) -> bool:
+        """Check if this environment supports code mode (execute_code)."""
+        return True
+
+    def _get_server_tools(self, mcp_server: Any) -> Dict[str, Any]:
+        """
+        Get tools from a FastMCP server, compatible with both 2.x and 3.x.
+
+        Returns:
+            Dictionary mapping tool names to tool objects.
+        """
+        return get_server_tools(mcp_server)
+
+    def get_callables(self) -> Dict[str, Callable]:
+        """
+        Get callable functions for code mode.
+
+        Returns tool functions as direct Python callables, enabling code mode
+        where agents write Python code that calls tools directly (no JSON-RPC
+        overhead). Mode-specific tools are filtered by the current mode.
+
+        Returns:
+            Dictionary mapping tool names to callables.
+        """
+        callables: Dict[str, Callable] = {}
+        current_mode = getattr(self, "_mode", None)
+
+        # Extract callables from FastMCP server using public API
+        for tool_name, tool in self._get_server_tools(self.mcp_server).items():
+            if hasattr(tool, "fn") and callable(tool.fn):
+                callables[tool_name] = tool.fn
+
+        # Add mode-specific tools available in current mode
+        for tool_name, mode_funcs in self._mode_tools.items():
+            if None in mode_funcs:
+                # Tool available in all modes (already in FastMCP if registered there)
+                if tool_name not in callables:
+                    callables[tool_name] = mode_funcs[None]
+            elif current_mode in mode_funcs:
+                # Tool available in current mode only
+                callables[tool_name] = mode_funcs[current_mode]
+
+        return callables
+
+    def execute_code(self, code: str) -> Observation:
+        """
+        Execute Python code with tools available as callables.
+
+        This enables the CodeAct pattern where agents write Python code
+        that calls tools directly as functions, avoiding JSON-RPC overhead.
+
+        Args:
+            code: Python code to execute. Tools are available as functions
+                in the execution namespace. Set a variable named 'result'
+                to capture the return value.
+
+        Returns:
+            Observation with result in metadata["result"] or error in
+            metadata["error"].
+        """
+        namespace = self.get_callables()
+
+        result_dict: Dict[str, Any] = {}
+        try:
+            exec(code, namespace, result_dict)
+            result = result_dict.get("result")
+            return Observation(done=False, reward=0.0, metadata={"result": result})
+        except SyntaxError as e:
+            return Observation(
+                done=False, reward=0.0, metadata={"error": f"Syntax error: {str(e)}"}
+            )
+        except Exception as e:
+            return Observation(done=False, reward=0.0, metadata={"error": str(e)})
+
+    def _validate_tool_names(self, mcp_server: Any) -> None:
+        """
+        Validate that no tools use reserved names.
+
+        Reserved names (reset, step, state, close) are protected to maintain
+        the dual API boundary between infrastructure and agent APIs.
+
+        Args:
+            mcp_server: The FastMCP server to validate.
+
+        Raises:
+            ValueError: If any tool uses a reserved name.
+        """
+        tools_dict = self._get_server_tools(mcp_server)
+        if tools_dict:
+            tool_names = set(tools_dict.keys())
+            conflicts = tool_names & RESERVED_TOOL_NAMES
+            if conflicts:
+                raise ValueError(
+                    f"MCP tools cannot use reserved names: {sorted(conflicts)}. "
+                    f"Reserved names are: {sorted(RESERVED_TOOL_NAMES)}"
+                )
+
+    def tool(self, mode: Optional[str] = None) -> Callable:
+        """
+        Decorator for registering mode-aware tools.
+
+        Args:
+            mode: Optional mode for the tool ("production" or "simulation").
+                If None, tool is available in all modes.
+
+        Returns:
+            A decorator function for registering tools.
+
+        Raises:
+            ValueError: If mode is not None, "production", or "simulation".
+        """
+        if mode is not None and mode not in VALID_MODES:
+            raise ValueError(
+                f"Invalid mode '{mode}'. Mode must be 'production', 'simulation', or None."
+            )
+
+        def decorator(func: Callable) -> Callable:
+            tool_name = func.__name__
+            # Validate tool name is not reserved
+            if tool_name in RESERVED_TOOL_NAMES:
+                raise ValueError(
+                    f"Tool name '{tool_name}' is reserved and cannot be used. "
+                    f"Reserved names are: {sorted(RESERVED_TOOL_NAMES)}"
+                )
+
+            # If mode is None, register with FastMCP as usual
+            if mode is None:
+                decorated_func = self.mcp_server.tool()(func)
+                self._mode_tools[tool_name][None] = func
+                return decorated_func
+
+            # For mode-specific tools, don't register with FastMCP
+            # Instead, track them ourselves
+            self._mode_tools[tool_name][mode] = func
+
+            # Extract schema information from function signature
+            sig = inspect.signature(func)
+            schema = {
+                "type": "object",
+                "properties": {},
+                "required": [],
+            }
+
+            for param_name, param in sig.parameters.items():
+                # Get type annotation
+                param_type = param.annotation
+                json_type = "string"  # default
+                if param_type in (int, "int"):
+                    json_type = "integer"
+                elif param_type in (float, "float"):
+                    json_type = "number"
+                elif param_type in (bool, "bool"):
+                    json_type = "boolean"
+
+                schema["properties"][param_name] = {"type": json_type}
+
+                # If no default value, it's required
+                if param.default == inspect.Parameter.empty:
+                    schema["required"].append(param_name)
+
+            # Store the schema for this mode-specific tool
+            self._mode_tool_schemas[tool_name][mode] = {
+                "name": tool_name,
+                "description": func.__doc__ or "",
+                "input_schema": schema,
+            }
+
+            return func
+
+        return decorator
+
+    def step(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Execute an action in the environment.
+
+        This method routes MCP-specific actions (ListToolsAction, CallToolAction)
+        to the appropriate handlers, while delegating all other actions to
+        the subclass's _step_impl() method.
+
+        Args:
+            action: The action to execute. Can be:
+                - ListToolsAction: Returns available MCP tools
+                - CallToolAction: Invokes a specific MCP tool
+                - Any other Action: Delegated to _step_impl()
+            timeout_s: Optional timeout in seconds for the action.
+                Defaults to MCP_TOOL_CALL_TIMEOUT (30s) for MCP actions.
+            **kwargs: Additional arguments passed to handlers.
+
+        Returns:
+            Observation appropriate to the action type:
+                - ListToolsObservation for ListToolsAction
+                - CallToolObservation for CallToolAction
+                - Subclass-defined Observation for other actions
+        """
+        if isinstance(action, ListToolsAction):
+            return self._handle_list_tools()
+        elif isinstance(action, CallToolAction):
+            return self._handle_call_tool(action, timeout_s=timeout_s)
+        else:
+            return self._step_impl(action, timeout_s=timeout_s, **kwargs)
+
+    def _handle_list_tools(self) -> ListToolsObservation:
+        """
+        Handle a ListToolsAction by querying the MCP server.
+
+        Returns:
+            ListToolsObservation containing all available tools with their
+            names, descriptions, and input schemas, filtered by current mode.
+        """
+        try:
+            # Get current mode
+            current_mode = getattr(self, "_mode", None)
+
+            # Start with tools from FastMCP server (mode=None tools)
+            tools_result = run_async_safely(self._async_list_tools())
+
+            # Build list of Tool objects
+            tools = []
+
+            # Add FastMCP tools that are not mode-specific
+            for tool in tools_result:
+                if tool.name not in self._mode_tool_schemas:
+                    tools.append(
+                        Tool(
+                            name=tool.name,
+                            description=tool.description or "",
+                            input_schema=tool.inputSchema
+                            if hasattr(tool, "inputSchema")
+                            else {},
+                        )
+                    )
+
+            # Add mode-specific tools available in current mode
+            for tool_name, mode_schemas in self._mode_tool_schemas.items():
+                if None in mode_schemas:
+                    # Tool available in all modes
+                    schema = mode_schemas[None]
+                    tools.append(
+                        Tool(
+                            name=schema["name"],
+                            description=schema["description"],
+                            input_schema=schema["input_schema"],
+                        )
+                    )
+                elif current_mode in mode_schemas:
+                    # Tool available in current mode
+                    schema = mode_schemas[current_mode]
+                    tools.append(
+                        Tool(
+                            name=schema["name"],
+                            description=schema["description"],
+                            input_schema=schema["input_schema"],
+                        )
+                    )
+
+            return ListToolsObservation(tools=tools)
+
+        except Exception as e:
+            # Return an observation with error in metadata
+            return ListToolsObservation(
+                tools=[],
+                metadata={
+                    "error": str(e),
+                    "error_type": "list_tools_failed",
+                },
+            )
+
+    async def _async_list_tools(self) -> list:
+        """
+        Async helper to list tools from the MCP client.
+
+        Returns:
+            List of tool objects from the MCP server.
+        """
+        async with self.mcp_client:
+            return await self.mcp_client.list_tools()
+
+    def _handle_call_tool(
+        self,
+        action: CallToolAction,
+        timeout_s: Optional[float] = None,
+    ) -> CallToolObservation:
+        """
+        Handle a CallToolAction by invoking the specified tool.
+
+        Args:
+            action: The CallToolAction containing tool_name and arguments.
+            timeout_s: Timeout in seconds. Defaults to MCP_TOOL_CALL_TIMEOUT (30s).
+
+        Returns:
+            CallToolObservation with the tool's result or an error.
+        """
+        timeout = timeout_s if timeout_s is not None else MCP_TOOL_CALL_TIMEOUT
+
+        # Check if this is a mode-specific tool
+        tool_name = action.tool_name
+        current_mode = getattr(self, "_mode", None)
+
+        if tool_name in self._mode_tools:
+            mode_info = self._mode_tools[tool_name]
+
+            # Check if tool is available in current mode
+            # Tool is available if:
+            # 1. It has a None mode (available in all modes), OR
+            # 2. It has an implementation for the current mode
+            if None in mode_info:
+                # Use the mode-agnostic version
+                func = mode_info[None]
+            elif current_mode in mode_info:
+                # Use the mode-specific version
+                func = mode_info[current_mode]
+            else:
+                # Tool not available in current mode
+                return CallToolObservation(
+                    tool_name=tool_name,
+                    result=None,
+                    error=ToolError(
+                        error_type=ToolErrorType.TOOL_NOT_FOUND,
+                        message=f"Tool '{tool_name}' not available in {current_mode} mode",
+                    ),
+                )
+
+            # Call the mode-specific function directly
+            try:
+                # Check if function is async and await if necessary
+                if inspect.iscoroutinefunction(func):
+                    result = run_async_safely(func(**action.arguments))
+                else:
+                    result = func(**action.arguments)
+
+                # Wrap result in CallToolResult format to match FastMCP behavior
+                return CallToolObservation(
+                    tool_name=tool_name,
+                    result=CallToolResult(
+                        content=[TextContent(type="text", text=str(result))],
+                        structured_content={"result": result},
+                        meta=None,
+                        data=result,
+                        is_error=False,
+                    ),
+                )
+            except Exception as e:
+                return CallToolObservation(
+                    tool_name=tool_name,
+                    result=None,
+                    error=ToolError(
+                        error_type=ToolErrorType.EXECUTION_ERROR,
+                        message=str(e),
+                    ),
+                )
+
+        # Not a mode-specific tool, use FastMCP
+        try:
+            # Run the async call_tool with timeout
+            # Use run_async_safely to handle both sync and async contexts
+            result = run_async_safely(
+                asyncio.wait_for(
+                    self._async_call_tool(action.tool_name, action.arguments),
+                    timeout=timeout,
+                )
+            )
+
+            return CallToolObservation(
+                tool_name=action.tool_name,
+                result=result,
+            )
+
+        except asyncio.TimeoutError:
+            return CallToolObservation(
+                tool_name=action.tool_name,
+                result=None,
+                error=ToolError(
+                    error_type=ToolErrorType.TIMEOUT,
+                    message=f"Tool '{action.tool_name}' timed out after {timeout} seconds",
+                ),
+            )
+
+        except Exception as e:
+            error_message = str(e)
+
+            # Determine error type based on the exception
+            if (
+                "not found" in error_message.lower()
+                or "unknown tool" in error_message.lower()
+            ):
+                error_type = ToolErrorType.TOOL_NOT_FOUND
+            elif (
+                "invalid" in error_message.lower()
+                or "argument" in error_message.lower()
+            ):
+                error_type = ToolErrorType.INVALID_ARGS
+            else:
+                error_type = ToolErrorType.EXECUTION_ERROR
+
+            return CallToolObservation(
+                tool_name=action.tool_name,
+                result=None,
+                error=ToolError(
+                    error_type=error_type,
+                    message=error_message,
+                ),
+            )
+
+    async def _async_call_tool(self, tool_name: str, arguments: dict) -> Any:
+        """
+        Async helper to call a tool on the MCP server.
+
+        Args:
+            tool_name: Name of the tool to invoke.
+            arguments: Dictionary of arguments to pass to the tool.
+
+        Returns:
+            The result from the tool execution.
+        """
+        async with self.mcp_client:
+            return await self.mcp_client.call_tool(tool_name, arguments)
+
+    @abstractmethod
+    def _step_impl(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Handle non-MCP actions in the environment.
+
+        Subclasses must implement this method to handle any actions that are
+        not ListToolsAction or CallToolAction. This is where environment-specific
+        action processing should occur.
+
+        Args:
+            action: The action to execute (guaranteed not to be an MCP action).
+            timeout_s: Optional timeout in seconds.
+            **kwargs: Additional arguments.
+
+        Returns:
+            An Observation appropriate for the action.
+        """
+        pass
+
+    def close(self) -> None:
+        """
+        Clean up resources used by the environment.
+
+        This method cleans up the MCP client and any other resources.
+        Subclasses should call super().close() if they override this method.
+        """
+        # The MCP client uses async context manager, so cleanup happens
+        # automatically when the context exits. We just clear references.
+        self.mcp_client = None
+        self.mcp_server = None

src/core/env_server/mcp_types.py

@@ -0,0 +1,321 @@
+# 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.
+
+"""
+MCP (Model Context Protocol) type definitions for OpenEnv.
+
+This module defines strongly typed models for MCP tool discovery and invocation,
+following RFC 003. These types map MCP's REST-like API (tools/list, tools/call)
+to Gym-style action types.
+
+Key design decisions:
+- Tool discovery (list_tools) does NOT require reset() first
+- Reserved tool names (reset, step, state, close) are prohibited
+- Both step() and WebSocket /mcp paths are supported
+"""
+
+from enum import Enum
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .types import Action, BaseMessage, Observation
+
+
+# =============================================================================
+# JSON-RPC 2.0 Types
+# =============================================================================
+
+
+class JsonRpcErrorCode(int, Enum):
+    """
+    Standard JSON-RPC 2.0 error codes.
+
+    See: https://www.jsonrpc.org/specification#error_object
+    """
+
+    # Standard JSON-RPC errors
+    PARSE_ERROR = -32700  # Invalid JSON was received
+    INVALID_REQUEST = -32600  # JSON is not a valid Request object
+    METHOD_NOT_FOUND = -32601  # Method does not exist / is not available
+    INVALID_PARAMS = -32602  # Invalid method parameter(s)
+    INTERNAL_ERROR = -32603  # Internal JSON-RPC error
+
+    # Server errors (reserved for implementation-defined errors)
+    SERVER_ERROR = -32000  # Generic server error
+
+
+class McpMethod(str, Enum):
+    """Supported MCP method names."""
+
+    TOOLS_LIST = "tools/list"
+    TOOLS_CALL = "tools/call"
+
+
+class JsonRpcError(BaseModel):
+    """
+    JSON-RPC 2.0 error object.
+
+    See: https://www.jsonrpc.org/specification#error_object
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    code: int = Field(description="Error code indicating the error type")
+    message: str = Field(description="Short description of the error")
+    data: Optional[Any] = Field(
+        default=None, description="Additional error information"
+    )
+
+    @classmethod
+    def from_code(
+        cls, code: JsonRpcErrorCode, message: Optional[str] = None, data: Any = None
+    ) -> "JsonRpcError":
+        """Create an error from a standard error code."""
+        default_messages = {
+            JsonRpcErrorCode.PARSE_ERROR: "Parse error",
+            JsonRpcErrorCode.INVALID_REQUEST: "Invalid Request",
+            JsonRpcErrorCode.METHOD_NOT_FOUND: "Method not found",
+            JsonRpcErrorCode.INVALID_PARAMS: "Invalid params",
+            JsonRpcErrorCode.INTERNAL_ERROR: "Internal error",
+            JsonRpcErrorCode.SERVER_ERROR: "Server error",
+        }
+        return cls(
+            code=code.value,
+            message=message or default_messages.get(code, "Unknown error"),
+            data=data,
+        )
+
+
+class JsonRpcRequest(BaseModel):
+    """
+    JSON-RPC 2.0 request object.
+
+    See: https://www.jsonrpc.org/specification#request_object
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    jsonrpc: Literal["2.0"] = Field(description="JSON-RPC version, must be '2.0'")
+    method: str = Field(description="Name of the method to be invoked")
+    params: Dict[str, Any] = Field(
+        default_factory=dict, description="Parameter values for the method"
+    )
+    id: Optional[Union[str, int]] = Field(
+        default=None, description="Request identifier established by the client"
+    )
+
+
+class JsonRpcResponse(BaseModel):
+    """
+    JSON-RPC 2.0 response object.
+
+    Per JSON-RPC 2.0 spec, a response has either 'result' or 'error', not both.
+    This model excludes None values during serialization to comply with the spec.
+
+    See: https://www.jsonrpc.org/specification#response_object
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    jsonrpc: Literal["2.0"] = Field(default="2.0", description="JSON-RPC version")
+    result: Optional[Any] = Field(
+        default=None, description="Result of the method invocation"
+    )
+    error: Optional[JsonRpcError] = Field(
+        default=None, description="Error object if method invocation failed"
+    )
+    id: Optional[Union[str, int]] = Field(
+        default=None, description="Request identifier from the request"
+    )
+
+    def model_dump(self, **kwargs) -> Dict[str, Any]:
+        """Serialize to dict, excluding result or error when None (JSON-RPC compliance)."""
+        # Always include jsonrpc and id, but only include result OR error
+        data: Dict[str, Any] = {"jsonrpc": self.jsonrpc, "id": self.id}
+        if self.error is not None:
+            data["error"] = (
+                self.error.model_dump()
+                if hasattr(self.error, "model_dump")
+                else self.error
+            )
+        else:
+            # Only include result if there's no error
+            data["result"] = self.result
+        return data
+
+    def model_dump_json(self, **kwargs) -> str:
+        """Serialize to JSON string, excluding result or error when None (JSON-RPC compliance)."""
+        import json
+
+        return json.dumps(self.model_dump())
+
+    @classmethod
+    def success(
+        cls, result: Any, request_id: Optional[Union[str, int]] = None
+    ) -> "JsonRpcResponse":
+        """Create a success response."""
+        return cls(result=result, id=request_id)
+
+    @classmethod
+    def error_response(
+        cls,
+        code: JsonRpcErrorCode,
+        message: Optional[str] = None,
+        data: Any = None,
+        request_id: Optional[Union[str, int]] = None,
+    ) -> "JsonRpcResponse":
+        """Create an error response from a standard error code."""
+        return cls(
+            error=JsonRpcError.from_code(code, message, data),
+            id=request_id,
+        )
+
+
+# =============================================================================
+# MCP Tool Types
+# =============================================================================
+
+
+class Tool(BaseModel):
+    """
+    Strongly typed MCP tool specification.
+
+    Follows the MCP ToolSpec format for tool discovery.
+    See: https://modelcontextprotocol.io/specification/2025-06-18/server/tools
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(description="Unique identifier for the tool")
+    description: str = Field(
+        description="Human-readable description of what the tool does"
+    )
+    input_schema: Dict[str, Any] = Field(
+        description="JSON Schema for the tool's input parameters"
+    )
+
+
+class ToolErrorType(str, Enum):
+    """Types of errors that can occur during tool execution."""
+
+    EXECUTION_ERROR = "execution_error"  # Tool ran but failed
+    INVALID_ARGS = "invalid_args"  # Invalid arguments provided
+    TRANSPORT_ERROR = "transport_error"  # Communication failure
+    TOOL_NOT_FOUND = "tool_not_found"  # Tool doesn't exist
+    TIMEOUT = "timeout"  # Operation timed out
+
+
+class ToolError(BaseModel):
+    """
+    Structured error for tool execution failures.
+
+    This is used for transport/framework errors, NOT for errors returned
+    by the tool itself (those go in the result field).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    error_type: ToolErrorType = Field(description="Category of the error")
+    message: str = Field(description="Human-readable error message")
+
+
+# --- MCP Actions ---
+
+
+class ListToolsAction(Action):
+    """
+    Request list of available tools from the environment.
+
+    This action triggers MCP's tools/list operation and returns
+    all available tools with their schemas.
+
+    Note: Does NOT require reset() to be called first.
+    """
+
+    type: Literal["list_tools"] = Field(
+        default="list_tools", description="Action type discriminator"
+    )
+
+
+class CallToolAction(Action):
+    """
+    Call a specific tool via MCP.
+
+    This action triggers MCP's tools/call operation with the
+    specified tool name and arguments.
+    """
+
+    type: Literal["call_tool"] = Field(
+        default="call_tool", description="Action type discriminator"
+    )
+    tool_name: str = Field(description="Name of the tool to call")
+    arguments: Dict[str, Any] = Field(
+        default_factory=dict, description="Arguments to pass to the tool"
+    )
+
+
+# --- MCP Observations ---
+
+
+class ListToolsObservation(Observation):
+    """
+    Response containing available tools.
+
+    Returned when processing a ListToolsAction.
+    """
+
+    tools: List[Tool] = Field(description="List of available tools with their schemas")
+
+
+class CallToolObservation(Observation):
+    """
+    Response from tool execution.
+
+    Contains the tool's result or an error if the call failed.
+    Tool-specific errors (from the tool itself) are included in the result.
+    Transport/framework errors use the error field.
+    """
+
+    tool_name: str = Field(description="Name of the tool that was called")
+    result: Any = Field(
+        default=None, description="Tool-specific result (may include tool errors)"
+    )
+    error: Optional[ToolError] = Field(
+        default=None, description="Transport/framework error if call failed"
+    )
+
+
+# --- WebSocket Message Types for MCP ---
+
+
+class WSMCPMessage(BaseMessage):
+    """
+    WebSocket message for MCP JSON-RPC requests.
+
+    Allows direct MCP access via WebSocket for production inference,
+    bypassing the step() API.
+    """
+
+    type: Literal["mcp"] = Field(default="mcp", description="Message type")
+    data: Dict[str, Any] = Field(description="JSON-RPC payload (method, params, id)")
+
+
+class WSMCPResponse(BaseModel):
+    """
+    WebSocket response for MCP JSON-RPC.
+
+    Contains the JSON-RPC response from the MCP server.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: str = Field(default="mcp", description="Response type")
+    data: Dict[str, Any] = Field(description="JSON-RPC response payload")
+
+
+# Reserved tool names that cannot be used (protects dual API boundary)
+RESERVED_TOOL_NAMES = frozenset(["reset", "step", "state", "close"])

src/core/env_server/route_config.py

@@ -0,0 +1,57 @@
+# 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.
+
+"""
+Route configuration utilities for declarative FastAPI route registration.
+
+This module provides utilities to reduce boilerplate in route registration
+by using configuration objects instead of repeated function calls.
+"""
+
+from dataclasses import dataclass
+from typing import Callable, List, Type
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+
+@dataclass
+class GetEndpointConfig:
+    """Configuration for a simple GET endpoint."""
+
+    path: str
+    handler: Callable[[], BaseModel | dict]
+    response_model: Type[BaseModel] | type[dict]
+    tag: str
+    summary: str
+    description: str
+
+
+def register_get_endpoints(app: FastAPI, configs: List[GetEndpointConfig]) -> None:
+    """
+    Register multiple GET endpoints from configuration.
+
+    Args:
+        app: FastAPI application instance
+        configs: List of GET endpoint configurations
+    """
+    for config in configs:
+        # Capture handler in a closure to avoid non-serializable default parameter
+        def make_endpoint(
+            handler: Callable[[], BaseModel | dict],
+        ) -> Callable[[], BaseModel | dict]:
+            async def endpoint() -> BaseModel | dict:
+                return handler()
+
+            return endpoint
+
+        app.get(
+            config.path,
+            response_model=config.response_model,
+            tags=[config.tag],
+            summary=config.summary,
+            description=config.description,
+        )(make_endpoint(config.handler))

src/core/env_server/serialization.py

@@ -0,0 +1,137 @@
+# 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.
+
+"""
+Shared serialization and deserialization utilities for OpenEnv HTTP servers.
+
+This module provides common utilities for converting between JSON dictionaries
+and Pydantic models (Action/Observation) to eliminate code duplication across
+HTTP server and web interface implementations.
+"""
+
+from typing import Any, Dict, Type
+
+from .types import Action, Observation
+
+
+def deserialize_action(action_data: Dict[str, Any], action_cls: Type[Action]) -> Action:
+    """
+    Convert JSON dict to Action instance using Pydantic validation.
+
+    This is a basic deserialization that works for most environments.
+    For special cases (e.g., tensor fields, custom type conversions),
+    use deserialize_action_with_preprocessing().
+
+    Args:
+        action_data: Dictionary containing action data
+        action_cls: The Action subclass to instantiate
+
+    Returns:
+        Action instance
+
+    Raises:
+        ValidationError: If action_data is invalid for the action class
+
+    Note:
+        This uses Pydantic's model_validate() for automatic validation.
+    """
+    return action_cls.model_validate(action_data)
+
+
+def deserialize_action_with_preprocessing(
+    action_data: Dict[str, Any], action_cls: Type[Action]
+) -> Action:
+    """
+    Convert JSON dict to Action instance with preprocessing for special types.
+
+    This version handles common type conversions needed for web interfaces:
+    - Converting lists/strings to tensors for 'tokens' field
+    - Converting string action_id to int
+    - Other custom preprocessing as needed
+
+    Args:
+        action_data: Dictionary containing action data
+        action_cls: The Action subclass to instantiate
+
+    Returns:
+        Action instance
+
+    Raises:
+        ValidationError: If action_data is invalid for the action class
+    """
+    processed_data = {}
+
+    for key, value in action_data.items():
+        if key == "tokens" and isinstance(value, (list, str)):
+            # Convert list or string to tensor
+            if isinstance(value, str):
+                # If it's a string, try to parse it as a list of numbers
+                try:
+                    import json
+
+                    value = json.loads(value)
+                except Exception:
+                    # If parsing fails, treat as empty list
+                    value = []
+            if isinstance(value, list):
+                try:
+                    import torch  # type: ignore
+
+                    processed_data[key] = torch.tensor(value, dtype=torch.long)
+                except ImportError:
+                    # If torch not available, keep as list
+                    processed_data[key] = value
+            else:
+                processed_data[key] = value
+        elif key == "action_id" and isinstance(value, str):
+            # Convert action_id from string to int
+            try:
+                processed_data[key] = int(value)
+            except ValueError:
+                # If conversion fails, keep original value
+                processed_data[key] = value
+        else:
+            processed_data[key] = value
+
+    return action_cls.model_validate(processed_data)
+
+
+def serialize_observation(observation: Observation) -> Dict[str, Any]:
+    """
+    Convert Observation instance to JSON-compatible dict using Pydantic.
+
+    Args:
+        observation: Observation instance
+
+    Returns:
+        Dictionary compatible with EnvClient._parse_result()
+
+    The format matches what EnvClient expects:
+    {
+        "observation": {...},  # Observation fields
+        "reward": float | None,
+        "done": bool,
+    }
+    """
+    # Use Pydantic's model_dump() for serialization
+    obs_dict = observation.model_dump(
+        exclude={
+            "reward",
+            "done",
+            "metadata",
+        }  # Exclude these from observation dict
+    )
+
+    # Extract reward and done directly from the observation
+    reward = observation.reward
+    done = observation.done
+
+    # Return in EnvClient expected format
+    return {
+        "observation": obs_dict,
+        "reward": reward,
+        "done": done,
+    }

src/core/env_server/types.py

@@ -4,54 +4,384 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
-from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional, Union
+from enum import Enum
+from typing import Annotated, Any, Dict, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 
 # Type aliases
 Scalar = Union[int, float, bool]
 
 
-@dataclass(kw_only=True)
-class Action:
-    """Base class for all environment actions."""
+# =============================================================================
+# Enums for Type Safety
+# =============================================================================
+
+
+class ServerMode(str, Enum):
+    """Server operation mode."""
+
+    SIMULATION = "simulation"
+    PRODUCTION = "production"
+
+
+class HealthStatus(str, Enum):
+    """Server health status values."""
+
+    HEALTHY = "healthy"
+    UNHEALTHY = "unhealthy"
+    DEGRADED = "degraded"
+
+
+class WSErrorCode(str, Enum):
+    """WebSocket error codes for structured error handling."""
+
+    INVALID_JSON = "INVALID_JSON"
+    UNKNOWN_TYPE = "UNKNOWN_TYPE"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    EXECUTION_ERROR = "EXECUTION_ERROR"
+    CAPACITY_REACHED = "CAPACITY_REACHED"
+    FACTORY_ERROR = "FACTORY_ERROR"
+    SESSION_ERROR = "SESSION_ERROR"
+
+
+# =============================================================================
+# Core Types
+# =============================================================================
+
+
+class Action(BaseModel):
+    """Base class for all environment actions.
+
+    All action subclasses should inherit from this base class.
+    Uses Pydantic for automatic validation and serialization.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",  # Reject unknown fields
+        validate_assignment=True,  # Validate on field assignment
+        arbitrary_types_allowed=True,  # Allow numpy arrays, torch tensors, etc.
+    )
+
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict, description="Additional metadata for the action"
+    )
+
+
+class Observation(BaseModel):
+    """Base class for all environment observations.
+
+    All observation subclasses should inherit from this base class.
+    Uses Pydantic for automatic validation and serialization.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        validate_assignment=True,
+        arbitrary_types_allowed=True,
+    )
+
+    done: bool = Field(default=False, description="Whether the episode has terminated")
+    reward: bool | int | float | None = Field(
+        default=None, description="Reward signal from the last action"
+    )
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict, description="Additional metadata for the observation"
+    )
 
-    metadata: Dict[str, Any] = field(default_factory=dict)
 
+class ResetRequest(BaseModel):
+    """Request model for environment reset."""
 
-@dataclass(kw_only=True)
-class Observation:
-    """Base class for all environment observations."""
+    model_config = ConfigDict(
+        extra="allow",  # Allow extra fields for custom reset parameters
+        json_schema_extra={"examples": [{"seed": 42, "episode_id": "episode-001"}, {}]},
+    )
 
-    done: bool = False
-    reward: Union[bool, int, float, None] = None
-    metadata: Dict[str, Any] = field(default_factory=dict)
+    seed: Optional[int] = Field(
+        default=None, ge=0, description="Random seed for reproducible episodes"
+    )
+    episode_id: Optional[str] = Field(
+        default=None, max_length=255, description="Custom episode identifier"
+    )
 
 
-@dataclass
-class State:
-    """Base class for environment state."""
+class ResetResponse(BaseModel):
+    """Response model for environment reset."""
 
-    episode_id: Optional[str] = None
-    step_count: int = 0
+    model_config = ConfigDict(extra="forbid")
 
+    observation: Dict[str, Any] = Field(
+        ..., description="Initial observation from the environment"
+    )
+    reward: Optional[float] = Field(
+        default=None, description="Initial reward (typically None at reset)"
+    )
+    done: bool = Field(
+        default=False, description="Whether episode is already done (typically False)"
+    )
 
-@dataclass
-class CodeExecResult:
+
+class StepRequest(BaseModel):
+    """Request model for environment step."""
+
+    model_config = ConfigDict(
+        extra="allow",  # Allow extra fields for custom step parameters
+        json_schema_extra={
+            "examples": [
+                {"action": {"value": 1}, "timeout_s": 30.0},
+                {"action": {"value": 1}, "render": True, "verbose": False},
+            ]
+        },
+    )
+
+    action: Dict[str, Any] = Field(
+        ...,
+        description="Action to execute, must conform to environment's action schema",
+    )
+    timeout_s: Optional[float] = Field(
+        default=None,
+        gt=0,
+        description="Optional timeout in seconds for action execution",
+    )
+    request_id: Optional[str] = Field(
+        default=None,
+        max_length=255,
+        description="Optional request identifier for tracking",
+    )
+
+
+class StepResponse(BaseModel):
+    """Response model for environment step."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    observation: Dict[str, Any] = Field(
+        ..., description="Observation resulting from the action"
+    )
+    reward: Optional[float] = Field(
+        default=None, description="Reward signal from the action"
+    )
+    done: bool = Field(default=False, description="Whether the episode has terminated")
+
+
+class BaseMessage(BaseModel):
+    """Base class for WebSocket messages with shared configuration."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        validate_assignment=True,
+    )
+
+
+class State(BaseModel):
+    """Base class for environment state.
+
+    Represents internal environment state, separate from observations.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",  # Allow extra fields for flexibility
+        validate_assignment=True,
+        arbitrary_types_allowed=True,
+    )
+
+    episode_id: Optional[str] = Field(
+        default=None, description="Unique identifier for the current episode"
+    )
+    step_count: int = Field(
+        default=0,
+        ge=0,  # Greater than or equal to 0
+        description="Number of steps taken in the current episode",
+    )
+
+
+class CodeExecResult(BaseMessage):
     """Result of code execution containing stdout, stderr, and exit code."""
 
-    stdout: str
-    stderr: str
-    exit_code: int
+    stdout: str = Field(description="Standard output from code execution")
+    stderr: str = Field(description="Standard error from code execution")
+    exit_code: int = Field(description="Exit code from code execution")
 
 
-@dataclass
-class EnvironmentMetadata:
+class EnvironmentMetadata(BaseMessage):
     """Metadata about an environment for documentation and UI purposes."""
-    
-    name: str
-    description: str
-    readme_content: Optional[str] = None
-    version: Optional[str] = None
-    author: Optional[str] = None
-    documentation_url: Optional[str] = None
+
+    name: str = Field(description="Name of the environment")
+    description: str = Field(description="Description of what the environment does")
+    readme_content: Optional[str] = Field(
+        default=None, description="Content of the README file for the environment"
+    )
+    version: Optional[str] = Field(
+        default=None, description="Version of the environment"
+    )
+    author: Optional[str] = Field(default=None, description="Author of the environment")
+    documentation_url: Optional[str] = Field(
+        default=None, description="URL to the environment's documentation"
+    )
+
+
+class SchemaResponse(BaseMessage):
+    """Response model for the combined schema endpoint."""
+
+    action: Dict[str, Any] = Field(
+        description="JSON schema for actions accepted by this environment"
+    )
+    observation: Dict[str, Any] = Field(
+        description="JSON schema for observations returned by this environment"
+    )
+    state: Dict[str, Any] = Field(
+        description="JSON schema for environment state objects"
+    )
+
+
+class HealthResponse(BaseMessage):
+    """Response model for health check endpoint."""
+
+    status: HealthStatus = Field(
+        default=HealthStatus.HEALTHY,
+        description="Health status of the environment server",
+    )
+
+
+class WSResetMessage(BaseMessage):
+    """WebSocket message to reset the environment."""
+
+    type: Literal["reset"] = Field(default="reset", description="Message type")
+    data: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Optional reset parameters (seed, episode_id, etc.)",
+    )
+
+
+class WSStepMessage(BaseMessage):
+    """WebSocket message to execute a step."""
+
+    type: Literal["step"] = Field(default="step", description="Message type")
+    data: Dict[str, Any] = Field(
+        ..., description="Action data conforming to environment's action schema"
+    )
+
+
+class WSStateMessage(BaseMessage):
+    """WebSocket message to request current state."""
+
+    type: Literal["state"] = Field(default="state", description="Message type")
+
+
+class WSCloseMessage(BaseMessage):
+    """WebSocket message to close the session."""
+
+    type: Literal["close"] = Field(default="close", description="Message type")
+
+
+# Discriminated union for incoming WebSocket messages
+# Note: WSMCPMessage is defined in mcp_types.py to avoid circular imports
+# The union here covers the core message types; MCP messages are handled separately
+WSIncomingMessage = Annotated[
+    WSResetMessage | WSStepMessage | WSStateMessage | WSCloseMessage,
+    Field(discriminator="type"),
+]
+
+
+class WSObservationResponse(BaseModel):
+    """WebSocket response containing an observation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["observation"] = Field(
+        default="observation", description="Response type"
+    )
+    data: Dict[str, Any] = Field(description="Observation data")
+
+
+class WSStateResponse(BaseModel):
+    """WebSocket response containing environment state."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["state"] = Field(default="state", description="Response type")
+    data: Dict[str, Any] = Field(description="State data")
+
+
+class WSErrorResponse(BaseModel):
+    """WebSocket response for errors."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["error"] = Field(default="error", description="Response type")
+    data: Dict[str, Any] = Field(description="Error details including message and code")
+
+
+class ConcurrencyConfig(BaseMessage):
+    """Configuration for concurrent environment sessions."""
+
+    max_concurrent_envs: int = Field(
+        default=1,
+        ge=1,
+        description="Maximum number of concurrent WebSocket sessions allowed",
+    )
+    session_timeout: Optional[float] = Field(
+        default=None,
+        gt=0,
+        description="Timeout in seconds for inactive sessions. None means no timeout.",
+    )
+
+
+class ServerCapacityStatus(BaseMessage):
+    """Status of server capacity for concurrent sessions."""
+
+    active_sessions: int = Field(
+        ge=0,
+        description="Number of currently active sessions",
+    )
+    max_sessions: int = Field(
+        ge=1,
+        description="Maximum number of allowed sessions",
+    )
+
+    @model_validator(mode="after")
+    def check_capacity_bounds(self) -> "ServerCapacityStatus":
+        if self.active_sessions > self.max_sessions:
+            raise ValueError(
+                f"active_sessions ({self.active_sessions}) cannot exceed "
+                f"max_sessions ({self.max_sessions})"
+            )
+        return self
+
+    @property
+    def available_slots(self) -> int:
+        """Number of available session slots."""
+        return self.max_sessions - self.active_sessions
+
+    @property
+    def is_at_capacity(self) -> bool:
+        """Whether the server has reached maximum capacity."""
+        return self.available_slots == 0
+
+    @classmethod
+    def from_counts(cls, active: int, max_sessions: int) -> "ServerCapacityStatus":
+        """Create status from active and max session counts."""
+        return cls(
+            active_sessions=active,
+            max_sessions=max_sessions,
+        )
+
+
+class SessionInfo(BaseMessage):
+    """Information about an active session."""
+
+    session_id: str = Field(description="Unique identifier for the session")
+    created_at: float = Field(description="Unix timestamp when the session was created")
+    last_activity_at: float = Field(
+        description="Unix timestamp of the last activity in the session"
+    )
+    step_count: int = Field(
+        default=0,
+        ge=0,
+        description="Number of steps executed in this session",
+    )
+    environment_type: str = Field(
+        description="Environment type for this session (e.g. `CodingEnv`)"
+    )

src/core/env_server/web_interface.py

@@ -7,61 +7,164 @@
 """
 Web interface for OpenEnv environments.
 
-This module provides a web-based interface for interacting with OpenEnv environments,
-including a two-pane layout for HumanAgent interaction and state observation.
+When ENABLE_WEB_INTERFACE is set, the server exposes a Gradio UI at /web for
+reset, step, and state observation. Controlled by the CLI enable_interface
+option (e.g. openenv push --enable-interface) or ENABLE_WEB_INTERFACE env var.
 """
 
 from __future__ import annotations
 
+import asyncio
 import json
-import time
-from dataclasses import asdict, dataclass
-from typing import Any, Dict, List, Optional, Type
+from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime
+from typing import Any, Callable, Dict, List, Optional, Type
 
-from fastapi import FastAPI, WebSocket, WebSocketDisconnect, Request
-from fastapi.responses import HTMLResponse, FileResponse
-from fastapi.staticfiles import StaticFiles
-from pydantic import BaseModel
+import gradio as gr
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from pydantic import BaseModel, ConfigDict, Field
 
+from .gradio_theme import OPENENV_GRADIO_CSS, OPENENV_GRADIO_THEME
+from .gradio_ui import build_gradio_app, get_gradio_display_title
 from .interfaces import Environment
-from .types import Action, Observation, State, EnvironmentMetadata
+from .serialization import deserialize_action_with_preprocessing, serialize_observation
+from .types import Action, EnvironmentMetadata, Observation, State
 
+# Quick Start markdown template; placeholders match init suffixes (__ENV_NAME__, __ENV_CLASS_NAME__*).
+DEFAULT_QUICK_START_MARKDOWN = """
+### Connect to this environment
 
-def load_environment_metadata(env: Environment, env_name: Optional[str] = None) -> EnvironmentMetadata:
+Connect from Python using `__ENV_CLASS_NAME__Env`:
+
+```python
+from __ENV_NAME__ import __ENV_CLASS_NAME__Action, __ENV_CLASS_NAME__Env
+
+with __ENV_CLASS_NAME__Env.from_env("<SPACE_ID>") as env:
+    result = await env.step(__ENV_CLASS_NAME__Action(message="..."))
+```
+
+Or connect directly to a running server:
+
+```python
+env = __ENV_CLASS_NAME__Env(base_url="http://localhost:8000")
+```
+
+### Contribute to this environment
+
+Submit improvements via pull request on the Hugging Face Hub.
+
+```bash
+openenv fork <SPACE_ID> --repo-id <your-username>/<your-repo-name>
+```
+
+Then make your changes and submit a pull request:
+
+```bash
+cd <forked-repo>
+openenv push <SPACE_ID> --create-pr
+```
+
+For more information, see the [OpenEnv documentation](https://meta-pytorch.org/OpenEnv/).
+"""
+
+
+def get_quick_start_markdown(
+    metadata: Optional[EnvironmentMetadata],
+    action_cls: Type[Action],
+    observation_cls: Type[Observation],
+) -> str:
+    """
+    Build Quick Start markdown with class names replaced from current env (init-style suffixes).
+
+    Uses the same placeholder names as the init template so that __ENV_CLASS_NAME__Env,
+    __ENV_CLASS_NAME__Action, __ENV_CLASS_NAME__Observation and __ENV_NAME__ are
+    replaced with the actual class/package names.
+    """
+    import os
+
+    # Prefix from action class (e.g. EchoAction -> Echo)
+    action_name = getattr(action_cls, "__name__", "Action")
+    if action_name.endswith("Action"):
+        prefix = action_name[: -len("Action")]
+    else:
+        prefix = action_name.replace("Action", "").strip() or "Env"
+
+    env_client_name = f"{prefix}Env"
+    obs_name = getattr(observation_cls, "__name__", "Observation")
+    pkg_name = (metadata.name if metadata else "env").replace(" ", "_").lower()
+
+    space_id = os.environ.get("SPACE_ID", "<hf-username>/<hf-repo-name>")
+
+    content = DEFAULT_QUICK_START_MARKDOWN
+    content = content.replace("__ENV_CLASS_NAME__Env", env_client_name)
+    content = content.replace("__ENV_CLASS_NAME__Action", action_name)
+    content = content.replace("__ENV_CLASS_NAME__Observation", obs_name)
+    content = content.replace("__ENV_CLASS_NAME__", prefix)
+    content = content.replace("__ENV_NAME__", pkg_name)
+    content = content.replace("<SPACE_ID>", space_id)
+    return content.strip()
+
+
+def load_environment_metadata(
+    env: Environment, env_name: Optional[str] = None
+) -> EnvironmentMetadata:
     """
     Load environment metadata including README content.
-    
+
     Args:
-        env: The environment instance
+        env: The environment instance, class, or factory function.
+             - If a class: used as a factory, won't call instance methods
+             - If a function: used as a factory, won't call instance methods
+             - If an instance: may call get_metadata() if available
         env_name: Optional environment name for README file lookup
-        
+
     Returns:
         EnvironmentMetadata with loaded information
     """
-    # Try to get metadata from environment if it has a method for it
-    if hasattr(env, 'get_metadata'):
+    import inspect
+
+    # Determine what type of env we received:
+    # 1. A class (used as factory) - e.g., PythonCodeActEnv
+    # 2. A function (factory function) - e.g., create_chat_environment
+    # 3. An actual instance - e.g., SnakeEnvironment()
+    is_class = inspect.isclass(env)
+    is_function = inspect.isfunction(env) or inspect.ismethod(env)
+    is_factory = is_class or is_function
+
+    # Try to get metadata from environment if it's an instance with get_metadata
+    if not is_factory and hasattr(env, "get_metadata"):
         return env.get_metadata()
-    
+
+    # Determine the class name for default metadata
+    if is_class:
+        # env is the class itself
+        class_name = env.__name__
+    elif is_function:
+        # env is a factory function - use its name or derive from env_name
+        class_name = env_name or env.__name__
+    else:
+        # env is an instance
+        class_name = env.__class__.__name__
+
     # Default metadata
     metadata = EnvironmentMetadata(
-        name=env_name or env.__class__.__name__,
-        description=f"{env.__class__.__name__} environment",
-        version="1.0.0"
+        name=env_name or class_name,
+        description=f"{class_name} environment",
+        version="1.0.0",
     )
-    
+
     # Try to load README from file system
     readme_content = _load_readme_from_filesystem(env_name)
     if readme_content:
         metadata.readme_content = readme_content
-    
+
     return metadata
 
 
 def _load_readme_from_filesystem(env_name: Optional[str]) -> Optional[str]:
     """
     Load README content from the filesystem.
-    
+
     Tries multiple locations:
     1. Container filesystem: /app/README.md
     2. Local development: src/envs/{env_name}/README.md
@@ -69,59 +172,73 @@ def _load_readme_from_filesystem(env_name: Optional[str]) -> Optional[str]:
     """
     import os
     from pathlib import Path
-    
+
     # Try container filesystem first
     container_readme = Path("/app/README.md")
     if container_readme.exists():
         try:
-            return container_readme.read_text(encoding='utf-8')
+            return container_readme.read_text(encoding="utf-8")
         except Exception:
             pass
-    
+
     # Try environment variable path
     custom_path = os.environ.get("ENV_README_PATH")
     if custom_path and Path(custom_path).exists():
         try:
-            return Path(custom_path).read_text(encoding='utf-8')
+            return Path(custom_path).read_text(encoding="utf-8")
         except Exception:
             pass
-    
+
     # Try local development path
     if env_name:
         local_readme = Path(f"src/envs/{env_name}/README.md")
         if local_readme.exists():
             try:
-                return local_readme.read_text(encoding='utf-8')
+                return local_readme.read_text(encoding="utf-8")
             except Exception:
                 pass
-    
+
     return None
 
 
-@dataclass
-class ActionLog:
+class ActionLog(BaseModel):
     """Log entry for an action taken."""
-    timestamp: str
-    action: Dict[str, Any]
-    observation: Dict[str, Any]
-    reward: Optional[float]
-    done: bool
-    step_count: int
+
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+    timestamp: str = Field(description="Timestamp when action was taken")
+    action: Dict[str, Any] = Field(description="Action that was taken")
+    observation: Dict[str, Any] = Field(description="Observation returned from action")
+    reward: Optional[float] = Field(
+        default=None, description="Reward received from action"
+    )
+    done: bool = Field(description="Whether the episode is done after this action")
+    step_count: int = Field(description="Step count when this action was taken")
 
 
-@dataclass
-class EpisodeState:
+class EpisodeState(BaseModel):
     """Current episode state for the web interface."""
-    episode_id: Optional[str]
-    step_count: int
-    current_observation: Optional[Dict[str, Any]]
-    action_logs: List[ActionLog]
-    is_reset: bool = True
+
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+    episode_id: Optional[str] = Field(default=None, description="Current episode ID")
+    step_count: int = Field(description="Current step count in episode")
+    current_observation: Optional[Dict[str, Any]] = Field(
+        default=None, description="Current observation"
+    )
+    action_logs: List[ActionLog] = Field(
+        default_factory=list, description="List of action logs"
+    )
+    is_reset: bool = Field(
+        default=True, description="Whether the episode has been reset"
+    )
 
 
 class WebInterfaceManager:
     """Manages the web interface for an environment."""
-    
+
+    MAX_ACTION_LOGS = 1000
+
     def __init__(
         self,
         env: Environment,
@@ -129,152 +246,146 @@ class WebInterfaceManager:
         observation_cls: Type[Observation],
         metadata: Optional[EnvironmentMetadata] = None,
     ):
-        self.env = env
+        import inspect
+
+        # If env is a class or factory function, instantiate it
+        if inspect.isclass(env) or inspect.isfunction(env):
+            self.env = env()
+        else:
+            self.env = env
         self.action_cls = action_cls
         self.observation_cls = observation_cls
         self.metadata = metadata or EnvironmentMetadata(
             name=env.__class__.__name__,
-            description=f"{env.__class__.__name__} environment"
+            description=f"{env.__class__.__name__} environment",
         )
         self.episode_state = EpisodeState(
             episode_id=None,
             step_count=0,
             current_observation=None,
-            action_logs=[]
+            action_logs=[],
         )
         self.connected_clients: List[WebSocket] = []
-    
+        # Thread pool for running sync code (e.g., Playwright sync API) in async context
+        self._executor = ThreadPoolExecutor(max_workers=1)
+
+    async def _run_sync_in_thread_pool(self, func, *args, **kwargs):
+        """Run a synchronous function in the thread pool executor.
+
+        This is needed for environments using sync libraries (e.g., Playwright sync API)
+        that cannot be called directly from an async context.
+        """
+        loop = asyncio.get_event_loop()
+        # Use default arguments to capture values at lambda definition time
+        # to avoid closure issues with late binding
+        return await loop.run_in_executor(
+            self._executor, lambda f=func, a=args, kw=kwargs: f(*a, **kw)
+        )
+
     async def connect_websocket(self, websocket: WebSocket):
         """Connect a new WebSocket client."""
         await websocket.accept()
         self.connected_clients.append(websocket)
-        
+
         # Send current state to the new client
         await self._send_state_update()
-    
+
     async def disconnect_websocket(self, websocket: WebSocket):
         """Disconnect a WebSocket client."""
         if websocket in self.connected_clients:
             self.connected_clients.remove(websocket)
-    
+
     async def _send_state_update(self):
         """Send current state to all connected clients."""
         if not self.connected_clients:
             return
-            
+
         state_data = {
             "type": "state_update",
-            "episode_state": asdict(self.episode_state)
+            "episode_state": self.episode_state.model_dump(),
         }
-        
+
         # Send to all connected clients
         disconnected_clients = []
         for client in self.connected_clients:
             try:
                 await client.send_text(json.dumps(state_data))
-            except:
+            except Exception:
                 disconnected_clients.append(client)
-        
+
         # Remove disconnected clients
         for client in disconnected_clients:
             self.connected_clients.remove(client)
-    
+
     async def reset_environment(self) -> Dict[str, Any]:
         """Reset the environment and update state."""
-        observation = self.env.reset()
-        state = self.env.state
-        
+        # Run sync reset in thread pool to avoid blocking event loop
+        # and to support environments using sync libraries (e.g., Playwright)
+        observation: Observation = await self._run_sync_in_thread_pool(self.env.reset)
+        state: State = self.env.state
+
+        # Serialize observation once using shared utility
+        serialized = serialize_observation(observation)
+
         # Update episode state
         self.episode_state.episode_id = state.episode_id
         self.episode_state.step_count = 0
-        self.episode_state.current_observation = asdict(observation)
+        self.episode_state.current_observation = serialized["observation"]
         self.episode_state.action_logs = []
         self.episode_state.is_reset = True
-        
+
         # Send state update
         await self._send_state_update()
-        
-        return {
-            "observation": asdict(observation),
-            "reward": observation.reward,
-            "done": observation.done,
-        }
-    
+
+        return serialized
+
     async def step_environment(self, action_data: Dict[str, Any]) -> Dict[str, Any]:
         """Execute a step in the environment and update state."""
-        # Deserialize action
-        action = self._deserialize_action(action_data)
-        
-        # Execute step
-        observation = self.env.step(action)
-        state = self.env.state
-        
+        # Deserialize action with preprocessing for web interface special cases
+        action: Action = deserialize_action_with_preprocessing(
+            action_data, self.action_cls
+        )
+
+        # Run sync step in thread pool to avoid blocking event loop
+        # and to support environments using sync libraries (e.g., Playwright)
+        observation: Observation = await self._run_sync_in_thread_pool(
+            self.env.step, action
+        )
+        state: State = self.env.state
+
+        # Serialize observation once using shared utility
+        serialized = serialize_observation(observation)
+
         # Create action log
         action_log = ActionLog(
             timestamp=datetime.now().isoformat(),
-            action=asdict(action),
-            observation=asdict(observation),
+            action=action.model_dump(exclude={"metadata"}),
+            observation=serialized["observation"],
             reward=observation.reward,
             done=observation.done,
-            step_count=state.step_count
+            step_count=state.step_count,
         )
-        
+
         # Update episode state
         self.episode_state.episode_id = state.episode_id
         self.episode_state.step_count = state.step_count
-        self.episode_state.current_observation = asdict(observation)
+        self.episode_state.current_observation = serialized["observation"]
         self.episode_state.action_logs.append(action_log)
+        if len(self.episode_state.action_logs) > self.MAX_ACTION_LOGS:
+            self.episode_state.action_logs = self.episode_state.action_logs[
+                -self.MAX_ACTION_LOGS :
+            ]
         self.episode_state.is_reset = False
-        
+
         # Send state update
         await self._send_state_update()
-        
-        return {
-            "observation": asdict(observation),
-            "reward": observation.reward,
-            "done": observation.done,
-        }
-    
+
+        return serialized
+
     def get_state(self) -> Dict[str, Any]:
         """Get current environment state."""
-        state = self.env.state
-        return asdict(state)
-    
-    def _deserialize_action(self, action_data: Dict[str, Any]) -> Action:
-        """Convert JSON dict to Action instance."""
-        metadata = action_data.pop("metadata", {})
-        
-        # Handle tensor fields that come from JSON as lists
-        processed_data = {}
-        for key, value in action_data.items():
-            if key == "tokens" and isinstance(value, (list, str)):
-                # Convert list or string to tensor
-                if isinstance(value, str):
-                    # If it's a string, try to parse it as a list of numbers
-                    try:
-                        import json
-                        value = json.loads(value)
-                    except:
-                        # If parsing fails, treat as empty list
-                        value = []
-                if isinstance(value, list):
-                    import torch
-                    processed_data[key] = torch.tensor(value, dtype=torch.long)
-                else:
-                    processed_data[key] = value
-            elif key == "action_id" and isinstance(value, str):
-                # Convert action_id from string to int
-                try:
-                    processed_data[key] = int(value)
-                except ValueError:
-                    # If conversion fails, keep original value
-                    processed_data[key] = value
-            else:
-                processed_data[key] = value
-        
-        action = self.action_cls(**processed_data)
-        action.metadata = metadata
-        return action
+        state: State = self.env.state
+        return state.model_dump()
 
 
 def create_web_interface_app(
@@ -282,44 +393,53 @@ def create_web_interface_app(
     action_cls: Type[Action],
     observation_cls: Type[Observation],
     env_name: Optional[str] = None,
+    max_concurrent_envs: Optional[int] = None,
+    concurrency_config: Optional[Any] = None,
+    gradio_builder: Optional[Callable[..., Any]] = None,
 ) -> FastAPI:
     """
     Create a FastAPI application with web interface for the given environment.
-    
+
     Args:
         env: The Environment instance to serve
         action_cls: The Action subclass this environment expects
         observation_cls: The Observation subclass this environment returns
         env_name: Optional environment name for README loading
-        
+        max_concurrent_envs: Maximum concurrent WebSocket sessions
+        concurrency_config: Optional ConcurrencyConfig for advanced concurrency settings
+        gradio_builder: Optional callable (web_manager, action_fields, metadata,
+            is_chat_env, title, quick_start_md) -> gr.Blocks to use instead of the
+            default Gradio UI. Lets envs replace or customize the /web interface.
+
     Returns:
         FastAPI application instance with web interface
     """
     from .http_server import create_fastapi_app
-    
+
     # Create the base environment app
-    app = create_fastapi_app(env, action_cls, observation_cls)
-    
+    app = create_fastapi_app(
+        env, action_cls, observation_cls, max_concurrent_envs, concurrency_config
+    )
+
     # Load environment metadata
     metadata = load_environment_metadata(env, env_name)
-    
+
     # Create web interface manager
     web_manager = WebInterfaceManager(env, action_cls, observation_cls, metadata)
-    
-    # Add web interface routes
-    @app.get("/web", response_class=HTMLResponse)
-    async def web_interface():
-        """Serve the web interface."""
-        return get_web_interface_html(action_cls, web_manager.metadata)
-    
+
+    # Web API routes first (so they take precedence over Gradio mount at /web)
     @app.get("/web/metadata")
     async def web_metadata():
         """Get environment metadata."""
-        return asdict(web_manager.metadata)
-    
-    @app.websocket("/ws")
-    async def websocket_endpoint(websocket: WebSocket):
-        """WebSocket endpoint for real-time updates."""
+        return web_manager.metadata.model_dump()
+
+    @app.websocket("/ws/ui")
+    async def websocket_ui_endpoint(websocket: WebSocket):
+        """WebSocket endpoint for web UI real-time updates.
+
+        Note: Uses /ws/ui to avoid conflict with /ws in http_server.py
+        which is used for concurrent environment sessions.
+        """
         await web_manager.connect_websocket(websocket)
         try:
             while True:
@@ -327,1287 +447,198 @@ def create_web_interface_app(
                 await websocket.receive_text()
         except WebSocketDisconnect:
             await web_manager.disconnect_websocket(websocket)
-    
+
     @app.post("/web/reset")
     async def web_reset():
         """Reset endpoint for web interface."""
         return await web_manager.reset_environment()
-    
+
     @app.post("/web/step")
     async def web_step(request: Dict[str, Any]):
         """Step endpoint for web interface."""
         # Check if this is a message-based request (chat environment)
         if "message" in request:
             message = request["message"]
-            # Convert message to action using the environment's message_to_action method
-            action = web_manager.env.message_to_action(message)
-            action_data = {"tokens": action.tokens.tolist()}
+            if hasattr(web_manager.env, "message_to_action"):
+                action = web_manager.env.message_to_action(message)
+                if hasattr(action, "tokens"):
+                    action_data = {"tokens": action.tokens.tolist()}
+                else:
+                    action_data = action.model_dump(exclude={"metadata"})
+            else:
+                action_data = {"message": message}
         else:
             action_data = request.get("action", {})
-        
+
         return await web_manager.step_environment(action_data)
-    
+
     @app.get("/web/state")
     async def web_state():
         """State endpoint for web interface."""
         return web_manager.get_state()
-    
+
+    action_fields = _extract_action_fields(action_cls)
+    is_chat_env = _is_chat_env(action_cls)
+    quick_start_md = get_quick_start_markdown(metadata, action_cls, observation_cls)
+
+    default_blocks = build_gradio_app(
+        web_manager,
+        action_fields,
+        metadata,
+        is_chat_env,
+        title=metadata.name,
+        quick_start_md=quick_start_md,
+    )
+    if gradio_builder is not None:
+        custom_blocks = gradio_builder(
+            web_manager,
+            action_fields,
+            metadata,
+            is_chat_env,
+            metadata.name,
+            quick_start_md,
+        )
+        if not isinstance(custom_blocks, gr.Blocks):
+            raise TypeError(
+                f"gradio_builder must return a gr.Blocks instance, "
+                f"got {type(custom_blocks).__name__}"
+            )
+        gradio_blocks = gr.TabbedInterface(
+            [default_blocks, custom_blocks],
+            tab_names=["Playground", "Visualization"],
+            title=get_gradio_display_title(metadata),
+        )
+    else:
+        gradio_blocks = default_blocks
+    app = gr.mount_gradio_app(
+        app,
+        gradio_blocks,
+        path="/web",
+        theme=OPENENV_GRADIO_THEME,
+        css=OPENENV_GRADIO_CSS,
+    )
+
     return app
 
 
-def get_web_interface_html(action_cls: Type[Action], metadata: Optional[EnvironmentMetadata] = None) -> str:
-    """Generate the HTML for the web interface."""
-    
-    # Check if this is a chat environment by looking for tokens field
-    is_chat_env = False
-    if hasattr(action_cls, '__dataclass_fields__'):
-        for field_name, field_info in action_cls.__dataclass_fields__.items():
-            if field_name == 'tokens' and hasattr(field_info.type, '__name__') and 'Tensor' in field_info.type.__name__:
-                is_chat_env = True
-                break
-    
-    # Get action fields for dynamic form generation with enhanced metadata
-    action_fields = _extract_action_fields(action_cls)
-    
-    return f"""
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>OpenEnv Web Interface</title>
-    <style>
-        * {{
-            margin: 0;
-            padding: 0;
-            box-sizing: border-box;
-        }}
-        
-        body {{
-            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-            background-color: #f5f5f5;
-            height: 100vh;
-            overflow: hidden;
-        }}
-        
-        .container {{
-            display: flex;
-            height: 100vh;
-        }}
-        
-        .left-pane {{
-            width: 50%;
-            background: white;
-            border-right: 1px solid #e0e0e0;
-            display: flex;
-            flex-direction: column;
-        }}
-        
-        .right-pane {{
-            width: 50%;
-            background: #fafafa;
-            display: flex;
-            flex-direction: column;
-        }}
-        
-        .pane-header {{
-            padding: 20px;
-            border-bottom: 1px solid #e0e0e0;
-            background: #f8f9fa;
-            font-weight: 600;
-            font-size: 16px;
-        }}
-        
-        .pane-content {{
-            flex: 1;
-            padding: 20px;
-            overflow-y: auto;
-        }}
-        
-        .action-form {{
-            background: white;
-            border: 1px solid #e0e0e0;
-            border-radius: 8px;
-            padding: 20px;
-            margin-bottom: 20px;
-        }}
-        
-        .form-group {{
-            margin-bottom: 15px;
-        }}
-        
-        .form-group label {{
-            display: block;
-            margin-bottom: 5px;
-            font-weight: 500;
-            color: #333;
-        }}
-        
-        .form-group input, .form-group textarea {{
-            width: 100%;
-            padding: 8px 12px;
-            border: 1px solid #ddd;
-            border-radius: 4px;
-            font-size: 14px;
-        }}
-        
-        .form-group input:focus, .form-group textarea:focus {{
-            outline: none;
-            border-color: #007bff;
-            box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
-        }}
-        
-        .btn {{
-            background: #007bff;
-            color: white;
-            border: none;
-            padding: 10px 20px;
-            border-radius: 4px;
-            cursor: pointer;
-            font-size: 14px;
-            margin-right: 10px;
-            margin-bottom: 10px;
-        }}
-        
-        .btn:hover {{
-            background: #0056b3;
-        }}
-        
-        .btn:disabled {{
-            background: #6c757d;
-            cursor: not-allowed;
-        }}
-        
-        .btn-secondary {{
-            background: #6c757d;
-        }}
-        
-        .btn-secondary:hover {{
-            background: #545b62;
-        }}
-        
-        .state-display {{
-            background: white;
-            border: 1px solid #e0e0e0;
-            border-radius: 8px;
-            padding: 15px;
-            margin-bottom: 20px;
-        }}
-        
-        .state-item {{
-            margin-bottom: 8px;
-        }}
-        
-        .state-label {{
-            font-weight: 500;
-            color: #666;
-        }}
-        
-        .state-value {{
-            color: #333;
-            font-family: monospace;
-        }}
-        
-        .logs-container {{
-            background: white;
-            border: 1px solid #e0e0e0;
-            border-radius: 8px;
-            padding: 15px;
-            max-height: 400px;
-            overflow-y: auto;
-        }}
-        
-        .log-entry {{
-            border-bottom: 1px solid #f0f0f0;
-            padding: 10px 0;
-        }}
-        
-        .log-entry:last-child {{
-            border-bottom: none;
-        }}
-        
-        .log-timestamp {{
-            font-size: 12px;
-            color: #666;
-            margin-bottom: 5px;
-        }}
-        
-        .log-action {{
-            background: #e3f2fd;
-            padding: 8px;
-            border-radius: 4px;
-            margin-bottom: 5px;
-            font-family: monospace;
-            font-size: 12px;
-        }}
-        
-        .log-observation {{
-            background: #f3e5f5;
-            padding: 8px;
-            border-radius: 4px;
-            font-family: monospace;
-            font-size: 12px;
-        }}
-        
-        .log-reward {{
-            font-weight: 600;
-            color: #28a745;
-        }}
-        
-        .log-done {{
-            font-weight: 600;
-            color: #dc3545;
-        }}
-        
-        .status-indicator {{
-            display: inline-block;
-            width: 8px;
-            height: 8px;
-            border-radius: 50%;
-            margin-right: 8px;
-        }}
-        
-        .status-connected {{
-            background: #28a745;
-        }}
-        
-        .status-disconnected {{
-            background: #dc3545;
-        }}
-        
-        .json-display {{
-            background: #f8f9fa;
-            border: 1px solid #e9ecef;
-            border-radius: 4px;
-            padding: 10px;
-            font-family: monospace;
-            font-size: 12px;
-            white-space: pre-wrap;
-            max-height: 200px;
-            overflow-y: auto;
-        }}
-        
-        /* Chat Interface Styles */
-        .chat-interface {{
-            background: white;
-            border: 1px solid #e0e0e0;
-            border-radius: 8px;
-            padding: 20px;
-            margin-bottom: 20px;
-        }}
-        
-        .chat-messages {{
-            background: #f8f9fa;
-            border: 1px solid #e0e0e0;
-            border-radius: 8px;
-            padding: 15px;
-            margin-bottom: 15px;
-            max-height: 400px;
-            overflow-y: auto;
-        }}
-        
-        .chat-message {{
-            margin-bottom: 15px;
-            padding: 10px;
-            border-radius: 8px;
-        }}
-        
-        .chat-message:last-child {{
-            margin-bottom: 0;
-        }}
-        
-        .chat-message.user {{
-            background: #e3f2fd;
-            margin-left: 20px;
-        }}
-        
-        .chat-message.assistant {{
-            background: #f3e5f5;
-            margin-right: 20px;
-        }}
-        
-        .chat-message.system {{
-            background: #e8f5e8;
-            font-style: italic;
-        }}
-        
-        .message-role {{
-            font-weight: 600;
-            font-size: 12px;
-            color: #666;
-            margin-bottom: 5px;
-        }}
-        
-        .message-content {{
-            font-size: 14px;
-            line-height: 1.4;
-        }}
-        
-        .chat-input-container {{
-            border-top: 1px solid #e0e0e0;
-            padding-top: 15px;
-        }}
-        
-        .role-selector {{
-            margin-bottom: 10px;
-        }}
-        
-        .role-selector label {{
-            font-weight: 500;
-            margin-right: 10px;
-        }}
-        
-        .role-selector select {{
-            padding: 5px 10px;
-            border: 1px solid #ddd;
-            border-radius: 4px;
-        }}
-        
-        .message-input {{
-            display: flex;
-            gap: 10px;
-            align-items: flex-end;
-        }}
-        
-        .message-input textarea {{
-            flex: 1;
-            padding: 10px;
-            border: 1px solid #ddd;
-            border-radius: 4px;
-            resize: vertical;
-            font-family: inherit;
-        }}
-        
-        .message-input textarea:focus {{
-            outline: none;
-            border-color: #007bff;
-            box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
-        }}
-        
-        /* Instructions Section Styles */
-        .instructions-section {{
-            background: white;
-            border: 1px solid #e0e0e0;
-            border-radius: 8px;
-            padding: 20px;
-            margin-bottom: 20px;
-        }}
-        
-        .instructions-header {{
-            display: flex;
-            justify-content: space-between;
-            align-items: center;
-            margin-bottom: 15px;
-        }}
-        
-        .instructions-title {{
-            font-size: 18px;
-            font-weight: 600;
-            color: #333;
-            margin: 0;
-        }}
-        
-        .instructions-toggle {{
-            background: #f8f9fa;
-            border: 1px solid #dee2e6;
-            border-radius: 4px;
-            padding: 5px 10px;
-            cursor: pointer;
-            font-size: 12px;
-            color: #6c757d;
-        }}
-        
-        .instructions-toggle:hover {{
-            background: #e9ecef;
-        }}
-        
-        .instructions-content {{
-            display: none;
-            max-height: 400px;
-            overflow-y: auto;
-            border-top: 1px solid #e0e0e0;
-            padding-top: 15px;
-        }}
-        
-        .instructions-content.expanded {{
-            display: block;
-        }}
-        
-        .instructions-content h1,
-        .instructions-content h2,
-        .instructions-content h3 {{
-            color: #333;
-            margin-top: 20px;
-            margin-bottom: 10px;
-        }}
-        
-        .instructions-content h1 {{
-            font-size: 24px;
-            border-bottom: 2px solid #007bff;
-            padding-bottom: 10px;
-        }}
-        
-        .instructions-content h2 {{
-            font-size: 20px;
-        }}
-        
-        .instructions-content h3 {{
-            font-size: 16px;
-        }}
-        
-        .instructions-content p {{
-            margin-bottom: 10px;
-            line-height: 1.6;
-        }}
-        
-        .instructions-content code {{
-            background: #f8f9fa;
-            padding: 2px 4px;
-            border-radius: 3px;
-            font-family: monospace;
-            font-size: 14px;
-        }}
-        
-        .instructions-content pre {{
-            background: #f8f9fa;
-            border: 1px solid #e9ecef;
-            border-radius: 4px;
-            padding: 15px;
-            overflow-x: auto;
-            margin: 10px 0;
-        }}
-        
-        .instructions-content pre code {{
-            background: none;
-            padding: 0;
-        }}
-        
-        .instructions-content ul,
-        .instructions-content ol {{
-            margin: 10px 0;
-            padding-left: 20px;
-        }}
-        
-        .instructions-content li {{
-            margin-bottom: 5px;
-        }}
-        
-        .instructions-content table {{
-            border-collapse: collapse;
-            width: 100%;
-            margin: 15px 0;
-        }}
-        
-        .instructions-content th,
-        .instructions-content td {{
-            border: 1px solid #dee2e6;
-            padding: 8px 12px;
-            text-align: left;
-        }}
-        
-        .instructions-content th {{
-            background: #f8f9fa;
-            font-weight: 600;
-        }}
-        
-        /* Enhanced Form Styles */
-        .help-text {{
-            display: block;
-            margin-top: 5px;
-            font-size: 12px;
-            color: #6c757d;
-            font-style: italic;
-        }}
-        
-        .form-group label {{
-            font-weight: 500;
-            color: #333;
-            margin-bottom: 5px;
-        }}
-        
-        .form-group select {{
-            width: 100%;
-            padding: 8px 12px;
-            border: 1px solid #ddd;
-            border-radius: 4px;
-            font-size: 14px;
-            background-color: white;
-        }}
-        
-        .form-group select:focus {{
-            outline: none;
-            border-color: #007bff;
-            box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
-        }}
-        
-        .form-group textarea {{
-            width: 100%;
-            padding: 8px 12px;
-            border: 1px solid #ddd;
-            border-radius: 4px;
-            font-size: 14px;
-            font-family: inherit;
-            resize: vertical;
-        }}
-        
-        .form-group textarea:focus {{
-            outline: none;
-            border-color: #007bff;
-            box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
-        }}
-        
-        .form-group input[type="number"] {{
-            width: 100%;
-            padding: 8px 12px;
-            border: 1px solid #ddd;
-            border-radius: 4px;
-            font-size: 14px;
-        }}
-        
-        .form-group input[type="number"]:focus {{
-            outline: none;
-            border-color: #007bff;
-            box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
-        }}
-        
-        .form-group input[type="text"]:focus {{
-            outline: none;
-            border-color: #007bff;
-            box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
-        }}
-        
-        .required-indicator {{
-            color: #dc3545;
-            font-weight: bold;
-        }}
-        
-        .form-group .field-description {{
-            font-size: 11px;
-            color: #666;
-            margin-top: 2px;
-            font-style: italic;
-        }}
-    </style>
-</head>
-<body>
-    <div class="container">
-        <!-- Left Pane: HumanAgent Interface -->
-        <div class="left-pane">
-            <div class="pane-header">
-                <span class="status-indicator status-disconnected" id="connection-status"></span>
-                HumanAgent Interface
-            </div>
-            <div class="pane-content">
-                <!-- Instructions Section -->
-                {_generate_instructions_section(metadata)}
-                
-                <!-- Action Form or Chat Interface -->
-                {_generate_action_interface(action_fields, is_chat_env)}
-                
-                <!-- Control Buttons -->
-                <div style="margin-bottom: 20px;">
-                    <button class="btn btn-secondary" id="reset-btn">Reset Environment</button>
-                    <button class="btn btn-secondary" id="state-btn">Get State</button>
-                </div>
-                
-                <!-- Current State Display -->
-                <div class="state-display">
-                    <h3>Current State</h3>
-                    <div id="current-state">
-                        <div class="state-item">
-                            <span class="state-label">Status:</span>
-                            <span class="state-value" id="env-status">Not initialized</span>
-                        </div>
-                        <div class="state-item">
-                            <span class="state-label">Episode ID:</span>
-                            <span class="state-value" id="episode-id">-</span>
-                        </div>
-                        <div class="state-item">
-                            <span class="state-label">Step Count:</span>
-                            <span class="state-value" id="step-count">0</span>
-                        </div>
-                    </div>
-                </div>
-            </div>
-        </div>
-        
-        <!-- Right Pane: State Observer -->
-        <div class="right-pane">
-            <div class="pane-header">
-                State Observer
-            </div>
-            <div class="pane-content">
-                <!-- Current Observation -->
-                <div class="state-display">
-                    <h3>Current Observation</h3>
-                    <div id="current-observation" class="json-display">
-                        No observation yet
-                    </div>
-                </div>
-                
-                <!-- Action Logs -->
-                <div class="logs-container">
-                    <h3>Action History</h3>
-                    <div id="action-logs">
-                        No actions taken yet
-                    </div>
-                </div>
-            </div>
-        </div>
-    </div>
-
-    <script>
-        class OpenEnvWebInterface {{
-            constructor() {{
-                this.ws = null;
-                this.isConnected = false;
-                this.init();
-            }}
-            
-            init() {{
-                this.connectWebSocket();
-                this.setupEventListeners();
-            }}
-            
-            connectWebSocket() {{
-                const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-                const wsUrl = `${{protocol}}//${{window.location.host}}/ws`;
-                
-                this.ws = new WebSocket(wsUrl);
-                
-                this.ws.onopen = () => {{
-                    this.isConnected = true;
-                    this.updateConnectionStatus(true);
-                    console.log('WebSocket connected');
-                }};
-                
-                this.ws.onmessage = (event) => {{
-                    const data = JSON.parse(event.data);
-                    if (data.type === 'state_update') {{
-                        this.updateUI(data.episode_state);
-                    }}
-                }};
-                
-                this.ws.onclose = () => {{
-                    this.isConnected = false;
-                    this.updateConnectionStatus(false);
-                    console.log('WebSocket disconnected');
-                    // Attempt to reconnect after 3 seconds
-                    setTimeout(() => this.connectWebSocket(), 3000);
-                }};
-                
-                this.ws.onerror = (error) => {{
-                    console.error('WebSocket error:', error);
-                }};
-            }}
-            
-            setupEventListeners() {{
-                // Instructions toggle
-                const instructionsToggle = document.getElementById('instructions-toggle');
-                const instructionsContent = document.getElementById('instructions-content');
-                if (instructionsToggle && instructionsContent) {{
-                    instructionsToggle.addEventListener('click', () => {{
-                        instructionsContent.classList.toggle('expanded');
-                        instructionsToggle.textContent = instructionsContent.classList.contains('expanded') 
-                            ? 'Hide Instructions' : 'Show Instructions';
-                    }});
-                }}
-                
-                // Check if this is a chat environment
-                const isChatEnv = document.getElementById('chat-messages') !== null;
-                
-                if (isChatEnv) {{
-                    // Chat environment event listeners
-                    document.getElementById('send-message-btn').addEventListener('click', () => {{
-                        this.sendMessage();
-                    }});
-                    
-                    // Send message on Enter (but allow Shift+Enter for new lines)
-                    document.getElementById('message-input').addEventListener('keydown', (e) => {{
-                        if (e.key === 'Enter' && !e.shiftKey) {{
-                            e.preventDefault();
-                            this.sendMessage();
-                        }}
-                    }});
-                }} else {{
-                    // Traditional action form submission
-                    const actionForm = document.getElementById('action-form');
-                    if (actionForm) {{
-                        actionForm.addEventListener('submit', (e) => {{
-                            e.preventDefault();
-                            this.submitAction();
-                        }});
-                    }}
-                }}
-                
-                // Reset button
-                document.getElementById('reset-btn').addEventListener('click', () => {{
-                    this.resetEnvironment();
-                }});
-                
-                // State button
-                document.getElementById('state-btn').addEventListener('click', () => {{
-                    this.getState();
-                }});
-            }}
-            
-            async sendMessage() {{
-                const messageInput = document.getElementById('message-input');
-                const roleSelect = document.getElementById('message-role');
-                const message = messageInput.value.trim();
-                const role = roleSelect.value;
-                
-                if (!message) {{
-                    return;
-                }}
-                
-                // Add message to chat display immediately
-                this.addMessageToChat(role, message);
-                
-                // Clear input
-                messageInput.value = '';
-                
-                try {{
-                    // Send message to server to convert to action and step
-                    const response = await fetch('/web/step', {{
-                        method: 'POST',
-                        headers: {{ 'Content-Type': 'application/json' }},
-                        body: JSON.stringify({{ 
-                            message: {{
-                                role: role,
-                                content: message
-                            }}
-                        }})
-                    }});
-                    
-                    if (!response.ok) {{
-                        throw new Error(`HTTP error! status: ${{response.status}}`);
-                    }}
-                    
-                    const result = await response.json();
-                    console.log('Message sent:', result);
-                }} catch (error) {{
-                    console.error('Error sending message:', error);
-                    alert('Error sending message: ' + error.message);
-                }}
-            }}
-            
-            addMessageToChat(role, content) {{
-                const chatMessages = document.getElementById('chat-messages');
-                const messageDiv = document.createElement('div');
-                messageDiv.className = `chat-message ${{role}}`;
-                
-                messageDiv.innerHTML = `
-                    <div class="message-role">${{role.charAt(0).toUpperCase() + role.slice(1)}}</div>
-                    <div class="message-content">${{content}}</div>
-                `;
-                
-                chatMessages.appendChild(messageDiv);
-                chatMessages.scrollTop = chatMessages.scrollHeight;
-            }}
-            
-            async submitAction() {{
-                const formData = new FormData(document.getElementById('action-form'));
-                const action = {{}};
-                
-                // Collect form data
-                for (const [key, value] of formData.entries()) {{
-                    if (value !== '') {{
-                        // Handle tensor fields (tokens) - convert comma-separated string to array
-                        if (key === 'tokens') {{
-                            try {{
-                                action[key] = value.split(',').map(x => parseInt(x.trim())).filter(x => !isNaN(x));
-                            }} catch (e) {{
-                                console.error('Error parsing tokens:', e);
-                                action[key] = [];
-                            }}
-                        }} else {{
-                            action[key] = value;
-                        }}
-                    }}
-                }}
-                
-                try {{
-                    const response = await fetch('/web/step', {{
-                        method: 'POST',
-                        headers: {{ 'Content-Type': 'application/json' }},
-                        body: JSON.stringify({{ action }})
-                    }});
-                    
-                    if (!response.ok) {{
-                        throw new Error(`HTTP error! status: ${{response.status}}`);
-                    }}
-                    
-                    const result = await response.json();
-                    console.log('Step result:', result);
-                }} catch (error) {{
-                    console.error('Error submitting action:', error);
-                    alert('Error submitting action: ' + error.message);
-                }}
-            }}
-            
-            async resetEnvironment() {{
-                try {{
-                    const response = await fetch('/web/reset', {{
-                        method: 'POST',
-                        headers: {{ 'Content-Type': 'application/json' }}
-                    }});
-                    
-                    if (!response.ok) {{
-                        throw new Error(`HTTP error! status: ${{response.status}}`);
-                    }}
-                    
-                    const result = await response.json();
-                    console.log('Reset result:', result);
-                }} catch (error) {{
-                    console.error('Error resetting environment:', error);
-                    alert('Error resetting environment: ' + error.message);
-                }}
-            }}
-            
-            async getState() {{
-                try {{
-                    const response = await fetch('/web/state');
-                    const state = await response.json();
-                    console.log('Current state:', state);
-                    alert('Current state: ' + JSON.stringify(state, null, 2));
-                }} catch (error) {{
-                    console.error('Error getting state:', error);
-                    alert('Error getting state: ' + error.message);
-                }}
-            }}
-            
-            updateConnectionStatus(connected) {{
-                const indicator = document.getElementById('connection-status');
-                if (connected) {{
-                    indicator.className = 'status-indicator status-connected';
-                }} else {{
-                    indicator.className = 'status-indicator status-disconnected';
-                }}
-            }}
-            
-            updateUI(episodeState) {{
-                // Check if this is a chat environment
-                const isChatEnv = document.getElementById('chat-messages') !== null;
-                
-                // Update current state
-                document.getElementById('env-status').textContent = 
-                    episodeState.is_reset ? 'Reset' : 'Running';
-                document.getElementById('episode-id').textContent = 
-                    episodeState.episode_id || '-';
-                document.getElementById('step-count').textContent = 
-                    episodeState.step_count.toString();
-                
-                if (isChatEnv) {{
-                    // Update chat interface
-                    this.updateChatInterface(episodeState);
-                }} else {{
-                    // Update traditional observation display
-                    const observationDiv = document.getElementById('current-observation');
-                    if (episodeState.current_observation) {{
-                        observationDiv.textContent = JSON.stringify(
-                            episodeState.current_observation, null, 2
-                        );
-                    }} else {{
-                        observationDiv.textContent = 'No observation yet';
-                    }}
-                }}
-                
-                // Update action logs
-                const logsDiv = document.getElementById('action-logs');
-                if (episodeState.action_logs.length === 0) {{
-                    logsDiv.innerHTML = 'No actions taken yet';
-                }} else {{
-                    logsDiv.innerHTML = episodeState.action_logs.map(log => `
-                        <div class="log-entry">
-                            <div class="log-timestamp">${{log.timestamp}} (Step ${{log.step_count}})</div>
-                            <div class="log-action">Action: ${{JSON.stringify(log.action, null, 2)}}</div>
-                            <div class="log-observation">Observation: ${{JSON.stringify(log.observation, null, 2)}}</div>
-                            <div>
-                                <span class="log-reward">Reward: ${{log.reward !== null ? log.reward : 'None'}}</span>
-                                ${{log.done ? '<span class="log-done">DONE</span>' : ''}}
-                            </div>
-                        </div>
-                    `).join('');
-                }}
-            }}
-            
-            updateChatInterface(episodeState) {{
-                const chatMessages = document.getElementById('chat-messages');
-                if (!chatMessages) return;
-                
-                // Clear existing messages (except system message)
-                const systemMessage = chatMessages.querySelector('.chat-message.system');
-                chatMessages.innerHTML = '';
-                if (systemMessage) {{
-                    chatMessages.appendChild(systemMessage);
-                }}
-                
-                // Add messages from current observation
-                if (episodeState.current_observation && episodeState.current_observation.messages) {{
-                    episodeState.current_observation.messages.forEach(msg => {{
-                        this.addMessageToChat(msg.role, msg.content);
-                    }});
-                }}
-            }}
-        }}
-        
-        // Initialize the web interface when the page loads
-        document.addEventListener('DOMContentLoaded', () => {{
-            new OpenEnvWebInterface();
-        }});
-    </script>
-</body>
-</html>
-    """.replace('{_generate_action_form_fields(action_fields)}', _generate_action_form_fields(action_fields))
-
-
-def _generate_instructions_section(metadata: Optional[EnvironmentMetadata]) -> str:
-    """Generate the instructions section with environment documentation."""
-    if not metadata or not metadata.readme_content:
-        return ''
-    
-    # Convert markdown to HTML (basic conversion)
-    import re
-    html_content = _markdown_to_html(metadata.readme_content)
-    
-    return f'''
-                <!-- Instructions Section -->
-                <div class="instructions-section">
-                    <div class="instructions-header">
-                        <h3 class="instructions-title">{metadata.name}</h3>
-                        <button class="instructions-toggle" id="instructions-toggle">Show Instructions</button>
-                    </div>
-                    <div class="instructions-content" id="instructions-content">
-                        <div class="instructions-readme">
-                            {html_content}
-                        </div>
-                    </div>
-                </div>
-    '''
+def _is_chat_env(action_cls: Type[Action]) -> bool:
+    """Return True if the action class is a chat-style env (tokens field)."""
+    if hasattr(action_cls, "model_fields"):
+        for field_name, field_info in action_cls.model_fields.items():
+            if (
+                field_name == "tokens"
+                and hasattr(field_info.annotation, "__name__")
+                and "Tensor" in str(field_info.annotation)
+            ):
+                return True
+    return False
 
 
 def _extract_action_fields(action_cls: Type[Action]) -> List[Dict[str, Any]]:
     """Extract enhanced field metadata from Action class for form generation."""
-    import typing
-    from typing import get_origin, get_args
-    
+    # Use Pydantic's JSON schema generation for robust metadata extraction
+    try:
+        schema = action_cls.model_json_schema()
+    except AttributeError:
+        # Fallback for non-Pydantic v2 models or if something goes wrong
+        return []
+
+    properties = schema.get("properties", {})
+    required_fields = schema.get("required", [])
+
     action_fields = []
-    if not hasattr(action_cls, '__dataclass_fields__'):
-        return action_fields
-    
-    for field_name, field_info in action_cls.__dataclass_fields__.items():
-        if field_name == 'metadata':
+
+    for field_name, field_info in properties.items():
+        if field_name == "metadata":
             continue
-            
-        field_type = field_info.type
-        field_metadata = _extract_field_metadata(field_name, field_info)
-        
-        # Determine input type based on field type
-        input_type = _determine_input_type(field_type)
-        
-        # Check if field is required
-        is_required = field_info.default is field_info.default_factory
-        
-        action_fields.append({
-            'name': field_name,
-            'type': input_type,
-            'required': is_required,
-            'description': field_metadata.get('description', ''),
-            'default_value': field_metadata.get('default_value'),
-            'choices': field_metadata.get('choices', []),
-            'min_value': field_metadata.get('min_value'),
-            'max_value': field_metadata.get('max_value'),
-            'placeholder': field_metadata.get('placeholder', ''),
-            'help_text': field_metadata.get('help_text', ''),
-        })
-    
+
+        # JSON schema "type" can be a string or list/undefined
+        # Determine our internal input type
+        input_type = _determine_input_type_from_schema(field_info, field_name)
+
+        is_required = field_name in required_fields
+
+        action_fields.append(
+            {
+                "name": field_name,
+                "type": input_type,
+                "required": is_required,
+                "description": field_info.get("description", ""),
+                "default_value": field_info.get("default"),
+                "choices": field_info.get("enum"),
+                "min_value": field_info.get("minimum"),
+                "max_value": field_info.get("maximum"),
+                "min_length": field_info.get("minLength"),
+                "max_length": field_info.get("maxLength"),
+                "pattern": field_info.get("pattern"),
+                "placeholder": _generate_placeholder(field_name, field_info),
+                "help_text": _generate_help_text(field_name, field_info),
+            }
+        )
+
     return action_fields
 
 
-def _extract_field_metadata(field_name: str, field_info) -> Dict[str, Any]:
-    """Extract metadata from dataclass field including docstring and type hints."""
-    import typing
-    from typing import get_origin, get_args, Literal, Union, Optional
-    
-    metadata = {}
-    
-    # Extract description from field docstring or annotation
-    if hasattr(field_info, 'metadata') and field_info.metadata:
-        # Check for custom metadata
-        for meta in field_info.metadata:
-            if isinstance(meta, dict):
-                metadata.update(meta)
-    
-    # Extract type information
-    field_type = field_info.type
-    origin = get_origin(field_type)
-    
-    # Handle Literal types for dropdown choices
-    if origin is Literal:
-        args = get_args(field_type)
-        metadata['choices'] = list(args)
-    
-    # Handle Optional types
-    if origin is Union:
-        args = get_args(field_type)
-        if len(args) == 2 and type(None) in args:
-            # This is Optional[SomeType]
-            non_none_type = args[0] if args[1] is type(None) else args[1]
-            metadata['optional'] = True
-            # Recursively check the non-None type for choices
-            if get_origin(non_none_type) is Literal:
-                metadata['choices'] = list(get_args(non_none_type))
-        else:
-            # Regular Union type
-            metadata['choices'] = [str(arg) for arg in args if arg is not type(None)]
-    
-    # Handle numeric constraints
-    if field_type in (int, float):
-        # Check for common constraint patterns in field name
-        if 'count' in field_name.lower() or 'num' in field_name.lower():
-            metadata['min_value'] = 0
-        if 'id' in field_name.lower():
-            metadata['min_value'] = 0
-    
-    # Generate placeholder text
-    if 'message' in field_name.lower():
-        metadata['placeholder'] = f'Enter {field_name.replace("_", " ")}...'
-    elif 'code' in field_name.lower():
-        metadata['placeholder'] = 'Enter Python code here...'
-    elif 'tokens' in field_name.lower():
-        metadata['placeholder'] = 'Enter comma-separated token IDs (e.g., 1,2,3,4,5)'
-    else:
-        metadata['placeholder'] = f'Enter {field_name.replace("_", " ")}...'
-    
-    # Generate help text based on field name and type
-    if 'action_id' in field_name.lower():
-        metadata['help_text'] = 'The action ID to execute in the environment'
-    elif 'game_name' in field_name.lower():
-        metadata['help_text'] = 'Name of the game or environment'
-    elif 'tokens' in field_name.lower():
-        metadata['help_text'] = 'Token IDs as a comma-separated list of integers'
-    elif 'code' in field_name.lower():
-        metadata['help_text'] = 'Python code to execute in the environment'
-    elif 'message' in field_name.lower():
-        metadata['help_text'] = 'Text message to send'
-    
-    return metadata
+def _determine_input_type_from_schema(
+    field_info: Dict[str, Any], field_name: str
+) -> str:
+    """Determine input type from JSON schema for form generation (Gradio UI)."""
+    schema_type = field_info.get("type")
 
+    # Check for specific tensor field convention
+    if "tokens" in field_name.lower():
+        return "tensor"
 
-def _determine_input_type(field_type) -> str:
-    """Determine the appropriate HTML input type for a field type."""
-    import typing
-    from typing import get_origin, get_args, Literal, Union
-    
-    # Handle direct types
-    if field_type == str:
-        return "text"
-    elif field_type == int:
-        return "number"
-    elif field_type == float:
-        return "number"
-    elif field_type == bool:
-        return "checkbox"
-    
-    # Handle complex types
-    origin = get_origin(field_type)
-    
-    if origin is Literal:
+    if "enum" in field_info:
         return "select"
-    elif origin is Union:
-        args = get_args(field_type)
-        if len(args) == 2 and type(None) in args:
-            # Optional type - use the non-None type
-            non_none_type = args[0] if args[1] is type(None) else args[1]
-            return _determine_input_type(non_none_type)
-        elif all(isinstance(arg, str) for arg in args if arg is not type(None)):
-            return "select"
-        else:
-            return "text"
-    elif hasattr(field_type, '__name__') and 'Tensor' in field_type.__name__:
-        return "tensor"
-    else:
+
+    if schema_type == "boolean":
+        return "checkbox"
+
+    if schema_type == "integer" or schema_type == "number":
+        return "number"
+
+    if schema_type == "string":
+        # Check if it should be a textarea
+        if (
+            field_info.get("maxLength", 0) > 100
+            or "message" in field_name.lower()
+            or "code" in field_name.lower()
+        ):
+            return "textarea"
         return "text"
 
+    # Default fallback
+    return "text"
 
-def _markdown_to_html(markdown: str) -> str:
-    """Convert basic markdown to HTML for README display."""
-    import html
-    import re
-    
-    # Escape HTML first
-    html_content = html.escape(markdown)
-    
-    # Convert headers
-    html_content = re.sub(r'^# (.*?)$', r'<h1>\1</h1>', html_content, flags=re.MULTILINE)
-    html_content = re.sub(r'^## (.*?)$', r'<h2>\1</h2>', html_content, flags=re.MULTILINE)
-    html_content = re.sub(r'^### (.*?)$', r'<h3>\1</h3>', html_content, flags=re.MULTILINE)
-    
-    # Convert code blocks
-    html_content = re.sub(r'```(.*?)\n(.*?)\n```', r'<pre><code>\2</code></pre>', html_content, flags=re.DOTALL)
-    html_content = re.sub(r'`([^`]+)`', r'<code>\1</code>', html_content)
-    
-    # Convert bold and italic
-    html_content = re.sub(r'\*\*(.*?)\*\*', r'<strong>\1</strong>', html_content)
-    html_content = re.sub(r'\*(.*?)\*', r'<em>\1</em>', html_content)
-    
-    # Convert lists
-    html_content = re.sub(r'^- (.*?)$', r'<li>\1</li>', html_content, flags=re.MULTILINE)
-    html_content = re.sub(r'(<li>.*</li>)', r'<ul>\1</ul>', html_content, flags=re.DOTALL)
-    
-    # Convert line breaks
-    html_content = html_content.replace('\n', '<br>')
-    
-    return html_content
-
-
-def _generate_action_interface(action_fields: List[Dict[str, Any]], is_chat_env: bool) -> str:
-    """Generate either a chat interface or action form based on environment type."""
-    if is_chat_env:
-        return _generate_chat_interface()
-    else:
-        return _generate_action_form(action_fields)
-
-def _generate_chat_interface() -> str:
-    """Generate a chat-style interface for chat environments."""
-    return '''
-                <!-- Chat Interface -->
-                <div class="chat-interface">
-                    <h3>Chat Interface</h3>
-                    <div class="chat-messages" id="chat-messages">
-                        <div class="chat-message system">
-                            <div class="message-role">System</div>
-                            <div class="message-content">Chat environment ready. Send a message to start the conversation.</div>
-                        </div>
-                    </div>
-                    <div class="chat-input-container">
-                        <div class="role-selector">
-                            <label for="message-role">Role:</label>
-                            <select id="message-role">
-                                <option value="user">User</option>
-                                <option value="assistant">Assistant</option>
-                            </select>
-                        </div>
-                        <div class="message-input">
-                            <textarea id="message-input" placeholder="Type your message here..." rows="3"></textarea>
-                            <button class="btn" id="send-message-btn">Send Message</button>
-                        </div>
-                    </div>
-                </div>
-    '''
-
-def _generate_action_form(action_fields: List[Dict[str, Any]]) -> str:
-    """Generate a traditional action form for non-chat environments."""
-    return f'''
-                <!-- Action Form -->
-                <div class="action-form">
-                    <h3>Take Action</h3>
-                    <form id="action-form">
-                        {_generate_action_form_fields(action_fields)}
-                        <button type="submit" class="btn" id="step-btn">Step</button>
-                    </form>
-                </div>
-    '''
-
-def _generate_action_form_fields(action_fields: List[Dict[str, Any]]) -> str:
-    """Generate HTML form fields for action input with enhanced metadata."""
-    if not action_fields:
-        return '<p>No action fields available</p>'
-    
-    fields_html = []
-    for field in action_fields:
-        field_html = _generate_single_field(field)
-        fields_html.append(field_html)
-    
-    return '\n'.join(fields_html)
-
-
-def _generate_single_field(field: Dict[str, Any]) -> str:
-    """Generate HTML for a single form field with enhanced metadata."""
-    field_name = field['name']
-    field_type = field['type']
-    required = field['required']
-    placeholder = field.get('placeholder', '')
-    help_text = field.get('help_text', '')
-    choices = field.get('choices', [])
-    min_value = field.get('min_value')
-    max_value = field.get('max_value')
-    default_value = field.get('default_value')
-    
-    # Build label with required indicator
-    label_text = field_name.replace('_', ' ').title()
-    if required:
-        label_text += ' <span style="color: red;">*</span>'
-    
-    # Build input attributes
-    input_attrs = []
-    if required:
-        input_attrs.append('required')
-    if placeholder:
-        input_attrs.append(f'placeholder="{placeholder}"')
-    if min_value is not None:
-        input_attrs.append(f'min="{min_value}"')
-    if max_value is not None:
-        input_attrs.append(f'max="{max_value}"')
-    if default_value is not None:
-        input_attrs.append(f'value="{default_value}"')
-    
-    attrs_str = ' '.join(input_attrs)
-    
-    if field_type == 'checkbox':
-        return f'''
-            <div class="form-group">
-                <label>
-                    <input type="checkbox" name="{field_name}" value="true" {attrs_str}>
-                    {label_text}
-                </label>
-                {f'<small class="help-text">{help_text}</small>' if help_text else ''}
-            </div>
-        '''
-    
-    elif field_type == 'select':
-        options_html = []
-        if not required:
-            options_html.append(f'<option value="">-- Select {label_text} --</option>')
-        
-        for choice in choices:
-            selected = 'selected' if str(choice) == str(default_value) else ''
-            options_html.append(f'<option value="{choice}" {selected}>{choice}</option>')
-        
-        return f'''
-            <div class="form-group">
-                <label for="{field_name}">{label_text}:</label>
-                <select name="{field_name}" id="{field_name}" {attrs_str}>
-                    {''.join(options_html)}
-                </select>
-                {f'<small class="help-text">{help_text}</small>' if help_text else ''}
-            </div>
-        '''
-    
-    elif field_type == 'tensor':
-        return f'''
-            <div class="form-group">
-                <label for="{field_name}">{label_text} (comma-separated integers):</label>
-                <input type="text" name="{field_name}" id="{field_name}" {attrs_str}>
-                <small class="help-text">{help_text or 'Enter token IDs as comma-separated integers (e.g., 1,2,3,4,5)'}</small>
-            </div>
-        '''
-    
-    elif field_type == 'text' and ('message' in field_name.lower() or 'code' in field_name.lower()):
-        return f'''
-            <div class="form-group">
-                <label for="{field_name}">{label_text}:</label>
-                <textarea name="{field_name}" id="{field_name}" rows="3" {attrs_str}></textarea>
-                {f'<small class="help-text">{help_text}</small>' if help_text else ''}
-            </div>
-        '''
-    
+
+def _generate_placeholder(field_name: str, field_info: Dict[str, Any]) -> str:
+    """Generate placeholder text."""
+    if "message" in field_name.lower():
+        return f"Enter {field_name.replace('_', ' ')}..."
+    elif "code" in field_name.lower():
+        return "Enter Python code here..."
+    elif "tokens" in field_name.lower():
+        return "Enter comma-separated token IDs (e.g., 1,2,3,4,5)"
     else:
-        return f'''
-            <div class="form-group">
-                <label for="{field_name}">{label_text}:</label>
-                <input type="{field_type}" name="{field_name}" id="{field_name}" {attrs_str}>
-                {f'<small class="help-text">{help_text}</small>' if help_text else ''}
-            </div>
-        '''
+        return f"Enter {field_name.replace('_', ' ')}..."
+
+
+def _generate_help_text(field_name: str, field_info: Dict[str, Any]) -> str:
+    """Generate help text."""
+    description = field_info.get("description", "")
+    if description:
+        return description
+
+    if "action_id" in field_name.lower():
+        return "The action ID to execute in environment"
+    elif "game_name" in field_name.lower():
+        return "Name of game or environment"
+    elif "tokens" in field_name.lower():
+        return "Token IDs as a comma-separated list of integers"
+    elif "code" in field_name.lower():
+        return "Python code to execute in environment"
+    elif "message" in field_name.lower():
+        return "Text message to send"
+
+    return ""

src/core/evals/__init__.py

@@ -0,0 +1,18 @@
+# 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.
+
+"""Evaluation harness support for OpenEnv."""
+
+from openenv.core.evals.base import EvalHarness
+from openenv.core.evals.inspect_harness import InspectAIHarness
+from openenv.core.evals.types import EvalConfig, EvalResult
+
+__all__ = [
+    "EvalHarness",
+    "EvalConfig",
+    "EvalResult",
+    "InspectAIHarness",
+]

src/core/evals/base.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.
+
+"""Base class for evaluation harnesses."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+from openenv.core.evals.types import EvalConfig, EvalResult
+
+
+class EvalHarness(ABC):
+    """Abstract base class for evaluation harnesses.
+
+    Subclasses implement run() to define evaluation logic.
+    """
+
+    @abstractmethod
+    def run(
+        self,
+        harness_version: str,
+        library_versions: Dict[str, str],
+        dataset: str,
+        eval_parameters: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Run the evaluation and return scores.
+
+        Args:
+            harness_version: Version of the evaluation harness.
+            library_versions: Versions of libraries used in the evaluation.
+            dataset: Name of the dataset to evaluate on.
+            eval_parameters: Parameters for the evaluation.
+
+        Returns:
+            Dictionary of scores from the evaluation.
+        """
+        raise NotImplementedError
+
+    def run_from_config(self, config: EvalConfig) -> EvalResult:
+        """Run evaluation from an EvalConfig and return an EvalResult.
+
+        Args:
+            config: Configuration for the evaluation.
+
+        Returns:
+            EvalResult containing the config and scores.
+        """
+        scores = self.run(
+            harness_version=config.harness_version,
+            library_versions=config.library_versions,
+            dataset=config.dataset,
+            eval_parameters=config.eval_parameters,
+        )
+        return EvalResult(config=config, scores=scores)
+
+    @property
+    def name(self) -> str:
+        """Return the name of the harness (class name)."""
+        return self.__class__.__name__

src/core/evals/inspect_harness.py

@@ -0,0 +1,160 @@
+# 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.
+
+"""Inspect AI harness integration for OpenEnv.
+
+Requires the ``inspect-ai`` package: ``pip install 'inspect-ai>=0.3.0'``
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from openenv.core.evals.base import EvalHarness
+
+
+class InspectAIHarness(EvalHarness):
+    """Evaluation harness wrapping Inspect AI's ``eval()`` function.
+
+    All ``inspect_ai`` imports are deferred to :meth:`run` so this class is
+    importable without inspect-ai installed.  An ``ImportError`` with a clear
+    message is raised at call time if the dependency is missing.
+
+    Args:
+        log_dir: Directory for evaluation log output. Defaults to None
+            (Inspect AI writes logs to its default location).
+
+    ``eval_parameters`` keys accepted by :meth:`run`:
+
+    +--------------------------+----------+-----------------+-----------------------------------+
+    | Key                      | Type     | Default         | Purpose                           |
+    +==========================+==========+=================+===================================+
+    | ``model``                | str      | *required*      | Model string, e.g. "openai/gpt-4o"|
+    | ``task``                 | str|None | ``dataset`` arg | Task file path or task string     |
+    | ``task_args``            | dict     | ``{}``          | Arguments to pass to the task     |
+    | ``max_samples``          | int|None | None            | Limit samples per task            |
+    | ``temperature``          | float|None| None           | Model generation temperature      |
+    | ``max_tokens``           | int|None | None            | Max generation tokens             |
+    | ``epochs``               | int|None | None            | Number of evaluation epochs       |
+    | ``solver``               | list|None| None            | Solver pipeline override          |
+    | ``scorer``               | list|None| None            | Scorer override                   |
+    | ``model_args``           | dict     | ``{}``          | Provider-specific model kwargs    |
+    +--------------------------+----------+-----------------+-----------------------------------+
+    """
+
+    def __init__(
+        self,
+        *,
+        log_dir: Optional[str] = None,
+    ):
+        self.log_dir = log_dir
+
+    def run(
+        self,
+        harness_version: str,
+        library_versions: Dict[str, str],
+        dataset: str,
+        eval_parameters: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Run an Inspect AI evaluation.
+
+        Args:
+            harness_version: Version of inspect-ai being used.
+            library_versions: Versions of supporting libraries.
+            dataset: Default task string (used when ``task`` is not specified
+                in *eval_parameters*).
+            eval_parameters: See class docstring for accepted keys.
+
+        Returns:
+            Dictionary mapping metric names to scores.
+
+        Raises:
+            ImportError: If ``inspect-ai`` is not installed.
+            ValueError: If ``model`` is missing from *eval_parameters*.
+            RuntimeError: If the evaluation fails (log status is not "success").
+        """
+        try:
+            from inspect_ai import eval as inspect_eval
+        except ImportError:
+            raise ImportError(
+                "inspect-ai is required for InspectAIHarness. "
+                "Install it with: pip install 'inspect-ai>=0.3.0'"
+            )
+
+        # Extract required model parameter
+        model = eval_parameters.get("model")
+        if model is None:
+            raise ValueError(
+                "eval_parameters must include 'model' "
+                "(e.g. 'openai/gpt-4o', 'hf/meta-llama/...')."
+            )
+
+        # Task: explicit parameter or fall back to dataset
+        task = eval_parameters.get("task", dataset)
+
+        # Build eval kwargs
+        eval_kwargs: Dict[str, Any] = {}
+
+        task_args = eval_parameters.get("task_args", {})
+        if task_args:
+            eval_kwargs["task_args"] = task_args
+
+        model_args = eval_parameters.get("model_args", {})
+        if model_args:
+            eval_kwargs["model_args"] = model_args
+
+        for key in ("max_samples", "temperature", "max_tokens", "epochs"):
+            value = eval_parameters.get(key)
+            if value is not None:
+                eval_kwargs[key] = value
+
+        if eval_parameters.get("solver") is not None:
+            eval_kwargs["solver"] = eval_parameters["solver"]
+
+        if eval_parameters.get("scorer") is not None:
+            eval_kwargs["scorer"] = eval_parameters["scorer"]
+
+        if self.log_dir is not None:
+            eval_kwargs["log_dir"] = self.log_dir
+
+        # Run evaluation
+        logs = inspect_eval(task, model=model, **eval_kwargs)
+
+        # Extract results from the first log
+        if not logs:
+            raise RuntimeError(
+                "Inspect AI evaluation returned no logs. "
+                "Check that the task and model arguments are valid."
+            )
+        log = logs[0]
+        if log.status != "success":
+            raise RuntimeError(
+                f"Inspect AI evaluation failed with status: {log.status}"
+            )
+
+        return self._extract_scores(log)
+
+    def _extract_scores(self, log: Any) -> Dict[str, Any]:
+        """Parse an EvalLog's results into a flat score dictionary.
+
+        Iterates over ``log.results.scores`` (a list of ``EvalScore``),
+        flattening each scorer's ``metrics`` dict into a single output dict.
+
+        Args:
+            log: An ``inspect_ai`` ``EvalLog`` object.
+
+        Returns:
+            Dictionary mapping metric names to their values.
+        """
+        scores: Dict[str, Any] = {}
+        if log.results is None:
+            return scores
+
+        for eval_score in log.results.scores:
+            for metric_name, metric in eval_score.metrics.items():
+                scores[metric_name] = metric.value
+
+        return scores