Deploy from feature/updates branch (PR #132)

Dockerfile

@@ -1,13 +1,17 @@
+# Use OpenEnv base image
 ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
 FROM ${BASE_IMAGE}
 
-COPY core/ /app/src/core/
-COPY src/envs/wildfire_env/ /app/src/envs/wildfire_env/
+# Copy all source files
+COPY src/ /app/src/
 COPY README.md /app/README.md
 
+# Set environment variables
 ENV ENABLE_WEB_INTERFACE=true
 
+# Health check
 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
     CMD curl -f http://localhost:8000/health || exit 1
 
+# Run the wildfire environment server
 CMD ["sh", "-lc", "python -m uvicorn envs.wildfire_env.server.app:app --host 0.0.0.0 --port ${PORT:-8000} --proxy-headers --forwarded-allow-ips='*'"]

core/env_server/http_server.py

@@ -1,257 +0,0 @@
-# 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.
-
-"""
-HTTP server wrapper for Environment instances.
-
-This module provides utilities to wrap any Environment subclass and expose it
-over HTTP endpoints that HTTPEnvClient can consume.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import os
-from concurrent.futures import ThreadPoolExecutor
-from dataclasses import asdict
-from typing import Any, Dict, Type
-
-from .interfaces import Environment
-from .types import Action, Observation
-from fastapi import Body, FastAPI
-
-class HTTPEnvServer:
-    """
-    HTTP server wrapper for Environment instances.
-
-    This class wraps an Environment and exposes its reset(), step(), and state
-    methods as HTTP endpoints compatible with HTTPEnvClient.
-
-    The server expects:
-    - Action deserialization: Converts JSON dict to Action subclass
-    - Observation serialization: Converts Observation subclass to JSON dict
-
-    Example:
-        >>> from core.env_server import HTTPEnvServer
-        >>> from envs.coding_env.server import CodeExecutionEnvironment
-        >>>
-        >>> env = CodeExecutionEnvironment()
-        >>> server = HTTPEnvServer(env)
-        >>>
-        >>> # Register routes with FastAPI
-        >>> from fastapi import FastAPI
-        >>> app = FastAPI()
-        >>> server.register_routes(app)
-    """
-
-    def __init__(
-        self,
-        env: Environment,
-        action_cls: Type[Action],
-        observation_cls: Type[Observation],
-    ):
-        """
-        Initialize HTTP server wrapper.
-
-        Args:
-            env: The Environment instance to wrap
-            action_cls: The Action subclass this environment expects
-            observation_cls: The Observation subclass this environment returns
-        """
-        self.env = env
-        self.action_cls = action_cls
-        self.observation_cls = observation_cls
-        # Create thread pool for running sync code in async context
-        # This is needed for environments using sync libraries (e.g., Playwright sync API)
-        self._executor = ThreadPoolExecutor(max_workers=1)
-
-    def register_routes(self, app: Any) -> None:
-        """
-        Register HTTP routes on a FastAPI application.
-
-        Args:
-            app: FastAPI application instance
-        """
-
-        if not isinstance(app, FastAPI):
-            raise TypeError("app must be a FastAPI instance")
-
-        @app.post("/reset")
-        async def reset(request: Dict[str, Any] = Body(default={})) -> Dict[str, Any]:
-            """Reset endpoint - returns initial observation."""
-            # TODO: Handle seed, episode_id from request if provided
-            # Run sync environment code in thread pool to avoid blocking asyncio loop
-            loop = asyncio.get_event_loop()
-            observation = await loop.run_in_executor(self._executor, self.env.reset)
-            return self._serialize_observation(observation)
-
-        @app.post("/step")
-        async def step(request: Dict[str, Any]) -> Dict[str, Any]:
-            """Step endpoint - executes action and returns observation."""
-            # Support both {"action": {...}} and direct action fields
-            action_data = request.get("action", request)
-            # TODO: Handle timeout_s, request_id, episode_id from request if provided
-
-            # Deserialize action
-            action = self._deserialize_action(action_data)
-
-            # Execute step in thread pool to avoid blocking asyncio loop
-            loop = asyncio.get_event_loop()
-            observation = await loop.run_in_executor(
-                self._executor, self.env.step, action
-            )
-
-            # Return serialized observation
-            return self._serialize_observation(observation)
-
-        @app.get("/state")
-        async def get_state() -> Dict[str, Any]:
-            """State endpoint - returns current environment state."""
-            state = self.env.state
-            return asdict(state)
-
-        @app.get("/health")
-        async def health() -> Dict[str, str]:
-            """Health check endpoint."""
-            return {"status": "healthy"}
-
-
-    def _deserialize_action(self, action_data: Dict[str, Any]) -> Action:
-        """
-        Convert JSON dict to Action instance.
-
-        Args:
-            action_data: Dictionary containing action data
-
-        Returns:
-            Action instance
-
-        Note:
-            This is a simple implementation. Subclasses may need to override
-            for more complex deserialization logic.
-        """
-        # Remove metadata if present (it will be set via kw_only field)
-        metadata = action_data.pop("metadata", {})
-        action = self.action_cls(**action_data)
-        action.metadata = metadata
-        return action
-
-    def _serialize_observation(self, observation: Observation) -> Dict[str, Any]:
-        """
-        Convert Observation instance to JSON-compatible dict.
-
-        Args:
-            observation: Observation instance
-
-        Returns:
-            Dictionary compatible with HTTPEnvClient._parse_result()
-
-        The format matches what HTTPEnvClient expects:
-        {
-            "observation": {...},  # Observation fields
-            "reward": float | None,
-            "done": bool,
-        }
-        """
-        obs_dict = asdict(observation)
-
-        # Convert numpy arrays to lists for JSON serialization
-        def _convert_numpy(obj):
-            """Recursively convert numpy arrays to lists."""
-            if hasattr(obj, '__array__'):  # numpy array
-                return obj.tolist()
-            elif isinstance(obj, dict):
-                return {k: _convert_numpy(v) for k, v in obj.items()}
-            elif isinstance(obj, (list, tuple)):
-                return type(obj)(_convert_numpy(item) for item in obj)
-            return obj
-
-        obs_dict = _convert_numpy(obs_dict)
-
-        # Extract reward and done (these are part of StepResult on client side)
-        reward = obs_dict.pop("reward", None)
-        done = obs_dict.pop("done", False)
-        obs_dict.pop("metadata", None)  # Remove metadata from observation
-
-        # Return in HTTPEnvClient expected format
-        return {
-            "observation": obs_dict,
-            "reward": reward,
-            "done": done,
-        }
-
-def create_app(
-    env: Environment,
-    action_cls: Type[Action],
-    observation_cls: Type[Observation],
-    env_name: Optional[str] = None,
-) -> Any:
-    """
-    Create a FastAPI application with or without web interface.
-    
-    This function creates a FastAPI app with the web interface enabled by default,
-    including README integration for better user experience.
-    
-    Args:
-        env: The Environment instance to serve
-        action_cls: The Action subclass this environment expects
-        observation_cls: The Observation subclass this environment returns
-        env_name: Optional environment name for README loading
-        
-    Returns:
-        FastAPI application instance with or without web interface and README integration
-    """
-    # Check if web interface should be enabled
-    # This can be controlled via environment variable or build argument
-    enable_web = (
-        os.getenv("ENABLE_WEB_INTERFACE", "false").lower() in ("true", "1", "yes")
-    )
-
-    if enable_web:
-        # Import web interface only when needed
-        from .web_interface import create_web_interface_app
-        return create_web_interface_app(env, action_cls, observation_cls, env_name)
-    else:
-        # Use standard FastAPI app without web interface
-        return create_fastapi_app(env, action_cls, observation_cls)
-    
-
-def create_fastapi_app(
-    env: Environment,
-    action_cls: Type[Action],
-    observation_cls: Type[Observation],
-) -> Any:
-    """
-    Create a FastAPI application with routes for the given environment.
-
-    Args:
-        env: The Environment instance to serve
-        action_cls: The Action subclass this environment expects
-        observation_cls: The Observation subclass this environment returns
-
-    Returns:
-        FastAPI application instance with routes registered
-
-    Example:
-        >>> from envs.coding_env.server import CodeExecutionEnvironment
-        >>> from envs.coding_env.models import CodeAction, CodeObservation
-        >>>
-        >>> env = CodeExecutionEnvironment()
-        >>> app = create_fastapi_app(env, CodeAction, CodeObservation)
-        >>>
-        >>> # Run with: uvicorn module:app --host 0.0.0.0 --port 8000
-    """
-    try:
-        from fastapi import FastAPI
-    except ImportError:
-        raise ImportError(
-            "FastAPI is required. Install with: pip install fastapi uvicorn"
-        )
-
-    app = FastAPI(title="Environment HTTP Server")
-    server = HTTPEnvServer(env, action_cls, observation_cls)
-    server.register_routes(app)
-    return app

core/env_server/types.py

@@ -1,57 +0,0 @@
-# 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.
-
-from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional, Union
-
-
-# Type aliases
-Scalar = Union[int, float, bool]
-
-
-@dataclass(kw_only=True)
-class Action:
-    """Base class for all environment actions."""
-
-    metadata: Dict[str, Any] = field(default_factory=dict)
-
-
-@dataclass(kw_only=True)
-class Observation:
-    """Base class for all environment observations."""
-
-    done: bool = False
-    reward: Union[bool, int, float, None] = None
-    metadata: Dict[str, Any] = field(default_factory=dict)
-
-
-@dataclass
-class State:
-    """Base class for environment state."""
-
-    episode_id: Optional[str] = None
-    step_count: int = 0
-
-
-@dataclass
-class CodeExecResult:
-    """Result of code execution containing stdout, stderr, and exit code."""
-
-    stdout: str
-    stderr: str
-    exit_code: int
-
-
-@dataclass
-class EnvironmentMetadata:
-    """Metadata about an environment for documentation and UI purposes."""
-    
-    name: str
-    description: str
-    readme_content: Optional[str] = None
-    version: Optional[str] = None
-    author: Optional[str] = None
-    documentation_url: Optional[str] = None

core/http_env_client.py

@@ -1,203 +0,0 @@
-"""
-core/runner_env.py
-Minimal HTTP-based environment client.
-- Talks to a single env worker exposing: POST /reset, POST /step
-
-Future hooks (commented below) for:
-- episode_id, seed on reset
-- request_id on step
-- custom headers (auth/trace)
-"""
-
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from typing import Any, Dict, Generic, Optional, Type, TYPE_CHECKING, TypeVar
-
-import requests
-
-from .client_types import StepResult
-from .containers.runtime import LocalDockerProvider
-
-if TYPE_CHECKING:
-    from .containers.runtime import ContainerProvider
-
-ActT = TypeVar("ActT")
-ObsT = TypeVar("ObsT")
-EnvClientT = TypeVar("EnvClientT", bound="HTTPEnvClient")
-
-
-class HTTPEnvClient(ABC, Generic[ActT, ObsT]):
-    def __init__(
-        self,
-        base_url: str,
-        request_timeout_s: float = 15.0,
-        default_headers: Optional[Dict[str, str]] = None,
-        provider: Optional["ContainerProvider"] = None,
-    ):
-        self._base = base_url.rstrip("/")
-        self._timeout = float(request_timeout_s)
-        self._http = requests.Session()
-        self._headers = default_headers or {}
-        self._provider = provider
-
-    @classmethod
-    def from_docker_image(
-        cls: Type[EnvClientT],
-        image: str,
-        provider: Optional["ContainerProvider"] = None,
-        **kwargs: Any,
-    ) -> EnvClientT:
-        """
-        Create an environment client by spinning up a Docker container locally.
-
-        This is a development utility that:
-        1. Starts a Docker container from the specified image
-        2. Waits for the server to be ready
-        3. Creates and returns a client instance connected to the container
-
-        Note: The container lifecycle management is left to the user or higher-level
-        orchestration. The container will keep running until manually stopped.
-
-        Args:
-            image: Docker image name to run (e.g., "echo-env:latest")
-            provider: Container provider to use (defaults to LocalDockerProvider)
-            **kwargs: Additional arguments to pass to provider.start_container()
-                     (e.g., env_vars, port)
-
-        Returns:
-            An instance of the client class connected to the running container
-
-        Example:
-            >>> from envs.coding_env.client import CodingEnv
-            >>> from envs.coding_env.models import CodeAction
-            >>>
-            >>> # Create environment from image
-            >>> env = CodingEnv.from_docker_image("coding-env:latest")
-            >>>
-            >>> # Create environment with custom env vars
-            >>> env = CodingEnv.from_docker_image(
-            ...     "coding-env:latest",
-            ...     env_vars={"MY_VAR": "value"}
-            ... )
-            >>>
-            >>> # Use the environment
-            >>> result = env.reset()
-            >>> print(result.observation)
-            >>>
-            >>> step_result = env.step(CodeAction(code="print('hello')"))
-            >>> print(step_result.observation.stdout)
-            >>>
-            >>> # Cleanup (optional)
-            >>> env.close()
-        """
-
-        # Use default provider if none provided
-        if provider is None:
-            provider = LocalDockerProvider()
-
-        # 1. Start container with optional kwargs (e.g., env_vars, port)
-        base_url = provider.start_container(image, **kwargs)
-
-        # 2. Wait for server to be ready
-        provider.wait_for_ready(base_url)
-
-        # 3. Create and return client instance with provider reference
-        return cls(base_url=base_url, provider=provider)
-
-    @classmethod
-    def from_hub(cls: Type[EnvClientT], repo_id: str, provider: Optional["ContainerProvider"] = None, **kwargs: Any) -> EnvClientT:
-        """
-        Create an environment client by pulling from a Hugging Face model hub.
-        """
-        
-        if provider is None:
-            provider = LocalDockerProvider()
-        
-        if "tag" in kwargs:
-            tag = kwargs["tag"]
-        else:
-            tag = "latest"
-        
-        base_url = f"registry.hf.space/{repo_id.replace('/', '-')}:{tag}"
-        
-        return cls.from_docker_image(image=base_url, provider=provider)
-
-    @abstractmethod
-    def _step_payload(self, action: ActT) -> dict:
-        """Convert an Action object to the JSON body expected by the env server."""
-        raise NotImplementedError
-
-    @abstractmethod
-    def _parse_result(self, payload: dict) -> StepResult[ObsT]:
-        """Convert a JSON response from the env server to StepResult[ObsT]."""
-        raise NotImplementedError
-
-    @abstractmethod
-    def _parse_state(self, payload: dict) -> Any:
-        """Convert a JSON response from the state endpoint to a State object."""
-        raise NotImplementedError
-
-    # ---------- Environment Server Interface Methods ----------
-    def reset(self) -> StepResult[ObsT]:
-        body: Dict[str, Any] = {}
-        # TODO: later:
-        # body["seed"] = seed
-        # body["episode_id"] = episode_id
-        r = self._http.post(
-            f"{self._base}/reset",
-            json=body,
-            headers=self._headers,
-            timeout=self._timeout,
-        )
-        r.raise_for_status()
-        return self._parse_result(r.json())
-
-    def step(self, action: ActT) -> StepResult[ObsT]:
-        body: Dict[str, Any] = {
-            "action": self._step_payload(action),
-            "timeout_s": int(self._timeout),
-        }
-        # TODO: later:
-        # body["request_id"] = str(uuid.uuid4())
-        # body["episode_id"] = current_episode_id
-        r = self._http.post(
-            f"{self._base}/step",
-            json=body,
-            headers=self._headers,
-            timeout=self._timeout,
-        )
-        r.raise_for_status()
-        return self._parse_result(r.json())
-
-    def state(self) -> Any:
-        """
-        Get the current environment state from the server.
-
-        Returns:
-            State object with environment state information (e.g., episode_id, step_count)
-
-        Example:
-            >>> client = EchoEnv.from_docker_image("echo-env:latest")
-            >>> result = client.reset()
-            >>> state = client.state()
-            >>> print(state.episode_id)
-            >>> print(state.step_count)
-        """
-        r = self._http.get(
-            f"{self._base}/state",
-            headers=self._headers,
-            timeout=self._timeout,
-        )
-        r.raise_for_status()
-        return self._parse_state(r.json())
-
-    def close(self) -> None:
-        """
-        Close the environment and clean up resources.
-
-        If this client was created via from_docker_image(), this will stop
-        and remove the associated container.
-        """
-        if self._provider is not None:
-            self._provider.stop_container()

core/pyproject.toml

@@ -1,47 +0,0 @@
-[build-system]
-requires = ["setuptools>=45", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "openenv-core"
-version = "0.1.0"
-description = "Core components for OpenEnv - HTTP-based agentic environments"
-readme = "README.md"
-requires-python = ">=3.10"
-license = {text = "BSD-3-Clause"}
-authors = [
-    {name = "Meta Platforms, Inc.", email = "opensource@meta.com"}
-]
-keywords = ["environment", "agent", "http", "docker", "fastapi"]
-
-dependencies = [
-    "fastapi>=0.104.0",
-    "pydantic>=2.0.0",
-    "uvicorn[standard]>=0.24.0",
-    "requests>=2.25.0",
-]
-
-[project.optional-dependencies]
-dev = [
-    "pytest>=7.0.0",
-    "black>=23.0.0",
-    "ruff>=0.1.0",
-    "mypy>=1.0.0",
-]
-
-[project.urls]
-Homepage = "https://github.com/facebookresearch/OpenEnv"
-Repository = "https://github.com/facebookresearch/OpenEnv"
-Documentation = "https://github.com/facebookresearch/OpenEnv/blob/main/README.md"
-"Bug Tracker" = "https://github.com/facebookresearch/OpenEnv/issues"
-
-[tool.setuptools]
-py-modules = ["openenv_core.__init__", "openenv_core.http_env_client", "openenv_core.client_types"]
-packages = [
-    "openenv_core",
-    "openenv_core.containers",
-    "openenv_core.containers.runtime",
-    "openenv_core.env_server",
-    "openenv_core.tools"
-]
-package-dir = {"openenv_core" = "."}

{core → src/core}/README.md

@@ -6,7 +6,7 @@ In addition to making it easier for researchers and RL framework writers, we als
 
 
 ## 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` provides the foundational building blocks for creating and interacting with containerized environments over HTTP. It enables you to build agent environments that can be deployed as Docker containers and accessed via a simple HTTP API.
 
 > ⚠️ **Early Development Warning** OpenEnv is currently in an experimental
 > stage. You should expect bugs, incomplete features, and APIs that may change
@@ -22,8 +22,8 @@ Core components for OpenEnv - a framework for building HTTP-based agentic enviro
 
 ## Features
 
-- **HTTPEnvClient**: Generic HTTP client for interacting with remote environments
-- **HTTPEnvServer**: FastAPI-based server wrapper for exposing environments over HTTP
+- **EnvClient**: Generic client for interacting with remote environments
+- **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
@@ -31,12 +31,12 @@ Core components for OpenEnv - a framework for building HTTP-based agentic enviro
 ## Installation
 
 ```bash
-pip install openenv-core
+pip install "openenv[core]"
 ```
 
 For development:
 ```bash
-pip install openenv-core[dev]
+pip install "openenv[core]"
 ```
 
 ## Quick Start
@@ -44,7 +44,7 @@ pip install openenv-core[dev]
 ### Creating an Environment Client
 
 ```python
-from openenv_core import HTTPEnvClient, StepResult
+from openenv.core import EnvClient, StepResult
 from dataclasses import dataclass
 
 @dataclass
@@ -55,7 +55,7 @@ class MyAction:
 class MyObservation:
     response: str
 
-class MyEnvClient(HTTPEnvClient[MyAction, MyObservation]):
+class MyEnvClient(EnvClient[MyAction, MyObservation]):
     def _step_payload(self, action: MyAction) -> dict:
         return {"text": action.text}
 
@@ -80,7 +80,7 @@ env.close()
 ### Creating an Environment Server
 
 ```python
-from openenv_core.env_server import Environment, HTTPEnvServer, create_app
+from openenv.core.env_server import Environment, HTTPEnvServer, create_app
 from dataclasses import dataclass
 
 @dataclass
@@ -118,7 +118,7 @@ OpenEnv Core supports multiple container providers:
 ### Local Docker Provider
 
 ```python
-from openenv_core.containers.runtime import LocalDockerProvider
+from openenv.core.containers.runtime import LocalDockerProvider
 
 provider = LocalDockerProvider()
 base_url = provider.start_container("my-env:latest")
@@ -130,7 +130,7 @@ provider.stop_container()
 ### Kubernetes Provider (Coming Soon)
 
 ```python
-from openenv_core.containers.runtime import KubernetesProvider
+from openenv.core.containers.runtime import KubernetesProvider
 
 provider = KubernetesProvider(namespace="envs")
 base_url = provider.start_container("my-env:latest")
@@ -141,7 +141,7 @@ provider.stop_container()
 
 ## API Reference
 
-### HTTPEnvClient
+### EnvClient
 
 Base class for environment clients with these abstract methods:
 

{core → src/core}/__init__.py

@@ -7,13 +7,10 @@
 """Core components for agentic environments."""
 
 # Re-export main components from submodules for convenience
-from .env_server import *
-from .client_types import StepResult
-from .http_env_client import HTTPEnvClient
+from .env_server import *  # noqa: F403
+from . import env_server
+from .env_client import EnvClient
 
 # Note: MCP module doesn't export anything yet
 
-__all__ = [
-    "HTTPEnvClient",
-    "StepResult",
-]
+__all__ = ["EnvClient"] + env_server.__all__  # type: ignore

{core → src/core}/client_types.py

@@ -1,9 +1,10 @@
 # Type definitions for EnvTorch
 from dataclasses import dataclass
-from typing import Any, Generic, Optional, TypeVar
+from typing import Generic, Optional, TypeVar
 
 # Generic type for observations
-ObsT = TypeVar("ObsT")  # TypeVar for typehinting in IDEs
+ObsT = TypeVar("ObsT")
+StateT = TypeVar("StateT")
 
 
 @dataclass

src/core/containers/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Container management for environment servers."""

{core → src/core}/containers/images/README.md

@@ -48,7 +48,7 @@ FROM openenv-base:latest
 
 # Copy only environment-specific files
 COPY src/core/ /app/src/core/
-COPY src/envs/my_env/ /app/src/envs/my_env/
+COPY 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"]
@@ -69,7 +69,7 @@ CMD ["uvicorn", "envs.my_env.server.app:app", "--host", "0.0.0.0", "--port", "80
 docker build -t openenv-base:latest -f src/core/containers/images/Dockerfile .
 
 # Step 2: Build echo environment (uses base)
-docker build -t echo-env:latest -f src/envs/echo_env/server/Dockerfile .
+docker build -t echo-env:latest -f envs/echo_env/server/Dockerfile .
 
 # Step 3: Run echo environment
 docker run -p 8000:8000 echo-env:latest
@@ -88,5 +88,5 @@ When dependencies need updating:
 docker build -t openenv-base:latest -f src/core/containers/images/Dockerfile .
 
 # Rebuild environments (they automatically use new base)
-docker build -t echo-env:latest -f src/envs/echo_env/server/Dockerfile .
+docker build -t echo-env:latest -f envs/echo_env/server/Dockerfile .
 ```

{core → src/core}/containers/runtime/__init__.py

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

{core → src/core}/containers/runtime/providers.py

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

src/core/containers/runtime/uv_provider.py

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

{core → src/core}/containers/test_local_docker_provider.py

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

src/core/env_client.py

@@ -0,0 +1,361 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Environment client for persistent sessions.
+
+This module provides a WebSocket-based client that maintains a persistent connection
+to an environment server, enabling efficient multi-step interactions without
+the overhead of HTTP request/response cycles.
+"""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Generic, Optional, Type, TYPE_CHECKING, TypeVar
+
+from .client_types import StepResult, StateT
+from .containers.runtime import LocalDockerProvider, UVProvider
+from .utils import convert_to_ws_url
+
+if TYPE_CHECKING:
+    from .containers.runtime import ContainerProvider, RuntimeProvider
+    from websockets.sync.client import ClientConnection
+
+from websockets.sync.client import connect as ws_connect
+
+ActT = TypeVar("ActT")
+ObsT = TypeVar("ObsT")
+EnvClientT = TypeVar("EnvClientT", bound="EnvClient")
+
+
+class EnvClient(ABC, Generic[ActT, ObsT, StateT]):
+    """
+    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.
+
+    Features:
+    - Lower latency for sequential interactions
+    - Session state is maintained server-side
+    - Better suited for long-running episodes
+
+    Example:
+        >>> from envs.coding_env.client import CodingEnv
+        >>>
+        >>> # Connect to a server
+        >>> with CodingEnv(base_url="ws://localhost:8000") as env:
+        ...     result = env.reset(seed=42)
+        ...     while not result.done:
+        ...         action = agent.predict(result.observation)
+        ...         result = env.step(action)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        connect_timeout_s: float = 10.0,
+        message_timeout_s: float = 60.0,
+        provider: Optional["ContainerProvider | RuntimeProvider"] = None,
+    ):
+        """
+        Initialize environment client.
+
+        Args:
+            base_url: Base URL of the environment server (http:// or ws://).
+                     Will be converted to ws:// if http:// is provided.
+            connect_timeout_s: Timeout for establishing WebSocket connection
+            message_timeout_s: Timeout for receiving responses to messages
+            provider: Optional container/runtime provider for lifecycle management.
+                     Can be a ContainerProvider (Docker) or RuntimeProvider (UV).
+        """
+        # Convert HTTP URL to WebSocket URL
+        ws_url = convert_to_ws_url(base_url)
+
+        self._ws_url = f"{ws_url}/ws"
+        self._connect_timeout = connect_timeout_s
+        self._message_timeout = message_timeout_s
+        self._provider = provider
+        self._ws: Optional[ClientConnection] = None
+
+    def connect(self) -> "EnvClient":
+        """
+        Establish WebSocket connection to the server.
+
+        Returns:
+            self for method chaining
+
+        Raises:
+            ConnectionError: If connection cannot be established
+        """
+        if self._ws is not None:
+            return self
+
+        try:
+            self._ws = ws_connect(
+                self._ws_url,
+                open_timeout=self._connect_timeout,
+            )
+        except Exception as e:
+            raise ConnectionError(f"Failed to connect to {self._ws_url}: {e}") from e
+
+        return self
+
+    def disconnect(self) -> None:
+        """Close the WebSocket connection."""
+        if self._ws is not None:
+            try:
+                # Send close message
+                self._send({"type": "close"})
+            except Exception:
+                pass  # Best effort
+            try:
+                self._ws.close()
+            except Exception:
+                pass
+            self._ws = None
+
+    def _ensure_connected(self) -> None:
+        """Ensure WebSocket connection is established."""
+        if self._ws is None:
+            self.connect()
+
+    def _send(self, message: Dict[str, Any]) -> None:
+        """Send a message over the WebSocket."""
+        self._ensure_connected()
+        assert self._ws is not None
+        self._ws.send(json.dumps(message))
+
+    def _receive(self) -> Dict[str, Any]:
+        """Receive and parse a message from the WebSocket."""
+        assert self._ws is not None
+        raw = self._ws.recv(timeout=self._message_timeout)
+        return json.loads(raw)
+
+    def _send_and_receive(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Send a message and wait for response."""
+        self._send(message)
+        response = 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 from_docker_image(
+        cls: Type[EnvClientT],
+        image: str,
+        provider: Optional["ContainerProvider"] = None,
+        **kwargs: Any,
+    ) -> EnvClientT:
+        """
+        Create an environment client by spinning up a Docker container.
+
+        Args:
+            image: Docker image name to run (e.g., "coding-env:latest")
+            provider: Container provider to use (defaults to LocalDockerProvider)
+            **kwargs: Additional arguments to pass to provider.start_container()
+
+        Returns:
+            Connected client instance
+        """
+        if provider is None:
+            provider = LocalDockerProvider()
+
+        # Start container
+        base_url = provider.start_container(image, **kwargs)
+
+        # Wait for server to be ready
+        provider.wait_for_ready(base_url)
+
+        # Create and connect client
+        client = cls(base_url=base_url, provider=provider)
+        client.connect()
+
+        return client
+
+    @classmethod
+    def from_hub(
+        cls: Type[EnvClientT],
+        repo_id: str,
+        *,
+        use_docker: bool = True,
+        provider: Optional["ContainerProvider | RuntimeProvider"] = None,
+        **provider_kwargs: Any,
+    ) -> EnvClientT:
+        """
+        Create a client from a Hugging Face Space.
+
+        Args:
+            repo_id: Hugging Face space identifier ``{org}/{space}``.
+            use_docker: When ``True`` (default) pull from the HF registry and
+                launch via :class:`LocalDockerProvider`. When ``False`` run the
+                space locally with :class:`UVProvider`.
+            provider: Optional provider instance to reuse. Must be a
+                :class:`ContainerProvider` when ``use_docker=True`` and a
+                :class:`RuntimeProvider` otherwise.
+            provider_kwargs: Additional keyword arguments forwarded to
+                either the container provider's ``start_container`` (docker)
+                or to the ``UVProvider`` constructor/start (uv). When
+                ``use_docker=False``, the ``project_path`` argument can be
+                used to override the default git URL
+                (``git+https://huggingface.co/spaces/{repo_id}``).
+
+        Returns:
+            Connected client instance
+
+        Examples:
+            >>> # Pull and run from HF Docker registry
+            >>> env = MyEnv.from_hub("openenv/echo-env")
+            >>>
+            >>> # Run locally with UV (clones the space)
+            >>> env = MyEnv.from_hub("openenv/echo-env", use_docker=False)
+            >>>
+            >>> # Run from a local checkout
+            >>> env = MyEnv.from_hub(
+            ...     "openenv/echo-env",
+            ...     use_docker=False,
+            ...     project_path="/path/to/local/checkout"
+            ... )
+        """
+        # Extract start args that apply to both providers
+        start_args = {}
+        for key in ("port", "env_vars", "workers"):
+            if key in provider_kwargs:
+                start_args[key] = provider_kwargs.pop(key)
+
+        if use_docker:
+            # Docker mode: pull from HF registry
+            docker_provider = provider or LocalDockerProvider()
+            tag = provider_kwargs.pop("tag", "latest")
+            image = f"registry.hf.space/{repo_id.replace('/', '-')}:{tag}"
+            base_url = docker_provider.start_container(
+                image, **start_args, **provider_kwargs
+            )
+            docker_provider.wait_for_ready(base_url)
+
+            client = cls(base_url=base_url, provider=docker_provider)
+            client.connect()
+            return client
+        else:
+            # UV mode: clone and run with uv
+            if provider is None:
+                uv_kwargs = dict(provider_kwargs)
+                project_path = uv_kwargs.pop("project_path", None)
+                if project_path is None:
+                    project_path = f"git+https://huggingface.co/spaces/{repo_id}"
+
+                provider = UVProvider(project_path=project_path, **uv_kwargs)
+            else:
+                if provider_kwargs:
+                    raise ValueError(
+                        "provider_kwargs cannot be used when supplying a provider instance"
+                    )
+
+            base_url = provider.start(**start_args)
+            provider.wait_for_ready()
+
+            client = cls(base_url=base_url, provider=provider)
+            client.connect()
+            return client
+
+    @abstractmethod
+    def _step_payload(self, action: ActT) -> Dict[str, Any]:
+        """Convert an Action object to the JSON data expected by the env server."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[ObsT]:
+        """Convert a JSON response from the env server to StepResult[ObsT]."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def _parse_state(self, payload: Dict[str, Any]) -> StateT:
+        """Convert a JSON response from the state endpoint to a State object."""
+        raise NotImplementedError
+
+    def reset(self, **kwargs: Any) -> StepResult[ObsT]:
+        """
+        Reset the environment with optional parameters.
+
+        Args:
+            **kwargs: Optional parameters passed to the environment's reset method.
+                     Common parameters include:
+                     - seed: Random seed for reproducibility
+                     - episode_id: Custom episode identifier
+
+        Returns:
+            StepResult containing initial observation
+        """
+        message = {
+            "type": "reset",
+            "data": kwargs,
+        }
+        response = self._send_and_receive(message)
+        return self._parse_result(response.get("data", {}))
+
+    def step(self, action: ActT, **kwargs: Any) -> StepResult[ObsT]:
+        """
+        Execute an action in the environment.
+
+        Args:
+            action: The action to execute
+            **kwargs: Optional parameters (currently ignored)
+
+        Returns:
+            StepResult containing observation, reward, and done status
+        """
+        message = {
+            "type": "step",
+            "data": self._step_payload(action),
+        }
+        response = self._send_and_receive(message)
+        return self._parse_result(response.get("data", {}))
+
+    def state(self) -> StateT:
+        """
+        Get the current environment state from the server.
+
+        Returns:
+            State object with environment state information
+        """
+        message = {"type": "state"}
+        response = self._send_and_receive(message)
+        return self._parse_state(response.get("data", {}))
+
+    def close(self) -> None:
+        """
+        Close the WebSocket connection and clean up resources.
+
+        If this client was created via from_docker_image() or from_hub(),
+        this will also stop and remove the associated container/process.
+        """
+        self.disconnect()
+
+        if self._provider is not None:
+            # Handle both ContainerProvider and RuntimeProvider
+            if hasattr(self._provider, "stop_container"):
+                self._provider.stop_container()
+            elif hasattr(self._provider, "stop"):
+                self._provider.stop()
+
+    def __enter__(self) -> "EnvClient":
+        """Enter context manager, ensuring connection is established."""
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit context manager, closing connection."""
+        self.close()

{core → src/core}/env_server/__init__.py

@@ -9,7 +9,39 @@
 from .base_transforms import CompositeTransform, NullTransform
 from .http_server import HTTPEnvServer, create_app, create_fastapi_app
 from .interfaces import Environment, Message, ModelTokenizer, Transform
-from .types import Action, Observation, State
+from .route_config import GetEndpointConfig
+from .serialization import (
+    deserialize_action,
+    deserialize_action_with_preprocessing,
+    serialize_observation,
+)
+from .types import (
+    Action,
+    Observation,
+    State,
+    SchemaResponse,
+    HealthResponse,
+    BaseMessage,
+    WSIncomingMessage,
+    WSResetMessage,
+    WSStepMessage,
+    WSStateMessage,
+    WSCloseMessage,
+    WSObservationResponse,
+    WSStateResponse,
+    WSErrorResponse,
+    ConcurrencyConfig,
+    ServerCapacityStatus,
+    SessionInfo,
+)
+from .exceptions import (
+    OpenEnvError,
+    ConcurrencyConfigurationError,
+    SessionCapacityError,
+    SessionNotFoundError,
+    SessionCreationError,
+    EnvironmentFactoryError,
+)
 from .web_interface import create_web_interface_app, WebInterfaceManager
 
 __all__ = [
@@ -22,6 +54,29 @@ __all__ = [
     "Action",
     "Observation",
     "State",
+    "SchemaResponse",
+    "HealthResponse",
+    # WebSocket message types
+    "BaseMessage",
+    "WSIncomingMessage",
+    "WSResetMessage",
+    "WSStepMessage",
+    "WSStateMessage",
+    "WSCloseMessage",
+    "WSObservationResponse",
+    "WSStateResponse",
+    "WSErrorResponse",
+    # Concurrency types
+    "ConcurrencyConfig",
+    "ServerCapacityStatus",
+    "SessionInfo",
+    # Exceptions
+    "OpenEnvError",
+    "ConcurrencyConfigurationError",
+    "SessionCapacityError",
+    "SessionNotFoundError",
+    "SessionCreationError",
+    "EnvironmentFactoryError",
     # Base transforms
     "CompositeTransform",
     "NullTransform",
@@ -32,4 +87,10 @@ __all__ = [
     # Web Interface
     "create_web_interface_app",
     "WebInterfaceManager",
+    # Serialization utilities
+    "deserialize_action",
+    "deserialize_action_with_preprocessing",
+    "serialize_observation",
+    # Route configuration
+    "GetEndpointConfig",
 ]

{core → src/core}/env_server/base_transforms.py

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

src/core/env_server/exceptions.py

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

src/core/env_server/http_server.py

@@ -0,0 +1,935 @@
+# 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.
+
+"""
+HTTP server wrapper for Environment instances.
+
+This module provides utilities to wrap any Environment subclass and expose it
+over HTTP and WebSocket endpoints that EnvClient can consume.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import os
+import time
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Dict, Optional, Type, Union
+
+from fastapi import Body, FastAPI, HTTPException, WebSocket, WebSocketDisconnect, status
+from pydantic import ValidationError
+
+from .interfaces import Environment
+from .route_config import (
+    GetEndpointConfig,
+    register_get_endpoints,
+)
+from .serialization import deserialize_action, serialize_observation
+from .types import (
+    Action,
+    Observation,
+    ResetRequest,
+    ResetResponse,
+    State,
+    StepRequest,
+    StepResponse,
+    EnvironmentMetadata,
+    SchemaResponse,
+    HealthResponse,
+    WSResetMessage,
+    WSStepMessage,
+    WSStateMessage,
+    WSCloseMessage,
+    WSObservationResponse,
+    WSStateResponse,
+    WSErrorResponse,
+    ConcurrencyConfig,
+    ServerCapacityStatus,
+    SessionInfo,
+)
+from .exceptions import (
+    ConcurrencyConfigurationError,
+    SessionCapacityError,
+    EnvironmentFactoryError,
+)
+
+
+class HTTPEnvServer:
+    """
+    HTTP server wrapper for Environment instances.
+
+    This class wraps an Environment and exposes its reset(), step(), and state
+    methods as HTTP and WebSocket endpoints compatible with EnvClient.
+
+    The server expects:
+    - Action deserialization: Converts JSON dict to Action subclass
+    - Observation serialization: Converts Observation subclass to JSON dict
+
+    Example:
+        >>> from core.env_server import HTTPEnvServer
+        >>> from envs.coding_env.server import CodeExecutionEnvironment
+        >>> from envs.coding_env.models import CodeAction, CodeObservation
+        >>>
+        >>> # Pass environment class (factory pattern)
+        >>> server = HTTPEnvServer(
+        ...     env=CodeExecutionEnvironment,
+        ...     action_cls=CodeAction,
+        ...     observation_cls=CodeObservation,
+        ...     max_concurrent_envs=4,
+        ... )
+        >>>
+        >>> # Register routes with FastAPI
+        >>> from fastapi import FastAPI
+        >>> app = FastAPI()
+        >>> server.register_routes(app)
+    """
+
+    def __init__(
+        self,
+        env: Callable[[], Environment],
+        action_cls: Type[Action],
+        observation_cls: Type[Observation],
+        max_concurrent_envs: Optional[int] = None,
+        concurrency_config: Optional[ConcurrencyConfig] = None,
+    ):
+        """
+        Initialize HTTP server wrapper.
+
+        Args:
+            env: Environment factory (callable) that creates new instances.
+                 Will be called to create a new environment for each WebSocket session.
+            action_cls: The Action subclass this environment expects
+            observation_cls: The Observation subclass this environment returns
+            max_concurrent_envs: Maximum number of concurrent WebSocket sessions.
+                                 Mutually exclusive with concurrency_config.
+            concurrency_config: Optional ConcurrencyConfig for advanced concurrency settings.
+                                Mutually exclusive with max_concurrent_envs.
+
+        Raises:
+            ValueError: If both max_concurrent_envs and concurrency_config are provided.
+            ConcurrencyConfigurationError: If max_concurrent_envs > 1 for an
+                environment that is not marked as SUPPORTS_CONCURRENT_SESSIONS.
+        """
+        # Validate that env is callable
+        if not callable(env):
+            raise TypeError(
+                f"env must be a callable (class or factory function), got {type(env)}. "
+                f"Pass the environment class (e.g., MyEnvironment) not an instance (e.g., MyEnvironment())."
+            )
+
+        self._env_factory: Callable[[], Environment] = env
+
+        # Handle concurrency configuration
+        if max_concurrent_envs is not None and concurrency_config is not None:
+            raise ValueError(
+                "Cannot specify both 'max_concurrent_envs' and 'concurrency_config'. "
+                "Please use only one method to configure concurrency."
+            )
+
+        if concurrency_config is not None:
+            self._concurrency_config = concurrency_config
+        elif max_concurrent_envs is not None:
+            self._concurrency_config = ConcurrencyConfig(
+                max_concurrent_envs=max_concurrent_envs,
+                session_timeout=None,
+            )
+        else:
+            # Default configuration
+            self._concurrency_config = ConcurrencyConfig(
+                max_concurrent_envs=1,
+                session_timeout=None,
+            )
+
+        self._max_concurrent_envs = self._concurrency_config.max_concurrent_envs
+
+        # Validate concurrency configuration
+        self._validate_concurrency_safety()
+
+        self.action_cls = action_cls
+        self.observation_cls = observation_cls
+
+        # Session management for WebSocket connections
+        self._sessions: Dict[str, Environment] = {}
+        self._session_executors: Dict[str, ThreadPoolExecutor] = {}
+        self._session_info: Dict[str, SessionInfo] = {}
+        self._session_lock = asyncio.Lock()
+
+        # Create thread pool for running sync code in async context
+        # This is needed for environments using sync libraries (e.g., Playwright)
+        self._executor = ThreadPoolExecutor(max_workers=32)
+
+    def _validate_concurrency_safety(self) -> None:
+        """
+        Validate that the environment supports the configured concurrency level.
+
+        Raises:
+            ConcurrencyConfigurationError: If max_concurrent_envs > 1 for an
+                environment that is not marked as SUPPORTS_CONCURRENT_SESSIONS.
+        """
+        if self._max_concurrent_envs <= 1:
+            return
+
+        if inspect.isclass(self._env_factory):
+            env_cls = self._env_factory
+        else:
+            _temp_env = self._env_factory()
+            env_cls = type(_temp_env)
+            _temp_env.close()
+            del _temp_env
+
+        if not getattr(env_cls, "SUPPORTS_CONCURRENT_SESSIONS", False):
+            raise ConcurrencyConfigurationError(
+                environment_name=env_cls.__name__,
+                max_concurrent_envs=self._max_concurrent_envs,
+            )
+
+    def get_capacity_status(self) -> ServerCapacityStatus:
+        """
+        Get the current capacity status of the server.
+
+        Returns:
+            ServerCapacityStatus with current session counts and availability.
+        """
+        return ServerCapacityStatus.from_counts(
+            active=len(self._sessions),
+            max_sessions=self._max_concurrent_envs,
+        )
+
+    async def _run_sync_in_thread_pool(
+        self, func: Callable[..., Observation], *args, **kwargs
+    ) -> Observation:
+        """Run a synchronous function in the thread pool executor."""
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(self._executor, lambda: func(*args, **kwargs))
+
+    def _get_valid_kwargs(
+        self,
+        sig: inspect.Signature,
+        kwargs: Dict[str, Any],
+        skip_params: Optional[set[str]] = None,
+    ) -> Dict[str, Any]:
+        """Filter kwargs to only include parameters accepted by the function signature."""
+        if skip_params is None:
+            skip_params = set()
+
+        valid_kwargs = {}
+
+        has_kwargs = any(
+            p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+        )
+
+        for k, v in kwargs.items():
+            if k in sig.parameters or has_kwargs:
+                if k not in skip_params:
+                    valid_kwargs[k] = v
+
+        return valid_kwargs
+
+    async def _create_session(self) -> tuple[str, Environment]:
+        """
+        Create a new WebSocket session with its own environment instance.
+
+        Returns:
+            Tuple of (session_id, environment)
+
+        Raises:
+            SessionCapacityError: If max concurrent sessions reached
+            EnvironmentFactoryError: If the factory fails to create an environment
+        """
+        async with self._session_lock:
+            if len(self._sessions) >= self._max_concurrent_envs:
+                raise SessionCapacityError(
+                    active_sessions=len(self._sessions),
+                    max_sessions=self._max_concurrent_envs,
+                )
+
+            session_id = str(uuid.uuid4())
+            current_time = time.time()
+
+            try:
+                env = self._env_factory()
+            except Exception as e:
+                factory_name = getattr(
+                    self._env_factory, "__name__", str(self._env_factory)
+                )
+                raise EnvironmentFactoryError(factory_name) from e
+
+            self._sessions[session_id] = env
+
+            self._session_executors[session_id] = ThreadPoolExecutor(max_workers=1)
+
+            # Track session metadata
+            self._session_info[session_id] = SessionInfo(
+                session_id=session_id,
+                created_at=current_time,
+                last_activity_at=current_time,
+                step_count=0,
+                environment_type=type(env).__name__,
+            )
+
+            return session_id, env
+
+    async def _destroy_session(self, session_id: str) -> None:
+        """
+        Destroy a WebSocket session and cleanup resources.
+
+        Args:
+            session_id: The session ID to destroy
+        """
+        async with self._session_lock:
+            if session_id in self._sessions:
+                env = self._sessions.pop(session_id)
+                env.close()
+
+            if session_id in self._session_executors:
+                executor = self._session_executors.pop(session_id)
+                executor.shutdown(wait=False)
+
+            self._session_info.pop(session_id, None)
+
+    def _update_session_activity(
+        self, session_id: str, increment_step: bool = False
+    ) -> None:
+        """
+        Update session activity timestamp and optionally increment step count.
+
+        Args:
+            session_id: The session ID to update
+            increment_step: If True, increment the step count
+        """
+        if session_id in self._session_info:
+            self._session_info[session_id].last_activity_at = time.time()
+            if increment_step:
+                self._session_info[session_id].step_count += 1
+
+    def get_session_info(self, session_id: str) -> Optional[SessionInfo]:
+        """
+        Get information about a specific session.
+
+        Args:
+            session_id: The session ID to query
+
+        Returns:
+            SessionInfo if the session exists, None otherwise
+        """
+        return self._session_info.get(session_id)
+
+    async def _run_in_session_executor(
+        self, session_id: str, func: Callable[..., Observation], *args, **kwargs
+    ) -> Observation:
+        """Run a synchronous function in the session's thread pool executor."""
+        executor = self._session_executors.get(session_id, self._executor)
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(executor, lambda: func(*args, **kwargs))
+
+    @property
+    def active_sessions(self) -> int:
+        """Return the number of active WebSocket sessions."""
+        return len(self._sessions)
+
+    @property
+    def max_concurrent_envs(self) -> int:
+        """Return the maximum number of concurrent environments."""
+        return self._max_concurrent_envs
+
+    @property
+    def is_concurrency_safe(self) -> bool:
+        """Return whether the environment is marked as concurrency safe."""
+        import inspect
+
+        if inspect.isclass(self._env_factory):
+            return getattr(self._env_factory, "SUPPORTS_CONCURRENT_SESSIONS", False)
+        else:
+            _temp_env = self._env_factory()
+            result = getattr(_temp_env, "SUPPORTS_CONCURRENT_SESSIONS", False)
+            _temp_env.close()
+            del _temp_env
+            return result
+
+    @property
+    def concurrency_config(self) -> ConcurrencyConfig:
+        """Return the concurrency configuration."""
+        return self._concurrency_config
+
+    def register_routes(self, app: FastAPI) -> None:
+        """
+        Register HTTP routes on a FastAPI application.
+
+        Args:
+            app: FastAPI application instance
+        """
+
+        # Helper function to handle reset endpoint
+        async def reset_handler(
+            request: ResetRequest = Body(default_factory=ResetRequest),
+        ) -> ResetResponse:
+            """Reset endpoint - returns initial observation."""
+            _env = self._env_factory()
+
+            try:
+                kwargs = request.model_dump(exclude_unset=True)
+
+                is_async = _env.reset_async.__func__ is not Environment.reset_async
+
+                if is_async:
+                    sig = inspect.signature(_env.reset_async)
+                else:
+                    sig = inspect.signature(_env.reset)
+                valid_kwargs = self._get_valid_kwargs(sig, kwargs)
+
+                if is_async:
+                    observation = await _env.reset_async(**valid_kwargs)
+                else:
+                    observation = await self._run_sync_in_thread_pool(
+                        _env.reset, **valid_kwargs
+                    )
+                return ResetResponse(**serialize_observation(observation))
+            finally:
+                _env.close()
+
+        # Helper function to handle step endpoint
+        async def step_handler(request: StepRequest) -> StepResponse:
+            """Step endpoint - executes action and returns observation."""
+            action_data = request.action
+
+            try:
+                action = deserialize_action(action_data, self.action_cls)
+            except ValidationError as e:
+                raise HTTPException(
+                    status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=e.errors()
+                )
+
+            _env = self._env_factory()
+
+            try:
+                kwargs = request.model_dump(exclude_unset=True, exclude={"action"})
+
+                is_async = _env.step_async.__func__ is not Environment.step_async
+
+                if is_async:
+                    sig = inspect.signature(_env.step_async)
+                else:
+                    sig = inspect.signature(_env.step)
+                valid_kwargs = self._get_valid_kwargs(
+                    sig, kwargs, skip_params={"action"}
+                )
+
+                if is_async:
+                    observation = await _env.step_async(action, **valid_kwargs)
+                else:
+                    observation = await self._run_sync_in_thread_pool(
+                        _env.step, action, **valid_kwargs
+                    )
+
+                return StepResponse(**serialize_observation(observation))
+            finally:
+                _env.close()
+
+        # Register routes using the helpers
+        @app.post(
+            "/reset",
+            response_model=ResetResponse,
+            tags=["Environment Control"],
+            summary="Reset the environment",
+            description="""
+Reset the environment to its initial state and return the first observation.
+
+You can optionally provide a seed for reproducibility and an episode_id for tracking.
+            """,
+            responses={
+                200: {
+                    "description": "Environment reset successfully",
+                    "content": {
+                        "application/json": {
+                            "example": {
+                                "observation": {"status": "ready", "data": {}},
+                                "reward": None,
+                                "done": False,
+                            }
+                        }
+                    },
+                }
+            },
+        )
+        async def reset(
+            request: ResetRequest = Body(default_factory=ResetRequest),
+        ) -> ResetResponse:
+            return await reset_handler(request)
+
+        @app.post(
+            "/step",
+            response_model=StepResponse,
+            tags=["Environment Control"],
+            summary="Execute an action in the environment",
+            description="""
+Execute an action in the environment and receive the resulting observation.
+
+The action must conform to the environment's action schema, which can be
+retrieved from the `/schema` endpoint. If the action is invalid,
+the endpoint will return HTTP 422 with detailed validation errors.
+
+The response includes:
+- **observation**: The environment's response to the action
+- **reward**: Optional reward signal (float or None)
+- **done**: Boolean indicating if the episode has terminated
+            """,
+            responses={
+                200: {
+                    "description": "Action executed successfully",
+                    "content": {
+                        "application/json": {
+                            "example": {
+                                "observation": {"status": "success", "data": {}},
+                                "reward": 1.0,
+                                "done": False,
+                            }
+                        }
+                    },
+                },
+                422: {
+                    "description": "Validation error - invalid action format or values",
+                    "content": {
+                        "application/json": {
+                            "example": {
+                                "detail": [
+                                    {
+                                        "type": "string_too_short",
+                                        "loc": ["body", "action", "message"],
+                                        "msg": "String should have at least 1 character",
+                                        "input": "",
+                                    }
+                                ]
+                            }
+                        }
+                    },
+                },
+                500: {"description": "Internal server error during action execution"},
+            },
+        )
+        async def step(request: StepRequest) -> StepResponse:
+            return await step_handler(request)
+
+        def get_state_handler() -> State:
+            _env = self._env_factory()
+            try:
+                return _env.state
+            finally:
+                _env.close()
+
+        def get_metadata_handler() -> EnvironmentMetadata:
+            _env = self._env_factory()
+            try:
+                return _env.get_metadata()
+            finally:
+                _env.close()
+
+        get_endpoints = [
+            GetEndpointConfig(
+                path="/state",
+                handler=get_state_handler,
+                response_model=State,
+                tag="State Management",
+                summary="Get current environment state",
+                description="""
+Retrieve the current internal state of the environment.
+
+The structure of the state object is defined by the environment's State model.
+                """,
+            ),
+            GetEndpointConfig(
+                path="/metadata",
+                handler=get_metadata_handler,
+                response_model=EnvironmentMetadata,
+                tag="Environment Info",
+                summary="Get environment metadata",
+                description="""
+Get metadata about this environment.
+
+Returns information about the environment including name, description,
+version, author, and documentation links.
+                """,
+            ),
+            GetEndpointConfig(
+                path="/health",
+                handler=lambda: HealthResponse(status="healthy"),
+                response_model=HealthResponse,
+                tag="Health",
+                summary="Health check",
+                description="Check if the environment server is running and healthy.",
+            ),
+        ]
+        register_get_endpoints(app, get_endpoints)
+
+        # Register combined schema endpoint
+        @app.get(
+            "/schema",
+            response_model=SchemaResponse,
+            tags=["Schema"],
+            summary="Get all JSON schemas",
+            description="""
+Get JSON schemas for actions, observations, and state in a single response.
+
+Returns a combined schema object containing:
+- **action**: JSON schema for actions accepted by this environment
+- **observation**: JSON schema for observations returned by this environment  
+- **state**: JSON schema for environment state objects
+
+This is more efficient than calling individual schema endpoints and provides
+all schema information needed to interact with the environment.
+            """,
+            responses={
+                200: {
+                    "description": "Combined schemas retrieved successfully",
+                    "content": {
+                        "application/json": {
+                            "example": {
+                                "action": {
+                                    "type": "object",
+                                    "properties": {"message": {"type": "string"}},
+                                },
+                                "observation": {
+                                    "type": "object",
+                                    "properties": {"response": {"type": "string"}},
+                                },
+                                "state": {
+                                    "type": "object",
+                                    "properties": {"step_count": {"type": "integer"}},
+                                },
+                            }
+                        }
+                    },
+                }
+            },
+        )
+        async def get_schemas() -> SchemaResponse:
+            """Return all schemas in one response."""
+            return SchemaResponse(
+                action=self.action_cls.model_json_schema(),
+                observation=self.observation_cls.model_json_schema(),
+                state=State.model_json_schema(),
+            )
+
+        # Register WebSocket endpoint for persistent sessions
+        @app.websocket("/ws")
+        async def websocket_endpoint(websocket: WebSocket):
+            """
+            WebSocket endpoint for persistent environment sessions.
+
+            Each WebSocket connection gets its own environment instance.
+
+            Message Protocol:
+            - Client sends: WSResetMessage | WSStepMessage | WSStateMessage | WSCloseMessage
+            - Server responds: WSObservationResponse | WSStateResponse | WSErrorResponse
+            """
+            await websocket.accept()
+
+            session_id = None
+            session_env = None
+
+            try:
+                # Create session with dedicated environment
+                session_id, session_env = await self._create_session()
+
+                while True:
+                    # Receive message from client
+                    raw_message = await websocket.receive_text()
+
+                    try:
+                        message_dict = json.loads(raw_message)
+                    except json.JSONDecodeError as e:
+                        error_resp = WSErrorResponse(
+                            data={
+                                "message": f"Invalid JSON: {e}",
+                                "code": "INVALID_JSON",
+                            }
+                        )
+                        await websocket.send_text(error_resp.model_dump_json())
+                        continue
+
+                    msg_type = message_dict.get("type", "")
+
+                    try:
+                        match msg_type:
+                            case "reset":
+                                msg = WSResetMessage(**message_dict)
+
+                                is_async = (
+                                    session_env.reset_async.__func__
+                                    is not Environment.reset_async
+                                )
+
+                                if is_async:
+                                    sig = inspect.signature(session_env.reset_async)
+                                    valid_kwargs = self._get_valid_kwargs(sig, msg.data)
+                                    observation = await session_env.reset_async(
+                                        **valid_kwargs
+                                    )
+                                else:
+                                    sig = inspect.signature(session_env.reset)
+                                    valid_kwargs = self._get_valid_kwargs(sig, msg.data)
+                                    observation = await self._run_in_session_executor(
+                                        session_id, session_env.reset, **valid_kwargs
+                                    )
+
+                                self._update_session_activity(session_id)
+
+                                response = WSObservationResponse(
+                                    data=serialize_observation(observation)
+                                )
+
+                            case "step":
+                                msg = WSStepMessage(**message_dict)
+                                action = deserialize_action(msg.data, self.action_cls)
+
+                                is_async = (
+                                    session_env.step_async.__func__
+                                    is not Environment.step_async
+                                )
+
+                                if is_async:
+                                    observation = await session_env.step_async(action)
+                                else:
+                                    observation = await self._run_in_session_executor(
+                                        session_id, session_env.step, action
+                                    )
+
+                                self._update_session_activity(
+                                    session_id, increment_step=True
+                                )
+
+                                response = WSObservationResponse(
+                                    data=serialize_observation(observation)
+                                )
+
+                            case "state":
+                                msg = WSStateMessage(**message_dict)
+                                state = session_env.state
+                                if hasattr(state, "model_dump"):
+                                    state_data = state.model_dump()
+                                else:
+                                    state_data = dict(state) if state else {}
+
+                                response = WSStateResponse(data=state_data)
+
+                            case "close":
+                                msg = WSCloseMessage(**message_dict)
+                                break
+
+                            case _:
+                                response = WSErrorResponse(
+                                    data={
+                                        "message": f"Unknown message type: {msg_type}",
+                                        "code": "UNKNOWN_TYPE",
+                                    }
+                                )
+
+                        await websocket.send_text(response.model_dump_json())
+
+                    except ValidationError as e:
+                        error_resp = WSErrorResponse(
+                            data={
+                                "message": "Invalid message",
+                                "code": "VALIDATION_ERROR",
+                                "errors": e.errors(),
+                            }
+                        )
+                        await websocket.send_text(error_resp.model_dump_json())
+                    except Exception as e:
+                        error_resp = WSErrorResponse(
+                            data={"message": str(e), "code": "EXECUTION_ERROR"}
+                        )
+                        await websocket.send_text(error_resp.model_dump_json())
+
+            except WebSocketDisconnect:
+                pass
+            except SessionCapacityError as e:
+                error_resp = WSErrorResponse(
+                    data={
+                        "message": str(e),
+                        "code": "CAPACITY_REACHED",
+                        "active_sessions": e.active_sessions,
+                        "max_sessions": e.max_sessions,
+                    }
+                )
+                await websocket.send_text(error_resp.model_dump_json())
+            except EnvironmentFactoryError as e:
+                error_resp = WSErrorResponse(
+                    data={
+                        "message": str(e),
+                        "code": "FACTORY_ERROR",
+                        "factory_name": e.factory_name,
+                    }
+                )
+                await websocket.send_text(error_resp.model_dump_json())
+            except Exception as e:
+                error_resp = WSErrorResponse(
+                    data={"message": str(e), "code": "SESSION_ERROR"}
+                )
+                await websocket.send_text(error_resp.model_dump_json())
+            finally:
+                if session_id:
+                    await self._destroy_session(session_id)
+                try:
+                    await websocket.close()
+                except RuntimeError:
+                    pass
+
+
+def create_app(
+    env: Callable[[], Environment],
+    action_cls: Type[Action],
+    observation_cls: Type[Observation],
+    env_name: Optional[str] = None,
+    max_concurrent_envs: Optional[int] = None,
+    concurrency_config: Optional[ConcurrencyConfig] = None,
+) -> FastAPI:
+    """
+    Create a FastAPI application with or without web interface.
+
+    This function creates a FastAPI app with the web interface enabled by default,
+    including README integration for better user experience.
+
+    Args:
+        env: Environment factory (callable) that creates new instances
+        action_cls: The Action subclass this environment expects
+        observation_cls: The Observation subclass this environment returns
+        env_name: Optional environment name for README loading
+        max_concurrent_envs: Maximum concurrent WebSocket sessions.
+                             Mutually exclusive with concurrency_config.
+        concurrency_config: Optional ConcurrencyConfig for advanced concurrency settings.
+                            Mutually exclusive with max_concurrent_envs.
+
+    Returns:
+        FastAPI application instance with or without web interface and README integration
+    """
+    # Check if web interface should be enabled
+    # This can be controlled via environment variable or build argument
+    enable_web = os.getenv("ENABLE_WEB_INTERFACE", "false").lower() in (
+        "true",
+        "1",
+        "yes",
+    )
+
+    if enable_web:
+        # Import web interface only when needed
+        from .web_interface import create_web_interface_app
+
+        return create_web_interface_app(
+            env,
+            action_cls,
+            observation_cls,
+            env_name,
+            max_concurrent_envs,
+            concurrency_config,
+        )
+    else:
+        # Use standard FastAPI app without web interface
+        return create_fastapi_app(
+            env, action_cls, observation_cls, max_concurrent_envs, concurrency_config
+        )
+
+
+def create_fastapi_app(
+    env: Callable[[], Environment],
+    action_cls: Type[Action],
+    observation_cls: Type[Observation],
+    max_concurrent_envs: Optional[int] = None,
+    concurrency_config: Optional[ConcurrencyConfig] = None,
+) -> FastAPI:
+    """
+    Create a FastAPI application with comprehensive documentation.
+
+    Args:
+        env: Environment factory (callable) that creates new instances
+        action_cls: The Action subclass this environment expects
+        observation_cls: The Observation subclass this environment returns
+        max_concurrent_envs: Maximum concurrent WebSocket sessions.
+                             Mutually exclusive with concurrency_config.
+        concurrency_config: Optional ConcurrencyConfig for advanced concurrency settings.
+                            Mutually exclusive with max_concurrent_envs.
+
+    Returns:
+        FastAPI application instance
+    """
+    try:
+        from fastapi import FastAPI
+    except ImportError:
+        raise ImportError(
+            "FastAPI is required. Install with: pip install fastapi uvicorn"
+        )
+
+    app = FastAPI(
+        title="OpenEnv Environment HTTP API",
+        version="1.0.0",
+        description="""
+# OpenEnv Environment HTTP API
+
+HTTP API for interacting with OpenEnv environments through a standardized interface.
+
+## Features
+
+* **Environment Reset**: Initialize or restart episodes
+* **Action Execution**: Send actions and receive observations
+* **State Inspection**: Query current environment state
+* **Schema Access**: Retrieve JSON schemas for actions and observations
+
+## Workflow
+
+1. Call `/reset` to start a new episode and get initial observation
+2. Call `/step` repeatedly with actions to interact with environment
+3. Episode ends when observation returns `done: true`
+4. Call `/state` anytime to inspect current environment state
+
+## Documentation
+
+* **Swagger UI**: Available at `/docs`
+* **ReDoc**: Available at `/redoc`
+* **OpenAPI Schema**: Available at `/openapi.json`
+        """,
+        openapi_tags=[
+            {
+                "name": "Environment Control",
+                "description": "Core operations for environment interaction (reset, step)",
+            },
+            {
+                "name": "State Management",
+                "description": "Operations for inspecting environment state",
+            },
+            {
+                "name": "Environment Info",
+                "description": "Information about the environment",
+            },
+            {
+                "name": "Schema",
+                "description": "JSON Schema endpoints for actions, observations, and state",
+            },
+            {"name": "Health", "description": "Service health and status checks"},
+        ],
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/openapi.json",
+        contact={
+            "name": "OpenEnv Team",
+            "url": "https://github.com/meta-pytorch/OpenEnv",
+        },
+        license_info={
+            "name": "BSD-3-Clause",
+            "url": "https://github.com/meta-pytorch/OpenEnv/blob/main/LICENSE",
+        },
+    )
+
+    server = HTTPEnvServer(
+        env,
+        action_cls,
+        observation_cls,
+        max_concurrent_envs,
+        concurrency_config=concurrency_config,
+    )
+    server.register_routes(app)
+    return app

{core → src/core}/env_server/interfaces.py

@@ -1,118 +1,194 @@
-# 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.
-
-from abc import ABC, abstractmethod
-from typing import Any, Protocol, TypedDict
-
-from .types import Action, Observation, State
-
-
-class Message(TypedDict):
-    """A message in a conversation.
-
-    Compatible with Huggingface chat template format.
-    """
-
-    role: str
-    content: str
-
-
-class ModelTokenizer(Protocol):
-    """Protocol for tokenizers that support chat templates.
-
-    This protocol defines the interface that tokenizers must implement
-    to work with chat-based environments. It's compatible with
-    Huggingface transformers tokenizers.
-    """
-
-    def apply_chat_template(
-        self,
-        conversation: list[Message],
-        tokenize: bool = True,
-        return_tensors: str | None = None,
-        **kwargs: Any,
-    ) -> Any:
-        """Apply a chat template to format and optionally tokenize a conversation.
-
-        Args:
-            conversation: List of message dictionaries with 'role' and 'content'
-            tokenize: Whether to tokenize the output
-            return_tensors: Format for returned tensors ('pt' for PyTorch)
-            **kwargs: Additional arguments
-
-        Returns:
-            Formatted and optionally tokenized conversation
-        """
-        ...
-
-    def decode(
-        self, token_ids: Any, skip_special_tokens: bool = False, **kwargs: Any
-    ) -> str:
-        """Decode token IDs back to text.
-
-        Args:
-            token_ids: Token IDs to decode
-            skip_special_tokens: Whether to skip special tokens in output
-            **kwargs: Additional arguments
-
-        Returns:
-            Decoded text string
-        """
-        ...
-
-
-class Transform(ABC):
-    """Transform observations to add rewards, metrics, or other modifications.
-
-    Transforms follow the TorchRL pattern where they take an observation
-    and return a (potentially modified) observation. This allows for
-    flexible reward computation and observation augmentation.
-    """
-
-    @abstractmethod
-    def __call__(self, observation: Observation) -> Observation:
-        """Transform an observation.
-
-        Args:
-            observation: The input observation
-
-        Returns:
-            The transformed observation
-        """
-        pass
-
-
-class Environment(ABC):
-    """Base class for all environment servers following Gym/Gymnasium API.
-
-    Args:
-        transform: Optional transform to apply to observations
-    """
-
-    def __init__(self, transform: Transform | None = None):
-        self.transform = transform
-
-    @abstractmethod
-    def reset(self) -> Observation:
-        """Reset the environment and return initial observation."""
-        pass
-
-    @abstractmethod
-    def step(self, action: Action) -> Observation:
-        """Take a step in the environment."""
-        pass
-
-    @property
-    @abstractmethod
-    def state(self) -> State:
-        """Get the current environment state."""
-        pass
-
-    def _apply_transform(self, observation: Observation) -> Observation:
-        """Apply transform if one is provided."""
-        if self.transform is not None:
-            return self.transform(observation)
-        return observation
+# 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.
+
+from abc import ABC, abstractmethod
+from typing import Any, Generic, Optional, Protocol, TypedDict, TypeVar
+
+from .types import Action, Observation, State, EnvironmentMetadata
+
+ActT = TypeVar("ActT", bound=Action)
+ObsT = TypeVar("ObsT", bound=Observation)
+StateT = TypeVar("StateT", bound=State)
+
+
+class Message(TypedDict):
+    """A message in a conversation.
+
+    Compatible with Huggingface chat template format.
+    """
+
+    role: str
+    content: str
+
+
+class ModelTokenizer(Protocol):
+    """Protocol for tokenizers that support chat templates.
+
+    This protocol defines the interface that tokenizers must implement
+    to work with chat-based environments. It's compatible with
+    Huggingface transformers tokenizers.
+    """
+
+    def apply_chat_template(
+        self,
+        conversation: list[Message],
+        tokenize: bool = True,
+        return_tensors: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Apply a chat template to format and optionally tokenize a conversation.
+
+        Args:
+            conversation: List of message dictionaries with 'role' and 'content'
+            tokenize: Whether to tokenize the output
+            return_tensors: Format for returned tensors ('pt' for PyTorch)
+            **kwargs: Additional arguments
+
+        Returns:
+            Formatted and optionally tokenized conversation
+        """
+        ...
+
+    def decode(
+        self, token_ids: Any, skip_special_tokens: bool = False, **kwargs: Any
+    ) -> str:
+        """Decode token IDs back to text.
+
+        Args:
+            token_ids: Token IDs to decode
+            skip_special_tokens: Whether to skip special tokens in output
+            **kwargs: Additional arguments
+
+        Returns:
+            Decoded text string
+        """
+        ...
+
+
+class Transform(ABC, Generic[ObsT]):
+    """Transform observations to add rewards, metrics, or other modifications.
+
+    Transforms follow the TorchRL pattern where they take an observation
+    and return a (potentially modified) observation. This allows for
+    flexible reward computation and observation augmentation.
+    """
+
+    @abstractmethod
+    def __call__(self, observation: ObsT) -> ObsT:
+        """Transform an observation.
+
+        Args:
+            observation: The input observation
+
+        Returns:
+            The transformed observation
+        """
+        pass
+
+
+class Environment(ABC, Generic[ActT, ObsT, StateT]):
+    """Base class for all environment servers following Gym/Gymnasium API.
+
+    Args:
+        transform: Optional transform to apply to observations
+
+    Class Attributes:
+        SUPPORTS_CONCURRENT_SESSIONS: Whether this environment supports concurrent sessions.
+            When True, multiple WebSocket connections can each have their own
+            environment instance (up to max_concurrent_envs). When False (default),
+            the environment should only be used with a single session at a time.
+
+            Set this to True in your Environment subclass if:
+            - The environment uses proper session isolation (e.g., unique working dirs)
+            - No shared mutable state exists between instances
+            - External resources (databases, APIs) can handle concurrent access
+    """
+
+    # Class-level flag indicating whether this environment supports concurrent sessions
+    SUPPORTS_CONCURRENT_SESSIONS: bool = False
+
+    def __init__(self, transform: Optional[Transform[ObsT]] = None):
+        self.transform = transform
+
+    @abstractmethod
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> ObsT:
+        """Reset the environment and return initial observation."""
+        pass
+
+    async def reset_async(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> ObsT:
+        """Async version of reset. Default implementation calls sync reset.
+
+        Override to provide true async implementation.
+        """
+        return self.reset(seed=seed, episode_id=episode_id, **kwargs)
+
+    @abstractmethod
+    def step(
+        self,
+        action: ActT,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> ObsT:
+        """Take a step in the environment."""
+        pass
+
+    async def step_async(
+        self,
+        action: ActT,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> ObsT:
+        """Async version of step. Default implementation calls sync step.
+
+        Override to provide true async implementation.
+        """
+        return self.step(action, timeout_s=timeout_s, **kwargs)
+
+    @property
+    @abstractmethod
+    def state(self) -> StateT:
+        """Get the current environment state."""
+        pass
+
+    def get_metadata(self) -> EnvironmentMetadata:
+        """
+        Get metadata about this environment.
+
+        Override this method to provide custom metadata for the environment.
+        Default implementation returns basic metadata derived from class name.
+
+        Returns:
+            EnvironmentMetadata with environment information
+        """
+        return EnvironmentMetadata(
+            name=self.__class__.__name__,
+            description=f"{self.__class__.__name__} environment",
+            version="1.0.0",
+        )
+
+    def _apply_transform(self, observation: ObsT) -> ObsT:
+        """Apply transform if one is provided."""
+        if self.transform is not None:
+            return self.transform(observation)
+        return observation
+
+    def close(self) -> None:
+        """Clean up resources used by the environment.
+
+        Override this method to implement custom cleanup logic.
+        Called when the environment is being destroyed or reset.
+        """
+        pass

src/core/env_server/route_config.py

@@ -0,0 +1,57 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Route configuration utilities for declarative FastAPI route registration.
+
+This module provides utilities to reduce boilerplate in route registration
+by using configuration objects instead of repeated function calls.
+"""
+
+from dataclasses import dataclass
+from typing import Callable, List, Type
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+
+@dataclass
+class GetEndpointConfig:
+    """Configuration for a simple GET endpoint."""
+
+    path: str
+    handler: Callable[[], BaseModel | dict]
+    response_model: Type[BaseModel] | type[dict]
+    tag: str
+    summary: str
+    description: str
+
+
+def register_get_endpoints(app: FastAPI, configs: List[GetEndpointConfig]) -> None:
+    """
+    Register multiple GET endpoints from configuration.
+
+    Args:
+        app: FastAPI application instance
+        configs: List of GET endpoint configurations
+    """
+    for config in configs:
+        # Capture handler in a closure to avoid non-serializable default parameter
+        def make_endpoint(
+            handler: Callable[[], BaseModel | dict],
+        ) -> Callable[[], BaseModel | dict]:
+            async def endpoint() -> BaseModel | dict:
+                return handler()
+
+            return endpoint
+
+        app.get(
+            config.path,
+            response_model=config.response_model,
+            tags=[config.tag],
+            summary=config.summary,
+            description=config.description,
+        )(make_endpoint(config.handler))

src/core/env_server/serialization.py

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

src/core/env_server/types.py

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

{core → src/core}/env_server/web_interface.py

@@ -13,55 +13,60 @@ including a two-pane layout for HumanAgent interaction and state observation.
 
 from __future__ import annotations
 
+import asyncio
 import json
-import time
-from dataclasses import asdict, dataclass
+from concurrent.futures import ThreadPoolExecutor
 from typing import Any, Dict, List, Optional, Type
 from datetime import datetime
 
-from fastapi import FastAPI, WebSocket, WebSocketDisconnect, Request
-from fastapi.responses import HTMLResponse, FileResponse
-from fastapi.staticfiles import StaticFiles
-from pydantic import BaseModel
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.responses import HTMLResponse
+from pydantic import BaseModel, Field, ConfigDict
 
 from .interfaces import Environment
+from .serialization import (
+    deserialize_action_with_preprocessing,
+    serialize_observation,
+)
 from .types import Action, Observation, State, EnvironmentMetadata
 
 
-def load_environment_metadata(env: Environment, env_name: Optional[str] = None) -> EnvironmentMetadata:
+def load_environment_metadata(
+    env: Environment, env_name: Optional[str] = None
+) -> EnvironmentMetadata:
     """
     Load environment metadata including README content.
-    
+
     Args:
         env: The environment instance
         env_name: Optional environment name for README file lookup
-        
+
     Returns:
         EnvironmentMetadata with loaded information
     """
     # Try to get metadata from environment if it has a method for it
-    if hasattr(env, 'get_metadata'):
+    if hasattr(env, "get_metadata"):
         return env.get_metadata()
-    
+
     # Default metadata
     metadata = EnvironmentMetadata(
         name=env_name or env.__class__.__name__,
         description=f"{env.__class__.__name__} environment",
-        version="1.0.0"
+        version="1.0.0",
     )
-    
+
     # Try to load README from file system
     readme_content = _load_readme_from_filesystem(env_name)
     if readme_content:
         metadata.readme_content = readme_content
-    
+
     return metadata
 
 
 def _load_readme_from_filesystem(env_name: Optional[str]) -> Optional[str]:
     """
     Load README content from the filesystem.
-    
+
     Tries multiple locations:
     1. Container filesystem: /app/README.md
     2. Local development: src/envs/{env_name}/README.md
@@ -69,59 +74,71 @@ def _load_readme_from_filesystem(env_name: Optional[str]) -> Optional[str]:
     """
     import os
     from pathlib import Path
-    
+
     # Try container filesystem first
     container_readme = Path("/app/README.md")
     if container_readme.exists():
         try:
-            return container_readme.read_text(encoding='utf-8')
+            return container_readme.read_text(encoding="utf-8")
         except Exception:
             pass
-    
+
     # Try environment variable path
     custom_path = os.environ.get("ENV_README_PATH")
     if custom_path and Path(custom_path).exists():
         try:
-            return Path(custom_path).read_text(encoding='utf-8')
+            return Path(custom_path).read_text(encoding="utf-8")
         except Exception:
             pass
-    
+
     # Try local development path
     if env_name:
         local_readme = Path(f"src/envs/{env_name}/README.md")
         if local_readme.exists():
             try:
-                return local_readme.read_text(encoding='utf-8')
+                return local_readme.read_text(encoding="utf-8")
             except Exception:
                 pass
-    
+
     return None
 
 
-@dataclass
-class ActionLog:
+class ActionLog(BaseModel):
     """Log entry for an action taken."""
-    timestamp: str
-    action: Dict[str, Any]
-    observation: Dict[str, Any]
-    reward: Optional[float]
-    done: bool
-    step_count: int
 
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+    timestamp: str = Field(description="Timestamp when action was taken")
+    action: Dict[str, Any] = Field(description="Action that was taken")
+    observation: Dict[str, Any] = Field(description="Observation returned from action")
+    reward: Optional[float] = Field(
+        default=None, description="Reward received from action"
+    )
+    done: bool = Field(description="Whether the episode is done after this action")
+    step_count: int = Field(description="Step count when this action was taken")
 
-@dataclass
-class EpisodeState:
+
+class EpisodeState(BaseModel):
     """Current episode state for the web interface."""
-    episode_id: Optional[str]
-    step_count: int
-    current_observation: Optional[Dict[str, Any]]
-    action_logs: List[ActionLog]
-    is_reset: bool = True
+
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+    episode_id: Optional[str] = Field(default=None, description="Current episode ID")
+    step_count: int = Field(description="Current step count in episode")
+    current_observation: Optional[Dict[str, Any]] = Field(
+        default=None, description="Current observation"
+    )
+    action_logs: List[ActionLog] = Field(
+        default_factory=list, description="List of action logs"
+    )
+    is_reset: bool = Field(
+        default=True, description="Whether the episode has been reset"
+    )
 
 
 class WebInterfaceManager:
     """Manages the web interface for an environment."""
-    
+
     def __init__(
         self,
         env: Environment,
@@ -134,147 +151,127 @@ class WebInterfaceManager:
         self.observation_cls = observation_cls
         self.metadata = metadata or EnvironmentMetadata(
             name=env.__class__.__name__,
-            description=f"{env.__class__.__name__} environment"
+            description=f"{env.__class__.__name__} environment",
         )
         self.episode_state = EpisodeState(
             episode_id=None,
             step_count=0,
             current_observation=None,
-            action_logs=[]
+            action_logs=[],
         )
         self.connected_clients: List[WebSocket] = []
-    
+        # Thread pool for running sync code (e.g., Playwright sync API) in async context
+        self._executor = ThreadPoolExecutor(max_workers=1)
+
+    async def _run_sync_in_thread_pool(self, func, *args, **kwargs):
+        """Run a synchronous function in the thread pool executor.
+
+        This is needed for environments using sync libraries (e.g., Playwright sync API)
+        that cannot be called directly from an async context.
+        """
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(self._executor, lambda: func(*args, **kwargs))
+
     async def connect_websocket(self, websocket: WebSocket):
         """Connect a new WebSocket client."""
         await websocket.accept()
         self.connected_clients.append(websocket)
-        
+
         # Send current state to the new client
         await self._send_state_update()
-    
+
     async def disconnect_websocket(self, websocket: WebSocket):
         """Disconnect a WebSocket client."""
         if websocket in self.connected_clients:
             self.connected_clients.remove(websocket)
-    
+
     async def _send_state_update(self):
         """Send current state to all connected clients."""
         if not self.connected_clients:
             return
-            
+
         state_data = {
             "type": "state_update",
-            "episode_state": asdict(self.episode_state)
+            "episode_state": self.episode_state.model_dump(),
         }
-        
+
         # Send to all connected clients
         disconnected_clients = []
         for client in self.connected_clients:
             try:
                 await client.send_text(json.dumps(state_data))
-            except:
+            except Exception:
                 disconnected_clients.append(client)
-        
+
         # Remove disconnected clients
         for client in disconnected_clients:
             self.connected_clients.remove(client)
-    
+
     async def reset_environment(self) -> Dict[str, Any]:
         """Reset the environment and update state."""
-        observation = self.env.reset()
-        state = self.env.state
-        
+        # Run sync reset in thread pool to avoid blocking event loop
+        # and to support environments using sync libraries (e.g., Playwright)
+        observation: Observation = await self._run_sync_in_thread_pool(self.env.reset)
+        state: State = self.env.state
+
+        # Serialize observation once using shared utility
+        serialized = serialize_observation(observation)
+
         # Update episode state
         self.episode_state.episode_id = state.episode_id
         self.episode_state.step_count = 0
-        self.episode_state.current_observation = asdict(observation)
+        self.episode_state.current_observation = serialized["observation"]
         self.episode_state.action_logs = []
         self.episode_state.is_reset = True
-        
+
         # Send state update
         await self._send_state_update()
-        
-        return {
-            "observation": asdict(observation),
-            "reward": observation.reward,
-            "done": observation.done,
-        }
-    
+
+        return serialized
+
     async def step_environment(self, action_data: Dict[str, Any]) -> Dict[str, Any]:
         """Execute a step in the environment and update state."""
-        # Deserialize action
-        action = self._deserialize_action(action_data)
-        
-        # Execute step
-        observation = self.env.step(action)
-        state = self.env.state
-        
+        # Deserialize action with preprocessing for web interface special cases
+        action: Action = deserialize_action_with_preprocessing(
+            action_data, self.action_cls
+        )
+
+        # Run sync step in thread pool to avoid blocking event loop
+        # and to support environments using sync libraries (e.g., Playwright)
+        observation: Observation = await self._run_sync_in_thread_pool(
+            self.env.step, action
+        )
+        state: State = self.env.state
+
+        # Serialize observation once using shared utility
+        serialized = serialize_observation(observation)
+
         # Create action log
         action_log = ActionLog(
             timestamp=datetime.now().isoformat(),
-            action=asdict(action),
-            observation=asdict(observation),
+            action=action.model_dump(exclude={"metadata"}),
+            observation=serialized["observation"],
             reward=observation.reward,
             done=observation.done,
-            step_count=state.step_count
+            step_count=state.step_count,
         )
-        
+
         # Update episode state
         self.episode_state.episode_id = state.episode_id
         self.episode_state.step_count = state.step_count
-        self.episode_state.current_observation = asdict(observation)
+        self.episode_state.current_observation = serialized["observation"]
         self.episode_state.action_logs.append(action_log)
         self.episode_state.is_reset = False
-        
+
         # Send state update
         await self._send_state_update()
-        
-        return {
-            "observation": asdict(observation),
-            "reward": observation.reward,
-            "done": observation.done,
-        }
-    
+
+        return serialized
+
     def get_state(self) -> Dict[str, Any]:
         """Get current environment state."""
-        state = self.env.state
-        return asdict(state)
-    
-    def _deserialize_action(self, action_data: Dict[str, Any]) -> Action:
-        """Convert JSON dict to Action instance."""
-        metadata = action_data.pop("metadata", {})
-        
-        # Handle tensor fields that come from JSON as lists
-        processed_data = {}
-        for key, value in action_data.items():
-            if key == "tokens" and isinstance(value, (list, str)):
-                # Convert list or string to tensor
-                if isinstance(value, str):
-                    # If it's a string, try to parse it as a list of numbers
-                    try:
-                        import json
-                        value = json.loads(value)
-                    except:
-                        # If parsing fails, treat as empty list
-                        value = []
-                if isinstance(value, list):
-                    import torch
-                    processed_data[key] = torch.tensor(value, dtype=torch.long)
-                else:
-                    processed_data[key] = value
-            elif key == "action_id" and isinstance(value, str):
-                # Convert action_id from string to int
-                try:
-                    processed_data[key] = int(value)
-                except ValueError:
-                    # If conversion fails, keep original value
-                    processed_data[key] = value
-            else:
-                processed_data[key] = value
-        
-        action = self.action_cls(**processed_data)
-        action.metadata = metadata
-        return action
+        state: State = self.env.state
+        return state.model_dump()
 
 
 def create_web_interface_app(
@@ -285,41 +282,45 @@ def create_web_interface_app(
 ) -> FastAPI:
     """
     Create a FastAPI application with web interface for the given environment.
-    
+
     Args:
         env: The Environment instance to serve
         action_cls: The Action subclass this environment expects
         observation_cls: The Observation subclass this environment returns
         env_name: Optional environment name for README loading
-        
+
     Returns:
         FastAPI application instance with web interface
     """
     from .http_server import create_fastapi_app
-    
+
     # Create the base environment app
     app = create_fastapi_app(env, action_cls, observation_cls)
-    
+
     # Load environment metadata
     metadata = load_environment_metadata(env, env_name)
-    
+
     # Create web interface manager
     web_manager = WebInterfaceManager(env, action_cls, observation_cls, metadata)
-    
+
     # Add web interface routes
     @app.get("/web", response_class=HTMLResponse)
     async def web_interface():
         """Serve the web interface."""
         return get_web_interface_html(action_cls, web_manager.metadata)
-    
+
     @app.get("/web/metadata")
     async def web_metadata():
         """Get environment metadata."""
-        return asdict(web_manager.metadata)
-    
-    @app.websocket("/ws")
-    async def websocket_endpoint(websocket: WebSocket):
-        """WebSocket endpoint for real-time updates."""
+        return web_manager.metadata.model_dump()
+
+    @app.websocket("/ws/ui")
+    async def websocket_ui_endpoint(websocket: WebSocket):
+        """WebSocket endpoint for web UI real-time updates.
+
+        Note: Uses /ws/ui to avoid conflict with /ws in http_server.py
+        which is used for concurrent environment sessions.
+        """
         await web_manager.connect_websocket(websocket)
         try:
             while True:
@@ -327,12 +328,12 @@ def create_web_interface_app(
                 await websocket.receive_text()
         except WebSocketDisconnect:
             await web_manager.disconnect_websocket(websocket)
-    
+
     @app.post("/web/reset")
     async def web_reset():
         """Reset endpoint for web interface."""
         return await web_manager.reset_environment()
-    
+
     @app.post("/web/step")
     async def web_step(request: Dict[str, Any]):
         """Step endpoint for web interface."""
@@ -344,31 +345,37 @@ def create_web_interface_app(
             action_data = {"tokens": action.tokens.tolist()}
         else:
             action_data = request.get("action", {})
-        
+
         return await web_manager.step_environment(action_data)
-    
+
     @app.get("/web/state")
     async def web_state():
         """State endpoint for web interface."""
         return web_manager.get_state()
-    
+
     return app
 
 
-def get_web_interface_html(action_cls: Type[Action], metadata: Optional[EnvironmentMetadata] = None) -> str:
+def get_web_interface_html(
+    action_cls: Type[Action], metadata: Optional[EnvironmentMetadata] = None
+) -> str:
     """Generate the HTML for the web interface."""
-    
+
     # Check if this is a chat environment by looking for tokens field
     is_chat_env = False
-    if hasattr(action_cls, '__dataclass_fields__'):
-        for field_name, field_info in action_cls.__dataclass_fields__.items():
-            if field_name == 'tokens' and hasattr(field_info.type, '__name__') and 'Tensor' in field_info.type.__name__:
+    if hasattr(action_cls, "model_fields"):
+        for field_name, field_info in action_cls.model_fields.items():
+            if (
+                field_name == "tokens"
+                and hasattr(field_info.annotation, "__name__")
+                and "Tensor" in field_info.annotation.__name__
+            ):
                 is_chat_env = True
                 break
-    
+
     # Get action fields for dynamic form generation with enhanced metadata
     action_fields = _extract_action_fields(action_cls)
-    
+
     return f"""
 <!DOCTYPE html>
 <html lang="en">
@@ -971,7 +978,7 @@ def get_web_interface_html(action_cls: Type[Action], metadata: Optional[Environm
             
             connectWebSocket() {{
                 const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-                const wsUrl = `${{protocol}}//${{window.location.host}}/ws`;
+                const wsUrl = `${{protocol}}//${{window.location.host}}/ws/ui`;
                 
                 this.ws = new WebSocket(wsUrl);
                 
@@ -1259,19 +1266,22 @@ def get_web_interface_html(action_cls: Type[Action], metadata: Optional[Environm
     </script>
 </body>
 </html>
-    """.replace('{_generate_action_form_fields(action_fields)}', _generate_action_form_fields(action_fields))
+    """.replace(
+        "{_generate_action_form_fields(action_fields)}",
+        _generate_action_form_fields(action_fields),
+    )
 
 
-def _generate_instructions_section(metadata: Optional[EnvironmentMetadata]) -> str:
+def _generate_instructions_section(
+    metadata: Optional[EnvironmentMetadata],
+) -> str:
     """Generate the instructions section with environment documentation."""
     if not metadata or not metadata.readme_content:
-        return ''
-    
-    # Convert markdown to HTML (basic conversion)
-    import re
+        return ""
+
     html_content = _markdown_to_html(metadata.readme_content)
-    
-    return f'''
+
+    return f"""
                 <!-- Instructions Section -->
                 <div class="instructions-section">
                     <div class="instructions-header">
@@ -1284,194 +1294,178 @@ def _generate_instructions_section(metadata: Optional[EnvironmentMetadata]) -> s
                         </div>
                     </div>
                 </div>
-    '''
+    """
 
 
 def _extract_action_fields(action_cls: Type[Action]) -> List[Dict[str, Any]]:
     """Extract enhanced field metadata from Action class for form generation."""
-    import typing
-    from typing import get_origin, get_args
-    
+    # Use Pydantic's JSON schema generation for robust metadata extraction
+    try:
+        schema = action_cls.model_json_schema()
+    except AttributeError:
+        # Fallback for non-Pydantic v2 models or if something goes wrong
+        return []
+
+    properties = schema.get("properties", {})
+    required_fields = schema.get("required", [])
+
     action_fields = []
-    if not hasattr(action_cls, '__dataclass_fields__'):
-        return action_fields
-    
-    for field_name, field_info in action_cls.__dataclass_fields__.items():
-        if field_name == 'metadata':
+
+    for field_name, field_info in properties.items():
+        if field_name == "metadata":
             continue
-            
-        field_type = field_info.type
-        field_metadata = _extract_field_metadata(field_name, field_info)
-        
-        # Determine input type based on field type
-        input_type = _determine_input_type(field_type)
-        
-        # Check if field is required
-        is_required = field_info.default is field_info.default_factory
-        
-        action_fields.append({
-            'name': field_name,
-            'type': input_type,
-            'required': is_required,
-            'description': field_metadata.get('description', ''),
-            'default_value': field_metadata.get('default_value'),
-            'choices': field_metadata.get('choices', []),
-            'min_value': field_metadata.get('min_value'),
-            'max_value': field_metadata.get('max_value'),
-            'placeholder': field_metadata.get('placeholder', ''),
-            'help_text': field_metadata.get('help_text', ''),
-        })
-    
+
+        # JSON schema "type" can be a string or list/undefined
+        # Determine our internal input type
+        input_type = _determine_input_type_from_schema(field_info, field_name)
+
+        is_required = field_name in required_fields
+
+        action_fields.append(
+            {
+                "name": field_name,
+                "type": input_type,
+                "required": is_required,
+                "description": field_info.get("description", ""),
+                "default_value": field_info.get("default"),
+                "choices": field_info.get("enum"),
+                "min_value": field_info.get("minimum"),
+                "max_value": field_info.get("maximum"),
+                "min_length": field_info.get("minLength"),
+                "max_length": field_info.get("maxLength"),
+                "pattern": field_info.get("pattern"),
+                "placeholder": _generate_placeholder(field_name, field_info),
+                "help_text": _generate_help_text(field_name, field_info),
+            }
+        )
+
     return action_fields
 
 
-def _extract_field_metadata(field_name: str, field_info) -> Dict[str, Any]:
-    """Extract metadata from dataclass field including docstring and type hints."""
-    import typing
-    from typing import get_origin, get_args, Literal, Union, Optional
-    
-    metadata = {}
-    
-    # Extract description from field docstring or annotation
-    if hasattr(field_info, 'metadata') and field_info.metadata:
-        # Check for custom metadata
-        for meta in field_info.metadata:
-            if isinstance(meta, dict):
-                metadata.update(meta)
-    
-    # Extract type information
-    field_type = field_info.type
-    origin = get_origin(field_type)
-    
-    # Handle Literal types for dropdown choices
-    if origin is Literal:
-        args = get_args(field_type)
-        metadata['choices'] = list(args)
-    
-    # Handle Optional types
-    if origin is Union:
-        args = get_args(field_type)
-        if len(args) == 2 and type(None) in args:
-            # This is Optional[SomeType]
-            non_none_type = args[0] if args[1] is type(None) else args[1]
-            metadata['optional'] = True
-            # Recursively check the non-None type for choices
-            if get_origin(non_none_type) is Literal:
-                metadata['choices'] = list(get_args(non_none_type))
-        else:
-            # Regular Union type
-            metadata['choices'] = [str(arg) for arg in args if arg is not type(None)]
-    
-    # Handle numeric constraints
-    if field_type in (int, float):
-        # Check for common constraint patterns in field name
-        if 'count' in field_name.lower() or 'num' in field_name.lower():
-            metadata['min_value'] = 0
-        if 'id' in field_name.lower():
-            metadata['min_value'] = 0
-    
-    # Generate placeholder text
-    if 'message' in field_name.lower():
-        metadata['placeholder'] = f'Enter {field_name.replace("_", " ")}...'
-    elif 'code' in field_name.lower():
-        metadata['placeholder'] = 'Enter Python code here...'
-    elif 'tokens' in field_name.lower():
-        metadata['placeholder'] = 'Enter comma-separated token IDs (e.g., 1,2,3,4,5)'
-    else:
-        metadata['placeholder'] = f'Enter {field_name.replace("_", " ")}...'
-    
-    # Generate help text based on field name and type
-    if 'action_id' in field_name.lower():
-        metadata['help_text'] = 'The action ID to execute in the environment'
-    elif 'game_name' in field_name.lower():
-        metadata['help_text'] = 'Name of the game or environment'
-    elif 'tokens' in field_name.lower():
-        metadata['help_text'] = 'Token IDs as a comma-separated list of integers'
-    elif 'code' in field_name.lower():
-        metadata['help_text'] = 'Python code to execute in the environment'
-    elif 'message' in field_name.lower():
-        metadata['help_text'] = 'Text message to send'
-    
-    return metadata
+def _determine_input_type_from_schema(
+    field_info: Dict[str, Any], field_name: str
+) -> str:
+    """Determine the appropriate HTML input type from JSON schema info."""
+    schema_type = field_info.get("type")
 
+    # Check for specific tensor field convention
+    if "tokens" in field_name.lower():
+        return "tensor"
 
-def _determine_input_type(field_type) -> str:
-    """Determine the appropriate HTML input type for a field type."""
-    import typing
-    from typing import get_origin, get_args, Literal, Union
-    
-    # Handle direct types
-    if field_type == str:
-        return "text"
-    elif field_type == int:
-        return "number"
-    elif field_type == float:
-        return "number"
-    elif field_type == bool:
-        return "checkbox"
-    
-    # Handle complex types
-    origin = get_origin(field_type)
-    
-    if origin is Literal:
+    if "enum" in field_info:
         return "select"
-    elif origin is Union:
-        args = get_args(field_type)
-        if len(args) == 2 and type(None) in args:
-            # Optional type - use the non-None type
-            non_none_type = args[0] if args[1] is type(None) else args[1]
-            return _determine_input_type(non_none_type)
-        elif all(isinstance(arg, str) for arg in args if arg is not type(None)):
-            return "select"
-        else:
-            return "text"
-    elif hasattr(field_type, '__name__') and 'Tensor' in field_type.__name__:
-        return "tensor"
-    else:
+
+    if schema_type == "boolean":
+        return "checkbox"
+
+    if schema_type == "integer" or schema_type == "number":
+        return "number"
+
+    if schema_type == "string":
+        # Check if it should be a textarea
+        if (
+            field_info.get("maxLength", 0) > 100
+            or "message" in field_name.lower()
+            or "code" in field_name.lower()
+        ):
+            return "textarea"
         return "text"
 
+    # Default fallback
+    return "text"
+
+
+def _generate_placeholder(field_name: str, field_info: Dict[str, Any]) -> str:
+    """Generate placeholder text."""
+    if "message" in field_name.lower():
+        return f"Enter {field_name.replace('_', ' ')}..."
+    elif "code" in field_name.lower():
+        return "Enter Python code here..."
+    elif "tokens" in field_name.lower():
+        return "Enter comma-separated token IDs (e.g., 1,2,3,4,5)"
+    else:
+        return f"Enter {field_name.replace('_', ' ')}..."
+
+
+def _generate_help_text(field_name: str, field_info: Dict[str, Any]) -> str:
+    """Generate help text."""
+    description = field_info.get("description", "")
+    if description:
+        return description
+
+    if "action_id" in field_name.lower():
+        return "The action ID to execute in environment"
+    elif "game_name" in field_name.lower():
+        return "Name of game or environment"
+    elif "tokens" in field_name.lower():
+        return "Token IDs as a comma-separated list of integers"
+    elif "code" in field_name.lower():
+        return "Python code to execute in environment"
+    elif "message" in field_name.lower():
+        return "Text message to send"
+
+    return ""
+
 
 def _markdown_to_html(markdown: str) -> str:
     """Convert basic markdown to HTML for README display."""
     import html
     import re
-    
+
     # Escape HTML first
     html_content = html.escape(markdown)
-    
+
     # Convert headers
-    html_content = re.sub(r'^# (.*?)$', r'<h1>\1</h1>', html_content, flags=re.MULTILINE)
-    html_content = re.sub(r'^## (.*?)$', r'<h2>\1</h2>', html_content, flags=re.MULTILINE)
-    html_content = re.sub(r'^### (.*?)$', r'<h3>\1</h3>', html_content, flags=re.MULTILINE)
-    
+    html_content = re.sub(
+        r"^# (.*?)$", r"<h1>\1</h1>", html_content, flags=re.MULTILINE
+    )
+    html_content = re.sub(
+        r"^## (.*?)$", r"<h2>\1</h2>", html_content, flags=re.MULTILINE
+    )
+    html_content = re.sub(
+        r"^### (.*?)$", r"<h3>\1</h3>", html_content, flags=re.MULTILINE
+    )
+
     # Convert code blocks
-    html_content = re.sub(r'```(.*?)\n(.*?)\n```', r'<pre><code>\2</code></pre>', html_content, flags=re.DOTALL)
-    html_content = re.sub(r'`([^`]+)`', r'<code>\1</code>', html_content)
-    
+    html_content = re.sub(
+        r"```(.*?)\n(.*?)\n```",
+        r"<pre><code>\2</code></pre>",
+        html_content,
+        flags=re.DOTALL,
+    )
+    html_content = re.sub(r"`([^`]+)`", r"<code>\1</code>", html_content)
+
     # Convert bold and italic
-    html_content = re.sub(r'\*\*(.*?)\*\*', r'<strong>\1</strong>', html_content)
-    html_content = re.sub(r'\*(.*?)\*', r'<em>\1</em>', html_content)
-    
+    html_content = re.sub(r"\*\*(.*?)\*\*", r"<strong>\1</strong>", html_content)
+    html_content = re.sub(r"\*(.*?)\*", r"<em>\1</em>", html_content)
+
     # Convert lists
-    html_content = re.sub(r'^- (.*?)$', r'<li>\1</li>', html_content, flags=re.MULTILINE)
-    html_content = re.sub(r'(<li>.*</li>)', r'<ul>\1</ul>', html_content, flags=re.DOTALL)
-    
+    html_content = re.sub(
+        r"^- (.*?)$", r"<li>\1</li>", html_content, flags=re.MULTILINE
+    )
+    html_content = re.sub(
+        r"(<li>.*</li>)", r"<ul>\1</ul>", html_content, flags=re.DOTALL
+    )
+
     # Convert line breaks
-    html_content = html_content.replace('\n', '<br>')
-    
+    html_content = html_content.replace("\n", "<br>")
+
     return html_content
 
 
-def _generate_action_interface(action_fields: List[Dict[str, Any]], is_chat_env: bool) -> str:
+def _generate_action_interface(
+    action_fields: List[Dict[str, Any]], is_chat_env: bool
+) -> str:
     """Generate either a chat interface or action form based on environment type."""
     if is_chat_env:
         return _generate_chat_interface()
     else:
         return _generate_action_form(action_fields)
 
+
 def _generate_chat_interface() -> str:
     """Generate a chat-style interface for chat environments."""
-    return '''
+    return """
                 <!-- Chat Interface -->
                 <div class="chat-interface">
                     <h3>Chat Interface</h3>
@@ -1495,11 +1489,12 @@ def _generate_chat_interface() -> str:
                         </div>
                     </div>
                 </div>
-    '''
+    """
+
 
 def _generate_action_form(action_fields: List[Dict[str, Any]]) -> str:
     """Generate a traditional action form for non-chat environments."""
-    return f'''
+    return f"""
                 <!-- Action Form -->
                 <div class="action-form">
                     <h3>Take Action</h3>
@@ -1508,106 +1503,119 @@ def _generate_action_form(action_fields: List[Dict[str, Any]]) -> str:
                         <button type="submit" class="btn" id="step-btn">Step</button>
                     </form>
                 </div>
-    '''
+    """
+
 
 def _generate_action_form_fields(action_fields: List[Dict[str, Any]]) -> str:
     """Generate HTML form fields for action input with enhanced metadata."""
     if not action_fields:
-        return '<p>No action fields available</p>'
-    
+        return "<p>No action fields available</p>"
+
     fields_html = []
     for field in action_fields:
         field_html = _generate_single_field(field)
         fields_html.append(field_html)
-    
-    return '\n'.join(fields_html)
+
+    return "\n".join(fields_html)
 
 
 def _generate_single_field(field: Dict[str, Any]) -> str:
     """Generate HTML for a single form field with enhanced metadata."""
-    field_name = field['name']
-    field_type = field['type']
-    required = field['required']
-    placeholder = field.get('placeholder', '')
-    help_text = field.get('help_text', '')
-    choices = field.get('choices', [])
-    min_value = field.get('min_value')
-    max_value = field.get('max_value')
-    default_value = field.get('default_value')
-    
+    field_name = field["name"]
+    field_type = field["type"]
+    required = field["required"]
+    placeholder = field.get("placeholder", "")
+    help_text = field.get("help_text", "")
+    choices = field.get("choices", [])
+    min_value = field.get("min_value")
+    max_value = field.get("max_value")
+    default_value = field.get("default_value")
+    min_length = field.get("min_length")
+    max_length = field.get("max_length")
+    pattern = field.get("pattern")
+
     # Build label with required indicator
-    label_text = field_name.replace('_', ' ').title()
+    label_text = field_name.replace("_", " ").title()
     if required:
         label_text += ' <span style="color: red;">*</span>'
-    
+
     # Build input attributes
     input_attrs = []
     if required:
-        input_attrs.append('required')
+        input_attrs.append("required")
     if placeholder:
         input_attrs.append(f'placeholder="{placeholder}"')
     if min_value is not None:
         input_attrs.append(f'min="{min_value}"')
     if max_value is not None:
         input_attrs.append(f'max="{max_value}"')
+    if min_length is not None:
+        input_attrs.append(f'minlength="{min_length}"')
+    if max_length is not None:
+        input_attrs.append(f'maxlength="{max_length}"')
+    if pattern is not None:
+        input_attrs.append(f'pattern="{pattern}"')
     if default_value is not None:
         input_attrs.append(f'value="{default_value}"')
-    
-    attrs_str = ' '.join(input_attrs)
-    
-    if field_type == 'checkbox':
+
+    attrs_str = " ".join(input_attrs)
+
+    if field_type == "checkbox":
+        checked = "checked" if default_value is True else ""
         return f'''
             <div class="form-group">
                 <label>
-                    <input type="checkbox" name="{field_name}" value="true" {attrs_str}>
+                    <input type="checkbox" name="{field_name}" value="true" {checked}>
                     {label_text}
                 </label>
-                {f'<small class="help-text">{help_text}</small>' if help_text else ''}
+                {f'<small class="help-text">{help_text}</small>' if help_text else ""}
             </div>
         '''
-    
-    elif field_type == 'select':
+
+    elif field_type == "select":
         options_html = []
         if not required:
             options_html.append(f'<option value="">-- Select {label_text} --</option>')
-        
+
         for choice in choices:
-            selected = 'selected' if str(choice) == str(default_value) else ''
-            options_html.append(f'<option value="{choice}" {selected}>{choice}</option>')
-        
+            selected = "selected" if str(choice) == str(default_value) else ""
+            options_html.append(
+                f'<option value="{choice}" {selected}>{choice}</option>'
+            )
+
         return f'''
             <div class="form-group">
                 <label for="{field_name}">{label_text}:</label>
                 <select name="{field_name}" id="{field_name}" {attrs_str}>
-                    {''.join(options_html)}
+                    {"".join(options_html)}
                 </select>
-                {f'<small class="help-text">{help_text}</small>' if help_text else ''}
+                {f'<small class="help-text">{help_text}</small>' if help_text else ""}
             </div>
         '''
-    
-    elif field_type == 'tensor':
+
+    elif field_type == "tensor":
         return f'''
             <div class="form-group">
                 <label for="{field_name}">{label_text} (comma-separated integers):</label>
                 <input type="text" name="{field_name}" id="{field_name}" {attrs_str}>
-                <small class="help-text">{help_text or 'Enter token IDs as comma-separated integers (e.g., 1,2,3,4,5)'}</small>
+                <small class="help-text">{help_text or "Enter token IDs as comma-separated integers (e.g., 1,2,3,4,5)"}</small>
             </div>
         '''
-    
-    elif field_type == 'text' and ('message' in field_name.lower() or 'code' in field_name.lower()):
+
+    elif field_type == "textarea":
         return f'''
             <div class="form-group">
                 <label for="{field_name}">{label_text}:</label>
-                <textarea name="{field_name}" id="{field_name}" rows="3" {attrs_str}></textarea>
-                {f'<small class="help-text">{help_text}</small>' if help_text else ''}
+                <textarea name="{field_name}" id="{field_name}" rows="3" {attrs_str}>{default_value if default_value is not None else ""}</textarea>
+                {f'<small class="help-text">{help_text}</small>' if help_text else ""}
             </div>
         '''
-    
+
     else:
         return f'''
             <div class="form-group">
                 <label for="{field_name}">{label_text}:</label>
                 <input type="{field_type}" name="{field_name}" id="{field_name}" {attrs_str}>
-                {f'<small class="help-text">{help_text}</small>' if help_text else ''}
+                {f'<small class="help-text">{help_text}</small>' if help_text else ""}
             </div>
         '''

{core → src/core}/tools/__init__.py

@@ -13,4 +13,4 @@ __all__ = [
     "PyExecutor",
     "GitServerClient",
     "RepoInfo",
-]
+]

{core → src/core}/tools/git_server_client.py

@@ -100,7 +100,9 @@ class GitServerClient:
         gitconfig_path.write_text(git_config)
 
         # Git credentials
-        git_credentials = f"http://{self.username}:{self.password}@{self.domain}:{self.port}\n"
+        git_credentials = (
+            f"http://{self.username}:{self.password}@{self.domain}:{self.port}\n"
+        )
         gitcreds_path = home_dir / ".git-credentials"
         gitcreds_path.write_text(git_credentials)
         gitcreds_path.chmod(0o600)
@@ -272,7 +274,12 @@ class GitServerClient:
             raise RuntimeError(f"Checkout failed: {result.stderr}")
 
         result = subprocess.run(
-            ["git", "reset", "--hard", f"origin/{commit}" if commit != "main" else commit],
+            [
+                "git",
+                "reset",
+                "--hard",
+                f"origin/{commit}" if commit != "main" else commit,
+            ],
             cwd=str(repo_path),
             capture_output=True,
             text=True,

{core → src/core}/tools/local_python_executor.py

@@ -28,7 +28,7 @@ from typing import Any
 
 from smolagents import LocalPythonExecutor
 
-from core.env_server.types import CodeExecResult
+from openenv.core.env_server.types import CodeExecResult
 
 logger = logging.getLogger(__name__)
 logger.addHandler(logging.NullHandler())
@@ -69,7 +69,10 @@ class PyExecutor:
         except Exception:
             # If the LocalPythonExecutor implementation doesn't support
             # send_tools or fails, log and continue — the executor is still usable.
-            logger.debug("LocalPythonExecutor.send_tools failed; continuing without extra tools", exc_info=True)
+            logger.debug(
+                "LocalPythonExecutor.send_tools failed; continuing without extra tools",
+                exc_info=True,
+            )
 
     def run(self, code: str) -> CodeExecResult:
         """Execute Python code and return a CodeExecResult.
@@ -127,7 +130,11 @@ class PyExecutor:
             # Determine exit code if provided
             try:
                 if hasattr(exec_result, "exit_code"):
-                    exit_code = int(exec_result.exit_code) if exec_result.exit_code is not None else 0
+                    exit_code = (
+                        int(exec_result.exit_code)
+                        if exec_result.exit_code is not None
+                        else 0
+                    )
                 elif hasattr(exec_result, "success"):
                     # Some versions use `success` boolean
                     exit_code = 0 if exec_result.success else 1

src/core/utils.py

@@ -0,0 +1,27 @@
+# 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.
+
+"""Utility functions for OpenEnv core."""
+
+
+def convert_to_ws_url(url: str) -> str:
+    """
+    Convert an HTTP/HTTPS URL to a WS/WSS URL.
+
+    Args:
+        url: The URL to convert.
+
+    Returns:
+        The converted WebSocket URL.
+    """
+    ws_url = url.rstrip("/")
+    if ws_url.startswith("http://"):
+        ws_url = "ws://" + ws_url[7:]
+    elif ws_url.startswith("https://"):
+        ws_url = "wss://" + ws_url[8:]
+    elif not ws_url.startswith("ws://") and not ws_url.startswith("wss://"):
+        ws_url = "ws://" + ws_url
+    return ws_url

src/openenv/__init__.py

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

{core/containers → src/openenv/cli}/__init__.py

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

src/openenv/cli/__main__.py

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

src/openenv/cli/_cli_utils.py

@@ -0,0 +1,76 @@
+# 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.
+
+"""CLI utilities for OpenEnv command-line interface."""
+
+from pathlib import Path
+from typing import List
+
+from rich.console import Console
+
+# Create a console instance for CLI output
+console = Console()
+
+
+def validate_env_structure(env_dir: Path, strict: bool = False) -> List[str]:
+    """
+    Validate that the directory follows OpenEnv environment structure.
+
+    Args:
+        env_dir: Path to environment directory
+        strict: If True, enforce all optional requirements
+
+    Returns:
+        List of validation warnings (empty if all checks pass)
+
+    Raises:
+        FileNotFoundError: If required files are missing
+    """
+    warnings = []
+
+    # Required files
+    required_files = [
+        "openenv.yaml",
+        "__init__.py",
+        "client.py",
+        "models.py",
+        "README.md",
+    ]
+
+    for file in required_files:
+        if not (env_dir / file).exists():
+            raise FileNotFoundError(f"Required file missing: {file}")
+
+    # Required directories
+    server_dir = env_dir / "server"
+    if not server_dir.exists() or not server_dir.is_dir():
+        raise FileNotFoundError("Required directory missing: server/")
+
+    # Server directory required files
+    server_required = [
+        "server/__init__.py",
+        "server/app.py",
+        "server/Dockerfile",
+    ]
+
+    for file in server_required:
+        if not (env_dir / file).exists():
+            raise FileNotFoundError(f"Required file missing: {file}")
+
+    # Check for dependency management (pyproject.toml required)
+    has_pyproject = (env_dir / "pyproject.toml").exists()
+
+    if not has_pyproject:
+        raise FileNotFoundError(
+            "No dependency specification found. 'pyproject.toml' is required."
+        )
+
+    # Warnings for recommended structure
+
+    if not (env_dir / "outputs").exists():
+        warnings.append("Recommended directory missing: outputs/")
+
+    return warnings

src/openenv/cli/_validation.py

@@ -0,0 +1,159 @@
+# 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.
+
+"""
+Validation utilities for multi-mode deployment readiness.
+
+This module provides functions to check if environments are properly
+configured for multi-mode deployment (Docker, direct Python, notebooks, clusters).
+"""
+
+import subprocess
+import tomllib
+from pathlib import Path
+
+
+def validate_multi_mode_deployment(env_path: Path) -> tuple[bool, list[str]]:
+    """
+    Validate that an environment is ready for multi-mode deployment.
+
+    Checks:
+    1. pyproject.toml exists
+    2. uv.lock exists and is up-to-date
+    3. pyproject.toml has [project.scripts] with server entry point
+    4. server/app.py has a main() function
+    5. Required dependencies are present
+
+    Returns:
+        Tuple of (is_valid, list of issues found)
+    """
+    issues = []
+
+    # Check pyproject.toml exists
+    pyproject_path = env_path / "pyproject.toml"
+    if not pyproject_path.exists():
+        issues.append("Missing pyproject.toml")
+        return False, issues
+
+    # Check uv.lock exists
+    lockfile_path = env_path / "uv.lock"
+    if not lockfile_path.exists():
+        issues.append("Missing uv.lock - run 'uv lock' to generate it")
+    else:
+        # Check if uv.lock is up-to-date (optional, can be expensive)
+        # We can add a check using `uv lock --check` if needed
+        try:
+            result = subprocess.run(
+                ["uv", "lock", "--check", "--directory", str(env_path)],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if result.returncode != 0:
+                issues.append(
+                    "uv.lock is out of date with pyproject.toml - run 'uv lock' to update"
+                )
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            # If uv is not available or times out, skip this check
+            pass
+
+    # Parse pyproject.toml
+    try:
+        with open(pyproject_path, "rb") as f:
+            pyproject = tomllib.load(f)
+    except Exception as e:
+        issues.append(f"Failed to parse pyproject.toml: {e}")
+        return False, issues
+
+    # Check [project.scripts] section
+    scripts = pyproject.get("project", {}).get("scripts", {})
+    if "server" not in scripts:
+        issues.append("Missing [project.scripts] server entry point")
+
+    # Check server entry point format
+    server_entry = scripts.get("server", "")
+    if server_entry and ":main" not in server_entry:
+        issues.append(
+            f"Server entry point should reference main function, got: {server_entry}"
+        )
+
+    # Check required dependencies
+    deps = [dep.lower() for dep in pyproject.get("project", {}).get("dependencies", [])]
+    has_openenv = any(
+        dep.startswith("openenv") and not dep.startswith("openenv-core") for dep in deps
+    )
+    has_legacy_core = any(dep.startswith("openenv-core") for dep in deps)
+
+    if not (has_openenv or has_legacy_core):
+        issues.append("Missing required dependency: openenv>=0.2.0")
+    elif has_legacy_core and not has_openenv:
+        issues.append(
+            "Dependency on openenv-core is deprecated; use openenv>=0.2.0 instead"
+        )
+
+    # Check server/app.py exists
+    server_app = env_path / "server" / "app.py"
+    if not server_app.exists():
+        issues.append("Missing server/app.py")
+    else:
+        # Check for main() function (flexible - with or without parameters)
+        app_content = server_app.read_text(encoding="utf-8")
+        if "def main(" not in app_content:
+            issues.append("server/app.py missing main() function")
+
+        # Check if main() is callable
+        if "__name__" not in app_content or "main()" not in app_content:
+            issues.append(
+                "server/app.py main() function not callable (missing if __name__ == '__main__')"
+            )
+
+    return len(issues) == 0, issues
+
+
+def get_deployment_modes(env_path: Path) -> dict[str, bool]:
+    """
+    Check which deployment modes are supported by the environment.
+
+    Returns:
+        Dictionary with deployment mode names and whether they're supported
+    """
+    modes = {
+        "docker": False,
+        "openenv_serve": False,
+        "uv_run": False,
+        "python_module": False,
+    }
+
+    # Check Docker
+    dockerfile = env_path / "server" / "Dockerfile"
+    modes["docker"] = dockerfile.exists()
+
+    # Check multi-mode deployment readiness
+    is_valid, _ = validate_multi_mode_deployment(env_path)
+    if is_valid:
+        modes["openenv_serve"] = True
+        modes["uv_run"] = True
+        modes["python_module"] = True
+
+    return modes
+
+
+def format_validation_report(env_name: str, is_valid: bool, issues: list[str]) -> str:
+    """
+    Format a validation report for display.
+
+    Returns:
+        Formatted report string
+    """
+    if is_valid:
+        return f"[OK] {env_name}: Ready for multi-mode deployment"
+
+    report = [f"[FAIL] {env_name}: Not ready for multi-mode deployment", ""]
+    report.append("Issues found:")
+    for issue in issues:
+        report.append(f"  - {issue}")
+
+    return "\n".join(report)

src/openenv/cli/commands/__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.
+
+"""OpenEnv CLI commands."""
+
+from . import build, init, push, serve, validate
+
+__all__ = ["build", "init", "push", "serve", "validate"]

src/openenv/cli/commands/build.py

@@ -0,0 +1,453 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Build Docker images for OpenEnv environments."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from .._cli_utils import console
+
+app = typer.Typer(help="Build Docker images for OpenEnv environments")
+
+
+def _detect_build_context(env_path: Path) -> tuple[str, Path, Path | None]:
+    """
+    Detect whether we're building a standalone or in-repo environment.
+
+    Returns:
+        tuple: (build_mode, build_context_path, repo_root)
+            - build_mode: "standalone" or "in-repo"
+            - build_context_path: Path to use as Docker build context
+            - repo_root: Path to repo root (None for standalone)
+    """
+    # Ensure env_path is absolute for proper comparison
+    env_path = env_path.absolute()
+
+    # Check if we're in a git repository
+    current = env_path
+    repo_root = None
+
+    # Walk up to find .git directory
+    for parent in [current] + list(current.parents):
+        if (parent / ".git").exists():
+            repo_root = parent
+            break
+
+    if repo_root is None:
+        # Not in a git repo = standalone
+        return "standalone", env_path, None
+
+    # Check if environment is under envs/ (in-repo pattern)
+    try:
+        rel_path = env_path.relative_to(repo_root)
+        rel_str = str(rel_path)
+        if (
+            rel_str.startswith("envs/")
+            or rel_str.startswith("envs\\")
+            or rel_str.startswith("envs/")
+        ):
+            # In-repo environment
+            return "in-repo", repo_root, repo_root
+    except ValueError:
+        pass
+
+    # Otherwise, it's standalone (environment outside repo structure)
+    return "standalone", env_path, None
+
+
+def _prepare_standalone_build(env_path: Path, temp_dir: Path) -> Path:
+    """
+    Prepare a standalone environment for building.
+
+    For standalone builds:
+    1. Copy environment to temp directory
+    2. Ensure pyproject.toml depends on openenv
+
+    Returns:
+        Path to the prepared build directory
+    """
+    console.print("[cyan]Preparing standalone build...[/cyan]")
+
+    # Copy environment to temp directory
+    build_dir = temp_dir / env_path.name
+    shutil.copytree(env_path, build_dir, symlinks=True)
+
+    console.print(f"[cyan]Copied environment to:[/cyan] {build_dir}")
+
+    # Check if pyproject.toml has openenv dependency
+    pyproject_path = build_dir / "pyproject.toml"
+    if pyproject_path.exists():
+        with open(pyproject_path, "rb") as f:
+            try:
+                import tomli
+
+                pyproject = tomli.load(f)
+                deps = pyproject.get("project", {}).get("dependencies", [])
+
+                # Check if openenv dependency is declared
+                has_openenv = any(dep.startswith("openenv") for dep in deps)
+
+                if not has_openenv:
+                    console.print(
+                        "[yellow]Warning:[/yellow] pyproject.toml doesn't list the openenv dependency",
+                    )
+                    console.print(
+                        "[yellow]You may need to add:[/yellow] openenv>=0.2.0",
+                    )
+            except ImportError:
+                console.print(
+                    "[yellow]Warning:[/yellow] tomli not available, skipping dependency check",
+                )
+
+    return build_dir
+
+
+def _prepare_inrepo_build(env_path: Path, repo_root: Path, temp_dir: Path) -> Path:
+    """
+    Prepare an in-repo environment for building.
+
+    For in-repo builds:
+    1. Create temp directory with environment and core
+    2. Set up structure that matches expected layout
+
+    Returns:
+        Path to the prepared build directory
+    """
+    console.print("[cyan]Preparing in-repo build...[/cyan]")
+
+    # Copy environment to temp directory
+    build_dir = temp_dir / env_path.name
+    shutil.copytree(env_path, build_dir, symlinks=True)
+
+    # Copy OpenEnv package to temp directory
+    package_src = repo_root / "src" / "openenv"
+    if package_src.exists():
+        package_dest = build_dir / "openenv"
+        shutil.copytree(package_src, package_dest, symlinks=True)
+        console.print(f"[cyan]Copied OpenEnv package to:[/cyan] {package_dest}")
+
+        # Update pyproject.toml to reference local OpenEnv copy
+        pyproject_path = build_dir / "pyproject.toml"
+        if pyproject_path.exists():
+            with open(pyproject_path, "rb") as f:
+                try:
+                    import tomli
+
+                    pyproject = tomli.load(f)
+                    deps = pyproject.get("project", {}).get("dependencies", [])
+
+                    # Replace openenv/openenv-core with local reference
+                    new_deps = []
+                    for dep in deps:
+                        if (
+                            dep.startswith("openenv-core")
+                            or dep.startswith("openenv_core")
+                            or dep.startswith("openenv")
+                        ):
+                            # Skip - we'll use local core
+                            continue
+                        new_deps.append(dep)
+
+                    # Write back with local core reference
+                    pyproject["project"]["dependencies"] = new_deps + [
+                        "openenv @ file:///app/env/openenv"
+                    ]
+
+                    # Write updated pyproject.toml
+                    with open(pyproject_path, "wb") as out_f:
+                        import tomli_w
+
+                        tomli_w.dump(pyproject, out_f)
+
+                    console.print(
+                        "[cyan]Updated pyproject.toml to use local core[/cyan]"
+                    )
+
+                    # Remove old lockfile since dependencies changed
+                    lockfile = build_dir / "uv.lock"
+                    if lockfile.exists():
+                        lockfile.unlink()
+                        console.print("[cyan]Removed outdated uv.lock[/cyan]")
+
+                except ImportError:
+                    console.print(
+                        "[yellow]Warning:[/yellow] tomli/tomli_w not available, using pyproject.toml as-is",
+                    )
+    else:
+        console.print(
+            "[yellow]Warning:[/yellow] OpenEnv package not found, building without it"
+        )
+
+    console.print(f"[cyan]Build directory prepared:[/cyan] {build_dir}")
+    return build_dir
+
+
+def _run_command(
+    cmd: list[str],
+    cwd: Path | None = None,
+    check: bool = True,
+) -> subprocess.CompletedProcess:
+    """Run a shell command and handle errors."""
+    console.print(f"[bold cyan]Running:[/bold cyan] {' '.join(cmd)}")
+    try:
+        result = subprocess.run(
+            cmd, cwd=cwd, check=check, capture_output=True, text=True
+        )
+        if result.stdout:
+            console.print(result.stdout)
+        if result.stderr:
+            print(result.stderr, file=sys.stderr)
+        return result
+    except subprocess.CalledProcessError as e:
+        print(f"Error running command: {e}", file=sys.stderr)
+        if e.stdout:
+            console.print(e.stdout)
+        if e.stderr:
+            print(e.stderr, file=sys.stderr)
+        if check:
+            raise typer.Exit(1) from e
+        return e
+
+
+def _build_docker_image(
+    env_path: Path,
+    tag: str | None = None,
+    context_path: Path | None = None,
+    dockerfile: Path | None = None,
+    build_args: dict[str, str] | None = None,
+    no_cache: bool = False,
+) -> bool:
+    """Build Docker image for the environment with smart context detection."""
+
+    # Detect build context (standalone vs in-repo)
+    build_mode, detected_context, repo_root = _detect_build_context(env_path)
+
+    console.print(f"[bold cyan]Build mode detected:[/bold cyan] {build_mode}")
+
+    # Use detected context unless explicitly overridden
+    if context_path is None:
+        context_path = detected_context
+
+    # Create temporary build directory
+    with tempfile.TemporaryDirectory() as temp_dir_str:
+        temp_dir = Path(temp_dir_str)
+
+        # Prepare build directory based on mode
+        if build_mode == "standalone":
+            build_dir = _prepare_standalone_build(env_path, temp_dir)
+        else:  # in-repo
+            build_dir = _prepare_inrepo_build(env_path, repo_root, temp_dir)
+
+        # Determine Dockerfile path
+        if dockerfile is None:
+            # Look for Dockerfile in server/ subdirectory
+            dockerfile = build_dir / "server" / "Dockerfile"
+            if not dockerfile.exists():
+                # Fallback to root of build directory
+                dockerfile = build_dir / "Dockerfile"
+
+        if not dockerfile.exists():
+            console.print(
+                f"[bold red]Error:[/bold red] Dockerfile not found at {dockerfile}",
+            )
+            return False
+
+        # Generate tag if not provided
+        if tag is None:
+            env_name = env_path.name
+            if env_name.endswith("_env"):
+                env_name = env_name[:-4]
+            tag = f"openenv-{env_name}"
+
+        console.print(f"[bold cyan]Building Docker image:[/bold cyan] {tag}")
+        console.print(f"[bold cyan]Build context:[/bold cyan] {build_dir}")
+        console.print(f"[bold cyan]Dockerfile:[/bold cyan] {dockerfile}")
+
+        # Prepare build args
+        if build_args is None:
+            build_args = {}
+
+        # Add build mode and env name to build args
+        build_args["BUILD_MODE"] = build_mode
+        build_args["ENV_NAME"] = env_path.name.replace("_env", "")
+
+        # Build Docker command
+        cmd = ["docker", "build", "-t", tag, "-f", str(dockerfile)]
+
+        if no_cache:
+            cmd.append("--no-cache")
+
+        for key, value in build_args.items():
+            cmd.extend(["--build-arg", f"{key}={value}"])
+
+        cmd.append(str(build_dir))
+
+        result = _run_command(cmd, check=False)
+        return result.returncode == 0
+
+
+def _push_docker_image(tag: str, registry: str | None = None) -> bool:
+    """Push Docker image to registry."""
+    if registry:
+        full_tag = f"{registry}/{tag}"
+        console.print(f"[bold cyan]Tagging image as {full_tag}[/bold cyan]")
+        _run_command(["docker", "tag", tag, full_tag])
+        tag = full_tag
+
+    console.print(f"[bold cyan]Pushing image:[/bold cyan] {tag}")
+    result = _run_command(["docker", "push", tag], check=False)
+    return result.returncode == 0
+
+
+@app.command()
+def build(
+    env_path: Annotated[
+        str | None,
+        typer.Argument(
+            help="Path to the environment directory (default: current directory)"
+        ),
+    ] = None,
+    tag: Annotated[
+        str | None,
+        typer.Option(
+            "--tag",
+            "-t",
+            help="Docker image tag (default: openenv-<env_name>)",
+        ),
+    ] = None,
+    context: Annotated[
+        str | None,
+        typer.Option(
+            "--context",
+            "-c",
+            help="Build context path (default: <env_path>/server)",
+        ),
+    ] = None,
+    dockerfile: Annotated[
+        str | None,
+        typer.Option(
+            "--dockerfile",
+            "-f",
+            help="Path to Dockerfile (default: <context>/Dockerfile)",
+        ),
+    ] = None,
+    no_cache: Annotated[
+        bool,
+        typer.Option(
+            "--no-cache",
+            help="Build without using cache",
+        ),
+    ] = False,
+    build_arg: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--build-arg",
+            help="Build arguments (can be used multiple times, format: KEY=VALUE)",
+        ),
+    ] = None,
+) -> None:
+    """
+    Build Docker images for OpenEnv environments.
+
+    This command builds Docker images using the environment's pyproject.toml
+    and uv for dependency management. Run from the environment root directory.
+
+    Examples:
+        # Build from environment root (recommended)
+        $ cd my_env
+        $ openenv build
+
+        # Build with custom tag
+        $ openenv build -t my-custom-tag
+
+        # Build without cache
+        $ openenv build --no-cache
+
+        # Build with custom build arguments
+        $ openenv build --build-arg VERSION=1.0 --build-arg ENV=prod
+
+        # Build from different directory
+        $ openenv build envs/echo_env
+    """
+    # Determine environment path (default to current directory)
+    if env_path is None:
+        env_path_obj = Path.cwd()
+    else:
+        env_path_obj = Path(env_path)
+
+    # Validate environment path
+    if not env_path_obj.exists():
+        print(
+            f"Error: Environment path does not exist: {env_path_obj}",
+            file=sys.stderr,
+        )
+        raise typer.Exit(1)
+
+    if not env_path_obj.is_dir():
+        print(
+            f"Error: Environment path is not a directory: {env_path_obj}",
+            file=sys.stderr,
+        )
+        raise typer.Exit(1)
+
+    # Check for openenv.yaml to confirm this is an environment directory
+    openenv_yaml = env_path_obj / "openenv.yaml"
+    if not openenv_yaml.exists():
+        print(
+            f"Error: Not an OpenEnv environment directory (missing openenv.yaml): {env_path_obj}",
+            file=sys.stderr,
+        )
+        print(
+            "Hint: Run this command from the environment root directory or specify the path",
+            file=sys.stderr,
+        )
+        raise typer.Exit(1)
+
+    console.print(f"[bold]Building Docker image for:[/bold] {env_path_obj.name}")
+    console.print("=" * 60)
+
+    # Parse build args
+    build_args = {}
+    if build_arg:
+        for arg in build_arg:
+            if "=" in arg:
+                key, value = arg.split("=", 1)
+                build_args[key] = value
+            else:
+                print(
+                    f"Warning: Invalid build arg format: {arg}",
+                    file=sys.stderr,
+                )
+
+    # Convert string paths to Path objects
+    context_path_obj = Path(context) if context else None
+    dockerfile_path_obj = Path(dockerfile) if dockerfile else None
+
+    # Build Docker image
+    success = _build_docker_image(
+        env_path=env_path_obj,
+        tag=tag,
+        context_path=context_path_obj,
+        dockerfile=dockerfile_path_obj,
+        build_args=build_args if build_args else None,
+        no_cache=no_cache,
+    )
+
+    if not success:
+        print("Γ£ù Docker build failed", file=sys.stderr)
+        raise typer.Exit(1)
+
+    console.print("[bold green]Γ£ô Docker build successful[/bold green]")
+    console.print("\n[bold green]Done![/bold green]")

src/openenv/cli/commands/init.py

@@ -0,0 +1,501 @@
+"""Initialize a new OpenEnv environment."""
+
+from __future__ import annotations
+
+import os
+import random
+import shutil
+import subprocess
+from importlib import resources
+from pathlib import Path
+from typing import Annotated, Dict, List, Optional, Tuple
+
+import typer
+
+from .._cli_utils import console
+
+# Commands are registered in __main__.py
+
+
+def _snake_to_pascal(snake_str: str) -> str:
+    """Convert snake_case to PascalCase (e.g., 'my_env' -> 'MyEnv')."""
+    return "".join(word.capitalize() for word in snake_str.split("_"))
+
+
+def _get_env_prefix(env_name: str) -> str:
+    """Extract the prefix for class names (e.g., 'my_env' -> 'My', 'test_env' -> 'Test')."""
+    # Remove trailing '_env' if present
+    if env_name.endswith("_env"):
+        base = env_name[:-4]  # Remove '_env'
+    else:
+        base = env_name
+
+    # If empty or just one part, use the whole thing
+    if not base or "_" not in base:
+        return base.capitalize() if base else env_name.capitalize()
+
+    # PascalCase all parts except the last
+    parts = base.split("_")
+    return "".join(word.capitalize() for word in parts)
+
+
+def _snake_to_camel(snake_str: str) -> str:
+    """Convert snake_case to camelCase (e.g., 'my_env' -> 'myEnv')."""
+    parts = snake_str.split("_")
+    return parts[0] + "".join(word.capitalize() for word in parts[1:])
+
+
+def _snake_to_title(snake_str: str) -> str:
+    """Convert snake_case to Title Case (e.g., 'my_env' -> 'My Env')."""
+    return " ".join(word.capitalize() for word in snake_str.split("_"))
+
+
+def _validate_env_name(name: str) -> str:
+    """Validate environment name (must be valid Python identifier in snake_case)."""
+    if not name:
+        raise typer.BadParameter("Environment name cannot be empty")
+
+    # Check if it's a valid Python identifier
+    if not name.isidentifier():
+        raise typer.BadParameter(
+            f"Environment name '{name}' is not a valid Python identifier. Use snake_case (e.g., 'my_env', 'game_env')."
+        )
+
+    # Check if it starts with a number
+    if name[0].isdigit():
+        raise typer.BadParameter(
+            f"Environment name '{name}' cannot start with a number."
+        )
+
+    return name
+
+
+def _get_random_hf_space_config() -> Dict[str, str]:
+    """
+    Get random Hugging Face Space configuration values.
+
+    Returns:
+        Dictionary with 'emoji', 'colorFrom', and 'colorTo' keys
+    """
+    # Valid emojis (emoji-only characters)
+    emojis = [
+        "🎮",
+        "🎯",
+        "🚀",
+        "🌟",
+        "🎨",
+        "🎪",
+        "🎭",
+        "🎬",
+        "🎤",
+        "🎧",
+        "🎵",
+        "🎶",
+        "🎸",
+        "🎹",
+        "🥁",
+        "🎺",
+        "🎻",
+        "🎼",
+        "🎯",
+        "🎲",
+        "🎳",
+        "🎰",
+        "🎴",
+        "🃏",
+        "🀄",
+        "🎴",
+        "🎨",
+        "🖼️",
+        "🎬",
+        "🎭",
+        "🎪",
+        "🎤",
+        "🎧",
+        "🎵",
+        "🎶",
+        "🎸",
+        "🎹",
+        "🎺",
+        "🎻",
+        "🥁",
+        "🎯",
+        "🎲",
+        "🎳",
+        "🎰",
+        "🏀",
+        "⚽",
+        "🏈",
+        "⚾",
+        "🎾",
+        "🏐",
+        "🏉",
+        "🎱",
+        "🏓",
+        "🏸",
+        "🥅",
+        "🏒",
+        "🏑",
+        "🏏",
+        "⛳",
+        "🏹",
+        "🎣",
+        "🥊",
+        "🥋",
+        "🎽",
+        "🏅",
+        "🎖️",
+        "🏆",
+        "🥇",
+        "🥈",
+        "🥉",
+        "🔊",
+        "🔉",
+        "🔈",
+        "🔇",
+        "📢",
+        "📣",
+        "📯",
+        "🔔",
+        "🔕",
+        "📻",
+        "📡",
+        "💻",
+        "🖥️",
+        "🖨️",
+        "⌨️",
+        "🖱️",
+        "🖲️",
+        "🕹️",
+        "🗜️",
+        "💾",
+        "💿",
+        "📀",
+        "📼",
+        "📷",
+        "📸",
+        "📹",
+        "🎥",
+        "📽️",
+        "🎞️",
+        "📞",
+        "☎️",
+        "📟",
+        "📠",
+        "📺",
+        "📻",
+        "🎙️",
+        "🎚️",
+        "🎛️",
+        "⏱️",
+        "⏲️",
+        "⏰",
+        "🕰️",
+        "⌚",
+        "📱",
+        "📲",
+        "💻",
+        "⌨️",
+        "🖥️",
+        "🖨️",
+        "🖱️",
+    ]
+
+    # Valid colors from HF Spaces config reference
+    colors = ["red", "yellow", "green", "blue", "indigo", "purple", "pink", "gray"]
+
+    return {
+        "emoji": random.choice(emojis),
+        "colorFrom": random.choice(colors),
+        "colorTo": random.choice(colors),
+    }
+
+
+def _create_template_replacements(env_name: str) -> Dict[str, str]:
+    """
+    Create comprehensive template replacement dictionary.
+
+    Supports all naming conventions:
+    - PascalCase for class names
+    - camelCase for variable names
+    - snake_case for module names, file paths
+    """
+    env_pascal = _snake_to_pascal(env_name)
+    env_prefix = _get_env_prefix(env_name)
+    env_camel = _snake_to_camel(env_name)
+    env_title = _snake_to_title(env_name)
+
+    # Get random HF Space config values
+    hf_config = _get_random_hf_space_config()
+
+    replacements = {
+        # Template placeholders (MUST come first - full class names before partial)
+        "__ENV_CLASS_NAME__Environment": f"{env_prefix}Environment",
+        "__ENV_CLASS_NAME__Action": f"{env_prefix}Action",
+        "__ENV_CLASS_NAME__Observation": f"{env_prefix}Observation",
+        "__ENV_CLASS_NAME__Env": f"{env_prefix}Env",
+        # Template placeholders (partial - must come after full replacements)
+        "__ENV_NAME__": env_name,
+        "__ENV_CLASS_NAME__": env_prefix,  # Use prefix, not full PascalCase
+        "__ENV_TITLE_NAME__": env_title,
+        "__ENV_CAMEL_NAME__": env_camel,
+        # Hugging Face Space config placeholders
+        "__HF_EMOJI__": hf_config["emoji"],
+        "__HF_COLOR_FROM__": hf_config["colorFrom"],
+        "__HF_COLOR_TO__": hf_config["colorTo"],
+    }
+
+    return replacements
+
+
+def _replace_in_content(content: str, replacements: Dict[str, str]) -> str:
+    """Replace all occurrences in content using case-sensitive replacements."""
+    result = content
+    # Sort by length (longest first) to avoid partial replacements
+    for old, new in sorted(replacements.items(), key=lambda x: len(x[0]), reverse=True):
+        result = result.replace(old, new)
+    return result
+
+
+def _should_rename_file(filename: str, env_name: str) -> Tuple[bool, str]:
+    """
+    Check if a file should be renamed and return the new name.
+
+    Handles template placeholders in filenames like:
+    - `__ENV_NAME___environment.py` → `<env_name>_environment.py`
+    """
+    # Check for template placeholder
+    if "__ENV_NAME__" in filename:
+        new_name = filename.replace("__ENV_NAME__", env_name)
+        return True, new_name
+
+    return False, filename
+
+
+def _copy_and_template_file(
+    src_path: Path,
+    dest_path: Path,
+    replacements: Dict[str, str],
+) -> None:
+    """Copy a file and apply template replacements."""
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        # Read source file
+        content = src_path.read_bytes()
+
+        # Try to decode as text and apply replacements
+        try:
+            text = content.decode("utf-8")
+            # Normalize line endings to LF before applying replacements
+            text = text.replace("\r\n", "\n").replace("\r", "\n")
+            text = _replace_in_content(text, replacements)
+            dest_path.write_text(text, encoding="utf-8", newline="\n")
+        except UnicodeDecodeError:
+            # Binary file, just copy
+            dest_path.write_bytes(content)
+    except Exception as e:
+        raise RuntimeError(
+            f"Failed to copy template file {src_path} to {dest_path}: {e}"
+        ) from e
+
+
+def _copy_template_directory(
+    template_pkg: str,
+    template_dir: str,
+    dest_dir: Path,
+    replacements: Dict[str, str],
+    env_name: str,
+) -> List[Path]:
+    """Recursively copy template directory and apply replacements."""
+    created_files: List[Path] = []
+
+    # Get the package path using importlib.resources but avoid importing the template package
+    # We'll use the package's __file__ to get the directory path
+    import importlib
+
+    try:
+        # Import the parent package (not the template package itself)
+        if "." in template_pkg:
+            parent_pkg = ".".join(template_pkg.split(".")[:-1])
+            pkg = importlib.import_module(parent_pkg)
+            template_path = Path(pkg.__file__).parent / template_pkg.split(".")[-1]
+        else:
+            pkg = importlib.import_module(template_pkg.split(".")[0])
+            template_path = Path(pkg.__file__).parent / template_pkg.split(".")[-1]
+    except Exception:
+        # Fallback: try to use resources.files but handle import errors
+        try:
+            base = resources.files(template_pkg.split(".")[0])
+            template_path = base.joinpath(*template_pkg.split(".")[1:])
+            if not template_path.exists():
+                raise FileNotFoundError(f"Template directory not found: {template_pkg}")
+        except Exception as e:
+            raise FileNotFoundError(
+                f"Template directory not found: {template_pkg}"
+            ) from e
+
+    if template_dir:
+        template_path = template_path / template_dir
+
+    if not template_path.exists() or not template_path.is_dir():
+        raise FileNotFoundError(
+            f"Template directory not found: {template_pkg}.{template_dir}"
+        )
+
+    # Walk through all files in template directory using Path
+    for item in template_path.rglob("*"):
+        if item.is_file():
+            rel_path = item.relative_to(template_path)
+            dest_path = dest_dir / rel_path
+
+            # Apply filename templating
+            should_rename, new_name = _should_rename_file(dest_path.name, env_name)
+            if should_rename:
+                dest_path = dest_path.parent / new_name
+
+            # Copy and apply replacements
+            _copy_and_template_file(item, dest_path, replacements)
+            created_files.append(dest_path)
+
+    return created_files
+
+
+def _generate_uv_lock(env_dir: Path) -> bool:
+    """Generate uv.lock from pyproject.toml using uv."""
+    pyproject_path = env_dir / "pyproject.toml"
+
+    if not pyproject_path.exists():
+        return False
+
+    try:
+        cmd = [
+            "uv",
+            "lock",
+            "--directory",
+            str(env_dir),
+        ]
+
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+
+        if result.stdout:
+            console.print(result.stdout)
+
+        return True
+
+    except subprocess.CalledProcessError as e:
+        console.print(
+            f"[yellow]Warning: Could not generate uv.lock: {e.stderr}[/yellow]"
+        )
+        return False
+    except FileNotFoundError:
+        console.print(
+            "[yellow]Warning: 'uv' not found. Install it to generate uv.lock[/yellow]"
+        )
+        return False
+
+
+def init(
+    env_name: Annotated[
+        str,
+        typer.Argument(
+            help="Name of the environment to create (snake_case, e.g., 'my_env')"
+        ),
+    ],
+    output_dir: Annotated[
+        Optional[str],
+        typer.Option(
+            "--output-dir",
+            "-o",
+            help="Output directory (defaults to current working directory)",
+        ),
+    ] = None,
+) -> None:
+    """
+    Initialize a new OpenEnv environment.
+
+    Creates a new directory with the environment name and generates all necessary
+    files based on the OpenEnv template structure.
+
+    Example:
+        $ openenv init my_game_env
+        $ openenv init my_env --output-dir /path/to/projects
+    """
+    # Validate environment name
+    env_name = _validate_env_name(env_name)
+
+    # Determine output directory
+    base_dir = Path(output_dir).resolve() if output_dir else Path.cwd().resolve()
+    env_dir = base_dir / env_name
+
+    # Check if directory already exists
+    if env_dir.exists():
+        if env_dir.is_file():
+            raise typer.BadParameter(f"Path '{env_dir}' exists and is a file")
+        if any(env_dir.iterdir()):
+            raise typer.BadParameter(
+                f"Directory '{env_dir}' already exists and is not empty. "
+                "Please choose a different name or remove the existing directory."
+            )
+
+    try:
+        # Create template replacements
+        replacements = _create_template_replacements(env_name)
+
+        # Create environment directory
+        env_dir.mkdir(parents=True, exist_ok=True)
+
+        console.print(
+            f"[bold cyan]Creating OpenEnv environment '{env_name}'...[/bold cyan]"
+        )
+
+        # Copy template files from template structure
+        template_pkg = "openenv.cli.templates.openenv_env"
+        created_files = _copy_template_directory(
+            template_pkg,
+            "",
+            env_dir,
+            replacements,
+            env_name,
+        )
+
+        console.print(f"[bold green]✓[/bold green] Created {len(created_files)} files")
+
+        # Generate uv.lock
+        console.print("\n[bold]Generating uv.lock...[/bold]")
+        if _generate_uv_lock(env_dir):
+            console.print("[green]✓[/green] Generated uv.lock")
+        else:
+            console.print("[yellow]⚠[/yellow] Could not generate uv.lock automatically")
+            console.print("    You can generate it manually with:")
+            console.print(f"    cd {env_dir} && uv lock")
+
+        console.print(
+            f"\n[bold green]Environment created successfully at: {env_dir}[/bold green]"
+        )
+        console.print("\n[bold]Next steps:[/bold]")
+        console.print(f"  cd {env_dir}")
+        console.print(
+            f"  # Edit your environment implementation in server/{env_name}_environment.py"
+        )
+        console.print("  # Edit your models in models.py")
+        console.print("  # Install dependencies: uv sync")
+        console.print("\n  # To integrate into OpenEnv repo:")
+        console.print(f"  # 1. Copy this directory to <repo_root>/envs/{env_name}_env")
+        console.print(
+            f"  # 2. Build from repo root: docker build -t {env_name}_env:latest -f envs/{env_name}_env/server/Dockerfile ."
+        )
+        console.print(
+            f"  # 3. Run your image: docker run -p 8000:8000 {env_name}_env:latest"
+        )
+
+    except Exception as e:
+        # Cleanup on error
+        if env_dir.exists() and env_dir.is_dir():
+            try:
+                shutil.rmtree(env_dir)
+            except Exception:
+                pass
+
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1) from e

src/openenv/cli/commands/push.py

@@ -0,0 +1,541 @@
+# 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.
+
+"""Push an OpenEnv environment to Hugging Face Spaces."""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Annotated
+import sys
+import typer
+import yaml
+from huggingface_hub import HfApi, login, whoami
+
+from .._cli_utils import console, validate_env_structure
+
+app = typer.Typer(help="Push an OpenEnv environment to Hugging Face Spaces")
+
+
+def _validate_openenv_directory(directory: Path) -> tuple[str, dict]:
+    """
+    Validate that the directory is an OpenEnv environment.
+
+    Returns:
+        Tuple of (env_name, manifest_data)
+    """
+    # Use the comprehensive validation function
+    try:
+        warnings = validate_env_structure(directory)
+        for warning in warnings:
+            console.print(f"[bold yellow]ΓÜá[/bold yellow] {warning}")
+    except FileNotFoundError as e:
+        raise typer.BadParameter(f"Invalid OpenEnv environment structure: {e}") from e
+
+    # Load and validate manifest
+    manifest_path = directory / "openenv.yaml"
+    try:
+        with open(manifest_path, "r") as f:
+            manifest = yaml.safe_load(f)
+    except Exception as e:
+        raise typer.BadParameter(f"Failed to parse openenv.yaml: {e}") from e
+
+    if not isinstance(manifest, dict):
+        raise typer.BadParameter("openenv.yaml must be a YAML dictionary")
+
+    env_name = manifest.get("name")
+    if not env_name:
+        raise typer.BadParameter("openenv.yaml must contain a 'name' field")
+
+    return env_name, manifest
+
+
+def _ensure_hf_authenticated() -> str:
+    """
+    Ensure user is authenticated with Hugging Face.
+
+    Returns:
+        Username of authenticated user
+    """
+    try:
+        # Try to get current user
+        user_info = whoami()
+        # Handle both dict and object return types
+        if isinstance(user_info, dict):
+            username = (
+                user_info.get("name")
+                or user_info.get("fullname")
+                or user_info.get("username")
+            )
+        else:
+            # If it's an object, try to get name attribute
+            username = (
+                getattr(user_info, "name", None)
+                or getattr(user_info, "fullname", None)
+                or getattr(user_info, "username", None)
+            )
+
+        if not username:
+            raise ValueError("Could not extract username from whoami response")
+
+        console.print(f"[bold green]Γ£ô[/bold green] Authenticated as: {username}")
+        return username
+    except Exception:
+        # Not authenticated, prompt for login
+        console.print(
+            "[bold yellow]Not authenticated with Hugging Face. Please login...[/bold yellow]"
+        )
+
+        try:
+            login()
+            # Verify login worked
+            user_info = whoami()
+            # Handle both dict and object return types
+            if isinstance(user_info, dict):
+                username = (
+                    user_info.get("name")
+                    or user_info.get("fullname")
+                    or user_info.get("username")
+                )
+            else:
+                username = (
+                    getattr(user_info, "name", None)
+                    or getattr(user_info, "fullname", None)
+                    or getattr(user_info, "username", None)
+                )
+
+            if not username:
+                raise ValueError("Could not extract username from whoami response")
+
+            console.print(f"[bold green]Γ£ô[/bold green] Authenticated as: {username}")
+            return username
+        except Exception as e:
+            raise typer.BadParameter(
+                f"Hugging Face authentication failed: {e}. Please run login manually."
+            ) from e
+
+
+def _prepare_staging_directory(
+    env_dir: Path,
+    env_name: str,
+    staging_dir: Path,
+    base_image: str | None = None,
+    enable_interface: bool = True,
+) -> None:
+    """
+    Prepare files for deployment.
+
+    This includes:
+    - Copying necessary files
+    - Modifying Dockerfile to optionally enable web interface and update base image
+    - Ensuring README has proper HF frontmatter (if interface enabled)
+    """
+    # Create staging directory structure
+    staging_dir.mkdir(parents=True, exist_ok=True)
+
+    # Copy all files from env directory
+    for item in env_dir.iterdir():
+        # Skip hidden files and common ignore patterns
+        if item.name.startswith(".") or item.name in ["__pycache__", ".git"]:
+            continue
+
+        dest = staging_dir / item.name
+        if item.is_dir():
+            shutil.copytree(item, dest, dirs_exist_ok=True)
+        else:
+            shutil.copy2(item, dest)
+
+    # Ensure Dockerfile is at repository root (required by Hugging Face)
+    dockerfile_server_path = staging_dir / "server" / "Dockerfile"
+    dockerfile_root_path = staging_dir / "Dockerfile"
+    dockerfile_path: Path | None = None
+
+    if dockerfile_server_path.exists():
+        if dockerfile_root_path.exists():
+            dockerfile_root_path.unlink()
+        dockerfile_server_path.rename(dockerfile_root_path)
+        console.print(
+            "[bold cyan]Moved Dockerfile to repository root for deployment[/bold cyan]"
+        )
+        dockerfile_path = dockerfile_root_path
+    elif dockerfile_root_path.exists():
+        dockerfile_path = dockerfile_root_path
+
+    # Modify Dockerfile to optionally enable web interface and update base image
+    if dockerfile_path and dockerfile_path.exists():
+        dockerfile_content = dockerfile_path.read_text()
+        lines = dockerfile_content.split("\n")
+        new_lines = []
+        cmd_found = False
+        base_image_updated = False
+        web_interface_env_exists = "ENABLE_WEB_INTERFACE" in dockerfile_content
+        last_instruction = None
+
+        for line in lines:
+            stripped = line.strip()
+            token = stripped.split(maxsplit=1)[0] if stripped else ""
+            current_instruction = token.upper()
+
+            is_healthcheck_continuation = last_instruction == "HEALTHCHECK"
+
+            # Update base image if specified
+            if base_image and stripped.startswith("FROM") and not base_image_updated:
+                new_lines.append(f"FROM {base_image}")
+                base_image_updated = True
+                last_instruction = "FROM"
+                continue
+
+            if (
+                stripped.startswith("CMD")
+                and not cmd_found
+                and not web_interface_env_exists
+                and enable_interface
+                and not is_healthcheck_continuation
+            ):
+                new_lines.append("ENV ENABLE_WEB_INTERFACE=true")
+                cmd_found = True
+
+            new_lines.append(line)
+
+            if current_instruction:
+                last_instruction = current_instruction
+
+        if not cmd_found and not web_interface_env_exists and enable_interface:
+            new_lines.append("ENV ENABLE_WEB_INTERFACE=true")
+
+        if base_image and not base_image_updated:
+            new_lines.insert(0, f"FROM {base_image}")
+
+        dockerfile_path.write_text("\n".join(new_lines))
+
+        changes = []
+        if base_image and base_image_updated:
+            changes.append("updated base image")
+        if enable_interface and not web_interface_env_exists:
+            changes.append("enabled web interface")
+        if changes:
+            console.print(
+                f"[bold green]Γ£ô[/bold green] Updated Dockerfile: {', '.join(changes)}"
+            )
+    else:
+        console.print(
+            "[bold yellow]ΓÜá[/bold yellow] No Dockerfile found at server/Dockerfile"
+        )
+
+    # Ensure README has proper HF frontmatter (only if interface enabled)
+    if enable_interface:
+        readme_path = staging_dir / "README.md"
+        if readme_path.exists():
+            readme_content = readme_path.read_text()
+            if "base_path: /web" not in readme_content:
+                # Check if frontmatter exists
+                if readme_content.startswith("---"):
+                    # Add base_path to existing frontmatter
+                    lines = readme_content.split("\n")
+                    new_lines = []
+                    _in_frontmatter = True
+                    for i, line in enumerate(lines):
+                        new_lines.append(line)
+                        if line.strip() == "---" and i > 0:
+                            # End of frontmatter, add base_path before this line
+                            if "base_path:" not in "\n".join(new_lines):
+                                new_lines.insert(-1, "base_path: /web")
+                            _in_frontmatter = False
+                    readme_path.write_text("\n".join(new_lines))
+                else:
+                    # No frontmatter, add it
+                    frontmatter = f"""---
+title: {env_name.replace("_", " ").title()} Environment Server
+emoji: 🔊
+colorFrom: '#00C9FF'
+colorTo: '#1B2845'
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+"""
+                    readme_path.write_text(frontmatter + readme_content)
+                console.print(
+                    "[bold green]Γ£ô[/bold green] Updated README with HF Space frontmatter"
+                )
+        else:
+            console.print("[bold yellow]ΓÜá[/bold yellow] No README.md found")
+
+
+def _create_hf_space(
+    repo_id: str,
+    api: HfApi,
+    private: bool = False,
+) -> None:
+    """Create a Hugging Face Space if it doesn't exist."""
+    console.print(f"[bold cyan]Creating/verifying space: {repo_id}[/bold cyan]")
+
+    try:
+        api.create_repo(
+            repo_id=repo_id,
+            repo_type="space",
+            space_sdk="docker",
+            private=private,
+            exist_ok=True,
+        )
+        console.print(f"[bold green]Γ£ô[/bold green] Space {repo_id} is ready")
+    except Exception as e:
+        # Space might already exist, which is okay with exist_ok=True
+        # But if there's another error, log it
+        console.print(f"[bold yellow]ΓÜá[/bold yellow] Space creation: {e}")
+
+
+def _upload_to_hf_space(
+    repo_id: str,
+    staging_dir: Path,
+    api: HfApi,
+    private: bool = False,
+) -> None:
+    """Upload files to Hugging Face Space."""
+    console.print(f"[bold cyan]Uploading files to {repo_id}...[/bold cyan]")
+
+    try:
+        api.upload_folder(
+            folder_path=str(staging_dir),
+            repo_id=repo_id,
+            repo_type="space",
+            ignore_patterns=[".git", "__pycache__", "*.pyc"],
+        )
+        console.print("[bold green]Γ£ô[/bold green] Upload completed successfully")
+        console.print(
+            f"[bold]Space URL:[/bold] https://huggingface.co/spaces/{repo_id}"
+        )
+    except Exception as e:
+        console.print(f"[bold red]Γ£ù[/bold red] Upload failed: {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def push(
+    directory: Annotated[
+        str | None,
+        typer.Argument(
+            help="Directory containing the OpenEnv environment (default: current directory)"
+        ),
+    ] = None,
+    repo_id: Annotated[
+        str | None,
+        typer.Option(
+            "--repo-id",
+            "-r",
+            help="Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)",
+        ),
+    ] = None,
+    base_image: Annotated[
+        str | None,
+        typer.Option(
+            "--base-image",
+            "-b",
+            help="Base Docker image to use (overrides Dockerfile FROM)",
+        ),
+    ] = None,
+    interface: Annotated[
+        bool,
+        typer.Option(
+            "--interface",
+            help="Enable web interface (default: True if no registry specified)",
+        ),
+    ] = None,
+    no_interface: Annotated[
+        bool,
+        typer.Option(
+            "--no-interface",
+            help="Disable web interface",
+        ),
+    ] = False,
+    registry: Annotated[
+        str | None,
+        typer.Option(
+            "--registry",
+            help="Custom registry URL (e.g., docker.io/username). Disables web interface by default.",
+        ),
+    ] = None,
+    private: Annotated[
+        bool,
+        typer.Option(
+            "--private",
+            help="Deploy the space as private",
+        ),
+    ] = False,
+) -> None:
+    """
+    Push an OpenEnv environment to Hugging Face Spaces or a custom Docker registry.
+
+    This command:
+    1. Validates that the directory is an OpenEnv environment (openenv.yaml present)
+    2. Builds and pushes to Hugging Face Spaces or custom Docker registry
+    3. Optionally enables web interface for deployment
+
+    The web interface is enabled by default when pushing to HuggingFace Spaces,
+    but disabled by default when pushing to a custom Docker registry.
+
+    Examples:
+        # Push to HuggingFace Spaces from current directory (web interface enabled)
+        $ cd my_env
+        $ openenv push
+
+        # Push to HuggingFace without web interface
+        $ openenv push --no-interface
+
+        # Push to Docker Hub
+        $ openenv push --registry docker.io/myuser
+
+        # Push to GitHub Container Registry
+        $ openenv push --registry ghcr.io/myorg
+
+        # Push to custom registry with web interface
+        $ openenv push --registry myregistry.io/path1/path2 --interface
+
+        # Push to specific HuggingFace repo
+        $ openenv push --repo-id my-org/my-env
+
+        # Push privately with custom base image
+        $ openenv push --private --base-image ghcr.io/meta-pytorch/openenv-base:latest
+    """
+    # Handle interface flag logic
+    if no_interface and interface:
+        console.print(
+            "[bold red]Error:[/bold red] Cannot specify both --interface and --no-interface",
+            file=sys.stderr,
+        )
+        raise typer.Exit(1)
+
+    # Determine if web interface should be enabled
+    if no_interface:
+        enable_interface = False
+    elif interface is not None:
+        enable_interface = interface
+    elif registry is not None:
+        # Custom registry: disable interface by default
+        enable_interface = False
+    else:
+        # HuggingFace: enable interface by default
+        enable_interface = True
+
+    # Determine directory
+    if directory:
+        env_dir = Path(directory).resolve()
+    else:
+        env_dir = Path.cwd().resolve()
+
+    if not env_dir.exists() or not env_dir.is_dir():
+        raise typer.BadParameter(f"Directory does not exist: {env_dir}")
+
+    # Check for openenv.yaml to confirm this is an environment directory
+    openenv_yaml = env_dir / "openenv.yaml"
+    if not openenv_yaml.exists():
+        console.print(
+            f"[bold red]Error:[/bold red] Not an OpenEnv environment directory (missing openenv.yaml): {env_dir}",
+        )
+        console.print(
+            "[yellow]Hint:[/yellow] Run this command from the environment root directory",
+        )
+        raise typer.Exit(1)
+
+    # Validate OpenEnv environment
+    console.print(
+        f"[bold cyan]Validating OpenEnv environment in {env_dir}...[/bold cyan]"
+    )
+    env_name, manifest = _validate_openenv_directory(env_dir)
+    console.print(f"[bold green]Γ£ô[/bold green] Found OpenEnv environment: {env_name}")
+
+    # Handle custom registry push
+    if registry:
+        console.print("[bold cyan]Preparing to push to custom registry...[/bold cyan]")
+        if enable_interface:
+            console.print("[bold cyan]Web interface will be enabled[/bold cyan]")
+
+        # Import build functions
+        from .build import _build_docker_image, _push_docker_image
+
+        # Prepare build args for custom registry deployment
+        build_args = {}
+        if enable_interface:
+            build_args["ENABLE_WEB_INTERFACE"] = "true"
+
+        # Build Docker image from the environment directory
+        tag = f"{registry}/{env_name}"
+        console.print(f"[bold cyan]Building Docker image: {tag}[/bold cyan]")
+
+        success = _build_docker_image(
+            env_path=env_dir,
+            tag=tag,
+            build_args=build_args if build_args else None,
+        )
+
+        if not success:
+            console.print("[bold red]Γ£ù Docker build failed[/bold red]")
+            raise typer.Exit(1)
+
+        console.print("[bold green]Γ£ô Docker build successful[/bold green]")
+
+        # Push to registry
+        console.print(f"[bold cyan]Pushing to registry: {registry}[/bold cyan]")
+
+        success = _push_docker_image(
+            tag, registry=None
+        )  # Tag already includes registry
+
+        if not success:
+            console.print("[bold red]Γ£ù Docker push failed[/bold red]")
+            raise typer.Exit(1)
+
+        console.print("\n[bold green]Γ£ô Deployment complete![/bold green]")
+        console.print(f"[bold]Image:[/bold] {tag}")
+        return
+
+    # Ensure authentication for HuggingFace
+    username = _ensure_hf_authenticated()
+
+    # Determine repo_id
+    if not repo_id:
+        repo_id = f"{username}/{env_name}"
+
+    # Validate repo_id format
+    if "/" not in repo_id or repo_id.count("/") != 1:
+        raise typer.BadParameter(
+            f"Invalid repo-id format: {repo_id}. Expected format: 'username/repo-name'"
+        )
+
+    # Initialize Hugging Face API
+    api = HfApi()
+
+    # Prepare staging directory
+    deployment_type = (
+        "with web interface" if enable_interface else "without web interface"
+    )
+    console.print(
+        f"[bold cyan]Preparing files for Hugging Face deployment ({deployment_type})...[/bold cyan]"
+    )
+    with tempfile.TemporaryDirectory() as tmpdir:
+        staging_dir = Path(tmpdir) / "staging"
+        _prepare_staging_directory(
+            env_dir,
+            env_name,
+            staging_dir,
+            base_image=base_image,
+            enable_interface=enable_interface,
+        )
+
+        # Create/verify space
+        _create_hf_space(repo_id, api, private=private)
+
+        # Upload files
+        _upload_to_hf_space(repo_id, staging_dir, api, private=private)
+
+        console.print("\n[bold green]Γ£ô Deployment complete![/bold green]")
+        console.print(f"Visit your space at: https://huggingface.co/spaces/{repo_id}")

src/openenv/cli/commands/serve.py

@@ -0,0 +1,92 @@
+# 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.
+
+"""Serve OpenEnv environments locally (TO BE IMPLEMENTED)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from .._cli_utils import console
+
+# Commands are registered in __main__.py
+
+def serve(
+    env_path: Annotated[
+        Optional[str],
+        typer.Argument(
+            help="Path to the environment directory (default: current directory)"
+        ),
+    ] = None,
+    port: Annotated[
+        int,
+        typer.Option("--port", help="Port to serve on"),
+    ] = 8000,
+    host: Annotated[
+        str,
+        typer.Option("--host", help="Host to bind to"),
+    ] = "0.0.0.0",
+    reload: Annotated[
+        bool,
+        typer.Option("--reload", help="Enable auto-reload on code changes"),
+    ] = False,
+) -> None:
+    """
+    Serve an OpenEnv environment locally.
+
+    TODO: This command is currently not implemented and has been deferred for later.
+
+    Planned functionality:
+    - Run environment server locally without Docker
+    - Support multiple deployment modes (local, notebook, cluster)
+    - Auto-reload for development
+    - Integration with environment's [project.scripts] entry point
+
+    For now, use Docker-based serving:
+        1. Build the environment: openenv build
+        2. Run the container: docker run -p 8000:8000 <image-name>
+
+    Or use uv directly:
+        uv run --project . server --port 8000
+    """
+    console.print("[bold yellow]⚠ This command is not yet implemented[/bold yellow]\n")
+
+    console.print(
+        "The [bold cyan]openenv serve[/bold cyan] command has been deferred for later."
+    )
+
+    console.print("[bold]Alternative approaches:[/bold]\n")
+
+    console.print("[cyan]Option 1: Docker-based serving (recommended)[/cyan]")
+    console.print("  1. Build the environment:")
+    console.print("     [dim]$ openenv build[/dim]")
+    console.print("  2. Run the Docker container:")
+    console.print(
+        f"     [dim]$ docker run -p {port}:{port} openenv-<env-name>:latest[/dim]\n"
+    )
+
+    console.print("[cyan]Option 2: Direct execution with uv[/cyan]")
+
+    # Determine environment path
+    if env_path is None:
+        env_path_obj = Path.cwd()
+    else:
+        env_path_obj = Path(env_path)
+
+    # Check for openenv.yaml
+    openenv_yaml = env_path_obj / "openenv.yaml"
+    if openenv_yaml.exists():
+        console.print("  From your environment directory:")
+        console.print(f"     [dim]$ cd {env_path_obj}[/dim]")
+        console.print(f"     [dim]$ uv run --project . server --port {port}[/dim]\n")
+    else:
+        console.print("  From an environment directory with pyproject.toml:")
+        console.print(f"     [dim]$ uv run --project . server --port {port}[/dim]\n")
+
+    raise typer.Exit(0)

src/openenv/cli/commands/validate.py

@@ -0,0 +1,108 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+OpenEnv validate command.
+
+This module provides the 'openenv validate' command to check if environments
+are properly configured for multi-mode deployment.
+"""
+
+from pathlib import Path
+
+import typer
+
+from openenv.cli._validation import (
+    format_validation_report,
+    get_deployment_modes,
+    validate_multi_mode_deployment,
+)
+
+
+def validate(
+    env_path: str | None = typer.Argument(
+        None, help="Path to the environment directory (default: current directory)"
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Show detailed information"
+    ),
+) -> None:
+    """
+    Validate an environment for standardized structure and deployment readiness.
+
+    This command checks if an environment is properly configured with:
+    - Required files (pyproject.toml, openenv.yaml, server/app.py, etc.)
+    - Docker deployment support
+    - uv run server capability
+    - python -m module execution
+
+    Examples:
+        # Validate current directory (recommended)
+        $ cd my_env
+        $ openenv validate
+
+        # Validate with detailed output
+        $ openenv validate --verbose
+
+        # Validate specific environment
+        $ openenv validate envs/echo_env
+    """
+    # Determine environment path (default to current directory)
+    if env_path is None:
+        env_path_obj = Path.cwd()
+    else:
+        env_path_obj = Path(env_path)
+
+    if not env_path_obj.exists():
+        typer.echo(f"Error: Path does not exist: {env_path_obj}", err=True)
+        raise typer.Exit(1)
+
+    if not env_path_obj.is_dir():
+        typer.echo(f"Error: Path is not a directory: {env_path_obj}", err=True)
+        raise typer.Exit(1)
+
+    # Check for openenv.yaml to confirm this is an environment directory
+    openenv_yaml = env_path_obj / "openenv.yaml"
+    if not openenv_yaml.exists():
+        typer.echo(
+            f"Error: Not an OpenEnv environment directory (missing openenv.yaml): {env_path_obj}",
+            err=True,
+        )
+        typer.echo(
+            "Hint: Run this command from the environment root directory or specify the path",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    env_name = env_path_obj.name
+    if env_name.endswith("_env"):
+        base_name = env_name[:-4]
+    else:
+        base_name = env_name
+
+    # Run validation
+    is_valid, issues = validate_multi_mode_deployment(env_path_obj)
+
+    # Show validation report
+    report = format_validation_report(base_name, is_valid, issues)
+    typer.echo(report)
+
+    # Show deployment modes if verbose
+    if verbose:
+        typer.echo("\nSupported deployment modes:")
+        modes = get_deployment_modes(env_path_obj)
+        for mode, supported in modes.items():
+            status = "[YES]" if supported else "[NO]"
+            typer.echo(f"  {status} {mode}")
+
+        if is_valid:
+            typer.echo("\nUsage examples:")
+            typer.echo(f"  cd {env_path_obj.name} && uv run server")
+            typer.echo(f"  cd {env_path_obj.name} && openenv build")
+            typer.echo(f"  cd {env_path_obj.name} && openenv push")
+
+    if not is_valid:
+        raise typer.Exit(1)

src/openenv/cli/templates/__init__.py

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

src/openenv/cli/templates/openenv_env/.dockerignore

@@ -0,0 +1,15 @@
+.venv
+.git
+.gitignore
+.env
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.pyw
+*.pyz
+*.pywz
+*.pyzw
+*.pyzwz
+
+

src/openenv/cli/templates/openenv_env/README.md

@@ -0,0 +1,255 @@
+---
+title: __ENV_TITLE_NAME__ Environment Server
+emoji: __HF_EMOJI__
+colorFrom: __HF_COLOR_FROM__
+colorTo: __HF_COLOR_TO__
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# __ENV_TITLE_NAME__ Environment
+
+A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
+
+## Quick Start
+
+The simplest way to use the __ENV_TITLE_NAME__ environment is through the `__ENV_CLASS_NAME__Env` class:
+
+```python
+from __ENV_NAME__ import __ENV_CLASS_NAME__Action, __ENV_CLASS_NAME__Env
+
+try:
+    # Create environment from Docker image
+    __ENV_NAME__env = __ENV_CLASS_NAME__Env.from_docker_image("__ENV_NAME__-env:latest")
+
+    # Reset
+    result = __ENV_NAME__env.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+
+    # Send multiple messages
+    messages = ["Hello, World!", "Testing echo", "Final message"]
+
+    for msg in messages:
+        result = __ENV_NAME__env.step(__ENV_CLASS_NAME__Action(message=msg))
+        print(f"Sent: '{msg}'")
+        print(f"  → Echoed: '{result.observation.echoed_message}'")
+        print(f"  → Length: {result.observation.message_length}")
+        print(f"  → Reward: {result.reward}")
+
+finally:
+    # Always clean up
+    __ENV_NAME__env.close()
+```
+
+That's it! The `__ENV_CLASS_NAME__Env.from_docker_image()` method handles:
+- Starting the Docker container
+- Waiting for the server to be ready
+- Connecting to the environment
+- Container cleanup when you call `close()`
+
+## Building the Docker Image
+
+Before using the environment, you need to build the Docker image:
+
+```bash
+# From project root
+docker build -t __ENV_NAME__-env:latest -f server/Dockerfile .
+```
+
+## Deploying to Hugging Face Spaces
+
+You can easily deploy your OpenEnv environment to Hugging Face Spaces using the `openenv push` command:
+
+```bash
+# From the environment directory (where openenv.yaml is located)
+openenv push
+
+# Or specify options
+openenv push --namespace my-org --private
+```
+
+The `openenv push` command will:
+1. Validate that the directory is an OpenEnv environment (checks for `openenv.yaml`)
+2. Prepare a custom build for Hugging Face Docker space (enables web interface)
+3. Upload to Hugging Face (ensuring you're logged in)
+
+### Prerequisites
+
+- Authenticate with Hugging Face: The command will prompt for login if not already authenticated
+
+### Options
+
+- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
+- `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
+- `--private`: Deploy the space as private (default: public)
+
+### Examples
+
+```bash
+# Push to your personal namespace (defaults to username/env-name from openenv.yaml)
+openenv push
+
+# Push to a specific repository
+openenv push --repo-id my-org/my-env
+
+# Push with a custom base image
+openenv push --base-image ghcr.io/meta-pytorch/openenv-base:latest
+
+# Push as a private space
+openenv push --private
+
+# Combine options
+openenv push --repo-id my-org/my-env --base-image custom-base:latest --private
+```
+
+After deployment, your space will be available at:
+`https://huggingface.co/spaces/<repo-id>`
+
+The deployed space includes:
+- **Web Interface** at `/web` - Interactive UI for exploring the environment
+- **API Documentation** at `/docs` - Full OpenAPI/Swagger interface
+- **Health Check** at `/health` - Container health monitoring
+- **WebSocket** at `/ws` - Persistent session endpoint for low-latency interactions
+
+## Environment Details
+
+### Action
+**__ENV_CLASS_NAME__Action**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**__ENV_CLASS_NAME__Observation**: Contains the echo response and metadata
+- `echoed_message` (str) - The message echoed back
+- `message_length` (int) - Length of the message
+- `reward` (float) - Reward based on message length (length × 0.1)
+- `done` (bool) - Always False for echo environment
+- `metadata` (dict) - Additional info like step count
+
+### Reward
+The reward is calculated as: `message_length × 0.1`
+- "Hi" → reward: 0.2
+- "Hello, World!" → reward: 1.3
+- Empty message → reward: 0.0
+
+## Advanced Usage
+
+### Connecting to an Existing Server
+
+If you already have a __ENV_TITLE_NAME__ environment server running, you can connect directly:
+
+```python
+from __ENV_NAME__ import __ENV_CLASS_NAME__Env
+
+# Connect to existing server
+__ENV_NAME__env = __ENV_CLASS_NAME__Env(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = __ENV_NAME__env.reset()
+result = __ENV_NAME__env.step(__ENV_CLASS_NAME__Action(message="Hello!"))
+```
+
+Note: When connecting to an existing server, `__ENV_NAME__env.close()` will NOT stop the server.
+
+### Using the Context Manager
+
+The client supports context manager usage for automatic connection management:
+
+```python
+from __ENV_NAME__ import __ENV_CLASS_NAME__Action, __ENV_CLASS_NAME__Env
+
+# Connect with context manager (auto-connects and closes)
+with __ENV_CLASS_NAME__Env(base_url="http://localhost:8000") as env:
+    result = env.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+    # Multiple steps with low latency
+    for msg in ["Hello", "World", "!"]:
+        result = env.step(__ENV_CLASS_NAME__Action(message=msg))
+        print(f"Echoed: {result.observation.echoed_message}")
+```
+
+The client uses WebSocket connections for:
+- **Lower latency**: No HTTP connection overhead per request
+- **Persistent session**: Server maintains your environment state
+- **Efficient for episodes**: Better for many sequential steps
+
+### Concurrent WebSocket Sessions
+
+The server supports multiple concurrent WebSocket connections. To enable this,
+modify `server/app.py` to use factory mode:
+
+```python
+# In server/app.py - use factory mode for concurrent sessions
+app = create_app(
+    __ENV_CLASS_NAME__Environment,  # Pass class, not instance
+    __ENV_CLASS_NAME__Action,
+    __ENV_CLASS_NAME__Observation,
+    max_concurrent_envs=4,  # Allow 4 concurrent sessions
+)
+```
+
+Then multiple clients can connect simultaneously:
+
+```python
+from __ENV_NAME__ import __ENV_CLASS_NAME__Action, __ENV_CLASS_NAME__Env
+from concurrent.futures import ThreadPoolExecutor
+
+def run_episode(client_id: int):
+    with __ENV_CLASS_NAME__Env(base_url="http://localhost:8000") as env:
+        result = env.reset()
+        for i in range(10):
+            result = env.step(__ENV_CLASS_NAME__Action(message=f"Client {client_id}, step {i}"))
+        return client_id, result.observation.message_length
+
+# Run 4 episodes concurrently
+with ThreadPoolExecutor(max_workers=4) as executor:
+    results = list(executor.map(run_episode, range(4)))
+```
+
+## Development & Testing
+
+### Direct Environment Testing
+
+Test the environment logic directly without starting the HTTP server:
+
+```bash
+# From the server directory
+python3 server/__ENV_NAME___environment.py
+```
+
+This verifies that:
+- Environment resets correctly
+- Step executes actions properly
+- State tracking works
+- Rewards are calculated correctly
+
+### Running Locally
+
+Run the server locally for development:
+
+```bash
+uvicorn server.app:app --reload
+```
+
+## Project Structure
+
+```
+__ENV_NAME__/
+├── .dockerignore         # Docker build exclusions
+├── __init__.py            # Module exports
+├── README.md              # This file
+├── openenv.yaml           # OpenEnv manifest
+├── pyproject.toml         # Project metadata and dependencies
+├── uv.lock                # Locked dependencies (generated)
+├── client.py              # __ENV_CLASS_NAME__Env client
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── __ENV_NAME___environment.py  # Core environment logic
+    ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
+    └── Dockerfile         # Container image definition
+```

src/openenv/cli/templates/openenv_env/__init__.py

@@ -0,0 +1,16 @@
+# 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.
+
+"""__ENV_TITLE_NAME__ Environment."""
+
+from .client import __ENV_CLASS_NAME__Env
+from .models import __ENV_CLASS_NAME__Action, __ENV_CLASS_NAME__Observation
+
+__all__ = [
+    "__ENV_CLASS_NAME__Action",
+    "__ENV_CLASS_NAME__Observation",
+    "__ENV_CLASS_NAME__Env",
+]

src/openenv/cli/templates/openenv_env/client.py

@@ -0,0 +1,99 @@
+# 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.
+
+"""__ENV_TITLE_NAME__ Environment Client."""
+
+from typing import Dict
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+from openenv.core import EnvClient
+
+from .models import __ENV_CLASS_NAME__Action, __ENV_CLASS_NAME__Observation
+
+
+class __ENV_CLASS_NAME__Env(
+    EnvClient[__ENV_CLASS_NAME__Action, __ENV_CLASS_NAME__Observation]
+):
+    """
+    Client for the __ENV_TITLE_NAME__ Environment.
+
+    This client maintains a persistent WebSocket connection to the environment server,
+    enabling efficient multi-step interactions with lower latency.
+    Each client instance has its own dedicated environment session on the server.
+
+    Example:
+        >>> # Connect to a running server
+        >>> with __ENV_CLASS_NAME__Env(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.echoed_message)
+        ...
+        ...     result = client.step(__ENV_CLASS_NAME__Action(message="Hello!"))
+        ...     print(result.observation.echoed_message)
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = __ENV_CLASS_NAME__Env.from_docker_image("__ENV_NAME__-env:latest")
+        >>> try:
+        ...     result = client.reset()
+        ...     result = client.step(__ENV_CLASS_NAME__Action(message="Test"))
+        ... finally:
+        ...     client.close()
+    """
+
+    def _step_payload(self, action: __ENV_CLASS_NAME__Action) -> Dict:
+        """
+        Convert __ENV_CLASS_NAME__Action to JSON payload for step message.
+
+        Args:
+            action: __ENV_CLASS_NAME__Action instance
+
+        Returns:
+            Dictionary representation suitable for JSON encoding
+        """
+        return {
+            "message": action.message,
+        }
+
+    def _parse_result(self, payload: Dict) -> StepResult[__ENV_CLASS_NAME__Observation]:
+        """
+        Parse server response into StepResult[__ENV_CLASS_NAME__Observation].
+
+        Args:
+            payload: JSON response data from server
+
+        Returns:
+            StepResult with __ENV_CLASS_NAME__Observation
+        """
+        obs_data = payload.get("observation", {})
+        observation = __ENV_CLASS_NAME__Observation(
+            echoed_message=obs_data.get("echoed_message", ""),
+            message_length=obs_data.get("message_length", 0),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            metadata=obs_data.get("metadata", {}),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> State:
+        """
+        Parse server response into State object.
+
+        Args:
+            payload: JSON response from state request
+
+        Returns:
+            State object with episode_id and step_count
+        """
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

src/openenv/cli/templates/openenv_env/models.py

@@ -0,0 +1,28 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Data models for the __ENV_TITLE_NAME__ Environment.
+
+The __ENV_NAME__ environment is a simple test environment that echoes back messages.
+"""
+
+from pydantic import Field
+
+from openenv.core.env_server.types import Action, Observation
+
+
+class __ENV_CLASS_NAME__Action(Action):
+    """Action for the __ENV_TITLE_NAME__ environment - just a message to echo."""
+
+    message: str = Field(..., description="Message to echo back")
+
+
+class __ENV_CLASS_NAME__Observation(Observation):
+    """Observation from the __ENV_TITLE_NAME__ environment - the echoed message."""
+
+    echoed_message: str = Field(default="", description="The echoed message")
+    message_length: int = Field(default=0, description="Length of the echoed message")

src/openenv/cli/templates/openenv_env/openenv.yaml

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

src/openenv/cli/templates/openenv_env/pyproject.toml

@@ -0,0 +1,45 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-__ENV_NAME__"
+version = "0.1.0"
+description = "__ENV_TITLE_NAME__ environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
+    # install from github
+    # "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git",
+    "openenv-core[core]>=0.2.0",
+    # Environment-specific dependencies
+    # Add all dependencies needed for your environment here
+    # Examples:
+    # "numpy>=1.19.0",
+    # "torch>=2.0.0",
+    # "gymnasium>=0.29.0",
+    # "openspiel>=1.0.0",
+    # "smolagents>=1.22.0,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m __ENV_NAME__.server.app
+server = "__ENV_NAME__.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["__ENV_NAME__", "__ENV_NAME__.server"]
+package-dir = { "__ENV_NAME__" = ".", "__ENV_NAME__.server" = "server" }

src/openenv/cli/templates/openenv_env/server/Dockerfile

@@ -0,0 +1,80 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=__ENV_NAME__
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed 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 dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+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
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]