Upload folder using huggingface_hub

Dockerfile

@@ -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.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local src/core)
+# - Standalone environments (with openenv from pip)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/huggingface/openenv-base:latest
+FROM ghcr.io/huggingface/openenv-base:latest AS builder
+
+WORKDIR /app
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already in the pyproject.toml dependencies
+# For standalone builds, openenv will be installed from pip via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+
+# Install git for building from git repos (build-time only)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install dependencies using uv sync
+# First pass: install dependencies without the project (for better caching)
+# Second pass: install the project itself
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
+    install -m 0755 /root/.local/bin/uv /usr/local/bin/uv && \
+    install -m 0755 /root/.local/bin/uvx /usr/local/bin/uvx
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ghcr.io/huggingface/openenv-base:latest
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Health check using Python (more portable than curl/wget)
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+
+# Run the FastAPI server from the installed package.
+CMD ["uvicorn", "chess_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]
+
+ENV ENABLE_WEB_INTERFACE=true

README.md

@@ -1,10 +1,166 @@
 ---
-title: Chess Env
-emoji: 🏢
-colorFrom: indigo
-colorTo: yellow
+title: Chess Environment Server
+emoji: ♟️
+colorFrom: blue
+colorTo: green
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv-0.10.0
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Chess Environment
+
+A chess reinforcement learning environment for OpenEnv, powered by the [moonfish](https://github.com/luccabb/moonfish) chess engine.
+
+![Chess web playground](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/openenv/chess.png)
+
+*The `/web` playground after a few moves: the board and one button per legal move.*
+
+## Features
+
+- **Full chess rules** via python-chess library
+- **Configurable opponent**: moonfish engine, random moves, or self-play
+- **Position evaluation**: Uses moonfish's PSQT-based evaluation
+- **Standard OpenEnv interface**: reset(), step(), state
+
+## Quick Start
+
+### Using Docker
+
+```bash
+# Build the image
+docker build -t chess-env:latest -f envs/chess_env/server/Dockerfile .
+
+# Run the server
+docker run -p 8000:8000 chess-env:latest
+```
+
+### Using the Client
+
+The client is **async by default**:
+
+```python
+import asyncio
+from chess_env import ChessEnv, ChessAction
+
+async def main():
+    async with ChessEnv(base_url="http://localhost:8000") as env:
+        # Reset for a new game
+        result = await env.reset()
+        print(f"Starting position: {result.observation.fen}")
+        print(f"Legal moves: {result.observation.legal_moves}")
+
+        # Make a move
+        result = await env.step(ChessAction(move="e2e4"))
+        print(f"Reward: {result.reward}, Done: {result.done}")
+
+        # Play until game ends
+        while not result.done:
+            move = result.observation.legal_moves[0]
+            result = await env.step(ChessAction(move=move))
+
+        print(f"Game result: {result.observation.result}")
+
+asyncio.run(main())
+```
+
+For **synchronous usage**, use the `.sync()` wrapper:
+
+```python
+from chess_env import ChessEnv, ChessAction
+
+with ChessEnv(base_url="http://localhost:8000").sync() as env:
+    result = env.reset()
+    result = env.step(ChessAction(move="e2e4"))
+    print(f"Reward: {result.reward}")
+```
+
+## Observation Space
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `fen` | str | Board position in FEN notation |
+| `legal_moves` | List[str] | Legal moves in UCI format |
+| `is_check` | bool | Whether current player is in check |
+| `done` | bool | Whether game has ended |
+| `reward` | float | Reward for last action |
+| `result` | str | Game result ("1-0", "0-1", "1/2-1/2") |
+
+## Action Space
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `move` | str | UCI format move (e.g., "e2e4", "e7e8q") |
+
+## Rewards
+
+| Outcome | Reward |
+|---------|--------|
+| Win | +1.0 |
+| Loss | -1.0 |
+| Draw | 0.0 |
+| Illegal move | -0.1 |
+
+## Configuration
+
+The environment supports these configuration options:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `opponent` | "moonfish" | Opponent type: "moonfish", "random", or None |
+| `opponent_depth` | 2 | Search depth for moonfish opponent |
+| `max_moves` | 500 | Maximum half-moves before draw |
+| `agent_color` | None | Agent color: "white", "black", or None (alternate each episode) |
+| `gamma` | 0.99 | Discount factor for temporal credit assignment |
+
+## Temporal Discounting
+
+For RL training, the environment computes temporally discounted rewards at episode end. This helps with credit assignment in long games where only the final outcome is known.
+
+When an episode ends, the terminal observation's `metadata` includes:
+- `discounted_rewards`: List of discounted rewards for each agent move
+- `gamma`: The discount factor used
+
+The formula is `r_t = γ^(T-1-t) × R_final` where:
+- `T` = total agent moves
+- `t` = move index (0-indexed)
+- `R_final` = terminal reward (+1, -1, or 0)
+
+Example for a 5-move win with γ=0.99:
+```
+Move 0: 0.99^4 × 1.0 = 0.961
+Move 1: 0.99^3 × 1.0 = 0.970
+Move 2: 0.99^2 × 1.0 = 0.980
+Move 3: 0.99^1 × 1.0 = 0.990
+Move 4: 0.99^0 × 1.0 = 1.000
+```
+
+## Links
+
+- [moonfish GitHub](https://github.com/luccabb/moonfish)
+- [Play online](https://huggingface.co/spaces/luccabb/moonfish_chess)
+
+## Hugging Face Space Deployment
+
+This Space is built from OpenEnv environment `chess_env`.
+
+- Space URL: `https://huggingface.co/spaces/openenv/chess_env`
+- OpenEnv pinned ref: `0.10.0`
+- Hub tag: `openenv`
+
+### Connecting from Code
+
+```bash
+pip install git+https://huggingface.co/spaces/openenv/chess_env
+```
+
+```python
+from chess_env import ChessEnv
+
+with ChessEnv(base_url="https://openenv-chess-env.hf.space").sync() as env:
+    result = env.reset()
+```

__init__.py

@@ -0,0 +1,34 @@
+# 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.
+
+"""
+Chess Environment for OpenEnv.
+
+This module provides OpenEnv integration for chess, using the moonfish
+chess engine for position evaluation and opponent play.
+
+Example:
+    >>> from envs.chess_env import ChessEnv, ChessAction
+    >>>
+    >>> # Connect to a running server or start via Docker
+    >>> env = ChessEnv.from_docker_image("chess-env:latest")
+    >>>
+    >>> # Reset and interact
+    >>> result = env.reset()
+    >>> print(result.observation.fen)
+    >>> print(result.observation.legal_moves)
+    >>>
+    >>> result = env.step(ChessAction(move="e2e4"))
+    >>> print(result.reward, result.done)
+    >>>
+    >>> # Cleanup
+    >>> env.close()
+"""
+
+from .client import ChessEnv
+from .models import ChessAction, ChessObservation, ChessState
+
+__all__ = ["ChessEnv", "ChessAction", "ChessObservation", "ChessState"]

client.py

@@ -0,0 +1,107 @@
+# 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.
+
+"""
+Chess Environment Client.
+
+This module provides the client for connecting to a Chess Environment server
+via WebSocket for persistent sessions.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_client import EnvClient
+
+from .models import ChessAction, ChessObservation, ChessState
+
+
+class ChessEnv(EnvClient[ChessAction, ChessObservation, ChessState]):
+    """
+    Client for Chess Environment.
+
+    This client maintains a persistent WebSocket connection to the environment
+    server, enabling efficient multi-step interactions with lower latency.
+
+    Uses the moonfish chess engine for opponent moves and position evaluation.
+
+    Example:
+        >>> with ChessEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.fen)
+        ...     print(result.observation.legal_moves)
+        ...
+        ...     result = client.step(ChessAction(move="e2e4"))
+        ...     print(result.reward, result.done)
+    """
+
+    def _step_payload(self, action: ChessAction) -> Dict[str, Any]:
+        """
+        Convert ChessAction to JSON payload for step request.
+
+        Args:
+            action: ChessAction instance with UCI move string.
+
+        Returns:
+            Dictionary representation suitable for JSON encoding.
+        """
+        return {
+            "move": action.move,
+        }
+
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[ChessObservation]:
+        """
+        Parse server response into StepResult[ChessObservation].
+
+        Args:
+            payload: JSON response from server.
+
+        Returns:
+            StepResult with ChessObservation.
+        """
+        obs_data = payload.get("observation", {})
+        # `serialize_observation` keeps reward and done on the envelope, not in
+        # the observation dict. Reading them from obs_data left every step
+        # reporting reward 0.0 and done False.
+        reward = payload.get("reward", 0.0)
+        done = payload.get("done", False)
+
+        observation = ChessObservation(
+            fen=obs_data.get("fen", ""),
+            legal_moves=obs_data.get("legal_moves", []),
+            is_check=obs_data.get("is_check", False),
+            done=bool(done),
+            reward=reward,
+            result=obs_data.get("result"),
+            metadata=payload.get("metadata", obs_data.get("metadata", {})),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=observation.reward,
+            done=observation.done,
+            metadata=payload.get("metadata"),
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> ChessState:
+        """
+        Parse server response into ChessState object.
+
+        Args:
+            payload: JSON response from /state endpoint.
+
+        Returns:
+            ChessState object with environment state information.
+        """
+        return ChessState(
+            episode_id=payload.get("episode_id", ""),
+            fen=payload.get("fen", ""),
+            current_player=payload.get("current_player", "white"),
+            move_history=payload.get("move_history", []),
+            step_count=payload.get("step_count", 0),
+        )

discovery.json

@@ -0,0 +1,9 @@
+{
+  "description": "Play chess with legal UCI moves against a Moonfish engine, a random opponent, or in self-play. Observations include the FEN board position, legal moves, and game outcome.",
+  "tags": ["openenv", "rl-environment", "chess", "strategy", "board-game", "self-play"],
+  "representative_queries": [
+    "find a chess environment with a configurable opponent",
+    "evaluate move selection from a FEN board position",
+    "run chess self-play through an OpenEnv client"
+  ]
+}

envs/chess_env/README.md

@@ -0,0 +1,144 @@
+---
+title: Chess Environment Server
+emoji: ♟️
+colorFrom: gray
+colorTo: green
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# Chess Environment
+
+A chess reinforcement learning environment for OpenEnv, powered by the [moonfish](https://github.com/luccabb/moonfish) chess engine.
+
+![Chess web playground](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/openenv/chess.png)
+
+*The `/web` playground after a few moves: the board and one button per legal move.*
+
+## Features
+
+- **Full chess rules** via python-chess library
+- **Configurable opponent**: moonfish engine, random moves, or self-play
+- **Position evaluation**: Uses moonfish's PSQT-based evaluation
+- **Standard OpenEnv interface**: reset(), step(), state
+
+## Quick Start
+
+### Using Docker
+
+```bash
+# Build the image
+docker build -t chess-env:latest -f envs/chess_env/server/Dockerfile .
+
+# Run the server
+docker run -p 8000:8000 chess-env:latest
+```
+
+### Using the Client
+
+The client is **async by default**:
+
+```python
+import asyncio
+from chess_env import ChessEnv, ChessAction
+
+async def main():
+    async with ChessEnv(base_url="http://localhost:8000") as env:
+        # Reset for a new game
+        result = await env.reset()
+        print(f"Starting position: {result.observation.fen}")
+        print(f"Legal moves: {result.observation.legal_moves}")
+
+        # Make a move
+        result = await env.step(ChessAction(move="e2e4"))
+        print(f"Reward: {result.reward}, Done: {result.done}")
+
+        # Play until game ends
+        while not result.done:
+            move = result.observation.legal_moves[0]
+            result = await env.step(ChessAction(move=move))
+
+        print(f"Game result: {result.observation.result}")
+
+asyncio.run(main())
+```
+
+For **synchronous usage**, use the `.sync()` wrapper:
+
+```python
+from chess_env import ChessEnv, ChessAction
+
+with ChessEnv(base_url="http://localhost:8000").sync() as env:
+    result = env.reset()
+    result = env.step(ChessAction(move="e2e4"))
+    print(f"Reward: {result.reward}")
+```
+
+## Observation Space
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `fen` | str | Board position in FEN notation |
+| `legal_moves` | List[str] | Legal moves in UCI format |
+| `is_check` | bool | Whether current player is in check |
+| `done` | bool | Whether game has ended |
+| `reward` | float | Reward for last action |
+| `result` | str | Game result ("1-0", "0-1", "1/2-1/2") |
+
+## Action Space
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `move` | str | UCI format move (e.g., "e2e4", "e7e8q") |
+
+## Rewards
+
+| Outcome | Reward |
+|---------|--------|
+| Win | +1.0 |
+| Loss | -1.0 |
+| Draw | 0.0 |
+| Illegal move | -0.1 |
+
+## Configuration
+
+The environment supports these configuration options:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `opponent` | "moonfish" | Opponent type: "moonfish", "random", or None |
+| `opponent_depth` | 2 | Search depth for moonfish opponent |
+| `max_moves` | 500 | Maximum half-moves before draw |
+| `agent_color` | None | Agent color: "white", "black", or None (alternate each episode) |
+| `gamma` | 0.99 | Discount factor for temporal credit assignment |
+
+## Temporal Discounting
+
+For RL training, the environment computes temporally discounted rewards at episode end. This helps with credit assignment in long games where only the final outcome is known.
+
+When an episode ends, the terminal observation's `metadata` includes:
+- `discounted_rewards`: List of discounted rewards for each agent move
+- `gamma`: The discount factor used
+
+The formula is `r_t = γ^(T-1-t) × R_final` where:
+- `T` = total agent moves
+- `t` = move index (0-indexed)
+- `R_final` = terminal reward (+1, -1, or 0)
+
+Example for a 5-move win with γ=0.99:
+```
+Move 0: 0.99^4 × 1.0 = 0.961
+Move 1: 0.99^3 × 1.0 = 0.970
+Move 2: 0.99^2 × 1.0 = 0.980
+Move 3: 0.99^1 × 1.0 = 0.990
+Move 4: 0.99^0 × 1.0 = 1.000
+```
+
+## Links
+
+- [moonfish GitHub](https://github.com/luccabb/moonfish)
+- [Play online](https://huggingface.co/spaces/luccabb/moonfish_chess)

envs/chess_env/__init__.py

@@ -0,0 +1,34 @@
+# 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.
+
+"""
+Chess Environment for OpenEnv.
+
+This module provides OpenEnv integration for chess, using the moonfish
+chess engine for position evaluation and opponent play.
+
+Example:
+    >>> from envs.chess_env import ChessEnv, ChessAction
+    >>>
+    >>> # Connect to a running server or start via Docker
+    >>> env = ChessEnv.from_docker_image("chess-env:latest")
+    >>>
+    >>> # Reset and interact
+    >>> result = env.reset()
+    >>> print(result.observation.fen)
+    >>> print(result.observation.legal_moves)
+    >>>
+    >>> result = env.step(ChessAction(move="e2e4"))
+    >>> print(result.reward, result.done)
+    >>>
+    >>> # Cleanup
+    >>> env.close()
+"""
+
+from .client import ChessEnv
+from .models import ChessAction, ChessObservation, ChessState
+
+__all__ = ["ChessEnv", "ChessAction", "ChessObservation", "ChessState"]

envs/chess_env/client.py

@@ -0,0 +1,107 @@
+# 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.
+
+"""
+Chess Environment Client.
+
+This module provides the client for connecting to a Chess Environment server
+via WebSocket for persistent sessions.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_client import EnvClient
+
+from .models import ChessAction, ChessObservation, ChessState
+
+
+class ChessEnv(EnvClient[ChessAction, ChessObservation, ChessState]):
+    """
+    Client for Chess Environment.
+
+    This client maintains a persistent WebSocket connection to the environment
+    server, enabling efficient multi-step interactions with lower latency.
+
+    Uses the moonfish chess engine for opponent moves and position evaluation.
+
+    Example:
+        >>> with ChessEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.fen)
+        ...     print(result.observation.legal_moves)
+        ...
+        ...     result = client.step(ChessAction(move="e2e4"))
+        ...     print(result.reward, result.done)
+    """
+
+    def _step_payload(self, action: ChessAction) -> Dict[str, Any]:
+        """
+        Convert ChessAction to JSON payload for step request.
+
+        Args:
+            action: ChessAction instance with UCI move string.
+
+        Returns:
+            Dictionary representation suitable for JSON encoding.
+        """
+        return {
+            "move": action.move,
+        }
+
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[ChessObservation]:
+        """
+        Parse server response into StepResult[ChessObservation].
+
+        Args:
+            payload: JSON response from server.
+
+        Returns:
+            StepResult with ChessObservation.
+        """
+        obs_data = payload.get("observation", {})
+        # `serialize_observation` keeps reward and done on the envelope, not in
+        # the observation dict. Reading them from obs_data left every step
+        # reporting reward 0.0 and done False.
+        reward = payload.get("reward", 0.0)
+        done = payload.get("done", False)
+
+        observation = ChessObservation(
+            fen=obs_data.get("fen", ""),
+            legal_moves=obs_data.get("legal_moves", []),
+            is_check=obs_data.get("is_check", False),
+            done=bool(done),
+            reward=reward,
+            result=obs_data.get("result"),
+            metadata=payload.get("metadata", obs_data.get("metadata", {})),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=observation.reward,
+            done=observation.done,
+            metadata=payload.get("metadata"),
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> ChessState:
+        """
+        Parse server response into ChessState object.
+
+        Args:
+            payload: JSON response from /state endpoint.
+
+        Returns:
+            ChessState object with environment state information.
+        """
+        return ChessState(
+            episode_id=payload.get("episode_id", ""),
+            fen=payload.get("fen", ""),
+            current_player=payload.get("current_player", "white"),
+            move_history=payload.get("move_history", []),
+            step_count=payload.get("step_count", 0),
+        )

envs/chess_env/discovery.json

@@ -0,0 +1,9 @@
+{
+  "description": "Play chess with legal UCI moves against a Moonfish engine, a random opponent, or in self-play. Observations include the FEN board position, legal moves, and game outcome.",
+  "tags": ["openenv", "rl-environment", "chess", "strategy", "board-game", "self-play"],
+  "representative_queries": [
+    "find a chess environment with a configurable opponent",
+    "evaluate move selection from a FEN board position",
+    "run chess self-play through an OpenEnv client"
+  ]
+}

envs/chess_env/models.py

@@ -0,0 +1,68 @@
+# 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 Chess Environment.
+
+This module defines the Action, Observation, and State types for chess games
+via the OpenEnv interface. Uses the moonfish chess engine for move search
+and position evaluation.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from openenv.core.env_server import Action, Observation, State
+from pydantic import Field
+
+
+class ChessAction(Action):
+    """
+    Action for Chess environment.
+
+    Attributes:
+        move: UCI format move string (e.g., "e2e4", "e7e8q" for promotion).
+    """
+
+    move: str
+
+
+class ChessObservation(Observation):
+    """
+    Observation for Chess environment.
+
+    Attributes:
+        fen: Board position in FEN notation.
+        legal_moves: List of legal moves in UCI format.
+        is_check: Whether the current player is in check.
+        done: Whether the game is over.
+        reward: Reward for the last action.
+        result: Game result string if game is over (e.g., "1-0", "0-1", "1/2-1/2").
+    """
+
+    fen: str = ""
+    legal_moves: List[str] = Field(default_factory=list)
+    is_check: bool = False
+    result: Optional[str] = None
+
+
+class ChessState(State):
+    """
+    State for Chess environment.
+
+    Attributes:
+        episode_id: Unique ID for the current game.
+        fen: Current board position in FEN notation.
+        current_player: "white" or "black".
+        move_history: List of moves played in UCI format.
+        step_count: Number of half-moves played.
+    """
+
+    fen: str = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
+    current_player: str = "white"
+    move_history: List[str] = Field(default_factory=list)
+    step_count: int = 0

envs/chess_env/openenv.yaml

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

envs/chess_env/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-chess-env"
+version = "0.1.0"
+description = "Chess Environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    "openenv @ git+https://github.com/huggingface/OpenEnv.git@v0.10.0",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0.0",
+    "uvicorn[standard]>=0.24.0",
+    "requests>=2.31.0",
+    "python-chess>=1.999",
+    "moonfish>=0.0.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+server = "chess_env.server.app:main"
+
+[tool.setuptools]
+packages = ["chess_env", "chess_env.server"]
+package-dir = { "chess_env" = ".", "chess_env.server" = "server" }

envs/chess_env/scripts/verify.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Verification script for chess_env
+# Run from repository root: bash envs/chess_env/scripts/verify.sh
+
+set -e
+
+echo "=== Chess Environment Verification ==="
+echo
+
+# Colors for output
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+check_pass() {
+    echo -e "${GREEN}✓ $1${NC}"
+}
+
+check_fail() {
+    echo -e "${RED}✗ $1${NC}"
+    exit 1
+}
+
+# 1. Run unit tests
+echo "1. Running unit tests..."
+if PYTHONPATH=src:. uv run pytest tests/envs/test_chess_environment.py -v; then
+    check_pass "Unit tests passed"
+else
+    check_fail "Unit tests failed"
+fi
+echo
+
+# 2. Run linting
+echo "2. Running linting..."
+if uv run ruff check envs/chess_env/ tests/envs/test_chess_environment.py; then
+    check_pass "Linting passed"
+else
+    check_fail "Linting failed"
+fi
+echo
+
+# 3. Check formatting
+echo "3. Checking formatting..."
+if uv run ruff format envs/chess_env/ tests/envs/test_chess_environment.py --check; then
+    check_pass "Formatting passed"
+else
+    check_fail "Formatting failed"
+fi
+echo
+
+# 4. Verify imports
+echo "4. Verifying module imports..."
+if PYTHONPATH=src:. uv run python -c "from envs.chess_env import ChessEnv, ChessAction, ChessObservation, ChessState; print('  Imports: ChessEnv, ChessAction, ChessObservation, ChessState')"; then
+    check_pass "Module imports successful"
+else
+    check_fail "Module imports failed"
+fi
+echo
+
+echo "=== All checks passed! ==="

envs/chess_env/server/Dockerfile

@@ -0,0 +1,79 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local src/core)
+# - Standalone environments (with openenv from pip)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/huggingface/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already in the pyproject.toml dependencies
+# For standalone builds, openenv will be installed from pip via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+
+# Install git for building from git repos (build-time only)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install dependencies using uv sync
+# First pass: install dependencies without the project (for better caching)
+# Second pass: install the project itself
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Health check using Python (more portable than curl/wget)
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+
+# Run the FastAPI server from the installed package.
+CMD ["uvicorn", "chess_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

envs/chess_env/server/__init__.py

@@ -0,0 +1,11 @@
+# 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.
+
+"""Chess Environment server module."""
+
+from .chess_environment import ChessEnvironment
+
+__all__ = ["ChessEnvironment"]

envs/chess_env/server/app.py

@@ -0,0 +1,35 @@
+# 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 Chess Environment."""
+
+import os
+
+from openenv.core.env_server import create_app
+
+from ..models import ChessAction, ChessObservation, ChessState
+from .chess_environment import ChessEnvironment
+
+# Create the FastAPI app
+# Pass the class (factory) instead of an instance for WebSocket session support
+app = create_app(
+    ChessEnvironment,
+    ChessAction,
+    ChessObservation,
+    env_name="chess_env",
+    state_cls=ChessState,
+    max_concurrent_envs=int(os.getenv("MAX_CONCURRENT_ENVS", "8")),
+)
+
+
+def main():
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

envs/chess_env/server/chess_environment.py

@@ -0,0 +1,337 @@
+# 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.
+
+"""
+Chess Environment for OpenEnv using moonfish.
+
+This module provides a chess environment for reinforcement learning,
+using python-chess for game logic and moonfish for position evaluation
+and opponent play.
+"""
+
+import random
+import threading
+import uuid
+from typing import Any, Dict, List, Optional, Tuple
+
+import chess
+from moonfish.lib import search_move
+from moonfish.psqt import board_evaluation, BOARD_EVALUATION_CACHE
+from openenv.core.env_server import Environment
+
+from ..models import ChessAction, ChessObservation, ChessState
+from .rubrics import ChessWinLossRubric
+
+# moonfish keeps one evaluation cache per process, so sessions take turns with it.
+_MOONFISH_LOCK = threading.Lock()
+
+
+class ChessEnvironment(Environment):
+    """
+    Chess environment implementing the OpenEnv interface.
+
+    Uses python-chess for game logic and moonfish for position evaluation.
+    Designed for RL training where an agent plays as one color against
+    an opponent (which can be random, moonfish engine, or self-play).
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS = True
+
+    def __init__(
+        self,
+        opponent: str = "moonfish",
+        opponent_depth: int = 2,
+        max_moves: int = 500,
+        agent_color: str | None = None,
+        gamma: float = 0.99,
+    ):
+        """
+        Initialize the chess environment.
+
+        Args:
+            opponent: Opponent type - "moonfish", "random", or None (self-play)
+            opponent_depth: Search depth when using moonfish as opponent
+            max_moves: Maximum half-moves before draw
+            agent_color: Which color the agent plays - "white", "black", or None (alternate each episode)
+            gamma: Discount factor for temporal credit assignment (0-1)
+        """
+        super().__init__(rubric=ChessWinLossRubric(gamma=gamma))
+        self._opponent = opponent
+        self._opponent_depth = opponent_depth
+        self._max_moves = max_moves
+        self._agent_color_setting = agent_color
+        self._gamma = gamma
+        self._board = None
+        self._state = None
+        self._agent_color = chess.WHITE
+        self._agent_move_count = 0  # Track agent moves for discounting
+        self.reset()
+
+    def reset(self, fen: str = None):
+        """
+        Initialize a new chess game episode.
+
+        Args:
+            fen: Optional starting position in FEN notation.
+
+        Returns:
+            Initial observation of the board state.
+        """
+        self._reset_rubric()
+        # moonfish's module-level evaluation cache is never trimmed.
+        with _MOONFISH_LOCK:
+            BOARD_EVALUATION_CACHE.clear()
+
+        if fen:
+            self._board = chess.Board(fen)
+        else:
+            self._board = chess.Board()
+
+        # Generate episode ID once
+        episode_id = str(uuid.uuid4())
+
+        # Determine agent color
+        if self._agent_color_setting == "white":
+            self._agent_color = chess.WHITE
+        elif self._agent_color_setting == "black":
+            self._agent_color = chess.BLACK
+        elif self._agent_color_setting is None:
+            # Alternate each episode based on episode_id hash
+            self._agent_color = (
+                chess.WHITE if hash(episode_id) % 2 == 0 else chess.BLACK
+            )
+        else:
+            self._agent_color = chess.WHITE
+
+        self._state = ChessState(
+            episode_id=episode_id,
+            step_count=0,
+            current_player="white" if self._board.turn else "black",
+            fen=self._board.fen(),
+            move_history=[],
+        )
+        self._agent_move_count = 0
+
+        # If agent plays Black and opponent is configured, opponent moves first
+        if self._opponent is not None and self._agent_color == chess.BLACK:
+            self._make_opponent_move()
+
+        # Check if starting position is already terminal (e.g., custom FEN with checkmate/stalemate)
+        _, done = self._calculate_reward_and_done()
+        return self._make_observation(done=done)
+
+    def step(self, action: ChessAction):
+        """
+        Execute a chess move and return the resulting state.
+
+        Args:
+            action: The move to make in UCI format (e.g., "e2e4").
+
+        Returns:
+            Observation with reward and done flag.
+        """
+        if self._board is None:
+            raise RuntimeError("Environment not initialized. Call reset() first.")
+
+        # Parse the move
+        try:
+            move = chess.Move.from_uci(action.move)
+        except ValueError:
+            return self._make_observation(reward=-0.1, done=False)
+
+        # Check if move is legal
+        if move not in self._board.legal_moves:
+            return self._make_observation(reward=-0.1, done=False)
+
+        # Execute the move
+        self._board.push(move)
+        self._state.step_count += 1
+        self._agent_move_count += 1
+        self._state.move_history.append(action.move)
+        self._state.current_player = "white" if self._board.turn else "black"
+        self._state.fen = self._board.fen()
+
+        # Calculate reward and check for game end
+        reward, done = self._calculate_reward_and_done()
+
+        # If game not over and opponent is configured, make opponent move
+        if not done and self._opponent is not None:
+            self._make_opponent_move()
+            reward, done = self._calculate_reward_and_done()
+
+        obs = self._make_observation(reward=reward, done=done)
+
+        # Feed to rubric for trajectory accumulation
+        self._apply_rubric(action, obs)
+
+        # Note: obs.reward is kept from _calculate_reward_and_done() rather than
+        # overridden by the rubric. The rubric here is a TrajectoryRubric that
+        # returns 0.0 until done then the final score — the inline reward logic
+        # already provides the correct per-step reward including penalties for
+        # invalid/illegal moves. The rubric's value is in compute_step_rewards()
+        # for training infrastructure, not in replacing obs.reward.
+
+        return obs
+
+    def _make_observation(self, reward: float = 0.0, done: bool = False):
+        """Build observation from current board state."""
+        legal_moves = [move.uci() for move in self._board.legal_moves]
+
+        result = None
+        if done:
+            result = self._get_result_string()
+
+        with _MOONFISH_LOCK:
+            evaluation = board_evaluation(self._board)
+        metadata = {
+            "evaluation": evaluation,
+            "fullmove_number": self._board.fullmove_number,
+            "halfmove_clock": self._board.halfmove_clock,
+        }
+
+        # Compute discounted rewards for all agent moves when episode ends
+        if done and self._agent_move_count > 0:
+            discounted_rewards = self._compute_discounted_rewards(reward)
+            metadata["discounted_rewards"] = discounted_rewards
+            metadata["gamma"] = self._gamma
+
+        return ChessObservation(
+            fen=self._board.fen(),
+            legal_moves=legal_moves,
+            is_check=self._board.is_check(),
+            done=done,
+            reward=reward,
+            result=result,
+            metadata=metadata,
+        )
+
+    def _calculate_reward_and_done(self):
+        """Calculate reward and check if episode is done."""
+        if self._board.is_checkmate():
+            winner = not self._board.turn
+            if winner == self._agent_color:
+                return 1.0, True
+            else:
+                return -1.0, True
+
+        if self._board.is_stalemate():
+            return 0.0, True
+
+        if self._board.is_insufficient_material():
+            return 0.0, True
+
+        if self._board.is_fifty_moves():
+            return 0.0, True
+
+        if self._board.is_repetition(3):
+            return 0.0, True
+
+        if self._state.step_count >= self._max_moves:
+            return 0.0, True
+
+        return 0.0, False
+
+    def _get_result_string(self):
+        """Get the game result as a string."""
+        if self._board.is_checkmate():
+            return "1-0" if not self._board.turn else "0-1"
+        return "1/2-1/2"
+
+    def _compute_discounted_rewards(self, terminal_reward: float) -> list[float]:
+        """
+        Compute temporally discounted rewards for all agent moves.
+
+        Uses exponential discounting: r_t = γ^(T-1-t) * R_final
+        where T is total agent moves, t is move index, R_final is terminal reward.
+
+        Earlier moves get less credit, later moves get more credit.
+        This helps with credit assignment in long games.
+
+        Args:
+            terminal_reward: The final reward (+1 win, -1 loss, 0 draw)
+
+        Returns:
+            List of discounted rewards, one per agent move
+        """
+        T = self._agent_move_count
+        discounted_rewards = []
+        for t in range(T):
+            # γ^(T-1-t) means last move (t=T-1) gets γ^0 = 1.0
+            # First move (t=0) gets γ^(T-1)
+            discount = self._gamma ** (T - 1 - t)
+            discounted_rewards.append(discount * terminal_reward)
+        return discounted_rewards
+
+    def _make_opponent_move(self):
+        """Make a move for the opponent using configured strategy."""
+        if not self._board.legal_moves:
+            return
+
+        if self._opponent == "moonfish":
+            with _MOONFISH_LOCK:
+                move = search_move(self._board, depth=self._opponent_depth)
+        elif self._opponent == "random":
+            move = random.choice(list(self._board.legal_moves))
+        else:
+            return
+
+        self._board.push(move)
+        self._state.step_count += 1
+        self._state.move_history.append(move.uci())
+        self._state.current_player = "white" if self._board.turn else "black"
+        self._state.fen = self._board.fen()
+
+    def web_actions(
+        self, observation: Dict[str, Any]
+    ) -> List[Tuple[str, Dict[str, Any]]]:
+        """The legal moves (UCI) as buttons, sorted so moves of the same piece sit together."""
+        return [
+            (move, {"move": move})
+            for move in sorted(observation.get("legal_moves") or [])
+        ]
+
+    def render_web(self, observation: Dict[str, Any]) -> Optional[str]:
+        """Draw the board from the FEN, white at the bottom, the king in check highlighted."""
+        if "fen" not in observation:
+            return None
+        board = chess.Board(observation["fen"])
+        checked = board.king(board.turn) if observation["is_check"] else None
+        cells = []
+        for rank in range(7, -1, -1):
+            cells.append(f'<span style="opacity:.6;font-size:12px">{rank + 1}</span>')
+            for file in range(8):
+                square = chess.square(file, rank)
+                piece = board.piece_at(square)
+                # Fixed board colours, so a1 stays dark in both themes.
+                if square == checked:
+                    bg = "var(--color-accent)"
+                elif (file + rank) % 2:
+                    bg = "hsl(37 50% 84%)"
+                else:
+                    bg = "hsl(28 33% 55%)"
+                # U+FE0E keeps the pawn as a text glyph instead of an emoji.
+                glyph = piece.unicode_symbol() + "\ufe0e" if piece else ""
+                cells.append(
+                    f'<span style="background:{bg};color:black">{glyph}</span>'
+                )
+        cells.append("<span></span>")
+        cells += [
+            f'<span style="opacity:.6;font-size:12px;line-height:20px">{f}</span>'
+            for f in "abcdefgh"
+        ]
+        return (
+            '<div role="img" aria-label="Chess board" style="display:inline-grid;'
+            "grid-template-columns:16px repeat(8,40px);grid-template-rows:repeat(8,40px) 20px;"
+            "line-height:40px;text-align:center;font-size:30px;color:var(--body-text-color);padding:10px;"
+            'border:1px solid var(--border-color-primary);border-radius:10px;background:var(--background-fill-secondary)">'
+            + "".join(cells)
+            + "</div>"
+        )
+
+    @property
+    def state(self):
+        """Return the current episode state."""
+        return self._state

envs/chess_env/server/rubrics.py

@@ -0,0 +1,86 @@
+# 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.
+
+"""Chess-specific rubrics for reward computation.
+
+Provides ChessWinLossRubric that extends ExponentialDiscountingTrajectoryRubric
+to compute temporally-discounted rewards based on chess game outcomes.
+
+See RFC 004 for rubric design: rfcs/004-rubrics.md
+"""
+
+from typing import Any, List, Tuple
+
+try:
+    from openenv.core.rubrics.trajectory import ExponentialDiscountingTrajectoryRubric
+except ModuleNotFoundError:
+
+    class ExponentialDiscountingTrajectoryRubric:
+        """Compatibility fallback when the installed core lacks rubrics."""
+
+        def __init__(self, gamma: float = 0.99, intermediate_reward: float = 0.0):
+            self.gamma = gamma
+            self.intermediate_reward = intermediate_reward
+            self._trajectory: List[Tuple[Any, Any]] = []
+
+        def __call__(self, action: Any, observation: Any) -> float:
+            self._trajectory.append((action, observation))
+            if getattr(observation, "done", False):
+                return self.score_trajectory(self._trajectory)
+            return self.intermediate_reward
+
+        def reset(self) -> None:
+            self._trajectory = []
+
+        def compute_step_rewards(self) -> List[float]:
+            if not self._trajectory:
+                return []
+
+            final_score = self.score_trajectory(self._trajectory)
+            total_steps = len(self._trajectory)
+            return [
+                self.gamma ** (total_steps - 1 - step_index) * final_score
+                for step_index in range(total_steps)
+            ]
+
+
+class ChessWinLossRubric(ExponentialDiscountingTrajectoryRubric):
+    """Score chess game based on win/loss/draw outcome with temporal discounting.
+
+    Per-step reward: r_t = gamma^(T-1-t) * R_final
+
+    Terminal rewards:
+    - Win:  +1.0
+    - Loss: -1.0
+    - Draw:  0.0
+
+    Note: Unlike the base class convention of 0.0-1.0 scores, chess uses
+    -1.0 for losses to match standard chess RL conventions.
+
+    Usage:
+        rubric = ChessWinLossRubric(gamma=0.99)
+        rubric.reset()
+        for action, obs in episode:
+            reward = rubric(action, obs)  # 0.0 until done
+        step_rewards = rubric.compute_step_rewards()
+    """
+
+    def score_trajectory(self, trajectory: List[Tuple[Any, Any]]) -> float:
+        """Score based on game outcome from final observation.
+
+        Reads the reward from the terminal observation, which encodes:
+        +1.0 for agent win, -1.0 for agent loss, 0.0 for draw.
+
+        Args:
+            trajectory: List of (action, observation) tuples.
+
+        Returns:
+            Terminal reward: +1.0 (win), -1.0 (loss), 0.0 (draw).
+        """
+        if not trajectory:
+            return 0.0
+        _, final_obs = trajectory[-1]
+        return getattr(final_obs, "reward", 0.0)

models.py

@@ -0,0 +1,68 @@
+# 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 Chess Environment.
+
+This module defines the Action, Observation, and State types for chess games
+via the OpenEnv interface. Uses the moonfish chess engine for move search
+and position evaluation.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from openenv.core.env_server import Action, Observation, State
+from pydantic import Field
+
+
+class ChessAction(Action):
+    """
+    Action for Chess environment.
+
+    Attributes:
+        move: UCI format move string (e.g., "e2e4", "e7e8q" for promotion).
+    """
+
+    move: str
+
+
+class ChessObservation(Observation):
+    """
+    Observation for Chess environment.
+
+    Attributes:
+        fen: Board position in FEN notation.
+        legal_moves: List of legal moves in UCI format.
+        is_check: Whether the current player is in check.
+        done: Whether the game is over.
+        reward: Reward for the last action.
+        result: Game result string if game is over (e.g., "1-0", "0-1", "1/2-1/2").
+    """
+
+    fen: str = ""
+    legal_moves: List[str] = Field(default_factory=list)
+    is_check: bool = False
+    result: Optional[str] = None
+
+
+class ChessState(State):
+    """
+    State for Chess environment.
+
+    Attributes:
+        episode_id: Unique ID for the current game.
+        fen: Current board position in FEN notation.
+        current_player: "white" or "black".
+        move_history: List of moves played in UCI format.
+        step_count: Number of half-moves played.
+    """
+
+    fen: str = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
+    current_player: str = "white"
+    move_history: List[str] = Field(default_factory=list)
+    step_count: int = 0

openenv.yaml

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

pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-chess-env"
+version = "0.1.0"
+description = "Chess Environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    "openenv @ git+https://github.com/huggingface/OpenEnv.git@v0.10.0",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0.0",
+    "uvicorn[standard]>=0.24.0",
+    "requests>=2.31.0",
+    "python-chess>=1.999",
+    "moonfish>=0.0.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+server = "chess_env.server.app:main"
+
+[tool.setuptools]
+packages = ["chess_env", "chess_env.server"]
+package-dir = { "chess_env" = ".", "chess_env.server" = "server" }

scripts/verify.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Verification script for chess_env
+# Run from repository root: bash envs/chess_env/scripts/verify.sh
+
+set -e
+
+echo "=== Chess Environment Verification ==="
+echo
+
+# Colors for output
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+check_pass() {
+    echo -e "${GREEN}✓ $1${NC}"
+}
+
+check_fail() {
+    echo -e "${RED}✗ $1${NC}"
+    exit 1
+}
+
+# 1. Run unit tests
+echo "1. Running unit tests..."
+if PYTHONPATH=src:. uv run pytest tests/envs/test_chess_environment.py -v; then
+    check_pass "Unit tests passed"
+else
+    check_fail "Unit tests failed"
+fi
+echo
+
+# 2. Run linting
+echo "2. Running linting..."
+if uv run ruff check envs/chess_env/ tests/envs/test_chess_environment.py; then
+    check_pass "Linting passed"
+else
+    check_fail "Linting failed"
+fi
+echo
+
+# 3. Check formatting
+echo "3. Checking formatting..."
+if uv run ruff format envs/chess_env/ tests/envs/test_chess_environment.py --check; then
+    check_pass "Formatting passed"
+else
+    check_fail "Formatting failed"
+fi
+echo
+
+# 4. Verify imports
+echo "4. Verifying module imports..."
+if PYTHONPATH=src:. uv run python -c "from envs.chess_env import ChessEnv, ChessAction, ChessObservation, ChessState; print('  Imports: ChessEnv, ChessAction, ChessObservation, ChessState')"; then
+    check_pass "Module imports successful"
+else
+    check_fail "Module imports failed"
+fi
+echo
+
+echo "=== All checks passed! ==="

server/Dockerfile

@@ -0,0 +1,79 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local src/core)
+# - Standalone environments (with openenv from pip)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/huggingface/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already in the pyproject.toml dependencies
+# For standalone builds, openenv will be installed from pip via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+
+# Install git for building from git repos (build-time only)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install dependencies using uv sync
+# First pass: install dependencies without the project (for better caching)
+# Second pass: install the project itself
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Health check using Python (more portable than curl/wget)
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+
+# Run the FastAPI server from the installed package.
+CMD ["uvicorn", "chess_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

server/__init__.py

@@ -0,0 +1,11 @@
+# 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.
+
+"""Chess Environment server module."""
+
+from .chess_environment import ChessEnvironment
+
+__all__ = ["ChessEnvironment"]

server/app.py

@@ -0,0 +1,35 @@
+# 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 Chess Environment."""
+
+import os
+
+from openenv.core.env_server import create_app
+
+from ..models import ChessAction, ChessObservation, ChessState
+from .chess_environment import ChessEnvironment
+
+# Create the FastAPI app
+# Pass the class (factory) instead of an instance for WebSocket session support
+app = create_app(
+    ChessEnvironment,
+    ChessAction,
+    ChessObservation,
+    env_name="chess_env",
+    state_cls=ChessState,
+    max_concurrent_envs=int(os.getenv("MAX_CONCURRENT_ENVS", "8")),
+)
+
+
+def main():
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

server/chess_environment.py

@@ -0,0 +1,337 @@
+# 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.
+
+"""
+Chess Environment for OpenEnv using moonfish.
+
+This module provides a chess environment for reinforcement learning,
+using python-chess for game logic and moonfish for position evaluation
+and opponent play.
+"""
+
+import random
+import threading
+import uuid
+from typing import Any, Dict, List, Optional, Tuple
+
+import chess
+from moonfish.lib import search_move
+from moonfish.psqt import board_evaluation, BOARD_EVALUATION_CACHE
+from openenv.core.env_server import Environment
+
+from ..models import ChessAction, ChessObservation, ChessState
+from .rubrics import ChessWinLossRubric
+
+# moonfish keeps one evaluation cache per process, so sessions take turns with it.
+_MOONFISH_LOCK = threading.Lock()
+
+
+class ChessEnvironment(Environment):
+    """
+    Chess environment implementing the OpenEnv interface.
+
+    Uses python-chess for game logic and moonfish for position evaluation.
+    Designed for RL training where an agent plays as one color against
+    an opponent (which can be random, moonfish engine, or self-play).
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS = True
+
+    def __init__(
+        self,
+        opponent: str = "moonfish",
+        opponent_depth: int = 2,
+        max_moves: int = 500,
+        agent_color: str | None = None,
+        gamma: float = 0.99,
+    ):
+        """
+        Initialize the chess environment.
+
+        Args:
+            opponent: Opponent type - "moonfish", "random", or None (self-play)
+            opponent_depth: Search depth when using moonfish as opponent
+            max_moves: Maximum half-moves before draw
+            agent_color: Which color the agent plays - "white", "black", or None (alternate each episode)
+            gamma: Discount factor for temporal credit assignment (0-1)
+        """
+        super().__init__(rubric=ChessWinLossRubric(gamma=gamma))
+        self._opponent = opponent
+        self._opponent_depth = opponent_depth
+        self._max_moves = max_moves
+        self._agent_color_setting = agent_color
+        self._gamma = gamma
+        self._board = None
+        self._state = None
+        self._agent_color = chess.WHITE
+        self._agent_move_count = 0  # Track agent moves for discounting
+        self.reset()
+
+    def reset(self, fen: str = None):
+        """
+        Initialize a new chess game episode.
+
+        Args:
+            fen: Optional starting position in FEN notation.
+
+        Returns:
+            Initial observation of the board state.
+        """
+        self._reset_rubric()
+        # moonfish's module-level evaluation cache is never trimmed.
+        with _MOONFISH_LOCK:
+            BOARD_EVALUATION_CACHE.clear()
+
+        if fen:
+            self._board = chess.Board(fen)
+        else:
+            self._board = chess.Board()
+
+        # Generate episode ID once
+        episode_id = str(uuid.uuid4())
+
+        # Determine agent color
+        if self._agent_color_setting == "white":
+            self._agent_color = chess.WHITE
+        elif self._agent_color_setting == "black":
+            self._agent_color = chess.BLACK
+        elif self._agent_color_setting is None:
+            # Alternate each episode based on episode_id hash
+            self._agent_color = (
+                chess.WHITE if hash(episode_id) % 2 == 0 else chess.BLACK
+            )
+        else:
+            self._agent_color = chess.WHITE
+
+        self._state = ChessState(
+            episode_id=episode_id,
+            step_count=0,
+            current_player="white" if self._board.turn else "black",
+            fen=self._board.fen(),
+            move_history=[],
+        )
+        self._agent_move_count = 0
+
+        # If agent plays Black and opponent is configured, opponent moves first
+        if self._opponent is not None and self._agent_color == chess.BLACK:
+            self._make_opponent_move()
+
+        # Check if starting position is already terminal (e.g., custom FEN with checkmate/stalemate)
+        _, done = self._calculate_reward_and_done()
+        return self._make_observation(done=done)
+
+    def step(self, action: ChessAction):
+        """
+        Execute a chess move and return the resulting state.
+
+        Args:
+            action: The move to make in UCI format (e.g., "e2e4").
+
+        Returns:
+            Observation with reward and done flag.
+        """
+        if self._board is None:
+            raise RuntimeError("Environment not initialized. Call reset() first.")
+
+        # Parse the move
+        try:
+            move = chess.Move.from_uci(action.move)
+        except ValueError:
+            return self._make_observation(reward=-0.1, done=False)
+
+        # Check if move is legal
+        if move not in self._board.legal_moves:
+            return self._make_observation(reward=-0.1, done=False)
+
+        # Execute the move
+        self._board.push(move)
+        self._state.step_count += 1
+        self._agent_move_count += 1
+        self._state.move_history.append(action.move)
+        self._state.current_player = "white" if self._board.turn else "black"
+        self._state.fen = self._board.fen()
+
+        # Calculate reward and check for game end
+        reward, done = self._calculate_reward_and_done()
+
+        # If game not over and opponent is configured, make opponent move
+        if not done and self._opponent is not None:
+            self._make_opponent_move()
+            reward, done = self._calculate_reward_and_done()
+
+        obs = self._make_observation(reward=reward, done=done)
+
+        # Feed to rubric for trajectory accumulation
+        self._apply_rubric(action, obs)
+
+        # Note: obs.reward is kept from _calculate_reward_and_done() rather than
+        # overridden by the rubric. The rubric here is a TrajectoryRubric that
+        # returns 0.0 until done then the final score — the inline reward logic
+        # already provides the correct per-step reward including penalties for
+        # invalid/illegal moves. The rubric's value is in compute_step_rewards()
+        # for training infrastructure, not in replacing obs.reward.
+
+        return obs
+
+    def _make_observation(self, reward: float = 0.0, done: bool = False):
+        """Build observation from current board state."""
+        legal_moves = [move.uci() for move in self._board.legal_moves]
+
+        result = None
+        if done:
+            result = self._get_result_string()
+
+        with _MOONFISH_LOCK:
+            evaluation = board_evaluation(self._board)
+        metadata = {
+            "evaluation": evaluation,
+            "fullmove_number": self._board.fullmove_number,
+            "halfmove_clock": self._board.halfmove_clock,
+        }
+
+        # Compute discounted rewards for all agent moves when episode ends
+        if done and self._agent_move_count > 0:
+            discounted_rewards = self._compute_discounted_rewards(reward)
+            metadata["discounted_rewards"] = discounted_rewards
+            metadata["gamma"] = self._gamma
+
+        return ChessObservation(
+            fen=self._board.fen(),
+            legal_moves=legal_moves,
+            is_check=self._board.is_check(),
+            done=done,
+            reward=reward,
+            result=result,
+            metadata=metadata,
+        )
+
+    def _calculate_reward_and_done(self):
+        """Calculate reward and check if episode is done."""
+        if self._board.is_checkmate():
+            winner = not self._board.turn
+            if winner == self._agent_color:
+                return 1.0, True
+            else:
+                return -1.0, True
+
+        if self._board.is_stalemate():
+            return 0.0, True
+
+        if self._board.is_insufficient_material():
+            return 0.0, True
+
+        if self._board.is_fifty_moves():
+            return 0.0, True
+
+        if self._board.is_repetition(3):
+            return 0.0, True
+
+        if self._state.step_count >= self._max_moves:
+            return 0.0, True
+
+        return 0.0, False
+
+    def _get_result_string(self):
+        """Get the game result as a string."""
+        if self._board.is_checkmate():
+            return "1-0" if not self._board.turn else "0-1"
+        return "1/2-1/2"
+
+    def _compute_discounted_rewards(self, terminal_reward: float) -> list[float]:
+        """
+        Compute temporally discounted rewards for all agent moves.
+
+        Uses exponential discounting: r_t = γ^(T-1-t) * R_final
+        where T is total agent moves, t is move index, R_final is terminal reward.
+
+        Earlier moves get less credit, later moves get more credit.
+        This helps with credit assignment in long games.
+
+        Args:
+            terminal_reward: The final reward (+1 win, -1 loss, 0 draw)
+
+        Returns:
+            List of discounted rewards, one per agent move
+        """
+        T = self._agent_move_count
+        discounted_rewards = []
+        for t in range(T):
+            # γ^(T-1-t) means last move (t=T-1) gets γ^0 = 1.0
+            # First move (t=0) gets γ^(T-1)
+            discount = self._gamma ** (T - 1 - t)
+            discounted_rewards.append(discount * terminal_reward)
+        return discounted_rewards
+
+    def _make_opponent_move(self):
+        """Make a move for the opponent using configured strategy."""
+        if not self._board.legal_moves:
+            return
+
+        if self._opponent == "moonfish":
+            with _MOONFISH_LOCK:
+                move = search_move(self._board, depth=self._opponent_depth)
+        elif self._opponent == "random":
+            move = random.choice(list(self._board.legal_moves))
+        else:
+            return
+
+        self._board.push(move)
+        self._state.step_count += 1
+        self._state.move_history.append(move.uci())
+        self._state.current_player = "white" if self._board.turn else "black"
+        self._state.fen = self._board.fen()
+
+    def web_actions(
+        self, observation: Dict[str, Any]
+    ) -> List[Tuple[str, Dict[str, Any]]]:
+        """The legal moves (UCI) as buttons, sorted so moves of the same piece sit together."""
+        return [
+            (move, {"move": move})
+            for move in sorted(observation.get("legal_moves") or [])
+        ]
+
+    def render_web(self, observation: Dict[str, Any]) -> Optional[str]:
+        """Draw the board from the FEN, white at the bottom, the king in check highlighted."""
+        if "fen" not in observation:
+            return None
+        board = chess.Board(observation["fen"])
+        checked = board.king(board.turn) if observation["is_check"] else None
+        cells = []
+        for rank in range(7, -1, -1):
+            cells.append(f'<span style="opacity:.6;font-size:12px">{rank + 1}</span>')
+            for file in range(8):
+                square = chess.square(file, rank)
+                piece = board.piece_at(square)
+                # Fixed board colours, so a1 stays dark in both themes.
+                if square == checked:
+                    bg = "var(--color-accent)"
+                elif (file + rank) % 2:
+                    bg = "hsl(37 50% 84%)"
+                else:
+                    bg = "hsl(28 33% 55%)"
+                # U+FE0E keeps the pawn as a text glyph instead of an emoji.
+                glyph = piece.unicode_symbol() + "\ufe0e" if piece else ""
+                cells.append(
+                    f'<span style="background:{bg};color:black">{glyph}</span>'
+                )
+        cells.append("<span></span>")
+        cells += [
+            f'<span style="opacity:.6;font-size:12px;line-height:20px">{f}</span>'
+            for f in "abcdefgh"
+        ]
+        return (
+            '<div role="img" aria-label="Chess board" style="display:inline-grid;'
+            "grid-template-columns:16px repeat(8,40px);grid-template-rows:repeat(8,40px) 20px;"
+            "line-height:40px;text-align:center;font-size:30px;color:var(--body-text-color);padding:10px;"
+            'border:1px solid var(--border-color-primary);border-radius:10px;background:var(--background-fill-secondary)">'
+            + "".join(cells)
+            + "</div>"
+        )
+
+    @property
+    def state(self):
+        """Return the current episode state."""
+        return self._state

server/rubrics.py

@@ -0,0 +1,86 @@
+# 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.
+
+"""Chess-specific rubrics for reward computation.
+
+Provides ChessWinLossRubric that extends ExponentialDiscountingTrajectoryRubric
+to compute temporally-discounted rewards based on chess game outcomes.
+
+See RFC 004 for rubric design: rfcs/004-rubrics.md
+"""
+
+from typing import Any, List, Tuple
+
+try:
+    from openenv.core.rubrics.trajectory import ExponentialDiscountingTrajectoryRubric
+except ModuleNotFoundError:
+
+    class ExponentialDiscountingTrajectoryRubric:
+        """Compatibility fallback when the installed core lacks rubrics."""
+
+        def __init__(self, gamma: float = 0.99, intermediate_reward: float = 0.0):
+            self.gamma = gamma
+            self.intermediate_reward = intermediate_reward
+            self._trajectory: List[Tuple[Any, Any]] = []
+
+        def __call__(self, action: Any, observation: Any) -> float:
+            self._trajectory.append((action, observation))
+            if getattr(observation, "done", False):
+                return self.score_trajectory(self._trajectory)
+            return self.intermediate_reward
+
+        def reset(self) -> None:
+            self._trajectory = []
+
+        def compute_step_rewards(self) -> List[float]:
+            if not self._trajectory:
+                return []
+
+            final_score = self.score_trajectory(self._trajectory)
+            total_steps = len(self._trajectory)
+            return [
+                self.gamma ** (total_steps - 1 - step_index) * final_score
+                for step_index in range(total_steps)
+            ]
+
+
+class ChessWinLossRubric(ExponentialDiscountingTrajectoryRubric):
+    """Score chess game based on win/loss/draw outcome with temporal discounting.
+
+    Per-step reward: r_t = gamma^(T-1-t) * R_final
+
+    Terminal rewards:
+    - Win:  +1.0
+    - Loss: -1.0
+    - Draw:  0.0
+
+    Note: Unlike the base class convention of 0.0-1.0 scores, chess uses
+    -1.0 for losses to match standard chess RL conventions.
+
+    Usage:
+        rubric = ChessWinLossRubric(gamma=0.99)
+        rubric.reset()
+        for action, obs in episode:
+            reward = rubric(action, obs)  # 0.0 until done
+        step_rewards = rubric.compute_step_rewards()
+    """
+
+    def score_trajectory(self, trajectory: List[Tuple[Any, Any]]) -> float:
+        """Score based on game outcome from final observation.
+
+        Reads the reward from the terminal observation, which encodes:
+        +1.0 for agent win, -1.0 for agent loss, 0.0 for draw.
+
+        Args:
+            trajectory: List of (action, observation) tuples.
+
+        Returns:
+            Terminal reward: +1.0 (win), -1.0 (loss), 0.0 (draw).
+        """
+        if not trajectory:
+            return 0.0
+        _, final_obs = trajectory[-1]
+        return getattr(final_obs, "reward", 0.0)

src/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""EnvTorch: Standardized agentic execution environments."""

src/core/README.md

@@ -0,0 +1,237 @@
+# 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.
+
+> [!NOTE]
+> OpenEnv is in early development, see the note in the [project README](../../../README.md) before contributing. The [README](../../../README.md#community-support--acknowledgments) lists the technical committee that governs the project, and the [charter](../../../GOVERNANCE.md) explains how it works.
+
+## 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.
+
+# 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
+- **Experimental Harness Helpers**: `openenv.core.harness` provides
+  `ResourceSessionFactory`, `StepEnvSessionAdapter`, and `HarnessAdapter` for
+  MCP-first training/evaluation harnesses
+
+## Experimental Harness Helpers
+
+OpenEnv now includes an additive harness-facing layer for cases where a rollout
+driver should interact with environment resources through tools instead of
+calling `reset()` / `step()` directly. These helpers are currently
+experimental while RFC 005 remains in review, so import them from
+`openenv.core.harness`.
+
+Core pieces:
+
+- `ResourceSessionFactory.create(task, seed, episode_id)` creates an isolated
+  per-rollout session
+- `StepEnvSessionAdapter` wraps an existing client and exposes session tools
+- `SessionMCPBridge` exposes a session through MCP-style JSON-RPC
+- `MCPHarnessAdapter` drives white-box rollouts where the trainer still owns
+  model sampling, token IDs, and logprobs
+- `CLIHarnessAdapter` supports opaque evaluation harnesses over the same session
+  surface
+- `build_harness_rollout_func(...)` builds a TRL-compatible `rollout_func`
+
+This layer is additive. Existing environment clients and MCP environments keep
+their current control-plane APIs unchanged.
+
+## Installation
+
+```bash
+pip install "openenv"
+```
+
+For development:
+```bash
+pip install "openenv"
+```
+
+## 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/huggingface/OpenEnv
+- **Documentation**: https://github.com/huggingface/OpenEnv/blob/main/README.md
+- **Bug Tracker**: https://github.com/huggingface/OpenEnv/issues

src/core/__init__.py

@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Core components for agentic environments."""
+
+from __future__ import annotations
+
+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__ = [
+    "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,29 @@
+# Type definitions for EnvTorch
+from dataclasses import dataclass
+from typing import Any, Dict, 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 (`float`, *optional*):
+            Scalar reward for this step.
+        done (`bool`, *optional*, defaults to `False`):
+            Whether the episode is finished.
+        metadata (`dict`, *optional*):
+            Additional metadata returned alongside the observation.
+    """
+
+    observation: ObsT
+    reward: Optional[float] = None
+    done: bool = False
+    metadata: Optional[Dict[str, Any]] = None

src/core/containers/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Container management for environment servers."""

src/core/containers/images/Dockerfile

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+#
+# 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
+# and uv for fast dependency management.
+#
+# 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 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/*
+
+# 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
+
+# Default environment variables
+ENV PYTHONPATH=/app/src
+ENV PYTHONUNBUFFERED=1
+ENV UV_SYSTEM_PYTHON=1
+
+# Default expose port (can be overridden)
+EXPOSE 8000
+
+# Note: CMD should be specified in child Dockerfiles

src/core/containers/images/README.md

@@ -0,0 +1,92 @@
+# OpenEnv Base Image
+
+Standard base image for all OpenEnv environment servers.
+
+## What's Included
+
+| Layer | Size | Contents |
+|-------|------|----------|
+| python:3.11-slim | 200 MB  | Base Python runtime |
+| + Dependencies   | 100 MB  | FastAPI, uvicorn, requests |
+| **Total**        | **~300 MB** | Ready for environment servers |
+
+## Image Sizes
+
+```
+openenv-base:latest   300 MB  (python + fastapi + uvicorn)
+```
+echo-env:latest        500 MB  (python + fastapi + uvicorn + app)
+coding-env:latest      520 MB  (python + fastapi + uvicorn + app + tools)
+another-env:latest     510 MB  (python + fastapi + uvicorn + app)
+---
+Total: 1.5 GB (with lots of duplication)
+```
+
+### With Base Images (✅ Solution)
+```
+openenv-base:latest    300 MB  (python + fastapi + uvicorn)
+echo-env:latest         50 MB  (app only, uses base)
+coding-env:latest       70 MB  (app + tools, uses base)
+another-env:latest      45 MB  (app only, uses base)
+---
+Total: 465 MB (base shared, minimal duplication)
+```
+
+## Building the Base Image
+
+```bash
+# From project root
+docker build -t openenv-base:latest -f src/openenv/core/containers/images/Dockerfile .
+```
+
+## Usage in Environment Dockerfiles
+
+Each environment Dockerfile should start with:
+
+```dockerfile
+FROM openenv-base:latest
+
+# Copy only environment-specific files
+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"]
+```
+
+## Base Image Contents
+
+- Python 3.11-slim
+- FastAPI >= 0.104.0
+- Uvicorn >= 0.24.0
+- Requests >= 2.25.0
+- curl (for health checks)
+
+## Example: Building Echo Environment
+
+```bash
+# Step 1: Build base image (do this once)
+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 envs/echo_env/server/Dockerfile .
+
+# Step 3: Run echo environment
+docker run -p 8000:8000 echo-env:latest
+```
+
+## Updating the Base
+
+When dependencies need updating:
+
+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/openenv/core/containers/images/Dockerfile .
+
+# Rebuild environments (they automatically use new base)
+docker build -t echo-env:latest -f envs/echo_env/server/Dockerfile .
+```

src/core/containers/runtime/__init__.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Container runtime providers."""
+
+from .providers import (
+    ContainerProvider,
+    DockerSwarmProvider,
+    KubernetesProvider,
+    LocalDockerProvider,
+    RuntimeProvider,
+)
+from .uv_provider import UVProvider
+
+# Note: optional cloud providers that require extra SDKs (e.g.
+# `ACASandboxProvider`, `DaytonaProvider`) are intentionally NOT re-exported
+# here. Import them from their module, e.g.
+# `from openenv.core.containers.runtime.aca_provider import ACASandboxProvider`.
+
+__all__ = [
+    "ContainerProvider",
+    "DockerSwarmProvider",
+    "LocalDockerProvider",
+    "KubernetesProvider",
+    "RuntimeProvider",
+    "UVProvider",
+]

src/core/containers/runtime/_server_config.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Shared helpers for reading environment server configuration."""
+
+from __future__ import annotations
+
+import json
+import re
+
+import yaml
+
+
+def parse_openenv_app_field(yaml_content: str) -> str | None:
+    """Extract the top-level ``app`` value from raw ``openenv.yaml`` content."""
+    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
+
+
+def parse_dockerfile_cmd(dockerfile_content: str) -> str | None:
+    """Extract the server command from the last Dockerfile ``CMD``."""
+    last_cmd: str | None = None
+    for line in dockerfile_content.splitlines():
+        stripped = line.strip()
+        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
+
+    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):
+            # Invalid exec-form JSON falls back to the raw CMD below.
+            pass
+
+    return last_cmd if last_cmd else None

src/core/containers/runtime/aca_provider.py

@@ -0,0 +1,690 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Azure Container Apps Sandbox provider for OpenEnv environments.
+
+Note: the ``RFC 002 security invariant S<n>`` references in this module point to
+the **proposed** "Cloud Sandbox Providers" amendment to RFC 002, which is pending
+review/sign-off by the RFC authors. They describe the security properties this
+provider enforces; treat them as proposed (not yet ratified) until that sign-off.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import time
+import warnings
+from typing import Any, Dict, Literal, Optional
+
+from .providers import ContainerProvider
+
+
+_DEFAULT_ACA_PORT = 8000
+# 15 minutes matches the conservative auto-stop default used by other cloud
+# sandbox providers (e.g. Daytona). A live RL rollout holds one WebSocket for
+# the whole episode, so an aggressive auto-suspend can silently drop the
+# session between slow steps. See RFC 002 "Cloud Sandbox Providers".
+_DEFAULT_AUTO_SUSPEND_SECONDS = 900
+_VALID_SUSPEND_MODES = {"Memory", "Disk"}
+
+
+def _require_secure_url(url: str) -> str:
+    """Enforce https/wss transport (RFC 002 security invariant S1).
+
+    `EnvClient` derives its WebSocket URL from this base URL, so a plaintext
+    URL would become a cleartext `ws://` connection. The offending URL is
+    deliberately omitted from the error because an anonymous ACA port URL is a
+    bearer capability (S2) that must not leak into logs.
+    """
+    if not isinstance(url, str) or not url.lower().startswith("https://"):
+        raise RuntimeError(
+            "ACA sandbox returned a non-HTTPS port URL. OpenEnv requires an "
+            "https/wss base_url so EnvClient traffic is encrypted. Refusing to "
+            "connect over plaintext."
+        )
+    return url
+
+
+def _validate_anonymous_port(anonymous_port: Optional[bool]) -> bool:
+    """Require explicit, public-only ingress opt-in (RFC 002 invariant S2).
+
+    Public exposure is never implicit (`None` is rejected), and authenticated
+    ACA ports are rejected because `EnvClient` has no WebSocket auth mechanism
+    yet.
+    """
+    if anonymous_port is None:
+        raise ValueError(
+            "ACASandboxProvider requires explicit anonymous_port=True. "
+            "ACA anonymous ports are public ingress; authenticated ACA "
+            "ports are not supported by EnvClient until a client-auth RFC "
+            "defines WebSocket credentials."
+        )
+    if not anonymous_port:
+        raise ValueError(
+            "authenticated ACA sandbox ports are not supported by EnvClient "
+            "yet. Use anonymous_port=True only for intentionally exposed "
+            "sandbox URLs, or wait for a client-auth RFC."
+        )
+    return True
+
+
+def _resolve_required(value: str | None, env_name: str, parameter: str) -> str:
+    resolved = value or os.environ.get(env_name)
+    if not resolved:
+        raise ValueError(
+            f"{parameter} is required. Pass it to ACASandboxProvider or set "
+            f"the {env_name} environment variable."
+        )
+    return resolved
+
+
+def _raise_install_error(exc: ImportError) -> None:
+    raise RuntimeError(
+        "Azure Container Apps sandbox support requires optional dependencies. "
+        "Install them with `pip install openenv[aca]`."
+    ) from exc
+
+
+class _DefaultACASandboxAdapter:
+    """Thin adapter over the preview `azure-containerapps-sandbox` SDK.
+
+    The provider talks to this private adapter instead of spreading SDK details
+    through its own logic; tests inject a duck-typed fake in its place.
+    """
+
+    def __init__(
+        self,
+        *,
+        subscription_id: str,
+        resource_group: str,
+        sandbox_group: str,
+        region: str | None,
+        endpoint: str | None,
+        credential: Any,
+        sdk_kwargs: dict[str, Any],
+    ):
+        try:
+            from azure.containerapps.sandbox import (
+                endpoint_for_region,
+                SandboxGroupClient,
+            )
+        except ImportError as exc:  # pragma: no cover - exercised via provider tests
+            _raise_install_error(exc)
+
+        if credential is None:
+            try:
+                from azure.identity import DefaultAzureCredential
+            except (
+                ImportError
+            ) as exc:  # pragma: no cover - exercised via provider tests
+                _raise_install_error(exc)
+
+            credential = DefaultAzureCredential()
+
+        if endpoint is None:
+            if region is None:
+                raise ValueError(
+                    "region is required when endpoint is not provided. Pass it to "
+                    "ACASandboxProvider or set AZURE_REGION."
+                )
+            endpoint = endpoint_for_region(region)
+
+        self._client = SandboxGroupClient(
+            endpoint,
+            credential,
+            subscription_id=subscription_id,
+            resource_group=resource_group,
+            sandbox_group=sandbox_group,
+            **sdk_kwargs,
+        )
+
+    def create_sandbox(
+        self,
+        *,
+        disk: str | None,
+        disk_id: str | None,
+        env_vars: dict[str, str] | None,
+        labels: dict[str, str] | None,
+        egress_policy: Any,
+        cpu: str,
+        memory: str,
+        disk_size: str | None,
+        auto_suspend_seconds: int,
+        auto_suspend_mode: str,
+        create_timeout: int,
+        polling_interval: int,
+    ) -> Any:
+        kwargs: dict[str, Any] = {
+            "disk": disk,
+            "disk_id": disk_id,
+            "cpu": cpu,
+            "memory": memory,
+            "disk_size": disk_size,
+            "auto_suspend_seconds": auto_suspend_seconds,
+            "auto_suspend_mode": auto_suspend_mode,
+            "labels": labels,
+            "environment": env_vars,
+            "egress_policy": egress_policy,
+            "polling_timeout": create_timeout,
+            "polling_interval": polling_interval,
+        }
+        kwargs = {key: value for key, value in kwargs.items() if value is not None}
+        # `begin_create_sandbox(...).result()` blocks until the sandbox is
+        # *Running* and returns a sandbox-scoped `SandboxClient` (not a plain
+        # data model). That client exposes exec / add_port / begin_delete
+        # directly, which is the handle the rest of this adapter operates on.
+        return self._client.begin_create_sandbox(**kwargs).result()
+
+    def add_port(self, sandbox: Any, *, port: int, anonymous: bool) -> str:
+        sandbox_port = sandbox.add_port(port, anonymous=anonymous)
+        url = getattr(sandbox_port, "url", None)
+        if not url and isinstance(sandbox_port, dict):
+            url = sandbox_port.get("url")
+        if not url:
+            raise RuntimeError(
+                "ACA sandbox did not return a URL for the exposed port. "
+                "OpenEnv requires a base_url that EnvClient can connect to directly."
+            )
+        return str(url)
+
+    def exec(
+        self,
+        sandbox: Any,
+        command: str,
+        *,
+        working_directory: str | None = None,
+    ) -> Any:
+        return sandbox.exec(command, working_directory=working_directory)
+
+    def delete_sandbox(self, sandbox: Any) -> None:
+        if hasattr(sandbox, "begin_delete"):
+            sandbox.begin_delete().result()
+        else:
+            sandbox.delete()
+
+    def close(self) -> None:
+        self._client.close()
+
+
+def _source_from_image(image: str) -> tuple[str | None, str | None]:
+    if not image or not image.strip():
+        raise ValueError("image must be a non-empty ACA disk or disk-id reference")
+    image = image.strip()
+
+    if image.startswith("disk:"):
+        disk = image[len("disk:") :].strip()
+        if not disk:
+            raise ValueError("disk: source must include a disk image name")
+        return disk, None
+    if image.startswith("disk-id:"):
+        disk_id = image[len("disk-id:") :].strip()
+        if not disk_id:
+            raise ValueError("disk-id: source must include a disk image id")
+        return None, disk_id
+
+    # A bare string is treated as a public disk-image name. Guard the common
+    # migration foot-gun: an ACA sandbox source is NOT a Docker/OCI registry
+    # image, so a value that looks like one (a registry path with "/", or an
+    # "image:tag") is almost certainly a mistake and would otherwise surface as
+    # an opaque ACA SDK error. Fail fast with guidance instead.
+    if "/" in image or ":" in image:
+        raise ValueError(
+            f"{image!r} looks like a container/OCI image reference, but "
+            "ACASandboxProvider sources are Azure Container Apps sandbox disks, "
+            "not Docker registry images. Use a bare public disk name, "
+            "'disk:<name>' for a public disk image, or 'disk-id:<id>' for a "
+            "private one (building a disk image from a container image is a "
+            "separate, out-of-band ACA step)."
+        )
+
+    return image, None
+
+
+def _exec_stdout(result: Any) -> str:
+    for attr in ("stdout", "result", "output"):
+        value = getattr(result, attr, None)
+        if value is not None:
+            return str(value)
+    if isinstance(result, dict):
+        for key in ("stdout", "result", "output"):
+            value = result.get(key)
+            if value is not None:
+                return str(value)
+    return str(result)
+
+
+class ACASandboxProvider(ContainerProvider):
+    """Container provider backed by Azure Container Apps Sandboxes.
+
+    `start_container`'s `image` is an ACA sandbox source (`disk:<name>` for a
+    public disk image or `disk-id:<id>` for a private one), not a Docker
+    registry image. The provider boots an OpenEnv server inside the sandbox,
+    exposes it on an anonymous ACA port, and returns an `https://` URL that
+    `EnvClient` connects to over `wss://`.
+
+    The environment runs untrusted code, so the provider is secure by default
+    (proposed RFC 002 security invariants): it requires explicit `anonymous_port=True`
+    ingress (S2), enforces https/wss transport (S1), offers
+    `deny_all_egress()` to block the cloud metadata/IMDS endpoint (S3), and
+    never surfaces raw sandbox output unless `surface_server_logs=True` (S4).
+
+    Validated end to end against a live ACA sandbox group; the underlying
+    `azure-containerapps-sandbox` SDK is preview, so pin it and re-validate
+    after upgrades (see `tests/test_core/test_aca_provider_integration.py`).
+
+    `close()` stops the active sandbox *and* releases the underlying SDK client,
+    so prefer using the provider as a context manager (or call `close()`
+    explicitly) for deterministic cleanup. `close()`/`__enter__`/`__exit__` are
+    defined on `ContainerProvider` (default no-op), so a caller holding a bare
+    `ContainerProvider` reference can release the client polymorphically.
+
+    Only one sandbox is active per provider: calling `start_container` again
+    before `stop_container()`/`close()` raises `RuntimeError` rather than
+    orphaning the running sandbox.
+
+    ```python
+    with ACASandboxProvider(
+        image="disk:my-env",
+        anonymous_port=True,
+        ...,
+    ) as provider:
+        base_url = provider.start_container(cmd=...)
+        ...
+    # sandbox deleted and SDK client closed on exit
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        subscription_id: Optional[str] = None,
+        resource_group: Optional[str] = None,
+        sandbox_group: Optional[str] = None,
+        region: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        credential: Any = None,
+        cpu: str = "1000m",
+        memory: str = "2048Mi",
+        disk_size: Optional[str] = None,
+        auto_suspend_seconds: int = _DEFAULT_AUTO_SUSPEND_SECONDS,
+        auto_suspend_mode: Literal["Memory", "Disk"] = "Memory",
+        labels: Optional[Dict[str, str]] = None,
+        egress_policy: Any = None,
+        anonymous_port: Literal[True] | None = None,
+        image: Optional[str] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        cmd: Optional[str] = None,
+        working_directory: Optional[str] = None,
+        surface_server_logs: bool = False,
+        create_timeout: int = 300,
+        polling_interval: int = 3,
+        sdk_kwargs: Optional[dict[str, Any]] = None,
+        _adapter: Any = None,
+    ):
+        if auto_suspend_mode not in _VALID_SUSPEND_MODES:
+            raise ValueError("auto_suspend_mode must be 'Memory' or 'Disk'")
+        _validate_anonymous_port(anonymous_port)
+
+        self.subscription_id = subscription_id or os.environ.get(
+            "AZURE_SUBSCRIPTION_ID"
+        )
+        self.resource_group = resource_group or os.environ.get("AZURE_RESOURCE_GROUP")
+        self.sandbox_group = sandbox_group or os.environ.get("AZURE_SANDBOX_GROUP")
+        self.region = region or os.environ.get("AZURE_REGION")
+        self.endpoint = endpoint
+
+        self.cpu = cpu
+        self.memory = memory
+        self.disk_size = disk_size
+        self.auto_suspend_seconds = auto_suspend_seconds
+        self.auto_suspend_mode = auto_suspend_mode
+        self.labels = dict(labels or {})
+        self.egress_policy = egress_policy
+        self.anonymous_port = anonymous_port
+        self._image = image
+        self._env_vars = dict(env_vars or {}) if env_vars is not None else None
+        self.cmd = cmd
+        self.working_directory = working_directory
+        self.surface_server_logs = surface_server_logs
+        self.create_timeout = create_timeout
+        self.polling_interval = polling_interval
+
+        if _adapter is None:
+            self._adapter = _DefaultACASandboxAdapter(
+                subscription_id=_resolve_required(
+                    self.subscription_id, "AZURE_SUBSCRIPTION_ID", "subscription_id"
+                ),
+                resource_group=_resolve_required(
+                    self.resource_group, "AZURE_RESOURCE_GROUP", "resource_group"
+                ),
+                sandbox_group=_resolve_required(
+                    self.sandbox_group, "AZURE_SANDBOX_GROUP", "sandbox_group"
+                ),
+                region=self.region,
+                endpoint=self.endpoint,
+                credential=credential,
+                sdk_kwargs=dict(sdk_kwargs or {}),
+            )
+            self._owns_adapter = True
+        else:
+            self._adapter = _adapter
+            self._owns_adapter = False
+
+        self._sandbox: Any = None
+        self._base_url: Optional[str] = None
+        self._port = _DEFAULT_ACA_PORT
+        self._started_server = False
+        # Injected env-var values, used to scrub captured server output before
+        # it is ever surfaced in an error (RFC 002 security invariant S4).
+        self._redact_values: set[str] = set()
+
+    @staticmethod
+    def deny_all_egress(allow: Optional[list[str]] = None) -> Any:
+        """Build a default-deny ACA `EgressPolicy` (RFC 002 security invariant S3).
+
+        Untrusted RL/agent code should not be able to exfiltrate data or reach
+        the cloud metadata/IMDS endpoint. This returns an `EgressPolicy` whose
+        default action is `Deny`, with an optional host allowlist (for example a
+        model endpoint or package registry the environment legitimately needs).
+
+        ```python
+        provider = ACASandboxProvider(
+            anonymous_port=True,
+            egress_policy=ACASandboxProvider.deny_all_egress(
+                allow=["my-model.openai.azure.com"]
+            ),
+        )
+        ```
+        """
+        try:
+            from azure.containerapps.sandbox import EgressHostRule, EgressPolicy
+        except ImportError as exc:  # pragma: no cover - exercised via provider tests
+            _raise_install_error(exc)
+
+        host_rules = [
+            EgressHostRule(pattern=pattern, action="Allow") for pattern in (allow or [])
+        ]
+        return EgressPolicy(default_action="Deny", host_rules=host_rules)
+
+    def start_container(
+        self,
+        image: Optional[str] = None,
+        port: Optional[int] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> str:
+        """Start an OpenEnv server in an ACA sandbox and return its base URL.
+
+        `image` is an ACA sandbox *source*, not a Docker/OCI registry image: a
+        bare string or `disk:<name>` for a public disk image, or `disk-id:<id>`
+        for a private one. It may be omitted when supplied to the constructor.
+        A value that looks like a container image (a registry path or
+        `name:tag`) is rejected with guidance. Only port 8000 is supported.
+        `**kwargs` accepts per-start overrides (`cmd`, `labels`,
+        `egress_policy`, `anonymous_port`); unknown options raise `ValueError`
+        so typos cannot silently change sandbox behavior.
+        """
+        if self._sandbox is not None:
+            raise RuntimeError(
+                "ACASandboxProvider already has an active sandbox. Call "
+                "stop_container() (or close()) before starting another — a "
+                "second start would orphan the running sandbox."
+            )
+
+        bind_port = port or _DEFAULT_ACA_PORT
+        if bind_port != _DEFAULT_ACA_PORT:
+            raise ValueError(
+                f"ACASandboxProvider only supports port {_DEFAULT_ACA_PORT} "
+                f"(got {bind_port})."
+            )
+
+        effective_image = image if image is not None else self._image
+        if effective_image is None:
+            raise ValueError(
+                "ACASandboxProvider requires an image. Pass it to the constructor "
+                "or start_container()."
+            )
+        effective_env_vars = self._env_vars if env_vars is None else env_vars
+
+        disk, disk_id = _source_from_image(effective_image)
+        labels = dict(self.labels)
+        labels.update(kwargs.pop("labels", {}) or {})
+        cmd = kwargs.pop("cmd", None) or self.cmd
+        egress_policy = kwargs.pop("egress_policy", self.egress_policy)
+        anonymous_port = kwargs.pop("anonymous_port", self.anonymous_port)
+        # Re-validate in case anonymous_port was overridden at start time: public
+        # exposure must stay an explicit, opt-in decision (S2).
+        _validate_anonymous_port(anonymous_port)
+
+        if kwargs:
+            unknown = ", ".join(sorted(kwargs))
+            raise ValueError(f"Unsupported ACASandboxProvider start options: {unknown}")
+
+        # Security (RFC 002 S3): the env server runs untrusted code and ACA's
+        # EgressPolicy defaults to default_action="Allow", so an unset policy
+        # means unrestricted egress — the workload could exfiltrate data or
+        # steal the sandbox managed-identity token from the cloud metadata
+        # endpoint. Warn loudly; do not silently allow it.
+        if egress_policy is None:
+            warnings.warn(
+                "ACASandboxProvider is starting a sandbox with unrestricted "
+                "egress (no egress_policy). The environment runs untrusted code; "
+                "prefer a default-deny policy via "
+                "ACASandboxProvider.deny_all_egress(allow=[...]) and ensure the "
+                "cloud metadata/IMDS endpoint is blocked.",
+                stacklevel=2,
+            )
+
+        # Record injected secret values so captured server output can be scrubbed
+        # before it is ever surfaced in an error (security invariant S4).
+        self._redact_values = {
+            value for value in (effective_env_vars or {}).values() if value
+        }
+
+        # Two-stage cleanup. A create failure created nothing, so just drop the
+        # recorded secrets and re-raise (notably it must NOT delete a sandbox
+        # this call did not create — e.g. one left over on the provider). Only a
+        # failure AFTER the sandbox exists runs stop_container() to delete it.
+        try:
+            self._sandbox = self._adapter.create_sandbox(
+                disk=disk,
+                disk_id=disk_id,
+                env_vars=dict(effective_env_vars or {}) if effective_env_vars else None,
+                labels=labels or None,
+                egress_policy=egress_policy,
+                cpu=self.cpu,
+                memory=self.memory,
+                disk_size=self.disk_size,
+                auto_suspend_seconds=self.auto_suspend_seconds,
+                auto_suspend_mode=self.auto_suspend_mode,
+                create_timeout=self.create_timeout,
+                polling_interval=self.polling_interval,
+            )
+        except Exception:
+            self._redact_values = set()
+            raise
+
+        try:
+            if cmd:
+                self._start_server(cmd)
+            self._base_url = _require_secure_url(
+                self._adapter.add_port(
+                    self._sandbox,
+                    port=bind_port,
+                    anonymous=anonymous_port,
+                )
+            )
+            self._port = bind_port
+        except Exception:
+            # A cleanup failure here must not mask the original error: swallow
+            # any exception from stop_container() so the root cause propagates.
+            try:
+                self.stop_container()
+            except Exception:
+                pass
+            raise
+
+        return self._base_url
+
+    def _start_server(self, cmd: str) -> None:
+        # `cmd` is trusted orchestrator configuration, not agent/environment
+        # input — callers must not pass agent-controlled text as `cmd`, and any
+        # dynamic value interpolated into it must be quoted by the caller. Given
+        # that, running it through the subshell below is safe (RFC 002 amendment
+        # S5 — no command injection from untrusted sources). `working_directory`
+        # is still shlex-quoted defensively.
+        if self.working_directory:
+            command = f"cd {shlex.quote(self.working_directory)} && {cmd}"
+        else:
+            command = cmd
+        escaped = shlex.quote(command)
+        # The adapter's `exec` maps to the ACA SDK's `executeShellCommand`
+        # endpoint, which runs its argument through a POSIX shell in the sandbox
+        # (the SDK docstring says "Execute a shell command" and tells callers to
+        # `shlex.quote()` interpolated input). That shell is what makes the
+        # backgrounding (`&`), output redirection, and `$!` PID capture below
+        # work; if a future preview SDK changes `exec` to bypass the shell, this
+        # start sequence must be revisited (re-validate via the integration test).
+        self._adapter.exec(
+            self._sandbox,
+            f"nohup bash -c {escaped} > /tmp/openenv-server.log 2>&1 & "
+            "echo $! > /tmp/openenv-server.pid",
+        )
+        self._started_server = True
+
+    def _redact(self, text: str, *, max_chars: int = 2000) -> str:
+        """Scrub injected secret values and bound length before surfacing output.
+
+        Replaces any injected env-var value with `***` and keeps only the tail.
+        This is best-effort (exact-match only), which is why server output is
+        withheld entirely unless `surface_server_logs=True` (RFC 002 S4).
+        """
+        redacted = text or ""
+        for value in self._redact_values:
+            redacted = redacted.replace(value, "***")
+        if len(redacted) > max_chars:
+            redacted = "...(truncated)...\n" + redacted[-max_chars:]
+        return redacted
+
+    def _server_died_message(self) -> str:
+        """Build the startup-crash error, secure by default (RFC 002 S4).
+
+        Untrusted code can print secrets then force a crash to exfiltrate them
+        through the exception (which lands in orchestrator/CI logs), so sandbox
+        output is excluded unless `surface_server_logs=True`, in which case a
+        best-effort redacted, bounded excerpt is included.
+        """
+        base = (
+            "ACA sandbox server process died during startup. Server output is "
+            "not surfaced to avoid leaking secrets injected into the sandbox; "
+            "retrieve /tmp/openenv-server.log from the sandbox out of band, or "
+            "construct the provider with surface_server_logs=True to include a "
+            "redacted excerpt."
+        )
+        if not self.surface_server_logs:
+            return base
+        if self._sandbox is None:
+            return base
+        log = self._redact(
+            _exec_stdout(
+                self._adapter.exec(
+                    self._sandbox,
+                    "cat /tmp/openenv-server.log 2>/dev/null",
+                )
+            )
+        )
+        return (
+            "ACA sandbox server process died during startup. The excerpt below "
+            "is the sandbox server output with injected secret values redacted "
+            "(best-effort); it may still contain secrets the workload printed "
+            f"by other means.\nLog (redacted):\n{log}"
+        )
+
+    def wait_for_ready(self, base_url: str, timeout_s: float = 120.0) -> None:
+        """Wait for the ACA-hosted OpenEnv server to answer on `/health`.
+
+        A `200` on `/health` proves HTTP reachability but not that the exposed
+        ACA port proxies the `/ws` WebSocket upgrade `EnvClient` needs; the
+        integration test covers the full `wss://` round-trip. If the captured
+        server process dies during startup this raises `RuntimeError` (sandbox
+        output is withheld unless `surface_server_logs=True`; see RFC 002 S4).
+        """
+        # Imported lazily inside the method that needs it, matching the other
+        # providers in this package (e.g. DaytonaProvider).
+        import requests
+
+        deadline = time.time() + timeout_s
+        health_url = f"{base_url}/health"
+
+        while time.time() < deadline:
+            try:
+                response = requests.get(health_url, timeout=5.0)
+                if response.status_code == 200:
+                    return
+            except requests.RequestException:
+                pass
+
+            if self._started_server and self._sandbox is not None:
+                status = _exec_stdout(
+                    self._adapter.exec(
+                        self._sandbox,
+                        "kill -0 $(cat /tmp/openenv-server.pid) 2>/dev/null "
+                        "&& echo RUNNING || echo DEAD",
+                    )
+                )
+                if "DEAD" in status:
+                    raise RuntimeError(self._server_died_message())
+
+            time.sleep(1.0)
+
+        raise TimeoutError(
+            f"ACA sandbox did not become ready within {timeout_s}s. "
+            "If the sandbox image starts the server itself, pass cmd= to let "
+            "ACASandboxProvider capture /tmp/openenv-server.log for early crash "
+            "diagnostics."
+        )
+
+    def stop_container(self) -> None:
+        """Delete the active ACA sandbox."""
+        if self._sandbox is None:
+            # Still drop any injected secret values recorded by a failed start
+            # (e.g. create_sandbox raised before a sandbox handle existed).
+            self._redact_values = set()
+            return
+
+        try:
+            self._adapter.delete_sandbox(self._sandbox)
+        finally:
+            self._sandbox = None
+            self._base_url = None
+            self._started_server = False
+            # Drop the previous episode's injected secret values; a new start
+            # repopulates them (avoids carrying stale values across sandboxes).
+            self._redact_values = set()
+
+    @property
+    def base_url(self) -> str:
+        """URL returned by the last `start_container`."""
+        if self._base_url is None:
+            raise RuntimeError(
+                "ACASandboxProvider has no active base_url. Start the provider "
+                "before reading base_url."
+            )
+        return self._base_url
+
+    def close(self) -> None:
+        """Stop the active sandbox and close the underlying SDK client.
+
+        Overrides the base no-op so a caller can release the preview SDK client
+        deterministically (also invoked on context-manager exit). The base
+        `ContainerProvider` defines `close()`/`__enter__`/`__exit__`, so callers
+        holding a bare `ContainerProvider` can release resources polymorphically.
+        """
+        self.stop_container()
+        if self._owns_adapter:
+            self._adapter.close()
+            # don't close a second time on a subsequent close()/context exit
+            self._owns_adapter = False
+
+
+__all__ = ["ACASandboxProvider"]

src/core/containers/runtime/daytona_provider.py

@@ -0,0 +1,547 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+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 os
+import shlex
+import time
+from typing import Any, Callable, Dict, Optional
+
+from ._server_config import parse_dockerfile_cmd, parse_openenv_app_field
+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,
+        *,
+        image: Optional[str] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        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:
+            image: Docker image, snapshot reference, or ``"dockerfile:<path>"``
+                source to use when ``start_container()`` is called without an
+                image.
+            env_vars: Environment variables to use when ``start_container()`` is
+                called without explicit ``env_vars``.
+            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._image = image
+        self._env_vars = env_vars
+        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.
+        """
+        return parse_openenv_app_field(yaml_content)
+
+    @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.
+        """
+        return parse_dockerfile_cmd(dockerfile_content)
+
+    @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: Optional[str] = None,
+        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`. May be omitted when supplied
+                   to the constructor.
+            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."
+            )
+
+        effective_image = image if image is not None else self._image
+        if effective_image is None:
+            raise ValueError(
+                "DaytonaProvider requires an image. Pass it to the constructor "
+                "or start_container()."
+            )
+        effective_env_vars = self._env_vars if env_vars is None else env_vars
+
+        # 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 effective_env_vars:
+            create_kwargs["env_vars"] = effective_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 effective_image.startswith("snapshot:"):
+            from daytona import CreateSandboxFromSnapshotParams
+
+            snapshot_name = effective_image[len("snapshot:") :]
+            params = CreateSandboxFromSnapshotParams(
+                snapshot=snapshot_name, **create_kwargs
+            )
+        elif effective_image.startswith("dockerfile:"):
+            from daytona import CreateSandboxFromImageParams, Image
+
+            dockerfile_path = effective_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": effective_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/hf_sandbox_provider.py

@@ -0,0 +1,342 @@
+# 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.
+
+"""Hugging Face-backed provider for OpenEnv environment servers."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import socket
+import threading
+import time
+from contextlib import suppress
+from typing import Any
+
+import requests
+from fastapi import FastAPI, Request, Response, WebSocket, WebSocketDisconnect
+from websockets.asyncio.client import connect as ws_connect
+from websockets.exceptions import ConnectionClosed
+
+from .providers import ContainerProvider
+
+
+_DEFAULT_PORT = 8000
+_SERVER_COMMAND = (
+    'export SBX_PROXY_DIR="${SBX_PROXY_DIR:-$HOME/.sbx/proxy}"; '
+    'mkdir -p "$SBX_PROXY_DIR"; '
+    'nohup server >"$HOME/openenv-server.log" 2>&1 &'
+)
+_MAX_WS_MESSAGE_SIZE = 100 * 1024 * 1024
+_HOP_BY_HOP_HEADERS = {
+    "connection",
+    "content-encoding",
+    "content-length",
+    "host",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+}
+_POOLS: dict[tuple[str, str], Any] = {}
+_POOL_LOCK = threading.Lock()
+
+
+def _find_available_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        sock.listen(1)
+        return sock.getsockname()[1]
+
+
+def _to_ws_url(url: str) -> str:
+    if url.startswith("https://"):
+        return "wss://" + url[len("https://") :]
+    if url.startswith("http://"):
+        return "ws://" + url[len("http://") :]
+    return url
+
+
+def _pool_name(image: str, flavor: str) -> str:
+    digest = hashlib.sha1(f"{image}\0{flavor}".encode("utf-8")).hexdigest()[:12]
+    return f"openenv-{digest}"
+
+
+def _get_sandbox_pool_cls() -> Any:
+    try:
+        from huggingface_hub import SandboxPool
+    except ImportError as exc:
+        raise RuntimeError(
+            "HFSandboxProvider requires a huggingface_hub version with "
+            "SandboxPool.create and Sandbox.proxy_url_for support."
+        ) from exc
+    return SandboxPool
+
+
+def _get_pool(image: str, flavor: str) -> Any:
+    key = (image, flavor)
+    with _POOL_LOCK:
+        pool = _POOLS.get(key)
+        if pool is None:
+            SandboxPool = _get_sandbox_pool_cls()
+            pool = SandboxPool(
+                image=image,
+                flavor=flavor,
+                name=_pool_name(image, flavor),
+            )
+            _POOLS[key] = pool
+        return pool
+
+
+class _LocalAuthProxy:
+    def __init__(self, *, target_url: str, headers: dict[str, str]):
+        self.target_url = target_url.rstrip("/")
+        self.headers = headers
+        self.port = _find_available_port()
+        self._server: Any = None
+        self._thread: threading.Thread | None = None
+
+    @property
+    def base_url(self) -> str:
+        return f"http://127.0.0.1:{self.port}"
+
+    def start(self) -> str:
+        app = FastAPI()
+
+        @app.api_route(
+            "/{path:path}",
+            methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+        )
+        async def proxy_http(path: str, request: Request) -> Response:
+            query = request.url.query
+            target = f"{self.target_url}/{path}"
+            if query:
+                target = f"{target}?{query}"
+            headers = dict(self.headers)
+            content_type = request.headers.get("content-type")
+            if content_type is not None:
+                headers["Content-Type"] = content_type
+            body = await request.body()
+            try:
+                upstream = await asyncio.to_thread(
+                    requests.request,
+                    request.method,
+                    target,
+                    data=body,
+                    headers=headers,
+                    timeout=60.0,
+                    allow_redirects=True,
+                )
+            except requests.RequestException:
+                return Response(
+                    content=b"upstream HF job unreachable",
+                    status_code=502,
+                )
+            response_headers = {
+                key: value
+                for key, value in upstream.headers.items()
+                if key.lower() not in _HOP_BY_HOP_HEADERS
+            }
+            return Response(
+                content=upstream.content,
+                status_code=upstream.status_code,
+                headers=response_headers,
+            )
+
+        @app.websocket("/{path:path}")
+        async def proxy_websocket(path: str, websocket: WebSocket) -> None:
+            query = websocket.url.query
+            target = f"{_to_ws_url(self.target_url)}/{path}"
+            if query:
+                target = f"{target}?{query}"
+            headers = {**self.headers, "accept": "*/*"}
+            upstream = await self._connect_upstream_websocket(target, headers)
+            await websocket.accept()
+            try:
+                to_upstream = asyncio.create_task(
+                    self._client_to_upstream(websocket, upstream)
+                )
+                to_client = asyncio.create_task(
+                    self._upstream_to_client(websocket, upstream)
+                )
+                done, pending = await asyncio.wait(
+                    {to_upstream, to_client},
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+                for task in pending:
+                    task.cancel()
+                for task in done:
+                    with suppress(ConnectionClosed, WebSocketDisconnect):
+                        task.result()
+            finally:
+                with suppress(Exception):
+                    await upstream.close()
+
+        import uvicorn
+
+        config = uvicorn.Config(
+            app,
+            host="127.0.0.1",
+            port=self.port,
+            log_level="warning",
+            access_log=False,
+        )
+        self._server = uvicorn.Server(config)
+        self._thread = threading.Thread(target=self._server.run, daemon=True)
+        self._thread.start()
+        while not self._server.started:
+            if not self._thread.is_alive():
+                raise RuntimeError("HF sandbox auth proxy failed to start")
+            time.sleep(0.05)
+        return self.base_url
+
+    async def _connect_upstream_websocket(
+        self, target: str, headers: dict[str, str]
+    ) -> Any:
+        last_error: Exception | None = None
+        for _ in range(5):
+            try:
+                return await ws_connect(
+                    target,
+                    additional_headers=headers,
+                    max_size=_MAX_WS_MESSAGE_SIZE,
+                    compression=None,
+                )
+            except Exception as exc:
+                last_error = exc
+                await asyncio.sleep(0.5)
+        assert last_error is not None
+        raise last_error
+
+    async def _client_to_upstream(self, websocket: WebSocket, upstream: Any) -> None:
+        # EnvClient sends JSON text frames; binary frames are only relayed downstream.
+        async for message in websocket.iter_text():
+            await upstream.send(message)
+
+    async def _upstream_to_client(self, websocket: WebSocket, upstream: Any) -> None:
+        async for message in upstream:
+            if isinstance(message, bytes):
+                await websocket.send_bytes(message)
+            else:
+                await websocket.send_text(message)
+
+    def stop(self) -> None:
+        if self._server is None or self._thread is None:
+            return
+        self._server.should_exit = True
+        self._thread.join(timeout=5.0)
+        self._server = None
+        self._thread = None
+
+
+class HFSandboxProvider(ContainerProvider):
+    """Run an OpenEnv server on Hugging Face infrastructure.
+
+    The server runs in a `huggingface_hub` sandbox pool, which bills its hosts as
+    Hugging Face Jobs. `start_container()` returns a local proxy URL that adds the
+    Hugging Face auth headers, so any `EnvClient` can connect to it unchanged.
+
+    Args:
+        image (`str`):
+            Image to run, for example `hf.co/spaces/openenv/coding_env`. It must
+            provide a `server` command that serves OpenEnv on port 8000.
+        env_vars (`dict[str, str]`, *optional*):
+            Environment variables for the server.
+        flavor (`str`, *optional*, defaults to `"cpu-basic"`):
+            Hugging Face hardware flavor of the sandbox hosts.
+    """
+
+    def __init__(
+        self,
+        *,
+        image: str,
+        env_vars: dict[str, str] | None = None,
+        flavor: str = "cpu-basic",
+    ):
+        self.image = image
+        self.env_vars = env_vars
+        self.flavor = flavor
+        self._sandbox: Any = None
+        self._proxy: _LocalAuthProxy | None = None
+
+    def start_container(
+        self,
+        image: str | None = None,
+        port: int | None = None,
+        env_vars: dict[str, str] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        if self._sandbox is not None:
+            raise RuntimeError("HFSandboxProvider already has an active service")
+        if kwargs:
+            unsupported = ", ".join(sorted(kwargs))
+            raise ValueError(
+                f"HFSandboxProvider does not support start_container kwargs: {unsupported}"
+            )
+
+        if port not in (None, _DEFAULT_PORT):
+            raise ValueError(
+                f"HFSandboxProvider only supports port {_DEFAULT_PORT} (got {port})."
+            )
+
+        effective_image = self.image if image is None else image
+        effective_env = self.env_vars if env_vars is None else env_vars
+        pool = _get_pool(effective_image, self.flavor)
+        self._sandbox = pool.create(env=effective_env)
+        try:
+            if not hasattr(self._sandbox, "proxy_url_for") or not hasattr(
+                self._sandbox, "proxy_headers"
+            ):
+                raise RuntimeError(
+                    "HFSandboxProvider requires a huggingface_hub version with "
+                    "Sandbox.proxy_url_for and Sandbox.proxy_headers support."
+                )
+            self._sandbox.run(
+                _SERVER_COMMAND,
+                shell=True,
+            )
+            self._proxy = _LocalAuthProxy(
+                target_url=self._sandbox.proxy_url_for(_DEFAULT_PORT, "/"),
+                headers=self._sandbox.proxy_headers,
+            )
+            return self._proxy.start()
+        except Exception:
+            self.stop_container()
+            raise
+
+    def stop_container(self) -> None:
+        if self._proxy is not None:
+            self._proxy.stop()
+            self._proxy = None
+        if self._sandbox is not None:
+            sandbox = self._sandbox
+            self._sandbox = None
+            with suppress(Exception):
+                sandbox.kill()
+
+    def wait_for_ready(self, base_url: str, timeout_s: float = 120.0) -> None:
+        deadline = time.time() + timeout_s
+        health_url = f"{base_url}/health"
+        while time.time() < deadline:
+            try:
+                response = requests.get(health_url, timeout=5.0)
+                if response.status_code == 200:
+                    return
+            except requests.exceptions.RequestException:
+                pass
+            time.sleep(1.0)
+        raise TimeoutError(
+            f"HF sandbox job at {base_url} did not become ready within {timeout_s}s"
+        )
+
+    def close(self) -> None:
+        self.stop_container()
+
+
+__all__ = ["HFSandboxProvider"]

src/core/containers/runtime/modal_provider.py

@@ -0,0 +1,697 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+Modal container provider for running OpenEnv environments in Modal sandboxes.
+
+Requires the ``modal`` SDK: ``pip install modal>=1.4``
+
+The provider boots an OpenEnv server inside a Modal sandbox, exposes it on an
+encrypted tunnel, and returns an ``https://`` URL that ``EnvClient`` connects to
+over ``wss://``.
+
+Supports both the stable Sandbox API (``modal.Sandbox.create``) and the beta
+Sandbox v2 API (``modal.Sandbox._experimental_create``). Sandbox v2 is opt-in
+via ``use_sandbox_v2=True`` because it is an experimental, private SDK feature;
+see https://modal.com/docs/guide/sandbox-v2 .
+"""
+
+from __future__ import annotations
+
+import logging
+import shlex
+import time
+from typing import Any, Dict, Optional
+
+from ._server_config import parse_dockerfile_cmd, parse_openenv_app_field
+from .providers import ContainerProvider
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_MODAL_PORT = 8000
+
+# Modal's default per-container resource requests. We pass configured cpu/memory
+# as the *limit* half of Modal's ``(request, limit)`` tuple so they cap usage
+# rather than reserving (and billing for) the full amount. See
+# https://modal.com/docs/guide/resources .
+_DEFAULT_CPU_REQUEST = 0.125
+_DEFAULT_MEMORY_REQUEST = 128
+
+
+def _require_secure_url(url: str) -> str:
+    """Enforce https/wss transport (RFC 002 security invariant S1).
+
+    ``EnvClient`` derives its WebSocket URL from this base URL, so a plaintext
+    URL would become a cleartext ``ws://`` connection. The offending URL is
+    deliberately omitted from the error because a Modal tunnel URL is a bearer
+    capability that must not leak into logs.
+    """
+    if not isinstance(url, str) or not url.lower().startswith("https://"):
+        raise RuntimeError(
+            "Modal sandbox returned a non-HTTPS tunnel URL. OpenEnv requires an "
+            "https/wss base_url so EnvClient traffic is encrypted. Refusing to "
+            "connect over plaintext."
+        )
+    return url
+
+
+class _DefaultModalAdapter:
+    """Thin adapter over the ``modal`` SDK.
+
+    The provider talks to this private adapter instead of spreading SDK details
+    through its own logic; tests inject a duck-typed fake in its place. Keeping
+    the SDK surface here also localizes the feature check for the private
+    Sandbox v2 (``_experimental_create``) API.
+    """
+
+    def __init__(self, *, app_name: str, use_sandbox_v2: bool):
+        import modal
+
+        self._modal = modal
+        self._app_name = app_name
+        self._use_sandbox_v2 = use_sandbox_v2
+
+        # Sandbox v2 rides on a private SDK entry point that is not present in
+        # every modal release. Fail fast at construction with clear guidance
+        # rather than at start_container time with an AttributeError.
+        if use_sandbox_v2 and not hasattr(modal.Sandbox, "_experimental_create"):
+            raise RuntimeError(
+                "use_sandbox_v2=True requires modal.Sandbox._experimental_create, "
+                "which is not available in the installed modal SDK. Upgrade modal, "
+                "or use the stable Sandbox API (use_sandbox_v2=False). Sandbox v2 "
+                "is an experimental feature; contact support@modal.com for access."
+            )
+
+    def image_from_registry(self, tag: str) -> Any:
+        return self._modal.Image.from_registry(tag)
+
+    def image_from_dockerfile(self, dockerfile_path: str, context_dir: str) -> Any:
+        return self._modal.Image.from_dockerfile(
+            dockerfile_path, context_dir=context_dir
+        )
+
+    def create_sandbox(
+        self,
+        *,
+        image: Any,
+        encrypted_ports: list[int],
+        timeout: int,
+        env: Optional[dict[str, str]],
+        extra: dict[str, Any],
+    ) -> Any:
+        app = self._modal.App.lookup(self._app_name, create_if_missing=True)
+        kwargs: Dict[str, Any] = {
+            "app": app,
+            "image": image,
+            "encrypted_ports": encrypted_ports,
+            "timeout": timeout,
+            **extra,
+        }
+        if env:
+            kwargs["env"] = dict(env)
+
+        # The sandbox is started with a keep-alive entrypoint; the server
+        # command is launched via exec afterwards (see ModalProvider).
+        if self._use_sandbox_v2:
+            return self._modal.Sandbox._experimental_create(
+                "sleep", "infinity", **kwargs
+            )
+        return self._modal.Sandbox.create("sleep", "infinity", **kwargs)
+
+    def exec(self, sandbox: Any, command: str, *, timeout: int = 10) -> str:
+        """Run *command* through a shell inside *sandbox* and return its stdout."""
+        proc = sandbox.exec("bash", "-c", command, timeout=timeout)
+        try:
+            out = proc.stdout.read()
+        except Exception:
+            out = ""
+        proc.wait()
+        return out or ""
+
+    def tunnel_url(self, sandbox: Any, port: int) -> str:
+        return sandbox.tunnels()[port].url
+
+    def terminate(self, sandbox: Any) -> None:
+        sandbox.terminate()
+
+
+class ModalProvider(ContainerProvider):
+    """
+    Container provider that runs environments in Modal sandboxes.
+
+    ``start_container``'s ``image`` is either a registry tag
+    (``"echo-env:latest"``) or a ``"dockerfile:<path>"`` reference returned by
+    :meth:`image_from_dockerfile`. The server is exposed on an encrypted Modal
+    tunnel and the returned ``https://`` URL is what ``EnvClient`` connects to
+    over ``wss://``.
+
+    The environment runs untrusted code, so the provider is secure by default:
+    it enforces https/wss transport, treats the tunnel URL as a bearer secret
+    (never interpolated into errors), and never surfaces raw sandbox output
+    unless ``surface_server_logs=True``.
+
+    Only one sandbox is active per provider: calling ``start_container`` again
+    before ``stop_container()``/``close()`` raises ``RuntimeError`` rather than
+    orphaning the running sandbox. ``close()`` (and context-manager exit) stops
+    the active sandbox.
+
+    Example:
+        ```python
+        with ModalProvider(app_name="openenv", cpu=2.0, memory=4096) as provider:
+            image = ModalProvider.image_from_dockerfile(
+                "envs/echo_env/server/Dockerfile"
+            )
+            base_url = provider.start_container(image)
+            provider.wait_for_ready(base_url)
+        # sandbox terminated on exit
+        ```
+
+    Sandbox v2 (beta) is opt-in:
+        ```python
+        provider = ModalProvider(app_name="openenv", use_sandbox_v2=True)
+        ```
+    """
+
+    _dockerfile_registry: Dict[str, Dict[str, Any]] = {}
+
+    def __init__(
+        self,
+        *,
+        image: str | None = None,
+        env_vars: dict[str, str] | None = None,
+        app_name: str = "openenv",
+        use_sandbox_v2: bool = False,
+        timeout: int = 300,
+        cmd: str | None = None,
+        cpu: float | None = None,
+        memory: int | None = None,
+        surface_server_logs: bool = False,
+        _adapter: Any = None,
+    ):
+        """
+        Args:
+            image (`str`, *optional*):
+                Registry image tag or ``"dockerfile:<path>"`` source to use
+                when ``start_container()`` is called without an image.
+            env_vars (`dict`, *optional*):
+                Environment variables to use when ``start_container()`` is
+                called without explicit ``env_vars``.
+            app_name (`str`, *optional*, defaults to `"openenv"`):
+                Modal app name the sandbox is created under. Looked up (and
+                created if missing) via ``modal.App.lookup``.
+            use_sandbox_v2 (`bool`, *optional*, defaults to `False`):
+                When `True`, sandboxes are created via the beta
+                ``modal.Sandbox._experimental_create`` API (Sandbox v2). This is
+                an experimental, private SDK feature and is therefore off by
+                default; a feature check fails fast at construction if the
+                installed SDK lacks it. See https://modal.com/docs/guide/sandbox-v2 .
+            timeout (`int`, *optional*, defaults to `300`):
+                Maximum sandbox lifetime in seconds.
+            cmd (`str`, *optional*):
+                Shell command to start the server inside the sandbox. When
+                omitted, the command is auto-discovered from ``openenv.yaml``
+                (falling back to the Dockerfile ``CMD``).
+            cpu (`float`, *optional*):
+                Hard CPU-core limit for the sandbox. Passed as the limit half of
+                Modal's ``(request, limit)`` tuple (request stays at Modal's
+                default), so it caps usage rather than reserving cores. When
+                `None`, Modal's default applies.
+            memory (`int`, *optional*):
+                Hard memory limit in MiB for the sandbox (containers exceeding it
+                are OOM-killed). Passed as the limit half of Modal's
+                ``(request, limit)`` tuple. When `None`, Modal's default applies.
+            surface_server_logs (`bool`, *optional*, defaults to `False`):
+                When `False` (default), captured sandbox output is withheld from
+                raised errors so secrets the workload printed cannot leak into
+                orchestrator/CI logs. When `True`, a best-effort redacted,
+                length-bounded excerpt is included in startup-crash errors.
+        """
+        self._image = image
+        self._env_vars = env_vars
+        self._app_name = app_name
+        self._use_sandbox_v2 = use_sandbox_v2
+        self._timeout = timeout
+        self._cmd = cmd
+        self._cpu = cpu
+        self._memory = memory
+        self._surface_server_logs = surface_server_logs
+        self._sandbox: Any = None
+        self._base_url: str | None = None
+        # Injected env-var values, used to scrub captured server output before
+        # it is ever surfaced in an error.
+        self._redact_values: set[str] = set()
+
+        if _adapter is None:
+            # Import eagerly (inside the adapter) so SDK/configuration errors —
+            # including the Sandbox v2 feature check — surface at construction.
+            self._adapter: Any = _DefaultModalAdapter(
+                app_name=app_name, use_sandbox_v2=use_sandbox_v2
+            )
+        else:
+            self._adapter = _adapter
+
+        if use_sandbox_v2:
+            logger.info(
+                "Using Modal Sandbox v2 (experimental). This feature must be "
+                "explicitly enabled. Contact support@modal.com to get access."
+            )
+
+    def _discover_server_cmd(self, port: int = _DEFAULT_MODAL_PORT) -> str:
+        """Discover the server command from ``openenv.yaml`` inside the 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()
+        if yaml_path is None:
+            raise ValueError(
+                "Could not find openenv.yaml inside the sandbox. "
+                "Pass an explicit cmd= to ModalProvider or start_container()."
+            )
+
+        content = self._adapter.exec(self._sandbox, f"cat {shlex.quote(yaml_path)}")
+        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 ModalProvider 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) -> str | None:
+        """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
+        out = self._adapter.exec(
+            self._sandbox, "test -f /app/env/openenv.yaml && echo found"
+        )
+        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).
+        path = self._adapter.exec(
+            self._sandbox,
+            "find /app -maxdepth 4 -name openenv.yaml -print -quit 2>/dev/null",
+        ).strip()
+        if path and path.startswith("/"):
+            return path
+
+        return None
+
+    @staticmethod
+    def _parse_app_field(yaml_content: str) -> str | None:
+        """Extract the ``app`` value from raw openenv.yaml content.
+
+        Uses PyYAML to handle comments, quotes, and nested keys correctly.
+        """
+        return parse_openenv_app_field(yaml_content)
+
+    @staticmethod
+    def _parse_dockerfile_cmd(dockerfile_content: str) -> str | None:
+        """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.
+        """
+        return parse_dockerfile_cmd(dockerfile_content)
+
+    @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) and stores
+        its content in an internal registry.  The actual ``modal.Image`` is
+        created later inside ``start_container``.
+
+        Args:
+            dockerfile_path (`str`):
+                Path to the Dockerfile on disk.
+            context_dir (`str`, *optional*):
+                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:
+            `str`: 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()
+
+        # 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 content.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 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)] = {
+            "dockerfile_path": str(src),
+            "context_dir": str(ctx),
+            "server_cmd": parsed_cmd,
+        }
+
+        return f"dockerfile:{src}"
+
+    def _build_image(self, image: str) -> Any:
+        """Build the ``modal.Image`` for *image* (registry tag or dockerfile:)."""
+        if image.startswith("dockerfile:"):
+            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 ModalProvider.image_from_dockerfile() first."
+                )
+            return self._adapter.image_from_dockerfile(
+                meta["dockerfile_path"], meta["context_dir"]
+            )
+
+        # Plain registry tag (e.g. "echo-env:latest").
+        return self._adapter.image_from_registry(image)
+
+    def start_container(
+        self,
+        image: str | None = None,
+        port: int | None = None,
+        env_vars: dict[str, str] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """
+        Create a Modal sandbox from a Docker image or Dockerfile.
+
+        The sandbox is started with a keep-alive process and the server
+        command is launched via ``exec`` afterwards, mirroring the discovery
+        flow used by other cloud providers. 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 (`str`, *optional*):
+                Registry image tag (e.g. ``"echo-env:latest"``) or
+                ``"dockerfile:<path>"`` returned by
+                :meth:`image_from_dockerfile`. May be omitted when supplied to
+                the constructor.
+            port (`int`, *optional*):
+                Must be ``None`` or ``8000``. Modal exposes port 8000 via an
+                encrypted tunnel; other ports raise ``ValueError``.
+            env_vars (`dict`, *optional*):
+                Environment variables forwarded to the sandbox.
+            **kwargs:
+                ``cmd`` (`str`) to override the server command; any remaining
+                keyword arguments are forwarded to ``modal.Sandbox.create``.
+
+        Returns:
+            `str`: HTTPS tunnel URL for the sandbox (base_url).
+        """
+        if self._sandbox is not None:
+            raise RuntimeError(
+                "ModalProvider already has an active sandbox. Call "
+                "stop_container() (or close()) before starting another — a "
+                "second start would orphan the running sandbox."
+            )
+
+        if port is not None and port != _DEFAULT_MODAL_PORT:
+            raise ValueError(
+                f"ModalProvider only supports port {_DEFAULT_MODAL_PORT} "
+                f"(got {port}). The Modal tunnel routes to port "
+                f"{_DEFAULT_MODAL_PORT} inside the sandbox."
+            )
+
+        effective_image = image if image is not None else self._image
+        if effective_image is None:
+            raise ValueError(
+                "ModalProvider requires an image. Pass it to the constructor "
+                "or start_container()."
+            )
+        effective_env_vars = self._env_vars if env_vars is None else env_vars
+
+        # 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: str | None = None
+        if effective_image.startswith("dockerfile:"):
+            meta = self._dockerfile_registry.get(effective_image[len("dockerfile:") :])
+            if meta is not None:
+                parsed_cmd = meta.get("server_cmd")
+
+        modal_image = self._build_image(effective_image)
+
+        extra: Dict[str, Any] = dict(kwargs)
+        if self._cpu is not None:
+            extra["cpu"] = (_DEFAULT_CPU_REQUEST, self._cpu)
+        if self._memory is not None:
+            extra["memory"] = (_DEFAULT_MEMORY_REQUEST, self._memory)
+
+        # Record injected secret values so captured server output can be
+        # scrubbed before it is ever surfaced in an error.
+        self._redact_values = {
+            value for value in (effective_env_vars or {}).values() if value
+        }
+
+        # A create failure created nothing, so just drop the recorded secrets
+        # and re-raise (the double-start guard above guarantees there is no
+        # pre-existing sandbox to delete).
+        try:
+            self._sandbox = self._adapter.create_sandbox(
+                image=modal_image,
+                encrypted_ports=[_DEFAULT_MODAL_PORT],
+                timeout=self._timeout,
+                env=effective_env_vars,
+                extra=extra,
+            )
+        except Exception:
+            self._redact_values = set()
+            raise
+
+        try:
+            # Discover server command from openenv.yaml if not explicitly set.
+            if cmd is None:
+                try:
+                    cmd = self._discover_server_cmd()
+                except ValueError:
+                    # Fall back to CMD parsed from Dockerfile (if available).
+                    if parsed_cmd:
+                        cmd = parsed_cmd
+                    else:
+                        raise
+
+            # Launch the server in the background. Write the PID so we can
+            # check whether the process crashed in wait_for_ready().
+            escaped_cmd = shlex.quote(cmd)
+            self._adapter.exec(
+                self._sandbox,
+                f"nohup bash -c {escaped_cmd} > /tmp/openenv-server.log 2>&1 &"
+                " echo $! > /tmp/openenv-server.pid",
+            )
+
+            # Resolve the public tunnel URL for port 8000.
+            self._base_url = _require_secure_url(
+                self._adapter.tunnel_url(self._sandbox, _DEFAULT_MODAL_PORT)
+            )
+        except Exception:
+            # A cleanup failure here must not mask the original error: swallow
+            # any exception from stop_container() so the root cause propagates.
+            try:
+                self.stop_container()
+            except Exception:
+                pass
+            raise
+
+        return self._base_url
+
+    def stop_container(self) -> None:
+        """Terminate the Modal sandbox."""
+        if self._sandbox is None:
+            # Still drop any injected secret values recorded by a failed start.
+            self._redact_values = set()
+            return
+
+        try:
+            self._adapter.terminate(self._sandbox)
+        finally:
+            self._sandbox = None
+            self._base_url = None
+            self._redact_values = set()
+
+    def close(self) -> None:
+        """Stop the active sandbox.
+
+        Overrides the base no-op so a caller holding a bare ``ContainerProvider``
+        reference can release the sandbox polymorphically (also invoked on
+        context-manager exit). ``ModalProvider`` holds no separate SDK client, so
+        this is equivalent to ``stop_container()``.
+        """
+        self.stop_container()
+
+    @property
+    def base_url(self) -> str:
+        """URL returned by the last ``start_container``."""
+        if self._base_url is None:
+            raise RuntimeError(
+                "ModalProvider has no active base_url. Start the provider "
+                "before reading base_url."
+            )
+        return self._base_url
+
+    def _redact(self, text: str, *, max_chars: int = 2000) -> str:
+        """Scrub injected secret values and bound length before surfacing output.
+
+        Replaces any injected env-var value with `***` and keeps only the tail.
+        This is best-effort (exact-match only), which is why server output is
+        withheld entirely unless ``surface_server_logs=True``.
+        """
+        redacted = text or ""
+        for value in self._redact_values:
+            redacted = redacted.replace(value, "***")
+        if len(redacted) > max_chars:
+            redacted = "...(truncated)...\n" + redacted[-max_chars:]
+        return redacted
+
+    def _server_died_message(self) -> str:
+        """Build the startup-crash error, secure by default.
+
+        Untrusted code can print secrets then force a crash to exfiltrate them
+        through the exception (which lands in orchestrator/CI logs), so sandbox
+        output is excluded unless ``surface_server_logs=True``, in which case a
+        best-effort redacted, bounded excerpt is included.
+        """
+        base = (
+            "Modal sandbox server process died during startup. Server output is "
+            "not surfaced to avoid leaking secrets injected into the sandbox; "
+            "retrieve /tmp/openenv-server.log from the sandbox out of band, or "
+            "construct the provider with surface_server_logs=True to include a "
+            "redacted excerpt."
+        )
+        if not self._surface_server_logs or self._sandbox is None:
+            return base
+
+        log = self._redact(
+            self._adapter.exec(self._sandbox, "cat /tmp/openenv-server.log 2>/dev/null")
+        )
+        return (
+            "Modal sandbox server process died during startup. The excerpt below "
+            "is the sandbox server output with injected secret values redacted "
+            "(best-effort); it may still contain secrets the workload printed "
+            f"by other means.\nLog (redacted):\n{log}"
+        )
+
+    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 local Docker providers
+        because Modal sandboxes may have cold-start latency.
+
+        Args:
+            base_url (`str`):
+                Tunnel URL returned by ``start_container()``.
+            timeout_s (`float`, *optional*, defaults to `120.0`):
+                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:
+                out = self._adapter.exec(
+                    self._sandbox,
+                    "kill -0 $(cat /tmp/openenv-server.pid) 2>/dev/null"
+                    " && echo RUNNING || echo DEAD",
+                )
+                if "DEAD" in (out or ""):
+                    raise RuntimeError(self._server_died_message())
+
+            time.sleep(1.0)
+
+        # The tunnel URL is a bearer capability, so it is deliberately omitted
+        # from the timeout error.
+        raise TimeoutError(f"Modal sandbox did not become ready within {timeout_s}s.")
+
+
+__all__ = ["ModalProvider"]

src/core/containers/runtime/novita_provider.py

@@ -0,0 +1,1216 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+Novita AI Sandbox container provider for running OpenEnv environments.
+
+Requires the ``novita-sandbox`` SDK: ``pip install openenv[novita]``
+
+The provider boots an OpenEnv server inside a Novita sandbox, exposes port 8000
+on the sandbox's public host, and returns an ``https://`` URL that ``EnvClient``
+connects to over ``wss://``.
+
+Note: the ``RFC 002 security invariant S<n>`` references in this module point to
+the **proposed** "Cloud Sandbox Providers" amendment to RFC 002, which is pending
+review/sign-off by the RFC authors. They describe the security properties this
+provider enforces; treat them as proposed (not yet ratified) until that sign-off.
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+from ._server_config import parse_openenv_app_field
+from .providers import ContainerProvider
+
+_DEFAULT_NOVITA_PORT = 8000
+
+# Novita defaults a sandbox to a 300s hard lifetime, which would kill an RL
+# rollout mid-episode. One hour is the documented ceiling for Hobby accounts, so
+# it is the largest default that cannot make ``create`` fail on plan limits;
+# longer-running work passes ``timeout=`` explicitly.
+_DEFAULT_SANDBOX_TIMEOUT_S = 3600
+
+# The sandbox is created with this as its start command so the image's own CMD
+# is not launched (see `_launch_server`). `sleep infinity` keeps the sandbox
+# alive with nothing bound to port 8000, leaving the port free for the server
+# this provider starts itself.
+_KEEPALIVE_CMD = "sleep infinity"
+_KEEPALIVE_READY_MS = 5_000
+
+# Resource defaults for a template built from a Dockerfile. The SDK's own
+# defaults, restated here so they are visible at the call site.
+_DEFAULT_TEMPLATE_CPU = 2
+_DEFAULT_TEMPLATE_MEMORY_MB = 1024
+
+# User the sandbox runs as. Root because the environment installs under /app,
+# which the image creates as root and the Novita parser's default user ("user")
+# cannot write to -- see `build_template`. Matches what a plain `docker run` of
+# the same image gives, which is what the other providers' users observe.
+_SANDBOX_USER = "root"
+
+_FROM_RE = re.compile(r"^\s*FROM\s+(?P<rest>.+?)\s*$", re.IGNORECASE)
+_COPY_FROM_RE = re.compile(
+    r"^\s*COPY\s+--from=(?P<stage>\S+)\s+(?P<src>\S+)\s+(?P<dst>\S+)\s*$",
+    re.IGNORECASE,
+)
+_COPY_FROM_REMAINDER_RE = re.compile(r"^\s*COPY\b.*\s--from(?:=|\s|$)", re.IGNORECASE)
+_USER_RE = re.compile(r"^\s*USER(?:\s+|$)", re.IGNORECASE)
+_RUN_RE = re.compile(r"^\s*RUN\s+(?P<rest>.*)$", re.IGNORECASE)
+_ARG_DEFAULT_RE = re.compile(
+    r"^\s*ARG\s+(?P<name>\w+)=(?P<value>\S+)\s*$", re.IGNORECASE
+)
+
+
+def _strip_mount_flags(content: str) -> str:
+    """Remove supported BuildKit cache mounts from ``RUN`` instructions.
+
+    Novita's template parser copies a ``RUN`` body verbatim into the build
+    command, so a leading ``--mount=type=cache,...`` would be handed to the
+    shell as an argument rather than honored as BuildKit syntax. Every in-repo
+    OpenEnv Dockerfile uses one to cache ``uv`` downloads, so explicit cache
+    mounts are stripped rather than left to fail the build. Other mount types
+    affect build semantics and cannot be represented by Novita's parser, so
+    they are rejected instead of silently removed.
+    """
+    lines = content.split("\n")
+    out: List[str] = []
+    in_run = False
+    for line in lines:
+        if _RUN_RE.match(line):
+            in_run = True
+        if in_run:
+            # Strip leading --mount flags from the RUN line itself and from any
+            # continuation lines that follow it.
+            stripped = line
+            prefix = ""
+            run_match = _RUN_RE.match(line)
+            if run_match:
+                prefix = line[: run_match.start("rest")]
+                stripped = run_match.group("rest")
+            while True:
+                mount = re.match(r"\s*--mount=(?P<spec>\S+)(?P<space>\s*)", stripped)
+                if not mount:
+                    break
+                spec = mount.group("spec")
+                options = spec.split(",")
+                types = [
+                    option.split("=", 1)[1].lower()
+                    for option in options
+                    if option.lower().startswith("type=")
+                ]
+                if types != ["cache"]:
+                    raise ValueError(
+                        "Novita Dockerfile rewriting only supports explicit "
+                        "RUN --mount=type=cache options; unsupported mount "
+                        "types must be handled by `openenv build` and a "
+                        "registry image."
+                    )
+                stripped = stripped[mount.end() :]
+            line = prefix + stripped
+            if not line.rstrip().endswith("\\"):
+                in_run = False
+        out.append(line)
+    return "\n".join(out)
+
+
+def _resolve_from_references(content: str) -> str:
+    """Substitute ``ARG`` defaults into ``FROM`` lines and drop ``--platform``.
+
+    Two parser limitations, handled together because both corrupt the base
+    image reference:
+
+    - The parser stores a ``FROM ${BASE_IMAGE}`` line verbatim, so the template
+      would be built from a literal image named ``${BASE_IMAGE}``. Only global
+      ARGs (declared before the first ``FROM``) are in scope for a ``FROM``
+      line, which is the form every in-repo Dockerfile uses.
+    - ``FROM --platform=linux/amd64 python:3.10-slim`` likewise keeps the flag
+      as part of the name. Novita builds for its own platform, so the flag is
+      dropped rather than propagated.
+
+    Substitutions are applied longest-name-first so a short unbraced prefix
+    cannot corrupt a longer sibling (e.g. ``$BASE`` must not rewrite
+    ``$BASE_IMAGE`` / ``${BASE_IMAGE}`` into ``python:3.12_IMAGE``).
+    """
+    arg_defaults: Dict[str, str] = {}
+    for line in content.split("\n"):
+        if _FROM_RE.match(line):
+            break
+        match = _ARG_DEFAULT_RE.match(line)
+        if match:
+            arg_defaults[match.group("name")] = match.group("value")
+
+    # Longest names first: `$BASE` must not rewrite `$BASE_IMAGE` mid-token.
+    arg_items = sorted(
+        arg_defaults.items(), key=lambda item: len(item[0]), reverse=True
+    )
+
+    out: List[str] = []
+    for line in content.split("\n"):
+        match = _FROM_RE.match(line)
+        if not match:
+            out.append(line)
+            continue
+
+        reference = match.group("rest").strip()
+        reference = re.sub(r"^(--platform=\S+\s*)+", "", reference).strip()
+        for name, value in arg_items:
+            reference = reference.replace(f"${{{name}}}", value)
+            reference = reference.replace(f"${name}", value)
+        out.append(f"FROM {reference}")
+    return "\n".join(out)
+
+
+def _split_stages(content: str) -> List[Dict[str, Any]]:
+    """Split a Dockerfile into its ``FROM``-delimited stages."""
+    stages: List[Dict[str, Any]] = []
+    current: Optional[Dict[str, Any]] = None
+    for line in content.split("\n"):
+        match = _FROM_RE.match(line)
+        if match:
+            rest = match.group("rest").strip()
+            alias_match = re.match(r"(?P<base>.+?)\s+[Aa][Ss]\s+(?P<alias>\S+)$", rest)
+            if alias_match:
+                base = alias_match.group("base").strip()
+                alias = alias_match.group("alias")
+            else:
+                base, alias = rest, None
+            current = {"base": base, "alias": alias, "body": []}
+            stages.append(current)
+        elif current is not None:
+            current["body"].append(line)
+    return stages
+
+
+def _dockerfile_declares_user(content: str) -> bool:
+    """Return whether *content* contains a Dockerfile ``USER`` instruction."""
+    return any(_USER_RE.match(line) for line in content.splitlines())
+
+
+def _reject_unflattened_copy_from(content: str) -> None:
+    """Reject COPY instructions with ``--from`` left after flattening."""
+    if any(_COPY_FROM_REMAINDER_RE.match(line) for line in content.splitlines()):
+        raise ValueError(
+            "Dockerfile contains a COPY --from instruction that Novita cannot "
+            "flatten. Use a simple `COPY --from=<stage> <src> <dst>` form or "
+            "build the image with `openenv build` and pass the registry image."
+        )
+
+
+def _flatten_multistage(content: str) -> str:
+    """Collapse a multi-stage Dockerfile into a single stage.
+
+    Novita's parser rejects multi-stage Dockerfiles outright, and that is the
+    layout every in-repo OpenEnv environment uses: a ``builder`` stage that runs
+    ``uv sync`` into ``/app/env/.venv``, then a runtime stage that copies the
+    result across. Both stages name the *same* base image, so the build can be
+    replayed linearly in one stage -- the builder's ``RUN`` steps execute, then
+    each ``COPY --from=builder`` becomes an in-place ``cp``.
+
+    A copy whose source and destination are equal is dropped: after flattening,
+    the file is already at its destination, and Novita rejects an absolute
+    source path.
+
+    Raises:
+        ValueError: If the stages do not share one base image, a copy pulls from
+            a stage other than the builder, or a ``COPY --from`` cannot be
+            flattened.
+    """
+    stages = _split_stages(content)
+    if len(stages) < 2:
+        _reject_unflattened_copy_from(content)
+        return content
+
+    bases = {stage["base"] for stage in stages}
+    if len(bases) != 1:
+        raise ValueError(
+            "Novita templates cannot express a multi-stage Dockerfile whose "
+            f"stages use different base images: {sorted(bases)}. Build the "
+            "image with `openenv build` and push it with "
+            "`openenv push --registry`, then pass the registry reference to "
+            "NovitaSandboxProvider(image=...)."
+        )
+
+    builder_alias = stages[0]["alias"]
+    if builder_alias is None:
+        raise ValueError(
+            "The first stage of a multi-stage Dockerfile must be named with "
+            "`AS <alias>` so its output can be referenced after flattening."
+        )
+
+    out: List[str] = [f"FROM {stages[0]['base']}"]
+    for index, stage in enumerate(stages):
+        for line in stage["body"]:
+            copy_match = _COPY_FROM_RE.match(line)
+            if copy_match is None:
+                out.append(line)
+                continue
+            if index == 0:
+                # A copy within the builder stage is already valid as written.
+                out.append(line)
+                continue
+            source_stage = copy_match.group("stage")
+            if source_stage != builder_alias:
+                raise ValueError(
+                    f"COPY --from={source_stage} does not reference the builder "
+                    f"stage ({builder_alias}), so it cannot be flattened into a "
+                    "single-stage template."
+                )
+            src = copy_match.group("src")
+            dst = copy_match.group("dst")
+            if src == dst:
+                continue
+            out.append(
+                f"RUN mkdir -p $(dirname {shlex.quote(dst)}) && "
+                f"cp -a {shlex.quote(src)} {shlex.quote(dst)}"
+            )
+
+    flattened = "\n".join(out)
+    _reject_unflattened_copy_from(flattened)
+    return flattened
+
+
+def _prepare_dockerfile(content: str) -> str:
+    """Rewrite an OpenEnv Dockerfile into what Novita's template parser accepts.
+
+    Applies, in order: BuildKit ``--mount`` stripping, ``ARG``/``--platform``
+    resolution in ``FROM``, then multi-stage flattening. Each transform
+    compensates for a parser limitation rather than changing the build's
+    meaning.
+    """
+    return _flatten_multistage(_resolve_from_references(_strip_mount_flags(content)))
+
+
+def _require_secure_url(url: str) -> str:
+    """Enforce https/wss transport (RFC 002 security invariant S1).
+
+    ``EnvClient`` derives its WebSocket URL from this base URL, so a plaintext
+    URL would become a cleartext ``ws://`` connection. The offending URL is
+    deliberately omitted from the error: a sandbox host is reachable only
+    through the account that owns it, so the address is treated as
+    account-scoped rather than pasted into logs.
+    """
+    if (
+        not isinstance(url, str)
+        or not url.lower().startswith("https://")
+        or "://" in url[len("https://") :]
+    ):
+        raise RuntimeError(
+            "Novita sandbox returned a non-HTTPS host URL. OpenEnv requires an "
+            "https/wss base_url so EnvClient traffic is encrypted. Refusing to "
+            "connect over plaintext."
+        )
+
+    # With NOVITA_DEBUG set, the SDK's `get_host` returns `localhost:<port>`
+    # instead of the sandbox host. Adding the scheme would yield a URL that
+    # looks valid and silently targets whatever is listening on the caller's
+    # machine, so reject it explicitly rather than connect to the wrong thing.
+    hostname = url.split("://", 1)[1].split("/", 1)[0].rsplit(":", 1)[0]
+    if hostname in ("localhost", "127.0.0.1", "::1"):
+        raise RuntimeError(
+            "Novita sandbox returned a loopback host URL, which means the SDK is "
+            "running with NOVITA_DEBUG enabled. Debug mode bypasses the sandbox "
+            "host and would connect to the local machine instead; unset "
+            "NOVITA_DEBUG to reach the sandbox."
+        )
+
+    return url
+
+
+def _require_bare_host(host: str) -> str:
+    """Require the SDK host value to contain no URL scheme."""
+    if not isinstance(host, str) or not host or "://" in host:
+        raise RuntimeError(
+            "Novita sandbox returned an invalid host. Expected a bare hostname "
+            "without a URL scheme."
+        )
+    return host
+
+
+def _raise_install_error(exc: ImportError) -> None:
+    raise RuntimeError(
+        "Novita sandbox support requires optional dependencies. "
+        "Install them with `pip install openenv[novita]`."
+    ) from exc
+
+
+class _DefaultNovitaAdapter:
+    """Thin adapter over the ``novita-sandbox`` SDK.
+
+    The provider talks to this private adapter instead of spreading SDK details
+    through its own logic; tests inject a duck-typed fake in its place. Keeping
+    the SDK surface here is what makes the provider testable without a Novita
+    account and localizes API churn (RFC 002 implementation-hygiene invariant).
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str],
+        domain: Optional[str],
+    ):
+        try:
+            from novita_sandbox import Novita
+        except ImportError as exc:  # pragma: no cover - exercised via provider tests
+            _raise_install_error(exc)
+
+        # `api_key`/`domain` fall back to NOVITA_API_KEY / NOVITA_DOMAIN inside
+        # the SDK's ConnectionConfig, so `None` is the documented "use the env
+        # var" spelling rather than a missing value.
+        self._novita = Novita(api_key=api_key, domain=domain)
+
+    def create_sandbox(
+        self,
+        *,
+        image: Optional[str],
+        template: Optional[str],
+        env_vars: Optional[Dict[str, str]],
+        timeout: int,
+        metadata: Optional[Dict[str, str]],
+        secure: Optional[bool],
+    ) -> Any:
+        # Exactly one source: a registry image (resolved and cached by the SDK
+        # itself) or an already-built template id from `image_from_dockerfile`.
+        kwargs: Dict[str, Any] = {
+            "timeout": timeout,
+        }
+
+        if template is not None:
+            kwargs["template"] = template
+        else:
+            from novita_sandbox import wait_for_timeout
+
+            # `image` is an OCI reference; the SDK resolves it to a template
+            # itself (Template.from_image -> Template.build) and caches the
+            # result by image fingerprint, so repeated starts do not rebuild.
+            #
+            # The `build` block exists solely to pin the template's start
+            # command to a keepalive. `from_image` defaults to
+            # `inherit_config=True`, which restores the image's ENV/WORKDIR
+            # *and* its ENTRYPOINT/CMD as the template start command -- for an
+            # OpenEnv image that CMD is the uvicorn server, so leaving it in
+            # place would bind port 8000 before this provider launches its own
+            # copy. Setting `start_cmd` here wins over the inherited value (the
+            # caller always overrides the image). The SDK attempts to restore
+            # the image's ENV, but callers must use explicit paths when a
+            # registry config cannot be read during OCI template conversion.
+            ready_cmd = wait_for_timeout(_KEEPALIVE_READY_MS)
+            kwargs["image"] = image
+            kwargs["build"] = {
+                "cmd": _KEEPALIVE_CMD,
+                # Sandbox.create fingerprints this mapping with json.dumps
+                # before converting it into a TemplateBuilder. Keep the
+                # serialized command here; Template.set_start_cmd accepts the
+                # string as well as the ReadyCmd helper.
+                "ready_cmd": ready_cmd.get_cmd(),
+            }
+
+        if env_vars:
+            kwargs["envs"] = dict(env_vars)
+        if metadata:
+            kwargs["metadata"] = dict(metadata)
+        if secure is not None:
+            kwargs["secure"] = secure
+
+        return self._novita.sandbox.create(**kwargs)
+
+    def exec(
+        self,
+        sandbox: Any,
+        command: str,
+        *,
+        timeout: float = 10,
+        background: bool = False,
+        user: Optional[str] = None,
+    ) -> str:
+        """Run *command* through a login shell inside *sandbox*, returning stdout.
+
+        The SDK runs commands as ``/bin/bash -l -c <command>`` and raises
+        ``CommandExitException`` on a non-zero exit. The discovery and liveness
+        probes below are *expected* to exit non-zero ("no openenv.yaml", "process
+        is dead"), so the exit code is swallowed and stdout returned; callers
+        distinguish states by the marker the command echoes, not by the status.
+        """
+        from novita_sandbox import CommandExitException
+
+        run_kwargs: Dict[str, Any] = {
+            "timeout": timeout,
+            "background": background,
+        }
+        if user is not None:
+            run_kwargs["user"] = user
+
+        try:
+            result = sandbox.commands.run(command, **run_kwargs)
+        except CommandExitException as exc:
+            return exc.stdout or ""
+        except ImportError:  # pragma: no cover - SDK always exports this
+            result = sandbox.commands.run(command, **run_kwargs)
+
+        return getattr(result, "stdout", "") or ""
+
+    def host(self, sandbox: Any, port: int) -> str:
+        """Return the public host (no scheme) exposing *port* on *sandbox*."""
+        return str(sandbox.get_host(port))
+
+    def kill(self, sandbox: Any) -> None:
+        sandbox.kill()
+
+    def build_template(
+        self,
+        *,
+        dockerfile_content: str,
+        context_dir: str,
+        name: str,
+        cpu_count: int,
+        memory_mb: int,
+        on_build_logs: Optional[Callable[[Any], None]],
+    ) -> str:
+        """Build a Novita template from Dockerfile *content* and return its id.
+
+        Uses ``Template.from_dockerfile`` to translate the Dockerfile into
+        builder instructions, pins the template's start command to a keepalive
+        (so the image's own ``CMD`` does not bind port 8000 before the provider
+        launches the server), and builds it. ``file_context_path`` is what makes
+        relative ``COPY`` sources resolve against the build context.
+
+        Returns:
+            `str`: The built template id, to pass to ``Sandbox.create``.
+        """
+        from novita_sandbox import Template, wait_for_timeout
+
+        template = Template(file_context_path=context_dir)
+        builder = template.from_dockerfile(dockerfile_content)
+
+        # The parser rewrites USER to "user" when the Dockerfile declares none
+        # (dockerfile_parser.py: `if not user_changed: set_user("user")`). For an
+        # OpenEnv image that is wrong: `WORKDIR /app`, created by root, stays
+        # root-owned, so the server and every command the environment later runs
+        # in-process (`TB2_MODE=local`, and any env doing the same) fail with
+        # "Permission denied" on the install tree. Preserve an explicit Dockerfile
+        # USER, though, so the provider does not override the image author's
+        # requested runtime identity.
+        if not _dockerfile_declares_user(dockerfile_content):
+            builder.set_user(_SANDBOX_USER)
+
+        # `set_start_cmd` is the only way to pin the start command and it
+        # requires a readiness check, so the keepalive gets a short timer. The
+        # provider's own `wait_for_ready` does the real health polling.
+        builder.set_start_cmd(_KEEPALIVE_CMD, wait_for_timeout(_KEEPALIVE_READY_MS))
+
+        build_kwargs: Dict[str, Any] = {
+            "cpu_count": cpu_count,
+            "memory_mb": memory_mb,
+        }
+        if on_build_logs is not None:
+            build_kwargs["on_build_logs"] = on_build_logs
+
+        # Build through the configured namespace so the SDK merges the
+        # api_key/domain passed to Novita(...) into Template.build's connection
+        # config. Calling Template.build directly would fall back to an empty
+        # ConnectionConfig when those values are not present in the environment.
+        info = self._novita.template.build(builder, name, **build_kwargs)
+        return str(info.template_id)
+
+
+class NovitaSandboxProvider(ContainerProvider):
+    """
+    Container provider that runs environments in Novita AI sandboxes.
+
+    ``start_container`` accepts either form of source:
+
+    - A Docker/OCI registry reference (e.g. ``"ghcr.io/org/env:tag"``), which is
+      the form the ``ContainerProvider`` contract specifies. The SDK resolves it
+      into a Novita template internally and caches it by image fingerprint.
+    - A ``"template:<id>"`` reference returned by
+      :meth:`image_from_dockerfile`, which builds a template from a local
+      Dockerfile.
+
+    :meth:`image_from_dockerfile` rewrites the Dockerfile for Novita's template
+    parser, which does not accept multi-stage build definitions. The rewrite is
+    mechanical and preserves the build's meaning: BuildKit ``--mount`` flags are
+    stripped, ``ARG``/``--platform`` in ``FROM`` lines are resolved, and a
+    two-stage build whose stages share one base image is replayed as a single
+    stage (see `_prepare_dockerfile`). A Dockerfile that does not fit those
+    rules raises `ValueError` with the registry route as the alternative.
+
+    The environment runs untrusted code, so the provider is secure by default: it
+    enforces https/wss transport (S1) and never surfaces raw sandbox output
+    unless ``surface_server_logs=True`` (S4).
+
+    Only one sandbox is active per provider: calling ``start_container`` again
+    before ``stop_container()``/``close()`` raises ``RuntimeError`` rather than
+    orphaning the running sandbox.
+
+    Examples:
+
+        ```python
+        # From a pre-built registry image
+        with NovitaSandboxProvider(image="ghcr.io/org/echo-env:latest") as provider:
+            base_url = provider.start_container()
+            provider.wait_for_ready(base_url)
+
+        # From a local Dockerfile (builds a template on first use)
+        image = NovitaSandboxProvider.image_from_dockerfile(
+            "envs/echo_env/server/Dockerfile"
+        )
+        with NovitaSandboxProvider(image=image) as provider:
+            base_url = provider.start_container()
+        # sandbox killed on exit
+        ```
+    """
+
+    # Prepared Dockerfile content, keyed by "template:<abs_path>". Populated by
+    # `image_from_dockerfile` so `start_container` can build the template later,
+    # mirroring DaytonaProvider / ModalProvider.
+    _dockerfile_registry: Dict[str, Dict[str, Any]] = {}
+
+    @classmethod
+    def image_from_dockerfile(
+        cls,
+        dockerfile_path: str,
+        context_dir: Optional[str] = None,
+    ) -> str:
+        """Validate a Dockerfile and return a ``template:`` reference for
+        :meth:`start_container`.
+
+        Eagerly validates the Dockerfile (existence, COPY sources) and stores
+        the rewritten content in an internal registry. The Novita template is
+        built later, inside ``start_container``, by the adapter's
+        ``build_template`` — building needs credentials and network, which this
+        class-level helper deliberately does not.
+
+        The rewrite compensates for Novita's Dockerfile parser, which rejects
+        multi-stage build definitions (the layout every in-repo OpenEnv
+        environment uses). BuildKit ``--mount`` flags are stripped, ``ARG`` and
+        ``--platform`` in ``FROM`` lines are resolved, and a two-stage build
+        whose stages share one base image is replayed as a single stage.
+
+        Args:
+            dockerfile_path (`str`):
+                Path to the Dockerfile on disk.
+            context_dir (`str`, *optional*):
+                Build context directory, used to resolve relative ``COPY``
+                sources. 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>/`.
+
+        Returns:
+            `str`: A `"template:<abs_path>"` reference to pass to
+            `start_container` or the constructor's `image`.
+
+        Raises:
+            FileNotFoundError: If *dockerfile_path* does not exist.
+            ValueError: If *context_dir* does not exist, if COPY sources cannot
+                be found under the resolved context directory, or if the
+                Dockerfile cannot be expressed as a Novita template (see
+                `_prepare_dockerfile`).
+
+        Examples:
+
+        ```python
+        image = NovitaSandboxProvider.image_from_dockerfile(
+            "envs/echo_env/server/Dockerfile"
+        )
+        provider = NovitaSandboxProvider(image=image)
+        base_url = provider.start_container()
+        ```
+        """
+        import pathlib
+
+        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
+
+        prepared = _prepare_dockerfile(src.read_text())
+
+        # Validate that COPY sources exist under the context directory. This
+        # catches mismatches early (e.g. a Dockerfile expecting the repo root as
+        # context when we defaulted to the env directory).
+        for line in prepared.splitlines():
+            match = re.match(r"^\s*COPY\s+(?!--from=)(\S+)\s+", line, re.IGNORECASE)
+            if not match:
+                continue
+            copy_src = match.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 under "
+                    f"context_dir '{ctx}'. This Dockerfile may expect a "
+                    "different build context (e.g. the repo root). Pass "
+                    "context_dir explicitly."
+                )
+
+        cls._dockerfile_registry[str(src)] = {
+            "content": prepared,
+            "context_dir": str(ctx),
+        }
+
+        return f"template:{src}"
+
+    def _resolve_template_ref(self, reference: str) -> str:
+        """Build the template for a ``template:<path>`` reference; return its id."""
+        path = reference[len("template:") :]
+        meta = self._dockerfile_registry.get(path)
+        if meta is None:
+            raise ValueError(
+                f"No registered Dockerfile metadata for {path}. Call "
+                "NovitaSandboxProvider.image_from_dockerfile() first."
+            )
+
+        return self._adapter.build_template(
+            dockerfile_content=meta["content"],
+            context_dir=meta["context_dir"],
+            name=self._template_name or self._default_template_name(path),
+            cpu_count=self._cpu_count,
+            memory_mb=self._memory_mb,
+            on_build_logs=self._on_build_logs,
+        )
+
+    @staticmethod
+    def _default_template_name(dockerfile_path: str) -> str:
+        """Derive a stable template name from the Dockerfile's env directory.
+
+        The env directory keeps the template recognizable in the Novita
+        dashboard; the content hash keeps two different Dockerfiles from
+        colliding on one name, while a rebuild of identical content still hits
+        the build cache.
+        """
+        import hashlib
+        import pathlib
+
+        src = pathlib.Path(dockerfile_path)
+        env_dir = src.parent.parent.name or src.parent.name
+        slug = re.sub(r"[^a-z0-9-]+", "-", env_dir.lower().replace("_", "-"))
+        digest = hashlib.sha256(src.read_bytes()).hexdigest()[:8]
+        return f"openenv-{slug.strip('-')}-{digest}"
+
+    def __init__(
+        self,
+        *,
+        image: Optional[str] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        api_key: Optional[str] = None,
+        domain: Optional[str] = None,
+        timeout: int = _DEFAULT_SANDBOX_TIMEOUT_S,
+        metadata: Optional[Dict[str, str]] = None,
+        secure: Optional[bool] = None,
+        cmd: Optional[str] = None,
+        working_directory: Optional[str] = None,
+        surface_server_logs: bool = False,
+        cpu_count: int = _DEFAULT_TEMPLATE_CPU,
+        memory_mb: int = _DEFAULT_TEMPLATE_MEMORY_MB,
+        template_name: Optional[str] = None,
+        on_build_logs: Optional[Callable[[Any], None]] = None,
+        _adapter: Any = None,
+    ):
+        """
+        Args:
+            image (`str`, *optional*):
+                Registry image reference (e.g. `"ghcr.io/org/env:latest"`) or a
+                `"template:<id>"` reference from
+                [`~image_from_dockerfile`], to use when `start_container()` is
+                called without an image.
+            env_vars (`dict`, *optional*):
+                Environment variables to use when `start_container()` is called
+                without explicit `env_vars`.
+            api_key (`str`, *optional*):
+                Novita API key. Falls back to the `NOVITA_API_KEY` environment
+                variable.
+            domain (`str`, *optional*):
+                Novita region domain. Falls back to the `NOVITA_DOMAIN`
+                environment variable, then to the SDK default (`us-phx-1`).
+                Features marked modern-domain-only (snapshots, secrets) are
+                unavailable on the legacy `us-virginia-1` domain.
+            timeout (`int`, *optional*, defaults to `3600`):
+                Hard sandbox lifetime in seconds. Counts down from creation
+                regardless of activity and always fires, so it must exceed the
+                longest expected episode.
+            metadata (`dict`, *optional*):
+                Arbitrary key/value labels on the sandbox. The `idle_timeout`
+                key is meaningful to Novita and takes seconds as a **string**
+                (e.g. `{"idle_timeout": "900"}`); omitting it disables the idle
+                timer, which is the conservative default for RL rollouts — an
+                automatic transition can drop a live WebSocket mid-episode
+                (RFC 002 invariant 6).
+            secure (`bool`, *optional*):
+                Whether envd requires its access token. `None` uses the SDK
+                default (secured on modern domains). This governs the sandbox
+                control plane, not the exposed server port.
+            cmd (`str`, *optional*):
+                Shell command to start the server inside the sandbox. When
+                omitted, the command is auto-discovered from `openenv.yaml`.
+            working_directory (`str`, *optional*):
+                Directory to `cd` into before running `cmd`.
+            surface_server_logs (`bool`, *optional*, defaults to `False`):
+                When `False` (default), captured sandbox output is withheld from
+                raised errors so secrets the workload printed cannot leak into
+                orchestrator/CI logs. When `True`, a best-effort redacted,
+                length-bounded excerpt is included in startup-crash errors (S4).
+            cpu_count (`int`, *optional*, defaults to `2`):
+                vCPU cores for sandboxes built from a Dockerfile via
+                [`~image_from_dockerfile`]. Ignored for registry images, whose
+                resources come from the image's own template.
+            memory_mb (`int`, *optional*, defaults to `1024`):
+                Memory in MiB for sandboxes built from a Dockerfile. Ignored for
+                registry images.
+            template_name (`str`, *optional*):
+                Template name to register when building from a Dockerfile.
+                Defaults to a name derived from the Dockerfile's directory plus a
+                content hash, so re-running with the same Dockerfile reuses the
+                build cache.
+            on_build_logs (`Callable`, *optional*):
+                Callback receiving build-log entries while a Dockerfile template
+                is built. Off by default: build logs are not redacted, so they
+                are withheld rather than printed (RFC 002 S4). Pass a callable to
+                surface them.
+            _adapter (`Any`, *optional*):
+                Injection seam for tests; a duck-typed fake replaces the SDK.
+        """
+        self._image = image
+        self._env_vars = env_vars
+        self._timeout = timeout
+        self._metadata = metadata
+        self._secure = secure
+        self._cmd = cmd
+        self._working_directory = working_directory
+        self.surface_server_logs = surface_server_logs
+        self._cpu_count = cpu_count
+        self._memory_mb = memory_mb
+        self._template_name = template_name
+        self._on_build_logs = on_build_logs
+
+        self._sandbox: Any = None
+        self._base_url: Optional[str] = None
+        self._server_user: Optional[str] = None
+        # Injected env-var values, used to scrub captured server output before
+        # it is ever surfaced in an error.
+        self._redact_values: set[str] = set()
+
+        if _adapter is None:
+            # Build the client eagerly so credential/region problems surface at
+            # construction rather than mid-episode, matching ModalProvider.
+            self._adapter: Any = _DefaultNovitaAdapter(api_key=api_key, domain=domain)
+        else:
+            self._adapter = _adapter
+
+    def _discover_server_cmd(self, port: int = _DEFAULT_NOVITA_PORT) -> str:
+        """Discover the server command from ``openenv.yaml`` inside the 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()
+        if yaml_path is None:
+            raise ValueError(
+                "Could not find openenv.yaml inside the sandbox. Pass an "
+                "explicit cmd= to NovitaSandboxProvider or start_container()."
+            )
+
+        content = self._adapter.exec(self._sandbox, f"cat {shlex.quote(yaml_path)}")
+        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 NovitaSandboxProvider 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) -> 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
+        out = self._adapter.exec(
+            self._sandbox, "test -f /app/env/openenv.yaml && echo found"
+        )
+        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).
+        path = self._adapter.exec(
+            self._sandbox,
+            "find /app -maxdepth 4 -name openenv.yaml -print -quit 2>/dev/null",
+        ).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.
+        """
+        return parse_openenv_app_field(yaml_content)
+
+    def start_container(
+        self,
+        image: Optional[str] = None,
+        port: Optional[int] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> str:
+        """
+        Create a Novita sandbox and start an OpenEnv server inside it.
+
+        Args:
+            image (`str`, *optional*):
+                Either a registry image reference (e.g.
+                `"ghcr.io/org/env:latest"`) or a `"template:<path>"` reference
+                returned by [`~image_from_dockerfile`]. May be omitted when
+                supplied to the constructor.
+            port (`int`, *optional*):
+                Must be `None` or `8000`. Novita exposes port 8000 on the
+                sandbox host; other ports raise `ValueError`.
+            env_vars (`dict`, *optional*):
+                Environment variables forwarded to the sandbox, overriding the
+                constructor's.
+            **kwargs:
+                `cmd` (`str`) to override the server command. For a registry
+                OCI image, pass the command explicitly together with any
+                runtime environment the image needs: Novita may not be able to
+                restore the image's ``ENV`` while converting it to a template.
+                For example, the tbench2 image requires:
+
+                ``cmd="cd /app/env && PYTHONPATH=/app/env "
+                "/app/.venv/bin/python -m uvicorn server.app:app "
+                "--host 0.0.0.0 --port 8000"``
+
+                and any additional values can be supplied through
+                ``env_vars``. The provider runs this command as ``root`` for a
+                registry image; a ``template:<id>`` keeps the template's
+                configured user. Prefer
+                ``NovitaSandboxProvider.image_from_dockerfile(...)`` when a
+                local Dockerfile is available; its build preserves the
+                environment and startup configuration in the generated
+                template. Unknown options raise `ValueError` so typos cannot
+                silently change sandbox behavior.
+
+        Returns:
+            `str`: HTTPS sandbox URL for the exposed port (base_url).
+
+        Raises:
+            RuntimeError: If a sandbox is already active on this provider.
+            ValueError: If no image is available, the port is unsupported, or an
+                unknown option is passed.
+        """
+        if self._sandbox is not None:
+            raise RuntimeError(
+                "NovitaSandboxProvider already has an active sandbox. Call "
+                "stop_container() (or close()) before starting another — a "
+                "second start would orphan the running sandbox."
+            )
+
+        if port is not None and port != _DEFAULT_NOVITA_PORT:
+            raise ValueError(
+                f"NovitaSandboxProvider only supports port {_DEFAULT_NOVITA_PORT} "
+                f"(got {port}). The sandbox host routes to port "
+                f"{_DEFAULT_NOVITA_PORT} inside the sandbox."
+            )
+
+        effective_image = image if image is not None else self._image
+        if effective_image is None:
+            raise ValueError(
+                "NovitaSandboxProvider requires an image. Pass it to the "
+                "constructor or start_container()."
+            )
+        effective_env_vars = self._env_vars if env_vars is None else env_vars
+
+        cmd = kwargs.pop("cmd", None) or self._cmd
+        # `AutoEnv.from_env()` forwards this unconditionally (default 30.0) via
+        # `from_docker_image` -> `_bootstrap_container`, so rejecting it would
+        # make the entire AutoEnv path unusable for this provider. It is
+        # meaningless here: `_bootstrap_container` calls `wait_for_ready(base_url)`
+        # without a timeout, so no provider ever sees the value. Accept and drop
+        # it rather than fail; unknown options still raise, so a typo cannot
+        # silently change sandbox behavior.
+        kwargs.pop("wait_timeout", None)
+        if kwargs:
+            unknown = ", ".join(sorted(kwargs))
+            raise ValueError(
+                f"Unsupported NovitaSandboxProvider start options: {unknown}"
+            )
+
+        # A "template:<path>" reference builds a Novita template from a local
+        # Dockerfile; anything else is a registry image the SDK resolves itself.
+        # The build runs before `create_sandbox` so a build failure never leaves
+        # a sandbox behind, and outside the `_redact_values` window below so its
+        # recorded secrets do not outlive a failed build.
+        if effective_image.startswith("template:"):
+            template_id: Optional[str] = self._resolve_template_ref(effective_image)
+            sandbox_image: Optional[str] = None
+        else:
+            template_id = None
+            sandbox_image = effective_image
+
+        # Record injected secret values so captured server output can be scrubbed
+        # before it is ever surfaced in an error (security invariant S4).
+        self._redact_values = {
+            value for value in (effective_env_vars or {}).values() if value
+        }
+
+        # A create failure created nothing, so just drop the recorded secrets and
+        # re-raise (the single-sandbox guard above guarantees there is no
+        # pre-existing sandbox to delete).
+        try:
+            self._sandbox = self._adapter.create_sandbox(
+                image=sandbox_image,
+                template=template_id,
+                env_vars=effective_env_vars,
+                timeout=self._timeout,
+                metadata=self._metadata,
+                secure=self._secure,
+            )
+        except Exception:
+            self._redact_values = set()
+            raise
+
+        try:
+            # Discovery runs after creation, when the filesystem can be read.
+            if cmd is None:
+                cmd = self._discover_server_cmd()
+
+            # Registry images can lose their Dockerfile USER/ownership settings
+            # while Novita converts them to a cached OCI template. Run the
+            # provider-managed server command as root for that path. A template
+            # keeps its configured user, including an explicit non-root USER.
+            self._server_user = _SANDBOX_USER if sandbox_image is not None else None
+            self._launch_server(
+                cmd,
+                user=self._server_user,
+            )
+            host = _require_bare_host(
+                self._adapter.host(self._sandbox, _DEFAULT_NOVITA_PORT)
+            )
+            self._base_url = _require_secure_url(f"https://{host}")
+        except Exception:
+            # A cleanup failure here must not mask the original error: swallow
+            # any exception from stop_container() so the root cause propagates.
+            try:
+                self.stop_container()
+            except Exception:
+                pass
+            raise
+
+        return self._base_url
+
+    def _launch_server(self, cmd: str, *, user: Optional[str] = None) -> None:
+        """Start the OpenEnv server inside the sandbox as a background process.
+
+        This is the one place the provider assumes something about the image, so
+        it is kept to a single method.
+
+        The server is launched through the SDK's background command support and
+        its PID is written to ``/tmp/openenv-server.pid``, so ``wait_for_ready``
+        can tell "still booting" apart from "crashed" instead of waiting out
+        the full timeout.
+        The sandbox was created with a ``sleep infinity`` start command rather
+        than the image's own CMD (see ``_DefaultNovitaAdapter.create_sandbox``),
+        which is what leaves port 8000 free for this process.
+
+        An alternative is to let the platform own it: pass the server command as
+        the template's start command via the SDK's ``build={"cmd": ...}`` and
+        drop this method. That trades the PID-based crash detection
+        below for platform-managed lifecycle and readiness. It is not the
+        default because a start command can only be set when the image is first
+        resolved into a template, so it would not apply to an already-cached
+        image.
+
+        ``cmd`` is trusted orchestrator configuration, not agent or environment
+        input — callers must not pass agent-controlled text, and any dynamic
+        value interpolated into it must be quoted by the caller (S5). The
+        sandbox SDK runs commands as ``/bin/bash -l -c <command>``; the command
+        itself owns the PID file and log redirection while ``background=True``
+        keeps the remote process alive after this call.
+        """
+        if self._working_directory:
+            command = f"cd {shlex.quote(self._working_directory)} && {cmd}"
+        else:
+            command = cmd
+
+        launch_command = (
+            "echo $$ > /tmp/openenv-server.pid; "
+            f"exec sh -c {shlex.quote(command)} "
+            "> /tmp/openenv-server.log 2>&1"
+        )
+        escaped = shlex.quote(launch_command)
+        self._adapter.exec(
+            self._sandbox,
+            f"sh -c {escaped}",
+            timeout=0,
+            background=True,
+            user=user,
+        )
+
+    def stop_container(self) -> None:
+        """Kill the active Novita sandbox.
+
+        `kill()` permanently removes the sandbox: it cannot be resumed or
+        reconnected, and any snapshot must have been taken beforehand.
+        """
+        if self._sandbox is None:
+            # Still drop any injected secret values recorded by a failed start.
+            self._redact_values = set()
+            return
+
+        sandbox = self._sandbox
+        try:
+            self._adapter.kill(sandbox)
+        finally:
+            self._sandbox = None
+            self._base_url = None
+            self._server_user = None
+            self._redact_values = set()
+
+    def close(self) -> None:
+        """Stop the active sandbox and release provider-held resources.
+
+        Overrides the base no-op so a caller holding a bare `ContainerProvider`
+        reference can release the sandbox polymorphically (also invoked on
+        context-manager exit). The Novita client is stateless HTTP per call, so
+        this is equivalent to `stop_container()`.
+        """
+        self.stop_container()
+
+    @property
+    def base_url(self) -> str:
+        """URL returned by the last `start_container`."""
+        if self._base_url is None:
+            raise RuntimeError(
+                "NovitaSandboxProvider has no active base_url. Start the "
+                "provider before reading base_url."
+            )
+        return self._base_url
+
+    def _redact(self, text: str, *, max_chars: int = 2000) -> str:
+        """Scrub injected secret values and bound length before surfacing output.
+
+        Replaces any injected env-var value with `***` and keeps only the tail.
+        This is best-effort (exact-match only), which is why server output is
+        withheld entirely unless `surface_server_logs=True` (RFC 002 S4).
+        """
+        redacted = text or ""
+        for value in self._redact_values:
+            redacted = redacted.replace(value, "***")
+        if len(redacted) > max_chars:
+            redacted = "...(truncated)...\n" + redacted[-max_chars:]
+        return redacted
+
+    def _server_died_message(self) -> str:
+        """Build the startup-crash error, secure by default (RFC 002 S4).
+
+        Untrusted code can print secrets then force a crash to exfiltrate them
+        through the exception (which lands in orchestrator/CI logs), so sandbox
+        output is excluded unless `surface_server_logs=True`, in which case a
+        best-effort redacted, bounded excerpt is included.
+        """
+        base = (
+            "Novita sandbox server process died during startup. Server output is "
+            "not surfaced to avoid leaking secrets injected into the sandbox; "
+            "retrieve /tmp/openenv-server.log from the sandbox out of band, or "
+            "construct the provider with surface_server_logs=True to include a "
+            "redacted excerpt."
+        )
+        if not self.surface_server_logs:
+            return base
+        if self._sandbox is None:
+            return base
+
+        log = self._redact(
+            self._adapter.exec(
+                self._sandbox,
+                "cat /tmp/openenv-server.log 2>/dev/null",
+                user=self._server_user,
+            )
+        )
+        return (
+            "Novita sandbox server process died during startup. The excerpt below "
+            "is the sandbox server output with injected secret values redacted "
+            "(best-effort); it may still contain secrets the workload printed "
+            f"by other means.\nLog (redacted):\n{log}"
+        )
+
+    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 local Docker providers because
+        a Novita sandbox is created from an image that may need to be resolved
+        and built on first use.
+
+        A `200` on `/health` proves HTTP reachability but **not** that the
+        exposed sandbox host proxies the `/ws` WebSocket upgrade `EnvClient`
+        needs; that requires a real `wss://` round-trip (RFC 002 invariant 2).
+
+        Args:
+            base_url (`str`):
+                Sandbox URL returned by `start_container()`.
+            timeout_s (`float`, *optional*, defaults to `120.0`):
+                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).
+        """
+        # Imported lazily inside the method that needs it, matching the other
+        # providers in this package (e.g. DaytonaProvider).
+        import requests
+
+        deadline = time.time() + timeout_s
+        health_url = f"{base_url}/health"
+
+        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:
+                out = self._adapter.exec(
+                    self._sandbox,
+                    "if test -s /tmp/openenv-server.pid; then "
+                    "kill -0 $(cat /tmp/openenv-server.pid) 2>/dev/null "
+                    "&& echo RUNNING || echo DEAD; "
+                    "else echo STARTING; fi",
+                    user=self._server_user,
+                )
+                if "DEAD" in (out or ""):
+                    raise RuntimeError(self._server_died_message())
+
+            time.sleep(1.0)
+
+        raise TimeoutError(f"Novita sandbox did not become ready within {timeout_s}s.")
+
+
+__all__ = ["NovitaSandboxProvider"]

src/core/containers/runtime/providers.py

@@ -0,0 +1,727 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+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 EnvClient.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, Sequence, TypeVar
+
+_ContainerProviderT = TypeVar("_ContainerProviderT", bound="ContainerProvider")
+
+
+class ContainerProvider(ABC):
+    """
+    Abstract base class for container providers.
+
+    Providers implement this interface to support different container platforms:
+    - LocalDockerProvider: Runs containers on local Docker daemon
+    - KubernetesProvider: Runs containers in Kubernetes cluster
+    - FargateProvider: Runs containers on AWS Fargate
+    - CloudRunProvider: Runs containers on Google Cloud Run
+
+    The provider manages a single container lifecycle and provides the base URL
+    for connecting to it.
+
+    Examples:
+
+        ```python
+        provider = LocalDockerProvider()
+        base_url = provider.start_container("echo-env:latest")
+        print(base_url)  # http://localhost:8000
+        # Use the environment via base_url
+        provider.stop_container()
+        ```
+    """
+
+    @abstractmethod
+    def start_container(
+        self,
+        image: str,
+        port: Optional[int] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> str:
+        """
+        Start a container from the specified image.
+
+        Args:
+            image (`str`):
+                Provider-specific container *source* identifier. For
+                container-based providers this is a registry image name (e.g.
+                `"echo-env:latest"`); other providers may map it to a
+                provider-specific source (see the provider's documentation).
+            port (`int`, *optional*):
+                Port to expose. If `None`, the provider chooses.
+            env_vars (`dict`, *optional*):
+                Environment variables to pass to container.
+            **kwargs:
+                Provider-specific options.
+
+        Returns:
+            `str`: Base URL to connect to the container (e.g., `"http://localhost:8000"`).
+
+        Raises:
+            RuntimeError: If container fails to start.
+        """
+        pass
+
+    @abstractmethod
+    def stop_container(self) -> None:
+        """
+        Stop and remove the running container.
+
+        This cleans up the container that was started by start_container().
+        """
+        pass
+
+    @abstractmethod
+    def wait_for_ready(self, base_url: str, timeout_s: float = 30.0) -> None:
+        """
+        Wait for the container to be ready to accept requests.
+
+        This typically polls the /health endpoint until it returns 200.
+
+        Args:
+            base_url (`str`):
+                Base URL of the container.
+            timeout_s (`float`, *optional*, defaults to `30.0`):
+                Maximum time to wait in seconds.
+
+        Raises:
+            TimeoutError: If container doesn't become ready in time.
+        """
+        pass
+
+    def close(self) -> None:
+        """
+        Release provider-held resources (e.g. SDK clients, connections).
+
+        Defaults to a no-op so existing providers are unaffected. Providers that
+        hold external resources beyond the container itself (such as a cloud SDK
+        client) override this to release them; it is also invoked on context-
+        manager exit. Lightweight providers need not override it.
+        """
+        pass
+
+    def __enter__(self: _ContainerProviderT) -> _ContainerProviderT:
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> Optional[bool]:
+        self.close()
+        return None
+
+
+class LocalDockerProvider(ContainerProvider):
+    """
+    Container provider for local Docker daemon.
+
+    This provider runs containers on the local machine using Docker.
+    Useful for development and testing.
+
+    Examples:
+
+        ```python
+        provider = LocalDockerProvider()
+        base_url = provider.start_container("echo-env:latest")
+        # Container running on http://localhost:<random-port>
+        provider.stop_container()
+        ```
+    """
+
+    def __init__(self):
+        """Initialize the local Docker provider."""
+        self._container_id: Optional[str] = None
+        self._container_name: Optional[str] = None
+
+        # Check if Docker is available
+        import subprocess
+
+        try:
+            subprocess.run(
+                ["docker", "version"],
+                check=True,
+                capture_output=True,
+                timeout=5,
+            )
+        except (
+            subprocess.CalledProcessError,
+            FileNotFoundError,
+            subprocess.TimeoutExpired,
+        ):
+            raise RuntimeError(
+                "Docker is not available. Please install Docker Desktop or Docker Engine."
+            )
+
+    def start_container(
+        self,
+        image: str,
+        port: Optional[int] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> str:
+        """
+        Start a Docker container locally.
+
+        Args:
+            image (`str`):
+                Docker image name.
+            port (`int`, *optional*):
+                Port to expose. If `None`, finds an available port.
+            env_vars (`dict`, *optional*):
+                Environment variables for the container.
+            **kwargs:
+                Additional Docker run options.
+
+        Returns:
+            `str`: Base URL to connect to the container.
+        """
+        import subprocess
+        import time
+
+        # Find available port if not specified
+        if port is None:
+            port = self._find_available_port()
+
+        # Generate container name
+        self._container_name = self._generate_container_name(image)
+
+        # Build docker run command
+        cmd = [
+            "docker",
+            "run",
+            "-d",  # Detached
+            "--name",
+            self._container_name,
+            "-p",
+            f"{port}:8000",  # Map port
+        ]
+
+        # Add environment variables
+        if env_vars:
+            for key, value in env_vars.items():
+                cmd.extend(["-e", f"{key}={value}"])
+
+        # Add image
+        cmd.append(image)
+
+        # Run container
+        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)
+
+        base_url = f"http://localhost:{port}"
+        return base_url
+
+    def stop_container(self) -> None:
+        """
+        Stop and remove the Docker container.
+        """
+        if self._container_id is None:
+            return
+
+        import subprocess
+
+        try:
+            # Stop container
+            subprocess.run(
+                ["docker", "stop", self._container_id],
+                capture_output=True,
+                check=True,
+                timeout=10,
+            )
+
+            # Remove container
+            subprocess.run(
+                ["docker", "rm", self._container_id],
+                capture_output=True,
+                check=True,
+                timeout=10,
+            )
+        except subprocess.CalledProcessError:
+            # Container might already be stopped/removed
+            pass
+        finally:
+            self._container_id = None
+            self._container_name = None
+
+    def wait_for_ready(self, base_url: str, timeout_s: float = 30.0) -> None:
+        """
+        Wait for container to be ready by polling /health endpoint.
+
+        Args:
+            base_url (`str`):
+                Base URL of the container.
+            timeout_s (`float`, *optional*, defaults to `30.0`):
+                Maximum time to wait in seconds.
+
+        Raises:
+            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, proxies=proxies)
+                if response.status_code == 200:
+                    return
+            except requests.RequestException:
+                pass
+
+            time.sleep(0.5)
+
+        raise TimeoutError(
+            f"Container at {base_url} did not become ready within {timeout_s}s"
+        )
+
+    def _find_available_port(self) -> int:
+        """
+        Find an available port on localhost.
+
+        Returns:
+            `int`: An available port number.
+        """
+        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_container_name(self, image: str) -> str:
+        """
+        Generate a unique container name based on image name and timestamp.
+
+        Args:
+            image (`str`):
+                Docker image name.
+
+        Returns:
+            `str`: A unique container name.
+        """
+        import time
+
+        clean_image = image.split("/")[-1].split(":")[0]
+        timestamp = int(time.time() * 1000)
+        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 (`bool`, *optional*, defaults to `True`):
+                Whether to call `docker swarm init` when Swarm is not active.
+                Otherwise, the user must manually initialize Swarm.
+            overlay_network (`str`, *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.
+
+        Args:
+            image (`str`):
+                Docker image name.
+            port (`int`, *optional*):
+                Port to expose. If `None`, finds an available port.
+            env_vars (`dict`, *optional*):
+                Environment variables for the container.
+            replicas (`int`, *optional*, defaults to `2`):
+                Number of container replicas.
+            cpu_limit (`float` or `str`, *optional*):
+                CPU limit passed to `--limit-cpu`.
+            memory_limit (`str`, *optional*):
+                Memory limit passed to `--limit-memory`.
+            constraints (`Sequence[str]`, *optional*):
+                Placement constraints.
+            labels (`dict`, *optional*):
+                Service labels.
+            command (`Sequence[str]` or `str`, *optional*):
+                Override container command.
+
+        Returns:
+            `str`: Base URL to connect to the service.
+        """
+        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.
+
+        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):
+    """
+    Planned container provider for Kubernetes clusters.
+
+    Not yet implemented: this is a placeholder for the planned Kubernetes
+    backend and does not implement the abstract `ContainerProvider` methods, so
+    it cannot be instantiated. Use `LocalDockerProvider`, `DockerSwarmProvider`,
+    `DaytonaProvider`, or `ACASandboxProvider` instead.
+    """
+
+    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.
+
+    Examples:
+
+        ```python
+        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 the runtime.
+
+        Args:
+            port (`int`, *optional*):
+                Port to expose. If `None`, the provider chooses.
+            env_vars (`dict`, *optional*):
+                Environment variables for the runtime.
+            **kwargs:
+                Additional runtime options.
+
+        Returns:
+            `str`: Base URL to connect to the runtime.
+        """
+
+    @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,309 @@
+"""Providers for launching ASGI applications via ``uv run``."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import socket
+import subprocess
+import tempfile
+import time
+from typing import Dict, Optional
+
+import requests
+
+from .providers import RuntimeProvider
+
+GIT_URL_PREFIX = "git+"
+
+
+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 _clone_git_project(git_url: str, timeout_s: float) -> str:
+    """Clone a `git+<url>` spec to a temp dir and return its local path.
+
+    `uv run --project` only discovers a project in a local directory (per
+    `uv run --help`) -- it has no support for remote git sources. Callers
+    that accept a `git+...` `project_path` (e.g. `EnvClient.from_env`)
+    must therefore clone it themselves before handing a path to `uv run`.
+    """
+    repo_url = git_url[len(GIT_URL_PREFIX) :]
+    clone_dir = tempfile.mkdtemp(prefix="openenv-uv-clone-")
+    try:
+        subprocess.run(
+            ["git", "clone", "--depth", "1", repo_url, clone_dir],
+            check=True,
+            capture_output=True,
+            text=True,
+            # A hung/slow remote would otherwise block start() (and the
+            # caller's own readiness timeout) indefinitely.
+            timeout=timeout_s,
+        )
+    except FileNotFoundError as exc:
+        shutil.rmtree(clone_dir, ignore_errors=True)
+        raise RuntimeError(
+            f"`git` executable not found; required to clone project_path {git_url!r}."
+        ) from exc
+    except subprocess.CalledProcessError as exc:
+        shutil.rmtree(clone_dir, ignore_errors=True)
+        raise RuntimeError(f"Failed to clone {repo_url!r}: {exc.stderr}") from exc
+    except subprocess.TimeoutExpired as exc:
+        shutil.rmtree(clone_dir, ignore_errors=True)
+        raise RuntimeError(
+            f"Timed out cloning {repo_url!r} after {timeout_s:.1f}s"
+        ) from exc
+    return clone_dir
+
+
+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:
+            # Server not accepting connections yet. Fall through to the sleep
+            # below rather than `continue`-ing: a refused connection returns
+            # immediately, so retrying without a pause busy-spins a CPU core
+            # for the whole timeout window while the server boots.
+            pass
+
+        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 (`str`):
+            Local path to a uv project (passed to `uv run --project`), or a
+            `git+<url>` spec that is cloned to a temp directory on `start()`.
+        app (`str`, *optional*, defaults to `"server.app:app"`):
+            ASGI application path for uvicorn.
+        host (`str`, *optional*, defaults to `"0.0.0.0"`):
+            Host interface to bind to.
+        reload (`bool`, *optional*, defaults to `False`):
+            Whether to enable uvicorn's reload mode.
+        env_vars (`dict`, *optional*):
+            Environment variables to pass through to the spawned process.
+        context_timeout_s (`float`, *optional*, defaults to `60.0`):
+            How long to wait for the environment to become ready.
+
+    Examples:
+
+        ```python
+        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."""
+        # `os.path.abspath` would mangle a `git+<url>` spec (e.g. collapsing
+        # `https://` to `https:/`) and is meaningless for one anyway -- only
+        # resolve it for genuine local paths. Git specs are cloned in `start()`.
+        self.project_path = (
+            project_path
+            if project_path.startswith(GIT_URL_PREFIX)
+            else 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
+        self._clone_dir: Optional[str] = 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 (`int`, *optional*):
+                The port to bind the environment to.
+            env_vars (`dict`, *optional*):
+                Environment variables to pass to the environment.
+            workers (`int`, *optional*, defaults to `1`):
+                The number of workers to use.
+
+        Returns:
+            `str`: 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()
+
+        # A previous start() may have left a clone dir behind if the spawned
+        # process later died on its own -- the "already running" guard above
+        # only checks liveness, so a restart in that state would otherwise
+        # overwrite self._clone_dir and leak the old directory.
+        if self._clone_dir is not None:
+            shutil.rmtree(self._clone_dir, ignore_errors=True)
+            self._clone_dir = None
+
+        project_path = self.project_path
+        if project_path.startswith(GIT_URL_PREFIX):
+            self._clone_dir = _clone_git_project(project_path, self.context_timeout_s)
+            project_path = self._clone_dir
+
+        command = _create_uv_command(
+            host=self.host,
+            port=bind_port,
+            reload=self.reload,
+            workers=workers,
+            app=self.app,
+            project_path=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:
+            if self._clone_dir is not None:
+                shutil.rmtree(self._clone_dir, ignore_errors=True)
+                self._clone_dir = None
+            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 | None = None) -> None:
+        """
+        Wait for the environment to become ready.
+
+        Args:
+            timeout_s (`float`, *optional*):
+                Maximum time in seconds to wait for the environment to become
+                ready. Defaults to the provider's `context_timeout_s`.
+
+        Raises:
+            RuntimeError: If the environment is not running.
+            TimeoutError: If the environment does not become ready within the timeout.
+        """
+        if timeout_s is None:
+            timeout_s = self.context_timeout_s
+
+        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.
+        """
+        if self._process is not None:
+            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
+
+        if self._clone_dir is not None:
+            shutil.rmtree(self._clone_dir, ignore_errors=True)
+            self._clone_dir = None
+
+    @property
+    def base_url(self) -> str:
+        """
+        The base URL of the environment.
+
+        Returns:
+            `str`: Base URL of the running environment.
+
+        Raises:
+            RuntimeError: If the environment has not been started.
+        """
+        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

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""
+End-to-end test for LocalDockerProvider.
+
+This script tests the complete flow:
+1. Start a container using LocalDockerProvider
+2. Wait for it to be ready
+3. Make HTTP requests to test the environment
+4. Clean up the container
+"""
+
+import sys
+from pathlib import Path
+
+# Add src to path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+import requests
+from openenv.core.containers.runtime import LocalDockerProvider
+
+
+# TODO: Remove this test or make it a functional test since this will be tested in e2e test for echo env
+def test_local_docker_provider():
+    """Test LocalDockerProvider end-to-end."""
+    print("=" * 60)
+    print("LocalDockerProvider End-to-End Test")
+    print("=" * 60)
+    print()
+
+    provider = None
+
+    try:
+        # Step 1: Create provider
+        print("Step 1: Creating LocalDockerProvider...")
+        provider = LocalDockerProvider()
+        print("✓ Provider created\n")
+
+        # Step 2: Start container
+        print("Step 2: Starting echo-env container...")
+        base_url = provider.start_container("echo-env:latest")
+        print(f"✓ Container started at: {base_url}")
+        if provider._container_id:
+            print(f"  Container ID: {provider._container_id[:12]}...")
+        if provider._container_name:
+            print(f"  Container name: {provider._container_name}\n")
+
+        # Step 3: Wait for ready
+        print("Step 3: Waiting for container to be ready...")
+        provider.wait_for_ready(base_url, timeout_s=30.0)
+        print("✓ Container is ready!\n")
+
+        # Step 4: Test health endpoint
+        print("Step 4: Testing /health endpoint...")
+        response = requests.get(f"{base_url}/health")
+        print(f"  Status: {response.status_code}")
+        print(f"  Response: {response.json()}")
+        assert response.status_code == 200
+        assert response.json()["status"] == "healthy"
+        print("✓ Health check passed\n")
+
+        # Step 5: Test reset endpoint
+        print("Step 5: Testing /reset endpoint...")
+        response = requests.post(
+            f"{base_url}/reset",
+            json={},
+            headers={"Content-Type": "application/json"},
+        )
+        print(f"  Status: {response.status_code}")
+        data = response.json()
+        print(f"  Message: {data['observation']['echoed_message']}")
+        print(f"  Reward: {data['reward']}")
+        print(f"  Done: {data['done']}")
+        assert response.status_code == 200
+        assert data["observation"]["echoed_message"] == "Echo environment ready!"
+        print("✓ Reset test passed\n")
+
+        # Step 6: Test step endpoint
+        print("Step 6: Testing /step endpoint...")
+        response = requests.post(
+            f"{base_url}/step",
+            json={"action": {"message": "Hello from LocalDockerProvider!"}},
+            headers={"Content-Type": "application/json"},
+        )
+        print(f"  Status: {response.status_code}")
+        data = response.json()
+        print(f"  Echoed: {data['observation']['echoed_message']}")
+        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"]["message_length"] == 31
+        print("✓ Step test passed\n")
+
+        # Step 7: Test state endpoint
+        print("Step 7: Testing /state endpoint...")
+        response = requests.get(f"{base_url}/state")
+        print(f"  Status: {response.status_code}")
+        data = response.json()
+        print(f"  Episode ID: {data['episode_id']}")
+        print(f"  Step count: {data['step_count']}")
+        assert response.status_code == 200
+        assert data["step_count"] == 1  # One step from above
+        print("✓ State test passed\n")
+
+        # Step 8: Multiple steps
+        print("Step 8: Testing multiple steps...")
+        for i in range(3):
+            response = requests.post(
+                f"{base_url}/step",
+                json={"action": {"message": f"Message {i + 1}"}},
+                headers={"Content-Type": "application/json"},
+            )
+            assert response.status_code == 200
+            print(f"  Step {i + 1}: ✓")
+
+        # Check state updated
+        response = requests.get(f"{base_url}/state")
+        data = response.json()
+        assert data["step_count"] == 4  # 1 + 3 more steps
+        print(f"  Final step count: {data['step_count']}")
+        print("✓ Multiple steps test passed\n")
+
+        print("=" * 60)
+        print("✓ All tests passed!")
+        print("=" * 60)
+        print()
+
+        return True
+
+    except Exception as e:
+        print(f"\n❌ Test failed: {e}")
+        import traceback
+
+        traceback.print_exc()
+        return False
+
+    finally:
+        # Step 9: Cleanup
+        if provider is not None:
+            print("\nStep 9: Cleaning up container...")
+            try:
+                provider.stop_container()
+                print("✓ Container stopped and removed\n")
+            except Exception as e:
+                print(f"⚠️  Cleanup warning: {e}\n")
+
+
+def test_provider_with_custom_port():
+    """Test provider with custom port."""
+    print("=" * 60)
+    print("LocalDockerProvider with Custom Port Test")
+    print("=" * 60)
+    print()
+
+    provider = None
+
+    try:
+        provider = LocalDockerProvider()
+
+        print("Starting container on custom port 8123...")
+        base_url = provider.start_container("echo-env:latest", port=8123)
+        print(f"✓ Started at: {base_url}")
+        assert ":8123" in base_url
+
+        print("Waiting for ready...")
+        provider.wait_for_ready(base_url)
+        print("✓ Ready!")
+
+        print("Testing health...")
+        response = requests.get(f"{base_url}/health")
+        assert response.status_code == 200
+        print("✓ Health check passed")
+
+        print("\n✓ Custom port test passed!\n")
+        return True
+
+    except Exception as e:
+        print(f"\n❌ Test failed: {e}")
+        return False
+
+    finally:
+        if provider is not None:
+            provider.stop_container()
+            print("✓ Cleaned up\n")
+
+
+def test_provider_with_env_vars():
+    """Test provider with environment variables."""
+    print("=" * 60)
+    print("LocalDockerProvider with Environment Variables Test")
+    print("=" * 60)
+    print()
+
+    provider = None
+
+    try:
+        provider = LocalDockerProvider()
+
+        print("Starting container with environment variables...")
+        base_url = provider.start_container(
+            "echo-env:latest", env_vars={"DEBUG": "true", "LOG_LEVEL": "info"}
+        )
+        print(f"✓ Started at: {base_url}")
+
+        print("Waiting for ready...")
+        provider.wait_for_ready(base_url)
+        print("✓ Ready!")
+
+        print("Testing health...")
+        response = requests.get(f"{base_url}/health")
+        assert response.status_code == 200
+        print("✓ Health check passed")
+
+        print("\n✓ Environment variables test passed!\n")
+        return True
+
+    except Exception as e:
+        print(f"\n❌ Test failed: {e}")
+        return False
+
+    finally:
+        if provider is not None:
+            provider.stop_container()
+            print("✓ Cleaned up\n")
+
+
+if __name__ == "__main__":
+    print()
+    print("🐳 LocalDockerProvider Test Suite")
+    print()
+
+    results = []
+
+    # Run basic test
+    results.append(("Basic End-to-End", test_local_docker_provider()))
+
+    # Run custom port test
+    results.append(("Custom Port", test_provider_with_custom_port()))
+
+    # Run environment variables test
+    results.append(("Environment Variables", test_provider_with_env_vars()))
+
+    # Summary
+    print("=" * 60)
+    print("Test Summary")
+    print("=" * 60)
+    for name, passed in results:
+        status = "✓ PASSED" if passed else "✗ FAILED"
+        print(f"{name:25} {status}")
+    print("=" * 60)
+
+    all_passed = all(result for _, result in results)
+    if all_passed:
+        print("\n🎉 All tests passed!")
+        exit(0)
+    else:
+        print("\n❌ Some tests failed")
+        exit(1)

src/core/env_client.py

@@ -0,0 +1,1197 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+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.
+
+Examples:
+
+    Async usage:
+
+    ```python
+    async with GenericEnvClient(base_url="ws://localhost:8000") as env:
+        result = await env.reset()
+        result = await env.step({"code": "print('hello')"})
+    ```
+
+    Sync usage via `.sync()` wrapper:
+
+    ```python
+    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 inspect
+import ipaddress
+import json
+import os
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Coroutine
+from contextlib import suppress
+from typing import Any, Callable, Dict, Generic, Optional, Type, TYPE_CHECKING, TypeVar
+from urllib.parse import urlsplit
+
+from .client_types import StateT, StepResult
+from .containers.runtime import LocalDockerProvider, UVProvider
+from .utils import convert_to_ws_url, hf_space_subdomain
+
+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
+from websockets.exceptions import ConnectionClosed
+from websockets.protocol import State
+
+ActT = TypeVar("ActT")
+ObsT = TypeVar("ObsT")
+EnvClientT = TypeVar("EnvClientT", bound="EnvClient")
+ResultT = TypeVar("ResultT")
+
+_VALID_CLIENT_MODES = ("simulation", "production")
+
+
+class _AutoAsyncResult(Generic[ResultT]):
+    """Awaitable result that can also be resolved by synchronous access."""
+
+    def __init__(
+        self,
+        client: "EnvClient[Any, Any, Any]",
+        coro_factory: Callable[[], Any],
+    ):
+        self._client = client
+        self._coro_factory = coro_factory
+        self._resolved = False
+        self._result: ResultT | None = None
+
+    def __await__(self):
+        async def _await_result():
+            self._client._claim_execution_mode("async")
+            return await self._coro_factory()
+
+        return _await_result().__await__()
+
+    def _sync_result(self) -> ResultT:
+        if not self._resolved:
+            self._result = self._client._run_sync(self._coro_factory)
+            self._resolved = True
+        return self._result
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._sync_result(), name)
+
+    def __bool__(self) -> bool:
+        return bool(self._sync_result())
+
+    def __repr__(self) -> str:
+        if self._resolved:
+            return repr(self._result)
+        return f"<{type(self).__name__} pending>"
+
+
+class _BootstrapResult(Coroutine, Generic[EnvClientT]):
+    """Bootstrap handle returned by the client factory methods.
+
+    Returned by [`~openenv.core.EnvClient.from_docker_image`] and
+    [`~openenv.core.EnvClient.from_env`]. Resolving the handle is what actually
+    starts the container / Space and connects the WebSocket, so a single factory
+    call serves both execution modes:
+
+    - `await handle` connects on the running event loop and returns the connected
+      async client (unchanged async behavior).
+    - `handle.sync()` connects on the sync background loop and returns a
+      `SyncEnvClient`, mirroring the instance-level [`~openenv.core.EnvClient.sync`].
+
+    The handle is a full coroutine (it implements `send` / `throw` / `close`), so
+    it is a drop-in for the previous `async def` factories: `asyncio.run(...)`,
+    `run_async_safely(...)`, and bare `await` all accept it, in addition to the
+    new `.sync()` chain. Bootstrap is lazy — the underlying coroutine (and the
+    container/Space start) is created only when the handle is driven or `.sync()`
+    is called.
+    """
+
+    def __init__(self, bootstrap: Callable[[], EnvClientT]):
+        self._bootstrap = bootstrap
+        self._coro: Optional[Coroutine[Any, Any, EnvClientT]] = None
+        self._used = False
+
+    def _consume(self) -> EnvClientT:
+        """Run the bootstrap exactly once; a second resolve is a programming error.
+
+        Mirrors native coroutine semantics (a coroutine cannot be awaited twice)
+        so that a handle re-driven via a second `.sync()`, or `await` followed by
+        `.sync()`, raises instead of silently starting a second container/Space.
+        """
+        if self._used:
+            raise RuntimeError(
+                "This bootstrap handle has already been resolved; call the "
+                "factory again to start a new environment."
+            )
+        self._used = True
+        return self._bootstrap()
+
+    async def _resolve_async(self) -> EnvClientT:
+        client = self._consume()
+        try:
+            await client.connect()
+        except asyncio.CancelledError:
+            # _connect_async releases the provider on ordinary failures, but
+            # cancellation bypasses its `except Exception`. No client reaches
+            # the caller, so release the provider here before propagating the
+            # original cancellation. A repeated cancellation or a stop failure
+            # during cleanup must not replace it.
+            with suppress(Exception, asyncio.CancelledError):
+                await client.close()
+            raise
+        return client
+
+    def _ensure_coro(self) -> "Coroutine[Any, Any, EnvClientT]":
+        if self._coro is None:
+            self._coro = self._resolve_async()
+        return self._coro
+
+    def __await__(self):
+        return self._ensure_coro().__await__()
+
+    def send(self, value: Any) -> Any:
+        return self._ensure_coro().send(value)
+
+    def throw(self, *args: Any, **kwargs: Any) -> Any:
+        return self._ensure_coro().throw(*args, **kwargs)
+
+    def close(self) -> None:
+        if self._coro is not None:
+            self._coro.close()
+
+    def sync(self) -> "SyncEnvClient":
+        client = self._consume()
+        try:
+            client._run_sync(client._connect_async)
+        except Exception:
+            # _consume() already started the provider. On the async path
+            # _connect_async releases it, but here the failure may be the sync
+            # loop setup itself (before _connect_async runs), so stop the
+            # provider directly rather than routing through the broken loop.
+            client._stop_provider_best_effort()
+            raise
+        return client.sync()
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} pending (await, run, or call .sync())>"
+
+
+def _normalize_mode(mode: Optional[str]) -> str:
+    """Resolve and validate the client communication mode."""
+    raw_mode = (
+        os.environ.get("OPENENV_CLIENT_MODE", "simulation") if mode is None else mode
+    )
+    normalized_mode = raw_mode.lower()
+    if normalized_mode not in _VALID_CLIENT_MODES:
+        raise ValueError(
+            f"Invalid mode: '{normalized_mode}'. Must be 'simulation' or 'production'. "
+            f"Set via constructor parameter or OPENENV_CLIENT_MODE environment variable."
+        )
+    return normalized_mode
+
+
+def _is_localhost_ws_url(ws_url: str) -> bool:
+    """Return True when the WebSocket URL targets the local loopback interface.
+
+    The hostname is parsed from the URL so that only the actual host is matched.
+    Substring matching is avoided because remote hosts such as
+    ``my-localhost-proxy.example.com`` or ``127.0.0.1.example.com`` must not be
+    treated as local.
+    """
+    hostname = urlsplit(ws_url).hostname
+    if hostname is None:
+        return False
+    if hostname == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(hostname).is_loopback
+    except ValueError:
+        return False
+
+
+def _required_start_container_parameters(provider: Any) -> list[str]:
+    """Return required arguments for a bound provider.start_container()."""
+    try:
+        signature = inspect.signature(provider.start_container)
+    except (TypeError, ValueError):
+        return []
+    return [
+        name
+        for name, parameter in signature.parameters.items()
+        if parameter.default is inspect.Parameter.empty
+        and parameter.kind
+        in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            inspect.Parameter.KEYWORD_ONLY,
+        )
+    ]
+
+
+async def _best_effort_close(ws: ClientConnection) -> None:
+    """Close a socket without letting a slow handshake or failure propagate.
+
+    Scheduled as a background task (never awaited directly) so a dropped
+    socket's close handshake can't hold up the caller that triggered the
+    drop -- see `EnvClient._receive()`. `EnvClient._close_async()` awaits
+    any still-running instance of this task before it returns, so a real
+    `close()` call does wait for the handshake; only the caller that
+    happened to trigger the drop is spared. `CancelledError` is caught
+    alongside `Exception` because that awaiting is exactly what would
+    otherwise cancel this mid-handshake if a caller called `close()`
+    concurrently.
+    """
+    try:
+        await ws.close()
+    except (Exception, asyncio.CancelledError):
+        pass  # Best effort
+
+
+async def _best_effort_graceful_close(ws: ClientConnection) -> None:
+    """Notify the server, then close a socket without propagating failures."""
+    try:
+        await ws.send(json.dumps({"type": "close"}))
+    except (Exception, asyncio.CancelledError):
+        pass  # Best effort
+    await _best_effort_close(ws)
+
+
+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
+
+    Examples:
+
+        Async usage:
+
+        ```python
+        from envs.coding_env.client import CodingEnv
+
+        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)
+        ```
+
+        Sync usage via `.sync()` wrapper:
+
+        ```python
+        env = CodingEnv(base_url="ws://localhost:8000").sync()
+        with env:
+            result = env.reset(seed=42)
+            result = env.step(action)
+        ```
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        connect_timeout_s: float = 10.0,
+        message_timeout_s: float = 60.0,
+        max_message_size_mb: float = 100.0,
+        websocket_ping_interval_s: Optional[float] = 20.0,
+        websocket_ping_timeout_s: Optional[float] = 20.0,
+        provider: Optional["ContainerProvider | RuntimeProvider"] = None,
+        mode: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ):
+        """
+        Initialize environment client.
+
+        Args:
+            base_url (`str`, *optional*):
+                Base URL of the environment server (http:// or ws://). Will be converted to
+                ws:// if http:// is provided. May be omitted when the provider
+                has enough constructor state to start itself.
+            connect_timeout_s (`float`, *optional*, defaults to `10.0`):
+                Timeout for establishing WebSocket connection.
+            message_timeout_s (`float`, *optional*, defaults to `60.0`):
+                Timeout for receiving responses to messages.
+            max_message_size_mb (`float`, *optional*, defaults to `100.0`):
+                Maximum WebSocket message size in megabytes. Default 100MB to handle large
+                observations (screenshots, DOM, etc.).
+            websocket_ping_interval_s (`float` or `None`, *optional*, defaults to `20.0`):
+                WebSocket keepalive ping interval. Pass `None` to disable.
+            websocket_ping_timeout_s (`float` or `None`, *optional*, defaults to `20.0`):
+                WebSocket keepalive pong timeout. Pass `None` to disable.
+            provider (`ContainerProvider` or `RuntimeProvider`, *optional*):
+                Container/runtime provider for lifecycle management.
+            mode (`str`, *optional*):
+                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.
+            headers (`dict[str, str]`, *optional*):
+                Extra HTTP headers sent when opening the connection, e.g.
+                `{"Authorization": f"Bearer {hf_token}"}` for a private Hugging Face Space.
+        """
+        if base_url is None and provider is None:
+            raise ValueError("EnvClient requires either base_url or provider.")
+
+        # Store mode (use object.__setattr__ to bypass immutability)
+        object.__setattr__(self, "_mode", _normalize_mode(mode))
+
+        self._base_url: Optional[str] = None
+        self._ws_url: Optional[str] = None
+        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._websocket_ping_interval_s = websocket_ping_interval_s
+        self._websocket_ping_timeout_s = websocket_ping_timeout_s
+        self._headers = headers
+        self._provider = provider
+        self._provider_stopped = False
+        self._provider_cleanup_pending = False
+        self._start_provider_on_connect = base_url is None
+        self._child_clients: list[EnvClient[Any, Any, Any]] = []
+        self._ws: Optional[ClientConnection] = None
+        self._execution_mode: Optional[str] = None
+        self._sync_client: Optional["SyncEnvClient[ActT, ObsT, StateT]"] = None
+        self._ws_loop: Optional[asyncio.AbstractEventLoop] = None
+        # Strong references for fire-and-forget socket closes (see _receive),
+        # so the task isn't garbage-collected mid-close. Discarded on done.
+        self._pending_close_tasks: set[asyncio.Task] = set()
+        if base_url is not None:
+            self._set_base_url(base_url)
+
+    @property
+    def base_url(self) -> Optional[str]:
+        """Public read-only URL of the environment server this client targets.
+
+        Returns the normalized `http(s)`/`ws(s)` base URL (no trailing slash),
+        or `None` when the client was created with a provider but has not yet
+        started its container (the URL is assigned lazily on `connect()`).
+
+        This is the public counterpart to the private `self._base_url`; the
+        previously-public `base_url` attribute was dropped in the `core`
+        refactor, leaving sync consumers with no way to read the URL back.
+        """
+        return self._base_url
+
+    def _set_base_url(self, base_url: str) -> None:
+        self._base_url = base_url.rstrip("/")
+        ws_url = convert_to_ws_url(base_url)
+        self._ws_url = f"{ws_url}/ws"
+
+    def _start_provider_if_needed(self) -> None:
+        # A missing URL does not mean the previous resource was released.
+        # Retry its cleanup before start can overwrite the provider's handle.
+        if self._provider_cleanup_pending:
+            if not self._start_provider_on_connect:
+                raise RuntimeError(
+                    "Provider cleanup is pending for this client with an existing "
+                    "base URL. Retry close() to finish cleanup, then create a new "
+                    "client instead of reconnecting to the old URL."
+                )
+            self._stop_provider()
+        if self._ws_url is not None:
+            return
+        if self._provider is None:
+            raise RuntimeError("EnvClient has no base URL or provider.")
+        if hasattr(self._provider, "start_container"):
+            required_parameters = _required_start_container_parameters(self._provider)
+            if required_parameters:
+                required = ", ".join(required_parameters)
+                raise ValueError(
+                    f"{type(self._provider).__name__} does not support "
+                    "provider-owned startup because start_container() requires "
+                    f"{required}. Start the provider manually and pass base_url, "
+                    "or configure a provider with a constructor-owned image/source."
+                )
+            self._provider_stopped = False
+            base_url = self._provider.start_container()
+            self._provider.wait_for_ready(base_url)
+        elif hasattr(self._provider, "start"):
+            self._provider_stopped = False
+            base_url = self._provider.start()
+            self._provider.wait_for_ready()
+        else:
+            raise TypeError("provider must define start_container() or start().")
+        self._set_base_url(base_url)
+
+    def _create_session_client(self) -> "EnvClient[Any, Any, Any]":
+        # Match _start_provider_if_needed's startup condition. A provider with
+        # an existing URL may already be serving the parent or other children.
+        starts_provider_here = self._provider is not None and self._ws_url is None
+        try:
+            self._start_provider_if_needed()
+            if self._base_url is None:
+                raise RuntimeError("EnvClient has no base URL.")
+
+            signature = inspect.signature(type(self))
+            accepts_kwargs = any(
+                parameter.kind == inspect.Parameter.VAR_KEYWORD
+                for parameter in signature.parameters.values()
+            )
+            candidate_kwargs = {
+                "base_url": self._base_url,
+                "connect_timeout_s": self._connect_timeout,
+                "message_timeout_s": self._message_timeout,
+                "max_message_size_mb": self._max_message_size / (1024 * 1024),
+                "websocket_ping_interval_s": self._websocket_ping_interval_s,
+                "websocket_ping_timeout_s": self._websocket_ping_timeout_s,
+                "mode": self._mode,
+                "headers": self._headers,
+            }
+            constructor_kwargs = {}
+            for name, value in candidate_kwargs.items():
+                if accepts_kwargs or name in signature.parameters:
+                    constructor_kwargs[name] = value
+
+            return type(self)(**constructor_kwargs)
+        except Exception:
+            if starts_provider_here and not self._provider_cleanup_pending:
+                self._stop_provider_best_effort()
+            raise
+
+    async def new_session(self) -> "EnvClient[Any, Any, Any]":
+        """
+        Create and connect a new session against the same environment server.
+
+        Returns:
+            `EnvClient`: A connected child client of the same concrete type.
+
+        The child session is tracked by this parent and closed when the parent
+        is closed. Server-side capacity still applies: when the server is at
+        `MAX_CONCURRENT_ENVS`, opening the child WebSocket can fail and is
+        surfaced as a connection error.
+        """
+        client = self._create_session_client()
+        await client.connect()
+        self._child_clients.append(client)
+        return client
+
+    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)
+
+    def _claim_execution_mode(self, mode: str) -> None:
+        """Lock the client to sync or async execution on first use."""
+        if self._execution_mode is None:
+            self._execution_mode = mode
+        elif self._execution_mode != mode:
+            raise RuntimeError(
+                f"EnvClient is already being used in {self._execution_mode} mode. "
+                "Create a separate client instance when mixing sync and async code."
+            )
+
+    def _run_sync(
+        self,
+        coro_factory: Callable[[], Any],
+        *,
+        allow_async_handoff: bool = False,
+    ) -> Any:
+        """Run an async operation through the sync wrapper."""
+        if allow_async_handoff and self._execution_mode == "async":
+            self._execution_mode = "sync"
+        else:
+            self._claim_execution_mode("sync")
+        if self._sync_client is None:
+            self._sync_client = self.sync()
+        return self._sync_client._run(coro_factory())
+
+    def _dispatch(self, coro_factory: Callable[[], Any]) -> Any:
+        """Return an awaitable in async code and a concrete result in sync code."""
+        try:
+            running_loop = asyncio.get_running_loop()
+        except RuntimeError:
+            running_loop = None
+
+        if self._execution_mode == "sync":
+            sync_loop = (
+                self._sync_client._loop if self._sync_client is not None else None
+            )
+            if running_loop is sync_loop:
+                return coro_factory()
+            return self._run_sync(coro_factory)
+        if running_loop is not None:
+            if self._execution_mode == "async":
+                return coro_factory()
+            return _AutoAsyncResult(self, coro_factory)
+
+        return self._run_sync(coro_factory, allow_async_handoff=True)
+
+    def connect(self) -> Any:
+        return self._dispatch(self._connect_async)
+
+    async def _connect_async(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:
+            if self._ws.state in (State.CLOSING, State.CLOSED):
+                # Closed by the far end: a keepalive timeout, a tunnel dropping
+                # the socket, the server restarting. The object is still not
+                # None, so without this check it stays cached and every later
+                # call raises `ConnectionClosed` for the rest of the process's
+                # life. Only a demonstrably closed socket is dropped, so one
+                # still CONNECTING is left alone.
+                self._ws = None
+                self._ws_loop = None
+            elif self._ws_loop is asyncio.get_running_loop():
+                return self
+            # Connected from a different event loop than the one running
+            # now -- e.g. `client = await Client.from_env(...)` inside
+            # `asyncio.run(...)`, then `client.sync()` drives every later
+            # call on `SyncEnvClient`'s own dedicated background loop. The
+            # websocket object is bound to internals of the original loop,
+            # which is typically already closed by the time we get here, so
+            # it cannot be reused (or even cleanly closed) from this loop.
+            # Drop the stale reference and reconnect fresh below rather than
+            # silently no-op-ing onto a dead connection.
+            self._ws = None
+            self._ws_loop = None
+
+        # A timed-out request drops its socket immediately but closes it in the
+        # background so the timeout itself remains prompt. Wait for that close
+        # before opening a replacement: the old server-side session continues
+        # occupying a capacity slot until the close handshake finishes, and
+        # many environments allow only one session.
+        await self._drain_pending_close_tasks()
+
+        try:
+            self._start_provider_if_needed()
+        except Exception:
+            # A failed cleanup retry must propagate without attempting stop
+            # again. For a new startup failure, preserve its original error.
+            if not self._provider_cleanup_pending:
+                with suppress(Exception):
+                    await self.close()
+            raise
+
+        assert self._ws_url is not None
+
+        # Disable the proxy for localhost connections via the per-connection
+        # `proxy` argument rather than mutating the process-global NO_PROXY
+        # env var: concurrent connect() calls (e.g. asyncio.gather over many
+        # env clients) would otherwise race on os.environ and leak state.
+        connect_kwargs: Dict[str, Any] = {}
+        if _is_localhost_ws_url(self._ws_url):
+            connect_kwargs["proxy"] = None
+
+        try:
+            self._ws = await ws_connect(
+                self._ws_url,
+                open_timeout=self._connect_timeout,
+                max_size=self._max_message_size,
+                ping_interval=self._websocket_ping_interval_s,
+                ping_timeout=self._websocket_ping_timeout_s,
+                additional_headers=self._headers,
+                **connect_kwargs,
+            )
+            self._ws_loop = asyncio.get_running_loop()
+        except Exception as e:
+            await self.close()
+            raise ConnectionError(f"Failed to connect to {self._ws_url}: {e}") from e
+
+        return self
+
+    def disconnect(self) -> Any:
+        return self._dispatch(self._disconnect_async)
+
+    def _schedule_socket_close(
+        self, ws: ClientConnection, *, notify_server: bool = False
+    ) -> asyncio.Task[None]:
+        """Schedule and track a socket close until its handshake finishes."""
+        close_coro = (
+            _best_effort_graceful_close(ws) if notify_server else _best_effort_close(ws)
+        )
+        close_task = asyncio.create_task(close_coro)
+        self._pending_close_tasks.add(close_task)
+        close_task.add_done_callback(self._pending_close_tasks.discard)
+        return close_task
+
+    async def _disconnect_async(self) -> None:
+        """Close the WebSocket connection."""
+        if self._ws is not None:
+            ws = self._ws
+            ws_loop = self._ws_loop
+            # Detach first so cancellation during the close handshake cannot
+            # leave a stale socket cached for a later operation.
+            self._ws = None
+            self._ws_loop = None
+            same_loop = ws_loop is asyncio.get_running_loop()
+            if same_loop:
+                # Keep ownership of the handshake if this caller is cancelled.
+                # A later close/reconnect drains the task before tearing down
+                # the loop or opening a replacement server session.
+                close_task = self._schedule_socket_close(ws, notify_server=True)
+                await asyncio.shield(close_task)
+
+    async def _drain_pending_close_tasks(self) -> None:
+        """Wait for background socket closes owned by the current event loop.
+
+        Shielding keeps cancellation of the caller from cancelling the close
+        tasks themselves. This matters both before reconnecting, when the old
+        server session must release its capacity slot, and during explicit
+        client shutdown.
+        """
+        loop = asyncio.get_running_loop()
+        tasks = [
+            task
+            for task in tuple(self._pending_close_tasks)
+            if not task.done() and task.get_loop() is loop
+        ]
+        if tasks:
+            await asyncio.shield(asyncio.gather(*tasks, return_exceptions=True))
+
+    async def _ensure_connected(self) -> None:
+        """Ensure WebSocket connection is established on the current loop.
+
+        Always delegates to `_connect_async()` rather than pre-checking
+        `self._ws is None`: `_connect_async()` itself is the one that knows
+        whether an existing `_ws` is reusable (same event loop) or stale (a
+        different one, e.g. from a prior `from_env()` call now being driven
+        through `.sync()`'s own loop).
+        """
+        await self._connect_async()
+
+    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 the response on the same WebSocket that carried the request.
+
+        Reconnecting here would wait on a fresh socket where the request was
+        never sent. The next complete operation may reconnect in `_send()`.
+        """
+        assert self._ws is not None
+        try:
+            raw = await asyncio.wait_for(self._ws.recv(), timeout=self._message_timeout)
+        except (asyncio.TimeoutError, asyncio.CancelledError):
+            # The server may still write the response for this request to the
+            # socket after we give up waiting on it. If we left the socket
+            # open, the next call's `_receive()` would read that stale frame
+            # and silently pair it with an unrelated request -- and every
+            # response after that would be shifted by one for the life of
+            # the connection. Drop the socket so the next `_send()` opens a
+            # fresh one instead of reusing a desynced one.
+            #
+            # An outer `asyncio.wait_for` around the whole call (e.g. a
+            # caller-imposed deadline on step()) cancels this await with
+            # CancelledError, not our own message_timeout's TimeoutError --
+            # same desync, different exception, so both are caught here.
+            ws = self._ws
+            self._ws = None
+            self._ws_loop = None
+            # Fire-and-forget: `close()` waits out the library's close
+            # handshake (`close_timeout`, 10s by default) if the server is
+            # slow to ack, and *awaiting* that here would hold up this
+            # exception -- so an outer `asyncio.wait_for(..., timeout=50ms)`
+            # would actually block for up to 10s before its deadline was
+            # honored. Scheduling it lets the exception propagate
+            # immediately while the close still happens in the background.
+            self._schedule_socket_close(ws)
+            raise
+        return json.loads(raw)
+
+    async def _send_and_receive(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Send a message and wait for response."""
+        try:
+            await self._send(message)
+        except ConnectionClosed:
+            # A refused session (e.g. at capacity) sends an error frame then closes. If
+            # the close beats our send, read the queued frame (recv() re-raises if none).
+            pass
+        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
+    def _bootstrap_container(
+        cls: Type[EnvClientT],
+        image: str,
+        provider: Optional["ContainerProvider"] = None,
+        **kwargs: Any,
+    ) -> EnvClientT:
+        """Start a Docker container and build an *unconnected* client for it.
+
+        Invoked lazily by the `from_docker_image` bootstrap handle when it is
+        awaited or `.sync()`'d: the container start / readiness wait is plain
+        blocking code, so the only thing that differs between the async and sync
+        resolution paths is how the WebSocket is connected (awaited vs. run sync).
+        """
+        if provider is None:
+            provider = LocalDockerProvider()
+
+        try:
+            # Start container, wait for readiness, then build the client.
+            base_url = provider.start_container(image, **kwargs)
+            provider.wait_for_ready(base_url)
+            return cls(base_url=base_url, provider=provider)
+        except Exception:
+            # No EnvClient exists yet for the caller to close(), so release the
+            # container here if start / readiness / construction fails.
+            provider.stop_container()
+            raise
+
+    @classmethod
+    def from_docker_image(
+        cls: Type[EnvClientT],
+        image: str,
+        provider: Optional["ContainerProvider"] = None,
+        **kwargs: Any,
+    ) -> "_BootstrapResult[EnvClientT]":
+        """
+        Create an environment client by spinning up a Docker container.
+
+        Returns a bootstrap handle so the same call works from both async and
+        synchronous code: `await` it for the connected async client, or chain
+        `.sync()` for a connected `SyncEnvClient` (e.g. a TRL GRPO rollout loop
+        that cannot `await`). Bootstrap is lazy — the container starts when the
+        handle is resolved.
+
+        Args:
+            image (`str`):
+                Docker image name to run (e.g., `"coding-env:latest"`).
+            provider (`ContainerProvider`, *optional*):
+                Container provider to use. Defaults to `LocalDockerProvider`.
+            **kwargs:
+                Additional arguments to pass to `provider.start_container()`.
+
+        Returns:
+            `_BootstrapResult`: `await` for a connected async client, or call
+            `.sync()` for a connected `SyncEnvClient`.
+
+        Examples:
+
+        ```python
+        # Async
+        env = await MyEnv.from_docker_image("coding-env:latest")
+
+        # Sync
+        env = MyEnv.from_docker_image("coding-env:latest").sync()
+        result = env.reset()
+        ```
+        """
+        return _BootstrapResult(
+            lambda: cls._bootstrap_container(image, provider, **kwargs)
+        )
+
+    @classmethod
+    def _bootstrap_env(
+        cls: Type[EnvClientT],
+        repo_id: str,
+        *,
+        use_docker: bool = True,
+        provider: Optional["ContainerProvider | RuntimeProvider"] = None,
+        **provider_kwargs: Any,
+    ) -> EnvClientT:
+        """Start a HF Space (docker or uv) and build an *unconnected* client.
+
+        Invoked lazily by the `from_env` bootstrap handle; see
+        `_bootstrap_container` for the same split rationale. On a startup
+        failure the spawned process (and, for a git+ `project_path`, the temp
+        clone directory) is released before re-raising; a later *connection*
+        failure is cleaned up by `_connect_async` via `close()`.
+        """
+        # 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/{hf_space_subdomain(repo_id)}:{tag}"
+            try:
+                base_url = docker_provider.start_container(
+                    image, **start_args, **provider_kwargs
+                )
+                docker_provider.wait_for_ready(base_url)
+                return cls(base_url=base_url, provider=docker_provider)
+            except Exception:
+                # No EnvClient exists yet for the caller to close(), so release
+                # the container here if start / readiness / construction fails.
+                docker_provider.stop_container()
+                raise
+        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"
+                    )
+
+            try:
+                context_timeout_s = getattr(provider, "context_timeout_s", None)
+                deadline = (
+                    time.monotonic() + context_timeout_s
+                    if context_timeout_s is not None
+                    else None
+                )
+                base_url = provider.start(**start_args)
+                if deadline is None:
+                    provider.wait_for_ready()
+                else:
+                    provider.wait_for_ready(
+                        timeout_s=max(0.0, deadline - time.monotonic())
+                    )
+                return cls(base_url=base_url, provider=provider)
+            except Exception:
+                # No EnvClient exists yet for the caller to close(), so this is
+                # the only chance to release the spawned process and (for a
+                # git+ project_path) the temp clone directory. Covers start,
+                # readiness, and client construction (e.g. an invalid mode).
+                provider.stop()
+                raise
+
+    @classmethod
+    def from_env(
+        cls: Type[EnvClientT],
+        repo_id: str,
+        *,
+        use_docker: bool = True,
+        provider: Optional["ContainerProvider | RuntimeProvider"] = None,
+        **provider_kwargs: Any,
+    ) -> "_BootstrapResult[EnvClientT]":
+        """
+        Create a client from a Hugging Face Space.
+
+        Returns a bootstrap handle: `await` it for the connected async client, or
+        chain `.sync()` for a connected `SyncEnvClient`. Bootstrap is lazy — the
+        Space starts when the handle is resolved.
+
+        Args:
+            repo_id (`str`):
+                Hugging Face space identifier `{org}/{space}`.
+            use_docker (`bool`, *optional*, defaults to `True`):
+                When `True`, pull from the HF registry and launch via `LocalDockerProvider`.
+                When `False`, run the space locally with `UVProvider`.
+            provider (`ContainerProvider` or `RuntimeProvider`, *optional*):
+                Provider instance to reuse. Must be a `ContainerProvider` when
+                `use_docker=True` and a `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:
+            `_BootstrapResult`: `await` for a connected async client, or call
+            `.sync()` for a connected `SyncEnvClient`.
+
+        Examples:
+
+            ```python
+            # Async: pull and run from HF Docker registry
+            env = await MyEnv.from_env("openenv/echo-env")
+
+            # Sync: chain .sync()
+            env = MyEnv.from_env("openenv/echo-env").sync()
+
+            # 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"
+            )
+            ```
+        """
+        return _BootstrapResult(
+            lambda: cls._bootstrap_env(
+                repo_id,
+                use_docker=use_docker,
+                provider=provider,
+                **provider_kwargs,
+            )
+        )
+
+    @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
+
+    def reset(self, **kwargs: Any) -> Any:
+        return self._dispatch(lambda: self._reset_async(**kwargs))
+
+    async def _reset_async(self, **kwargs: Any) -> StepResult[ObsT]:
+        """
+        Reset the environment with optional parameters.
+
+        Args:
+            **kwargs:
+                Optional parameters passed to the environment's reset method.
+
+        Returns:
+            StepResult containing initial observation
+        """
+        message = {
+            "type": "reset",
+            "data": kwargs,
+        }
+        response = await self._send_and_receive(message)
+        return self._parse_result(response.get("data", {}))
+
+    def step(self, action: ActT, **kwargs: Any) -> Any:
+        return self._dispatch(lambda: self._step_async(action, **kwargs))
+
+    async def _step_async(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", {}))
+
+    def state(self) -> Any:
+        return self._dispatch(self._state_async)
+
+    async def _state_async(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", {}))
+
+    def close(self) -> Any:
+        return self._dispatch(self._close_async)
+
+    async def _close_child_clients(self) -> asyncio.CancelledError | None:
+        """Close every captured child while deferring caller cancellation."""
+        children = list(self._child_clients)
+        self._child_clients.clear()
+        close_tasks = []
+        deferred_cancellation: asyncio.CancelledError | None = None
+
+        for child in children:
+            try:
+                close_tasks.append(asyncio.ensure_future(child.close()))
+            except asyncio.CancelledError as exc:
+                if deferred_cancellation is None:
+                    deferred_cancellation = exc
+            except Exception:
+                pass  # Best effort
+
+        if close_tasks:
+            close_group = asyncio.gather(*close_tasks, return_exceptions=True)
+            while not close_group.done():
+                try:
+                    await asyncio.shield(close_group)
+                except asyncio.CancelledError as exc:
+                    if deferred_cancellation is None:
+                        deferred_cancellation = exc
+
+            for result in close_group.result():
+                if (
+                    isinstance(result, asyncio.CancelledError)
+                    and deferred_cancellation is None
+                ):
+                    deferred_cancellation = result
+
+        return deferred_cancellation
+
+    async def _close_async(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.
+        """
+        deferred_cancellation: asyncio.CancelledError | None = None
+        try:
+            try:
+                try:
+                    child_cancellation = await self._close_child_clients()
+                except asyncio.CancelledError as exc:
+                    child_cancellation = exc
+                if child_cancellation is not None:
+                    deferred_cancellation = child_cancellation
+
+                # A real close waits out backgrounded closes, while shielding
+                # their socket handshakes from cancellation.
+                try:
+                    await self._drain_pending_close_tasks()
+                except asyncio.CancelledError as exc:
+                    if deferred_cancellation is None:
+                        deferred_cancellation = exc
+            finally:
+                # Run even when child or pending-close cleanup is cancelled. A
+                # client may already have reconnected, and that current socket
+                # must not remain cached or open during teardown.
+                try:
+                    await self._disconnect_async()
+                except asyncio.CancelledError as exc:
+                    if deferred_cancellation is None:
+                        deferred_cancellation = exc
+        finally:
+            self._stop_provider()
+
+        if deferred_cancellation is not None:
+            raise deferred_cancellation
+
+    def _stop_provider(self) -> None:
+        """Stop the provider once, retaining it for retries and later startup."""
+        try:
+            provider = self._provider
+            if provider is None or self._provider_stopped:
+                return
+
+            if hasattr(provider, "stop_container"):
+                stop = provider.stop_container
+            elif hasattr(provider, "stop"):
+                stop = provider.stop
+            else:
+                return
+
+            self._provider_cleanup_pending = True
+            stop()
+            # Only a successful stop discharges our cleanup responsibility.
+            self._provider_cleanup_pending = False
+            self._provider_stopped = True
+        finally:
+            if self._start_provider_on_connect:
+                self._base_url = None
+                self._ws_url = None
+
+    def _stop_provider_best_effort(self) -> None:
+        """Stop the underlying provider directly, ignoring any errors.
+
+        Releases a started container/process when there is no connected client
+        to `close()` through the normal path — e.g. sync bootstrap setup fails
+        after the provider started but before the connection is established, so
+        routing cleanup through the (possibly broken) sync loop is not an option.
+        """
+        with suppress(Exception):
+            self._stop_provider()
+
+    async def __aenter__(self) -> "EnvClient":
+        """Enter async context manager, ensuring connection is established."""
+        self._claim_execution_mode("async")
+        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":
+        """Enter sync context manager, ensuring connection is established."""
+        self._run_sync(self._connect_async)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit sync context manager, closing connection."""
+        self._run_sync(self._close_async)
+
+    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
+
+        Examples:
+
+            ```python
+            async_client = GenericEnvClient(base_url="http://localhost:8000")
+            sync_client = async_client.sync()
+
+            with sync_client:
+                result = sync_client.reset()
+                result = sync_client.step({"code": "print('hello')"})
+            ```
+        """
+        from .sync_client import SyncEnvClient
+
+        if self._sync_client is None:
+            self._sync_client = SyncEnvClient(self)
+        return self._sync_client

src/core/env_server/__init__.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Core environment interfaces and types."""
+
+from .base_transforms import CompositeTransform, NullTransform
+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, TaskProvider, Transform
+
+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,
+    GetTaskRangeRequest,
+    GetTaskRequest,
+    HealthResponse,
+    HealthStatus,
+    ListTasksRequest,
+    NumTasksRequest,
+    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
+    "Environment",
+    "Transform",
+    "TaskProvider",
+    "Message",
+    "ModelTokenizer",
+    # Types
+    "Action",
+    "Observation",
+    "State",
+    "SchemaResponse",
+    "HealthResponse",
+    "ListTasksRequest",
+    "NumTasksRequest",
+    "GetTaskRequest",
+    "GetTaskRangeRequest",
+    # 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",
+    # HTTP Server
+    "HTTPEnvServer",
+    "create_app",
+    "create_fastapi_app",
+    # 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/_utils.py

@@ -0,0 +1,10 @@
+"""Shared env server implementation helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def overrides_method(method: Any, base_method: Any) -> bool:
+    """Return whether a bound method differs from the base implementation."""
+    return getattr(method, "__func__", method) is not base_method

src/core/env_server/base_transforms.py

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Base transform implementations for composing environment-specific transforms."""
+
+from .interfaces import Transform
+from .types import Observation
+
+
+class CompositeTransform(Transform):
+    """Combines multiple transforms into a single transform."""
+
+    def __init__(self, transforms: list[Transform]):
+        self.transforms = transforms
+
+    def __call__(self, observation: Observation) -> Observation:
+        for transform in self.transforms:
+            observation = transform(observation)
+        return observation
+
+
+class NullTransform(Transform):
+    """Default transform that passes through unchanged."""
+
+    def __call__(self, observation: Observation) -> Observation:
+        return observation

src/core/env_server/exceptions.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""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,142 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Theme for the OpenEnv Gradio UI: white, hairline borders, one green accent."""
+
+from __future__ import annotations
+
+import gradio as gr
+
+_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="#fafafa",
+    c100="#f4f4f5",
+    c200="#e4e4e7",
+    c300="#d4d4d8",
+    c400="#a1a1aa",
+    c500="#71717a",
+    c600="#52525b",
+    c700="#3f3f46",
+    c800="#27272a",
+    c900="#18181b",
+    c950="#0a0a0a",
+)
+
+OPENENV_GRADIO_THEME = gr.themes.Base(
+    primary_hue=_GREEN_HUE,
+    secondary_hue=_NEUTRAL_HUE,
+    neutral_hue=_NEUTRAL_HUE,
+    font=(gr.themes.GoogleFont("Geist"), "system-ui", "sans-serif"),
+    font_mono=(gr.themes.GoogleFont("Geist Mono"), "ui-monospace", "monospace"),
+    radius_size=gr.themes.sizes.radius_md,
+).set(
+    body_background_fill="#ffffff",
+    body_text_color="#0a0a0a",
+    background_fill_primary="#ffffff",
+    background_fill_secondary="#fafafa",
+    block_background_fill="#ffffff",
+    block_border_width="0px",
+    block_label_text_color="#52525b",
+    block_label_background_fill="transparent",
+    border_color_primary="#ecedef",
+    input_background_fill="#ffffff",
+    input_border_color="#e4e4e7",
+    input_border_color_focus="#1a7f37",
+    button_primary_background_fill="#0a0a0a",
+    button_primary_background_fill_hover="#27272a",
+    button_primary_text_color="#ffffff",
+    button_primary_border_color="#0a0a0a",
+    button_secondary_background_fill="#ffffff",
+    button_secondary_background_fill_hover="#fafafa",
+    button_secondary_text_color="#0a0a0a",
+    button_secondary_border_color="#e4e4e7",
+    button_border_width="1px",
+    checkbox_background_color_selected="#1a7f37",
+    checkbox_border_color_selected="#1a7f37",
+    color_accent="#1a7f37",
+    color_accent_soft="#f0f7f2",
+    color_accent_soft_dark="#0d2416",
+    body_text_color_subdued="#52525b",
+    body_text_color_subdued_dark="#a1a1aa",
+    body_background_fill_dark="#0a0a0a",
+    body_text_color_dark="#fafafa",
+    background_fill_primary_dark="#0a0a0a",
+    background_fill_secondary_dark="#141414",
+    block_background_fill_dark="#0a0a0a",
+    block_label_text_color_dark="#a1a1aa",
+    border_color_primary_dark="#27272a",
+    input_background_fill_dark="#0a0a0a",
+    input_border_color_dark="#3f3f46",
+    button_primary_background_fill_dark="#fafafa",
+    button_primary_background_fill_hover_dark="#e4e4e7",
+    button_primary_text_color_dark="#0a0a0a",
+    button_primary_border_color_dark="#fafafa",
+    button_secondary_background_fill_dark="#0a0a0a",
+    button_secondary_background_fill_hover_dark="#18181b",
+    button_secondary_text_color_dark="#fafafa",
+    button_secondary_border_color_dark="#3f3f46",
+)
+
+OPENENV_GRADIO_CSS = """
+.gradio-container { max-width: 1120px !important; margin: 0 auto !important; }
+.oe-header { padding: 24px 0 12px; }
+.oe-header h1 { margin: 6px 0 4px; font-size: 40px; line-height: 1.1; font-weight: 700; letter-spacing: -.03em; }
+.oe-header p, .oe-step p, .oe-episode small, .oe-muted { color: var(--body-text-color-subdued); }
+.oe-header p { margin: 0; font-size: 16px; max-width: 640px; }
+.oe-eyebrow { font-family: var(--font-mono); font-size: 13px; font-weight: 500; color: var(--color-accent); }
+.oe-card { border: 1px solid var(--border-color-primary) !important; border-radius: 12px !important; padding: 18px 20px !important; background: var(--background-fill-primary) !important; gap: 12px !important; }
+.oe-row { align-items: center !important; }
+.oe-step h2, .oe-episode h2 { margin: 0; font-size: 17px; font-weight: 600; }
+.oe-step p { margin: 2px 0 0; font-size: 14px; }
+.oe-step code, .oe-episode code, .oe-result code { font-family: var(--font-mono); background: none; padding: 0; }
+.oe-run { flex: none !important; align-self: flex-start !important; width: auto !important; min-width: 140px !important; padding: 0 22px !important; margin-left: var(--block-padding, 10px) !important; }
+.oe-card textarea, .oe-card input[type=number], .oe-card input[type=password], .oe-card input[type=text] { border: 1px solid var(--input-border-color) !important; border-radius: 8px !important; padding: 10px 12px !important; font-family: var(--font-mono) !important; }
+.oe-tools .wrap, .oe-actions .wrap { gap: 8px; }
+.oe-tools .wrap { display: grid !important; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); }
+.oe-actions .wrap { display: flex !important; flex-wrap: wrap; }
+.oe-tools .wrap label, .oe-actions .wrap label { border: 1px solid var(--input-border-color) !important; border-radius: 10px !important; background: var(--background-fill-primary) !important; font-family: var(--font-mono); cursor: pointer; }
+.oe-tools .wrap label { padding: 12px 14px !important; font-size: 13px; }
+.oe-actions .wrap label { padding: 10px 16px !important; font-size: 14px; }
+.oe-tools .wrap label.selected { border: 1.5px solid var(--color-accent) !important; background: var(--color-accent-soft) !important; }
+.oe-actions input[type=radio] { display: none; }
+.oe-result { border: 1px solid var(--border-color-primary); border-radius: 10px; overflow: hidden; }
+.oe-output, .oe-fields { background: var(--background-fill-secondary); border-bottom: 1px solid var(--border-color-primary); }
+.oe-output { margin: 0; padding: 14px 16px; font-family: var(--font-mono); font-size: 15px; white-space: pre-wrap; word-break: break-word; }
+.oe-fields { padding: 10px 16px; }
+.oe-fields div { display: grid; grid-template-columns: minmax(96px, 28%) minmax(0, 1fr); gap: 12px; padding: 3px 0; font-size: 13px; }
+.oe-fields code { white-space: pre-wrap; word-break: break-word; }
+.oe-fields span, .oe-stats span, .oe-episode li > span { font-family: var(--font-mono); color: var(--body-text-color-subdued); }
+.oe-fields span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.oe-stats { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.oe-stats div { padding: 8px 16px; border-right: 1px solid var(--border-color-primary); }
+.oe-stats div:last-child { border-right: none; }
+.oe-stats span { display: block; font-size: 12px; }
+.oe-stats code { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.oe-error { color: #b42318; }
+.dark .oe-error { color: #ff8a80; }
+.oe-episode ol { list-style: none; margin: 8px 0 0; padding: 0; }
+.oe-episode li { display: flex; gap: 12px; padding: 8px 0; border-top: 1px solid var(--border-color-primary); }
+.oe-episode li > span { flex: none; width: 20px; font-size: 12px; }
+.oe-episode code { display: block; font-size: 13px; word-break: break-word; }
+.oe-episode small { display: block; font-size: 13px; word-break: break-word; }
+.oe-muted { margin: 8px 0 0; font-size: 14px; }
+.oe-code pre code { white-space: pre-wrap !important; word-break: break-word; }
+.oe-json .code_wrap, .oe-json .cm-editor { max-height: 360px; overflow: auto; }
+.oe-code pre { background: var(--background-fill-secondary) !important; border: 1px solid var(--border-color-primary); border-radius: 8px; }
+.oe-raw { border: none !important; }
+.oe-visual { flex: none !important; width: auto !important; min-width: 0 !important; }
+.dark { --color-accent: #3fb950; }
+footer { display: none !important; }
+"""