Upload folder using huggingface_hub

Dockerfile

@@ -11,7 +11,7 @@
 # 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
+FROM ghcr.io/meta-pytorch/openenv-base:latest AS builder
 
 WORKDIR /app
 
@@ -40,22 +40,26 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 # Install dependencies using uv sync
 # First pass: install dependencies without the project (for better caching)
 # Second pass: install the project itself
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
+    install -m 0755 /root/.local/bin/uv /usr/local/bin/uv && \
+    install -m 0755 /root/.local/bin/uvx /usr/local/bin/uvx
+
 RUN --mount=type=cache,target=/root/.cache/uv \
     if [ -f uv.lock ]; then \
-        uv sync --frozen --no-install-project --no-editable; \
+        uv sync --no-install-project --no-editable; \
     else \
         uv sync --no-install-project --no-editable; \
     fi
 
 RUN --mount=type=cache,target=/root/.cache/uv \
     if [ -f uv.lock ]; then \
-        uv sync --frozen --no-editable; \
+        uv sync --no-editable; \
     else \
         uv sync --no-editable; \
     fi
 
 # Final runtime stage
-FROM ${BASE_IMAGE}
+FROM ghcr.io/meta-pytorch/openenv-base:latest
 
 WORKDIR /app
 
@@ -77,5 +81,6 @@ HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
 
 # Run the FastAPI server
 # The module path is constructed to work with the /app/env structure
-ENV ENABLE_WEB_INTERFACE=true
 CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]
+
+ENV ENABLE_WEB_INTERFACE=true

README.md

@@ -2,54 +2,82 @@
 title: Echo Environment Server
 emoji: 🔊
 colorFrom: blue
-colorTo: blue
+colorTo: green
 sdk: docker
 pinned: false
 app_port: 8000
 base_path: /web
 tags:
+  - openenv-main
   - openenv
 ---
 
+## Hugging Face Space Deployment
+
+This Space is built from OpenEnv environment `echo_env`.
+
+- Space URL: `https://huggingface.co/spaces/openenv/echo_env`
+- OpenEnv pinned ref: `main`
+- Hub tag: `openenv`
+
+### Connecting from Code
+
+```python
+from envs.echo_env import EchoEnv
+
+env = EchoEnv(base_url="https://huggingface.co/spaces/openenv/echo_env")
+```
+
 # Echo 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 Echo environment is through the `EchoEnv` class:
+The simplest way to use the Echo environment is through the `EchoEnv` class. The client is **async by default**:
 
 ```python
-from envs.echo_env import EchoAction, EchoEnv
+import asyncio
+from echo_env import EchoAction, EchoEnv
 
-try:
+async def main():
     # Create environment from Docker image
-    echo_env = EchoEnv.from_docker_image("echo-env:latest")
+    client = await EchoEnv.from_docker_image("echo-env:latest")
 
-    # Reset
-    result = echo_env.reset()
-    print(f"Reset: {result.observation.echoed_message}")
+    async with client:
+        # Reset
+        result = await client.reset()
+        print(f"Reset: {result.observation.echoed_message}")
 
-    # Send multiple messages
-    messages = ["Hello, World!", "Testing echo", "Final message"]
+        # Send multiple messages
+        messages = ["Hello, World!", "Testing echo", "Final message"]
 
-    for msg in messages:
-        result = echo_env.step(EchoAction(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}")
+        for msg in messages:
+            result = await client.step(EchoAction(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
-    echo_env.close()
+asyncio.run(main())
 ```
 
-That's it! The `EchoEnv.from_docker_image()` method handles:
+For **synchronous usage**, use the `.sync()` wrapper:
+
+```python
+from echo_env import EchoAction, EchoEnv
+
+with EchoEnv(base_url="http://localhost:8000").sync() as client:
+    result = client.reset()
+    result = client.step(EchoAction(message="Hello!"))
+    print(result.observation.echoed_message)
+```
+
+The `EchoEnv.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()`
+- Container cleanup when the context manager exits
 
 ## Building the Docker Image
 
@@ -87,17 +115,20 @@ The reward is calculated as: `message_length × 0.1`
 If you already have an Echo environment server running, you can connect directly:
 
 ```python
-from envs.echo_env import EchoEnv
+from echo_env import EchoAction, EchoEnv
 
-# Connect to existing server
-echo_env = EchoEnv(base_url="<ENV_HTTP_URL_HERE>")
+# Async usage
+async with EchoEnv(base_url="http://localhost:8000") as client:
+    result = await client.reset()
+    result = await client.step(EchoAction(message="Hello!"))
 
-# Use as normal
-result = echo_env.reset()
-result = echo_env.step(EchoAction(message="Hello!"))
+# Sync usage
+with EchoEnv(base_url="http://localhost:8000").sync() as client:
+    result = client.reset()
+    result = client.step(EchoAction(message="Hello!"))
 ```
 
-Note: When connecting to an existing server, `echo_env.close()` will NOT stop the server.
+Note: When connecting to an existing server, closing the client will NOT stop the server.
 
 ## Development & Testing
 

__init__.py

@@ -4,9 +4,26 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
-"""Echo Environment - A simple test environment for HTTP server."""
+"""
+Echo Environment - A pure MCP environment for testing and demonstration.
+
+This environment exposes all functionality through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from echo_env import EchoEnv
+    >>>
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...     tools = env.list_tools()
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+"""
+
+# Re-export MCP types for convenience
+from openenv.core.env_server.mcp_types import CallToolAction, ListToolsAction
 
 from .client import EchoEnv
-from .models import EchoAction, EchoObservation
 
-__all__ = ["EchoAction", "EchoObservation", "EchoEnv"]
+__all__ = ["EchoEnv", "CallToolAction", "ListToolsAction"]

build/lib/build/lib/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

build/lib/build/lib/server/app.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.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from ..models import EchoAction, EchoObservation
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from models import EchoAction, EchoObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+app = create_app(EchoEnvironment, EchoAction, EchoObservation, env_name="echo_env")
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

build/lib/build/lib/server/echo_environment.py

@@ -0,0 +1,102 @@
+# 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.
+
+"""
+Echo Environment Implementation.
+
+A simple test environment that echoes back messages sent to it.
+Perfect for testing HTTP server infrastructure.
+"""
+
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from ..models import EchoAction, EchoObservation
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from models import EchoAction, EchoObservation
+
+
+class EchoEnvironment(Environment):
+    """
+    A simple echo environment that echoes back messages.
+
+    This environment is designed for testing the HTTP server infrastructure.
+    It maintains minimal state and simply echoes back whatever message it receives.
+
+    Example:
+        >>> env = EchoEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.echoed_message)  # "Echo environment ready!"
+        >>>
+        >>> obs = env.step(EchoAction(message="Hello"))
+        >>> print(obs.echoed_message)  # "Hello"
+        >>> print(obs.message_length)  # 5
+    """
+
+    def __init__(self):
+        """Initialize the echo environment."""
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(self) -> EchoObservation:
+        """
+        Reset the environment.
+
+        Returns:
+            EchoObservation with a ready message
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count += 1
+
+        return EchoObservation(
+            echoed_message="Echo environment ready!",
+            message_length=0,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: EchoAction) -> EchoObservation:  # type: ignore[override]
+        """
+        Execute a step in the environment by echoing the message.
+
+        Args:
+            action: EchoAction containing the message to echo
+
+        Returns:
+            EchoObservation with the echoed message and its length
+        """
+        self._state.step_count += 1
+
+        message = action.message
+        length = len(message)
+
+        # Simple reward: longer messages get higher rewards
+        reward = length * 0.1
+
+        return EchoObservation(
+            echoed_message=message,
+            message_length=length,
+            done=False,
+            reward=reward,
+            metadata={"original_message": message, "step": self._state.step_count},
+        )
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

build/lib/echo_env/__init__.py

@@ -0,0 +1,29 @@
+# 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.
+
+"""
+Echo Environment - A pure MCP environment for testing and demonstration.
+
+This environment exposes all functionality through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from echo_env import EchoEnv
+    >>>
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...     tools = env.list_tools()
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+"""
+
+from .client import EchoEnv
+
+# Re-export MCP types for convenience
+from openenv.core.env_server.mcp_types import CallToolAction, ListToolsAction
+
+__all__ = ["EchoEnv", "CallToolAction", "ListToolsAction"]

build/lib/echo_env/client.py

@@ -0,0 +1,81 @@
+# 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.
+
+"""
+Echo Environment Client.
+
+This module provides the client for connecting to an Echo Environment server.
+EchoEnv extends MCPToolClient to provide tool-calling style interactions.
+
+Example:
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...
+    ...     # Discover tools
+    ...     tools = env.list_tools()
+    ...     print([t.name for t in tools])  # ['echo_message', 'echo_with_length']
+    ...
+    ...     # Call tools
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+    ...
+    ...     result = env.call_tool("echo_with_length", message="Test")
+    ...     print(result)  # {"message": "Test", "length": 4}
+"""
+
+from openenv.core.mcp_client import MCPToolClient
+
+
+class EchoEnv(MCPToolClient):
+    """
+    Client for the Echo Environment.
+
+    This client provides a simple interface for interacting with the Echo
+    Environment via MCP tools. It inherits all functionality from MCPToolClient:
+    - `list_tools()`: Discover available tools
+    - `call_tool(name, **kwargs)`: Call a tool by name
+    - `reset(**kwargs)`: Reset the environment
+    - `step(action)`: Execute an action (for advanced use)
+
+    Example:
+        >>> # Connect to a running server
+        >>> with EchoEnv(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...
+        ...     # List available tools
+        ...     tools = env.list_tools()
+        ...     for tool in tools:
+        ...         print(f"{tool.name}: {tool.description}")
+        ...
+        ...     # Echo a message
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)  # "Hello!"
+        ...
+        ...     # Echo with length
+        ...     result = env.call_tool("echo_with_length", message="Test")
+        ...     print(result)  # {"message": "Test", "length": 4}
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> env = EchoEnv.from_docker_image("echo-env:latest")
+        >>> try:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+
+    Example with HuggingFace Space:
+        >>> # Run from HuggingFace Space
+        >>> env = EchoEnv.from_env("openenv/echo-env")
+        >>> try:
+        ...     env.reset()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+    """
+
+    pass  # MCPToolClient provides all needed functionality

build/lib/echo_env/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

build/lib/echo_env/server/app.py

@@ -0,0 +1,60 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with MCPToolClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+# Use MCP types for action/observation since this is a pure MCP environment
+app = create_app(
+    EchoEnvironment, CallToolAction, CallToolObservation, env_name="echo_env"
+)
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

build/lib/echo_env/server/echo_environment.py

@@ -0,0 +1,196 @@
+# 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.
+
+"""
+Echo Environment Implementation.
+
+A pure MCP environment that echoes back messages sent to it.
+This demonstrates how to build an MCPEnvironment with inline FastMCP tools.
+
+All interactions happen through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from openenv.core.env_server.mcp_types import ListToolsAction, CallToolAction
+    >>> env = EchoEnvironment()
+    >>> env.reset()
+    >>>
+    >>> # List available tools
+    >>> obs = env.step(ListToolsAction())
+    >>> print([t.name for t in obs.tools])  # ["echo_message", "echo_with_length"]
+    >>>
+    >>> # Call a tool
+    >>> obs = env.step(CallToolAction(tool_name="echo_message", arguments={"message": "Hi!"}))
+    >>> print(obs.result)  # "Hi!"
+"""
+
+from typing import Any, Optional
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
+
+from fastmcp import FastMCP
+
+
+class EchoEnvironment(MCPEnvironment):
+    """
+    A pure MCP echo environment that echoes back messages.
+
+    This environment exposes all functionality through MCP tools:
+    - `echo_message`: Echo back the provided message
+    - `echo_with_length`: Echo back the message with its length
+
+    The environment inherits MCP support (ListToolsAction, CallToolAction)
+    from the MCPEnvironment base class. No legacy action types are supported.
+
+    Example using MCPToolClient:
+        >>> from openenv.core.mcp_client import MCPToolClient
+        >>>
+        >>> with MCPToolClient(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     print([t.name for t in tools])
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)
+    """
+
+    def __init__(self):
+        """Initialize the echo environment with MCP server and tools."""
+        # Create MCP server and define tools inline
+        mcp = FastMCP("echo_env")
+
+        @mcp.tool
+        def echo_message(message: str) -> str:
+            """
+            Echo back the provided message.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                The same message that was provided
+            """
+            return message
+
+        @mcp.tool
+        def echo_with_length(message: str) -> dict:
+            """
+            Echo back the message with its length.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                Dictionary with the message and its length
+            """
+            return {"message": message, "length": len(message)}
+
+        # Pass the MCP server to the base class
+        super().__init__(mcp)
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Reset the environment.
+
+        Args:
+            seed: Optional random seed (unused in echo env)
+            episode_id: Optional episode ID to use
+            **kwargs: Additional reset options
+
+        Returns:
+            Observation indicating the environment is ready
+        """
+        self._state = State(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+        )
+        self._reset_count += 1
+
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={"status": "ready", "message": "Echo environment ready!"},
+        )
+
+    def _step_impl(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Handle non-MCP actions.
+
+        This environment only supports MCP actions (ListToolsAction, CallToolAction).
+        Any other action type returns an error observation.
+
+        Args:
+            action: The action to execute
+            timeout_s: Optional timeout (unused)
+            **kwargs: Additional arguments
+
+        Returns:
+            Observation with error for unknown action types
+        """
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={
+                "error": f"Unknown action type: {type(action).__name__}. "
+                "Use ListToolsAction or CallToolAction for MCP interactions."
+            },
+        )
+
+    def step(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Execute a step in the environment.
+
+        Delegates to base class for MCP actions. Increments step count for all actions.
+
+        Args:
+            action: The MCP action to execute (ListToolsAction or CallToolAction)
+            timeout_s: Optional timeout for the action
+            **kwargs: Additional arguments
+
+        Returns:
+            Observation from the action execution
+        """
+        # Increment step count for all actions
+        self._state.step_count += 1
+
+        # Let the base class handle MCP actions and non-MCP routing
+        return super().step(action, timeout_s=timeout_s, **kwargs)
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

build/lib/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

build/lib/server/app.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.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from ..models import EchoAction, EchoObservation
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from models import EchoAction, EchoObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+app = create_app(EchoEnvironment, EchoAction, EchoObservation, env_name="echo_env")
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

build/lib/server/echo_environment.py

@@ -0,0 +1,102 @@
+# 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.
+
+"""
+Echo Environment Implementation.
+
+A simple test environment that echoes back messages sent to it.
+Perfect for testing HTTP server infrastructure.
+"""
+
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from ..models import EchoAction, EchoObservation
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from models import EchoAction, EchoObservation
+
+
+class EchoEnvironment(Environment):
+    """
+    A simple echo environment that echoes back messages.
+
+    This environment is designed for testing the HTTP server infrastructure.
+    It maintains minimal state and simply echoes back whatever message it receives.
+
+    Example:
+        >>> env = EchoEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.echoed_message)  # "Echo environment ready!"
+        >>>
+        >>> obs = env.step(EchoAction(message="Hello"))
+        >>> print(obs.echoed_message)  # "Hello"
+        >>> print(obs.message_length)  # 5
+    """
+
+    def __init__(self):
+        """Initialize the echo environment."""
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(self) -> EchoObservation:
+        """
+        Reset the environment.
+
+        Returns:
+            EchoObservation with a ready message
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count += 1
+
+        return EchoObservation(
+            echoed_message="Echo environment ready!",
+            message_length=0,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: EchoAction) -> EchoObservation:  # type: ignore[override]
+        """
+        Execute a step in the environment by echoing the message.
+
+        Args:
+            action: EchoAction containing the message to echo
+
+        Returns:
+            EchoObservation with the echoed message and its length
+        """
+        self._state.step_count += 1
+
+        message = action.message
+        length = len(message)
+
+        # Simple reward: longer messages get higher rewards
+        reward = length * 0.1
+
+        return EchoObservation(
+            echoed_message=message,
+            message_length=length,
+            done=False,
+            reward=reward,
+            metadata={"original_message": message, "step": self._state.step_count},
+        )
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

client.py

@@ -7,105 +7,75 @@
 """
 Echo Environment Client.
 
-This module provides the client for connecting to an Echo Environment server
-via WebSocket for persistent sessions.
+This module provides the client for connecting to an Echo Environment server.
+EchoEnv extends MCPToolClient to provide tool-calling style interactions.
+
+Example:
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...
+    ...     # Discover tools
+    ...     tools = env.list_tools()
+    ...     print([t.name for t in tools])  # ['echo_message', 'echo_with_length']
+    ...
+    ...     # Call tools
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+    ...
+    ...     result = env.call_tool("echo_with_length", message="Test")
+    ...     print(result)  # {"message": "Test", "length": 4}
 """
 
-from typing import Any, Dict
+from openenv.core.mcp_client import MCPToolClient
 
-# Support both in-repo and standalone imports
-try:
-    # In-repo imports (when running from OpenEnv repository)
-    from openenv.core.client_types import StepResult
-    from openenv.core.env_server.types import State
-    from openenv.core.env_client import EnvClient
-    from .models import EchoAction, EchoObservation
-except ImportError:
-    # Standalone imports (when environment is standalone with openenv from pip)
-    from openenv.core.client_types import StepResult
-    from openenv.core.env_server.types import State
-    from openenv.core.env_client import EnvClient
-    from models import EchoAction, EchoObservation
 
-
-class EchoEnv(EnvClient[EchoAction, EchoObservation, State]):
+class EchoEnv(MCPToolClient):
     """
     Client for the Echo 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.
+    This client provides a simple interface for interacting with the Echo
+    Environment via MCP tools. It inherits all functionality from MCPToolClient:
+    - `list_tools()`: Discover available tools
+    - `call_tool(name, **kwargs)`: Call a tool by name
+    - `reset(**kwargs)`: Reset the environment
+    - `step(action)`: Execute an action (for advanced use)
 
     Example:
         >>> # Connect to a running server
-        >>> with EchoEnv(base_url="http://localhost:8000") as client:
-        ...     result = client.reset()
-        ...     print(result.observation.echoed_message)
+        >>> with EchoEnv(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...
+        ...     # List available tools
+        ...     tools = env.list_tools()
+        ...     for tool in tools:
+        ...         print(f"{tool.name}: {tool.description}")
         ...
-        ...     result = client.step(EchoAction(message="Hello!"))
-        ...     print(result.observation.echoed_message)
-        ...     print(result.reward)
+        ...     # Echo a message
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)  # "Hello!"
+        ...
+        ...     # Echo with length
+        ...     result = env.call_tool("echo_with_length", message="Test")
+        ...     print(result)  # {"message": "Test", "length": 4}
 
     Example with Docker:
         >>> # Automatically start container and connect
-        >>> client = EchoEnv.from_docker_image("echo-env:latest")
+        >>> env = EchoEnv.from_docker_image("echo-env:latest")
         >>> try:
-        ...     result = client.reset()
-        ...     result = client.step(EchoAction(message="Test"))
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     result = env.call_tool("echo_message", message="Hello!")
         ... finally:
-        ...     client.close()
-    """
-
-    def _step_payload(self, action: EchoAction) -> Dict:
-        """
-        Convert EchoAction to JSON payload for step request.
-
-        Args:
-            action: EchoAction instance
-
-        Returns:
-            Dictionary representation suitable for JSON encoding
-        """
-        return {
-            "message": action.message,
-        }
-
-    def _parse_result(self, payload: Dict) -> StepResult[EchoObservation]:
-        """
-        Parse server response into StepResult[EchoObservation].
+        ...     env.close()
 
-        Args:
-            payload: JSON response from server
-
-        Returns:
-            StepResult with EchoObservation
-        """
-        obs_data = payload.get("observation", {})
-        observation = EchoObservation(
-            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 endpoint
+    Example with HuggingFace Space:
+        >>> # Run from HuggingFace Space
+        >>> env = EchoEnv.from_env("openenv/echo-env")
+        >>> try:
+        ...     env.reset()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+    """
 
-        Returns:
-            State object with episode_id and step_count
-        """
-        return State(
-            episode_id=payload.get("episode_id"),
-            step_count=payload.get("step_count", 0),
-        )
+    pass  # MCPToolClient provides all needed functionality

envs/echo_env/README.md

@@ -0,0 +1,160 @@
+---
+title: Echo Environment Server
+emoji: 🔊
+colorFrom: blue
+colorTo: blue
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# Echo 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 Echo environment is through the `EchoEnv` class. The client is **async by default**:
+
+```python
+import asyncio
+from echo_env import EchoAction, EchoEnv
+
+async def main():
+    # Create environment from Docker image
+    client = await EchoEnv.from_docker_image("echo-env:latest")
+
+    async with client:
+        # Reset
+        result = await client.reset()
+        print(f"Reset: {result.observation.echoed_message}")
+
+        # Send multiple messages
+        messages = ["Hello, World!", "Testing echo", "Final message"]
+
+        for msg in messages:
+            result = await client.step(EchoAction(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}")
+
+asyncio.run(main())
+```
+
+For **synchronous usage**, use the `.sync()` wrapper:
+
+```python
+from echo_env import EchoAction, EchoEnv
+
+with EchoEnv(base_url="http://localhost:8000").sync() as client:
+    result = client.reset()
+    result = client.step(EchoAction(message="Hello!"))
+    print(result.observation.echoed_message)
+```
+
+The `EchoEnv.from_docker_image()` method handles:
+- Starting the Docker container
+- Waiting for the server to be ready
+- Connecting to the environment
+- Container cleanup when the context manager exits
+
+## Building the Docker Image
+
+Before using the environment, you need to build the Docker image:
+
+```bash
+# From project root
+docker build -t echo-env:latest -f envs/echo_env/server/Dockerfile .
+```
+
+## Environment Details
+
+### Action
+**EchoAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**EchoObservation**: 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 an Echo environment server running, you can connect directly:
+
+```python
+from echo_env import EchoAction, EchoEnv
+
+# Async usage
+async with EchoEnv(base_url="http://localhost:8000") as client:
+    result = await client.reset()
+    result = await client.step(EchoAction(message="Hello!"))
+
+# Sync usage
+with EchoEnv(base_url="http://localhost:8000").sync() as client:
+    result = client.reset()
+    result = client.step(EchoAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, closing the client will NOT stop the server.
+
+## Development & Testing
+
+### Direct Environment Testing
+
+Test the environment logic directly without starting the HTTP server:
+
+```bash
+# From the server directory
+python3 envs/echo_env/server/test_echo_env.py
+```
+
+This verifies that:
+- Environment resets correctly
+- Step executes actions properly
+- State tracking works
+- Rewards are calculated correctly
+
+### Running the Full Example
+
+Run the complete example that demonstrates the full workflow:
+
+```bash
+python3 examples/local_echo_env.py
+```
+
+This example shows:
+- Creating an environment from a Docker image
+- Resetting and stepping through the environment
+- Automatic cleanup with `close()`
+
+## Project Structure
+
+```
+echo_env/
+├── __init__.py            # Module exports
+├── README.md              # This file
+├── client.py              # EchoEnv client implementation
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── echo_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application
+    ├── test_echo_env.py   # Direct environment tests
+    └── Dockerfile         # Container image definition
+```

envs/echo_env/__init__.py

@@ -0,0 +1,29 @@
+# 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.
+
+"""
+Echo Environment - A pure MCP environment for testing and demonstration.
+
+This environment exposes all functionality through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from echo_env import EchoEnv
+    >>>
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...     tools = env.list_tools()
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+"""
+
+# Re-export MCP types for convenience
+from openenv.core.env_server.mcp_types import CallToolAction, ListToolsAction
+
+from .client import EchoEnv
+
+__all__ = ["EchoEnv", "CallToolAction", "ListToolsAction"]

envs/echo_env/build/lib/build/lib/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

envs/echo_env/build/lib/build/lib/server/app.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.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from ..models import EchoAction, EchoObservation
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from models import EchoAction, EchoObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+app = create_app(EchoEnvironment, EchoAction, EchoObservation, env_name="echo_env")
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

envs/echo_env/build/lib/build/lib/server/echo_environment.py

@@ -0,0 +1,102 @@
+# 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.
+
+"""
+Echo Environment Implementation.
+
+A simple test environment that echoes back messages sent to it.
+Perfect for testing HTTP server infrastructure.
+"""
+
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from ..models import EchoAction, EchoObservation
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from models import EchoAction, EchoObservation
+
+
+class EchoEnvironment(Environment):
+    """
+    A simple echo environment that echoes back messages.
+
+    This environment is designed for testing the HTTP server infrastructure.
+    It maintains minimal state and simply echoes back whatever message it receives.
+
+    Example:
+        >>> env = EchoEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.echoed_message)  # "Echo environment ready!"
+        >>>
+        >>> obs = env.step(EchoAction(message="Hello"))
+        >>> print(obs.echoed_message)  # "Hello"
+        >>> print(obs.message_length)  # 5
+    """
+
+    def __init__(self):
+        """Initialize the echo environment."""
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(self) -> EchoObservation:
+        """
+        Reset the environment.
+
+        Returns:
+            EchoObservation with a ready message
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count += 1
+
+        return EchoObservation(
+            echoed_message="Echo environment ready!",
+            message_length=0,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: EchoAction) -> EchoObservation:  # type: ignore[override]
+        """
+        Execute a step in the environment by echoing the message.
+
+        Args:
+            action: EchoAction containing the message to echo
+
+        Returns:
+            EchoObservation with the echoed message and its length
+        """
+        self._state.step_count += 1
+
+        message = action.message
+        length = len(message)
+
+        # Simple reward: longer messages get higher rewards
+        reward = length * 0.1
+
+        return EchoObservation(
+            echoed_message=message,
+            message_length=length,
+            done=False,
+            reward=reward,
+            metadata={"original_message": message, "step": self._state.step_count},
+        )
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

envs/echo_env/build/lib/echo_env/__init__.py

@@ -0,0 +1,29 @@
+# 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.
+
+"""
+Echo Environment - A pure MCP environment for testing and demonstration.
+
+This environment exposes all functionality through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from echo_env import EchoEnv
+    >>>
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...     tools = env.list_tools()
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+"""
+
+from .client import EchoEnv
+
+# Re-export MCP types for convenience
+from openenv.core.env_server.mcp_types import CallToolAction, ListToolsAction
+
+__all__ = ["EchoEnv", "CallToolAction", "ListToolsAction"]

envs/echo_env/build/lib/echo_env/client.py

@@ -0,0 +1,81 @@
+# 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.
+
+"""
+Echo Environment Client.
+
+This module provides the client for connecting to an Echo Environment server.
+EchoEnv extends MCPToolClient to provide tool-calling style interactions.
+
+Example:
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...
+    ...     # Discover tools
+    ...     tools = env.list_tools()
+    ...     print([t.name for t in tools])  # ['echo_message', 'echo_with_length']
+    ...
+    ...     # Call tools
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+    ...
+    ...     result = env.call_tool("echo_with_length", message="Test")
+    ...     print(result)  # {"message": "Test", "length": 4}
+"""
+
+from openenv.core.mcp_client import MCPToolClient
+
+
+class EchoEnv(MCPToolClient):
+    """
+    Client for the Echo Environment.
+
+    This client provides a simple interface for interacting with the Echo
+    Environment via MCP tools. It inherits all functionality from MCPToolClient:
+    - `list_tools()`: Discover available tools
+    - `call_tool(name, **kwargs)`: Call a tool by name
+    - `reset(**kwargs)`: Reset the environment
+    - `step(action)`: Execute an action (for advanced use)
+
+    Example:
+        >>> # Connect to a running server
+        >>> with EchoEnv(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...
+        ...     # List available tools
+        ...     tools = env.list_tools()
+        ...     for tool in tools:
+        ...         print(f"{tool.name}: {tool.description}")
+        ...
+        ...     # Echo a message
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)  # "Hello!"
+        ...
+        ...     # Echo with length
+        ...     result = env.call_tool("echo_with_length", message="Test")
+        ...     print(result)  # {"message": "Test", "length": 4}
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> env = EchoEnv.from_docker_image("echo-env:latest")
+        >>> try:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+
+    Example with HuggingFace Space:
+        >>> # Run from HuggingFace Space
+        >>> env = EchoEnv.from_env("openenv/echo-env")
+        >>> try:
+        ...     env.reset()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+    """
+
+    pass  # MCPToolClient provides all needed functionality

envs/echo_env/build/lib/echo_env/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

envs/echo_env/build/lib/echo_env/server/app.py

@@ -0,0 +1,60 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with MCPToolClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+# Use MCP types for action/observation since this is a pure MCP environment
+app = create_app(
+    EchoEnvironment, CallToolAction, CallToolObservation, env_name="echo_env"
+)
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

envs/echo_env/build/lib/echo_env/server/echo_environment.py

@@ -0,0 +1,196 @@
+# 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.
+
+"""
+Echo Environment Implementation.
+
+A pure MCP environment that echoes back messages sent to it.
+This demonstrates how to build an MCPEnvironment with inline FastMCP tools.
+
+All interactions happen through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from openenv.core.env_server.mcp_types import ListToolsAction, CallToolAction
+    >>> env = EchoEnvironment()
+    >>> env.reset()
+    >>>
+    >>> # List available tools
+    >>> obs = env.step(ListToolsAction())
+    >>> print([t.name for t in obs.tools])  # ["echo_message", "echo_with_length"]
+    >>>
+    >>> # Call a tool
+    >>> obs = env.step(CallToolAction(tool_name="echo_message", arguments={"message": "Hi!"}))
+    >>> print(obs.result)  # "Hi!"
+"""
+
+from typing import Any, Optional
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
+
+from fastmcp import FastMCP
+
+
+class EchoEnvironment(MCPEnvironment):
+    """
+    A pure MCP echo environment that echoes back messages.
+
+    This environment exposes all functionality through MCP tools:
+    - `echo_message`: Echo back the provided message
+    - `echo_with_length`: Echo back the message with its length
+
+    The environment inherits MCP support (ListToolsAction, CallToolAction)
+    from the MCPEnvironment base class. No legacy action types are supported.
+
+    Example using MCPToolClient:
+        >>> from openenv.core.mcp_client import MCPToolClient
+        >>>
+        >>> with MCPToolClient(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     print([t.name for t in tools])
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)
+    """
+
+    def __init__(self):
+        """Initialize the echo environment with MCP server and tools."""
+        # Create MCP server and define tools inline
+        mcp = FastMCP("echo_env")
+
+        @mcp.tool
+        def echo_message(message: str) -> str:
+            """
+            Echo back the provided message.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                The same message that was provided
+            """
+            return message
+
+        @mcp.tool
+        def echo_with_length(message: str) -> dict:
+            """
+            Echo back the message with its length.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                Dictionary with the message and its length
+            """
+            return {"message": message, "length": len(message)}
+
+        # Pass the MCP server to the base class
+        super().__init__(mcp)
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Reset the environment.
+
+        Args:
+            seed: Optional random seed (unused in echo env)
+            episode_id: Optional episode ID to use
+            **kwargs: Additional reset options
+
+        Returns:
+            Observation indicating the environment is ready
+        """
+        self._state = State(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+        )
+        self._reset_count += 1
+
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={"status": "ready", "message": "Echo environment ready!"},
+        )
+
+    def _step_impl(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Handle non-MCP actions.
+
+        This environment only supports MCP actions (ListToolsAction, CallToolAction).
+        Any other action type returns an error observation.
+
+        Args:
+            action: The action to execute
+            timeout_s: Optional timeout (unused)
+            **kwargs: Additional arguments
+
+        Returns:
+            Observation with error for unknown action types
+        """
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={
+                "error": f"Unknown action type: {type(action).__name__}. "
+                "Use ListToolsAction or CallToolAction for MCP interactions."
+            },
+        )
+
+    def step(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Execute a step in the environment.
+
+        Delegates to base class for MCP actions. Increments step count for all actions.
+
+        Args:
+            action: The MCP action to execute (ListToolsAction or CallToolAction)
+            timeout_s: Optional timeout for the action
+            **kwargs: Additional arguments
+
+        Returns:
+            Observation from the action execution
+        """
+        # Increment step count for all actions
+        self._state.step_count += 1
+
+        # Let the base class handle MCP actions and non-MCP routing
+        return super().step(action, timeout_s=timeout_s, **kwargs)
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

envs/echo_env/build/lib/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

envs/echo_env/build/lib/server/app.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.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from ..models import EchoAction, EchoObservation
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from models import EchoAction, EchoObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+app = create_app(EchoEnvironment, EchoAction, EchoObservation, env_name="echo_env")
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

envs/echo_env/build/lib/server/echo_environment.py

@@ -0,0 +1,102 @@
+# 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.
+
+"""
+Echo Environment Implementation.
+
+A simple test environment that echoes back messages sent to it.
+Perfect for testing HTTP server infrastructure.
+"""
+
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from ..models import EchoAction, EchoObservation
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.interfaces import Environment
+    from openenv.core.env_server.types import State
+    from models import EchoAction, EchoObservation
+
+
+class EchoEnvironment(Environment):
+    """
+    A simple echo environment that echoes back messages.
+
+    This environment is designed for testing the HTTP server infrastructure.
+    It maintains minimal state and simply echoes back whatever message it receives.
+
+    Example:
+        >>> env = EchoEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.echoed_message)  # "Echo environment ready!"
+        >>>
+        >>> obs = env.step(EchoAction(message="Hello"))
+        >>> print(obs.echoed_message)  # "Hello"
+        >>> print(obs.message_length)  # 5
+    """
+
+    def __init__(self):
+        """Initialize the echo environment."""
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(self) -> EchoObservation:
+        """
+        Reset the environment.
+
+        Returns:
+            EchoObservation with a ready message
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count += 1
+
+        return EchoObservation(
+            echoed_message="Echo environment ready!",
+            message_length=0,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: EchoAction) -> EchoObservation:  # type: ignore[override]
+        """
+        Execute a step in the environment by echoing the message.
+
+        Args:
+            action: EchoAction containing the message to echo
+
+        Returns:
+            EchoObservation with the echoed message and its length
+        """
+        self._state.step_count += 1
+
+        message = action.message
+        length = len(message)
+
+        # Simple reward: longer messages get higher rewards
+        reward = length * 0.1
+
+        return EchoObservation(
+            echoed_message=message,
+            message_length=length,
+            done=False,
+            reward=reward,
+            metadata={"original_message": message, "step": self._state.step_count},
+        )
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

envs/echo_env/client.py

@@ -0,0 +1,81 @@
+# 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.
+
+"""
+Echo Environment Client.
+
+This module provides the client for connecting to an Echo Environment server.
+EchoEnv extends MCPToolClient to provide tool-calling style interactions.
+
+Example:
+    >>> with EchoEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...
+    ...     # Discover tools
+    ...     tools = env.list_tools()
+    ...     print([t.name for t in tools])  # ['echo_message', 'echo_with_length']
+    ...
+    ...     # Call tools
+    ...     result = env.call_tool("echo_message", message="Hello!")
+    ...     print(result)  # "Hello!"
+    ...
+    ...     result = env.call_tool("echo_with_length", message="Test")
+    ...     print(result)  # {"message": "Test", "length": 4}
+"""
+
+from openenv.core.mcp_client import MCPToolClient
+
+
+class EchoEnv(MCPToolClient):
+    """
+    Client for the Echo Environment.
+
+    This client provides a simple interface for interacting with the Echo
+    Environment via MCP tools. It inherits all functionality from MCPToolClient:
+    - `list_tools()`: Discover available tools
+    - `call_tool(name, **kwargs)`: Call a tool by name
+    - `reset(**kwargs)`: Reset the environment
+    - `step(action)`: Execute an action (for advanced use)
+
+    Example:
+        >>> # Connect to a running server
+        >>> with EchoEnv(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...
+        ...     # List available tools
+        ...     tools = env.list_tools()
+        ...     for tool in tools:
+        ...         print(f"{tool.name}: {tool.description}")
+        ...
+        ...     # Echo a message
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)  # "Hello!"
+        ...
+        ...     # Echo with length
+        ...     result = env.call_tool("echo_with_length", message="Test")
+        ...     print(result)  # {"message": "Test", "length": 4}
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> env = EchoEnv.from_docker_image("echo-env:latest")
+        >>> try:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+
+    Example with HuggingFace Space:
+        >>> # Run from HuggingFace Space
+        >>> env = EchoEnv.from_env("openenv/echo-env")
+        >>> try:
+        ...     env.reset()
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ... finally:
+        ...     env.close()
+    """
+
+    pass  # MCPToolClient provides all needed functionality

envs/echo_env/openenv.yaml

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

envs/echo_env/openenv_echo_env.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: openenv-echo-env
+Version: 0.1.0
+Summary: Echo Environment for OpenEnv - simple test environment that echoes back messages
+Requires-Python: >=3.10
+Requires-Dist: openenv-core[core]>=0.2.1
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

envs/echo_env/openenv_echo_env.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+__init__.py
+client.py
+pyproject.toml
+./__init__.py
+./client.py
+openenv_echo_env.egg-info/PKG-INFO
+openenv_echo_env.egg-info/SOURCES.txt
+openenv_echo_env.egg-info/dependency_links.txt
+openenv_echo_env.egg-info/entry_points.txt
+openenv_echo_env.egg-info/requires.txt
+openenv_echo_env.egg-info/top_level.txt
+server/__init__.py
+server/app.py
+server/echo_environment.py

envs/echo_env/openenv_echo_env.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

envs/echo_env/openenv_echo_env.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+server = echo_env.server.app:main

envs/echo_env/openenv_echo_env.egg-info/requires.txt

@@ -0,0 +1,9 @@
+openenv-core[core]>=0.2.1
+fastapi>=0.115.0
+pydantic>=2.0.0
+uvicorn>=0.24.0
+requests>=2.31.0
+
+[dev]
+pytest>=8.0.0
+pytest-cov>=4.0.0

envs/echo_env/openenv_echo_env.egg-info/top_level.txt

@@ -0,0 +1 @@
+echo_env

envs/echo_env/pyproject.toml

@@ -0,0 +1,40 @@
+# 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-echo-env"
+version = "0.1.0"
+description = "Echo Environment for OpenEnv - simple test environment that echoes back messages"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv dependencies (required for server functionality)
+    "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git@main",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0.0",
+    "uvicorn>=0.24.0",
+    "requests>=2.31.0",
+    # No additional environment-specific dependencies needed for echo_env
+]
+
+[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 echo_env.server.app
+server = "echo_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["echo_env", "echo_env.server"]
+package-dir = { "echo_env" = ".", "echo_env.server" = "server" }

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

envs/echo_env/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Echo environment server components."""
+
+from .echo_environment import EchoEnvironment
+
+__all__ = ["EchoEnvironment"]

envs/echo_env/server/app.py

@@ -0,0 +1,61 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Echo Environment.
+
+This module creates an HTTP server that exposes the EchoEnvironment
+over HTTP and WebSocket endpoints, compatible with MCPToolClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    uv run --project . server
+"""
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.http_server import create_app
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+
+    from .echo_environment import EchoEnvironment
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.http_server import create_app
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+    from server.echo_environment import EchoEnvironment
+
+# Create the app with web interface and README integration
+# Pass the class (factory) instead of an instance for WebSocket session support
+# Use MCP types for action/observation since this is a pure MCP environment
+app = create_app(
+    EchoEnvironment, CallToolAction, CallToolObservation, env_name="echo_env"
+)
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.echo_env.server.app
+        openenv serve echo_env
+
+    """
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

envs/echo_env/server/echo_environment.py

@@ -0,0 +1,196 @@
+# 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.
+
+"""
+Echo Environment Implementation.
+
+A pure MCP environment that echoes back messages sent to it.
+This demonstrates how to build an MCPEnvironment with inline FastMCP tools.
+
+All interactions happen through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from openenv.core.env_server.mcp_types import ListToolsAction, CallToolAction
+    >>> env = EchoEnvironment()
+    >>> env.reset()
+    >>>
+    >>> # List available tools
+    >>> obs = env.step(ListToolsAction())
+    >>> print([t.name for t in obs.tools])  # ["echo_message", "echo_with_length"]
+    >>>
+    >>> # Call a tool
+    >>> obs = env.step(CallToolAction(tool_name="echo_message", arguments={"message": "Hi!"}))
+    >>> print(obs.result)  # "Hi!"
+"""
+
+from typing import Any, Optional
+from uuid import uuid4
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
+
+from fastmcp import FastMCP
+
+
+class EchoEnvironment(MCPEnvironment):
+    """
+    A pure MCP echo environment that echoes back messages.
+
+    This environment exposes all functionality through MCP tools:
+    - `echo_message`: Echo back the provided message
+    - `echo_with_length`: Echo back the message with its length
+
+    The environment inherits MCP support (ListToolsAction, CallToolAction)
+    from the MCPEnvironment base class. No legacy action types are supported.
+
+    Example using MCPToolClient:
+        >>> from openenv.core.mcp_client import MCPToolClient
+        >>>
+        >>> with MCPToolClient(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     print([t.name for t in tools])
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)
+    """
+
+    def __init__(self):
+        """Initialize the echo environment with MCP server and tools."""
+        # Create MCP server and define tools inline
+        mcp = FastMCP("echo_env")
+
+        @mcp.tool
+        def echo_message(message: str) -> str:
+            """
+            Echo back the provided message.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                The same message that was provided
+            """
+            return message
+
+        @mcp.tool
+        def echo_with_length(message: str) -> dict:
+            """
+            Echo back the message with its length.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                Dictionary with the message and its length
+            """
+            return {"message": message, "length": len(message)}
+
+        # Pass the MCP server to the base class
+        super().__init__(mcp)
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Reset the environment.
+
+        Args:
+            seed: Optional random seed (unused in echo env)
+            episode_id: Optional episode ID to use
+            **kwargs: Additional reset options
+
+        Returns:
+            Observation indicating the environment is ready
+        """
+        self._state = State(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+        )
+        self._reset_count += 1
+
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={"status": "ready", "message": "Echo environment ready!"},
+        )
+
+    def _step_impl(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Handle non-MCP actions.
+
+        This environment only supports MCP actions (ListToolsAction, CallToolAction).
+        Any other action type returns an error observation.
+
+        Args:
+            action: The action to execute
+            timeout_s: Optional timeout (unused)
+            **kwargs: Additional arguments
+
+        Returns:
+            Observation with error for unknown action types
+        """
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={
+                "error": f"Unknown action type: {type(action).__name__}. "
+                "Use ListToolsAction or CallToolAction for MCP interactions."
+            },
+        )
+
+    def step(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Execute a step in the environment.
+
+        Delegates to base class for MCP actions. Increments step count for all actions.
+
+        Args:
+            action: The MCP action to execute (ListToolsAction or CallToolAction)
+            timeout_s: Optional timeout for the action
+            **kwargs: Additional arguments
+
+        Returns:
+            Observation from the action execution
+        """
+        # Increment step count for all actions
+        self._state.step_count += 1
+
+        # Let the base class handle MCP actions and non-MCP routing
+        return super().step(action, timeout_s=timeout_s, **kwargs)
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

openenv.yaml

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

openenv_echo_env.egg-info/PKG-INFO

@@ -3,7 +3,7 @@ Name: openenv-echo-env
 Version: 0.1.0
 Summary: Echo Environment for OpenEnv - simple test environment that echoes back messages
 Requires-Python: >=3.10
-Requires-Dist: openenv-core>=0.2.0
+Requires-Dist: openenv-core[core]>=0.2.1
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: uvicorn>=0.24.0

openenv_echo_env.egg-info/SOURCES.txt

@@ -1,14 +1,15 @@
 README.md
+__init__.py
+client.py
 pyproject.toml
 ./__init__.py
 ./client.py
-./models.py
-./server/__init__.py
-./server/app.py
-./server/echo_environment.py
 openenv_echo_env.egg-info/PKG-INFO
 openenv_echo_env.egg-info/SOURCES.txt
 openenv_echo_env.egg-info/dependency_links.txt
 openenv_echo_env.egg-info/entry_points.txt
 openenv_echo_env.egg-info/requires.txt
-openenv_echo_env.egg-info/top_level.txt
+openenv_echo_env.egg-info/top_level.txt
+server/__init__.py
+server/app.py
+server/echo_environment.py

openenv_echo_env.egg-info/requires.txt

@@ -1,4 +1,4 @@
-openenv-core>=0.2.0
+openenv-core[core]>=0.2.1
 fastapi>=0.115.0
 pydantic>=2.0.0
 uvicorn>=0.24.0

pyproject.toml

@@ -15,7 +15,7 @@ description = "Echo Environment for OpenEnv - simple test environment that echoe
 requires-python = ">=3.10"
 dependencies = [
     # Core OpenEnv dependencies (required for server functionality)
-    "openenv-core @ git+https://github.com/meta-pytorch/OpenEnv.git@v0.2.1",
+    "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git@main",
     "fastapi>=0.115.0",
     "pydantic>=2.0.0",
     "uvicorn>=0.24.0",

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

server/__init__.py

@@ -8,4 +8,4 @@
 
 from .echo_environment import EchoEnvironment
 
-__all__ = ["EchoEnvironment"]
+__all__ = ["EchoEnvironment"]

server/app.py

@@ -8,7 +8,7 @@
 FastAPI application for the Echo Environment.
 
 This module creates an HTTP server that exposes the EchoEnvironment
-over HTTP and WebSocket endpoints, compatible with EnvClient.
+over HTTP and WebSocket endpoints, compatible with MCPToolClient.
 
 Usage:
     # Development (with auto-reload):
@@ -25,17 +25,21 @@ Usage:
 try:
     # In-repo imports (when running from OpenEnv repository)
     from openenv.core.env_server.http_server import create_app
-    from ..models import EchoAction, EchoObservation
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+
     from .echo_environment import EchoEnvironment
 except ImportError:
     # Standalone imports (when environment is standalone with openenv from pip)
     from openenv.core.env_server.http_server import create_app
-    from models import EchoAction, EchoObservation
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
     from server.echo_environment import EchoEnvironment
 
 # Create the app with web interface and README integration
 # Pass the class (factory) instead of an instance for WebSocket session support
-app = create_app(EchoEnvironment, EchoAction, EchoObservation, env_name="echo_env")
+# Use MCP types for action/observation since this is a pure MCP environment
+app = create_app(
+    EchoEnvironment, CallToolAction, CallToolObservation, env_name="echo_env"
+)
 
 
 def main():

server/echo_environment.py

@@ -7,91 +7,183 @@
 """
 Echo Environment Implementation.
 
-A simple test environment that echoes back messages sent to it.
-Perfect for testing HTTP server infrastructure.
+A pure MCP environment that echoes back messages sent to it.
+This demonstrates how to build an MCPEnvironment with inline FastMCP tools.
+
+All interactions happen through MCP tools:
+- `echo_message(message)`: Echo back the provided message
+- `echo_with_length(message)`: Echo back the message with its length
+
+Example:
+    >>> from openenv.core.env_server.mcp_types import ListToolsAction, CallToolAction
+    >>> env = EchoEnvironment()
+    >>> env.reset()
+    >>>
+    >>> # List available tools
+    >>> obs = env.step(ListToolsAction())
+    >>> print([t.name for t in obs.tools])  # ["echo_message", "echo_with_length"]
+    >>>
+    >>> # Call a tool
+    >>> obs = env.step(CallToolAction(tool_name="echo_message", arguments={"message": "Hi!"}))
+    >>> print(obs.result)  # "Hi!"
 """
 
+from typing import Any, Optional
 from uuid import uuid4
 
 # Support both in-repo and standalone imports
 try:
     # In-repo imports (when running from OpenEnv repository)
-    from openenv.core.env_server.interfaces import Environment
-    from openenv.core.env_server.types import State
-    from ..models import EchoAction, EchoObservation
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
 except ImportError:
     # Standalone imports (when environment is standalone with openenv from pip)
-    from openenv.core.env_server.interfaces import Environment
-    from openenv.core.env_server.types import State
-    from models import EchoAction, EchoObservation
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
 
+from fastmcp import FastMCP
 
-class EchoEnvironment(Environment):
+
+class EchoEnvironment(MCPEnvironment):
     """
-    A simple echo environment that echoes back messages.
+    A pure MCP echo environment that echoes back messages.
+
+    This environment exposes all functionality through MCP tools:
+    - `echo_message`: Echo back the provided message
+    - `echo_with_length`: Echo back the message with its length
 
-    This environment is designed for testing the HTTP server infrastructure.
-    It maintains minimal state and simply echoes back whatever message it receives.
+    The environment inherits MCP support (ListToolsAction, CallToolAction)
+    from the MCPEnvironment base class. No legacy action types are supported.
 
-    Example:
-        >>> env = EchoEnvironment()
-        >>> obs = env.reset()
-        >>> print(obs.echoed_message)  # "Echo environment ready!"
+    Example using MCPToolClient:
+        >>> from openenv.core.mcp_client import MCPToolClient
         >>>
-        >>> obs = env.step(EchoAction(message="Hello"))
-        >>> print(obs.echoed_message)  # "Hello"
-        >>> print(obs.message_length)  # 5
+        >>> with MCPToolClient(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...     tools = env.list_tools()
+        ...     print([t.name for t in tools])
+        ...     result = env.call_tool("echo_message", message="Hello!")
+        ...     print(result)
     """
 
-    SUPPORTS_CONCURRENT_SESSIONS: bool = True
-
     def __init__(self):
-        """Initialize the echo environment."""
+        """Initialize the echo environment with MCP server and tools."""
+        # Create MCP server and define tools inline
+        mcp = FastMCP("echo_env")
+
+        @mcp.tool
+        def echo_message(message: str) -> str:
+            """
+            Echo back the provided message.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                The same message that was provided
+            """
+            return message
+
+        @mcp.tool
+        def echo_with_length(message: str) -> dict:
+            """
+            Echo back the message with its length.
+
+            Args:
+                message: The message to echo back
+
+            Returns:
+                Dictionary with the message and its length
+            """
+            return {"message": message, "length": len(message)}
+
+        # Pass the MCP server to the base class
+        super().__init__(mcp)
         self._state = State(episode_id=str(uuid4()), step_count=0)
         self._reset_count = 0
 
-    def reset(self) -> EchoObservation:
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Observation:
         """
         Reset the environment.
 
+        Args:
+            seed: Optional random seed (unused in echo env)
+            episode_id: Optional episode ID to use
+            **kwargs: Additional reset options
+
         Returns:
-            EchoObservation with a ready message
+            Observation indicating the environment is ready
         """
-        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._state = State(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+        )
         self._reset_count += 1
 
-        return EchoObservation(
-            echoed_message="Echo environment ready!",
-            message_length=0,
+        return Observation(
             done=False,
             reward=0.0,
+            metadata={"status": "ready", "message": "Echo environment ready!"},
         )
 
-    def step(self, action: EchoAction) -> EchoObservation:  # type: ignore[override]
+    def _step_impl(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
         """
-        Execute a step in the environment by echoing the message.
+        Handle non-MCP actions.
+
+        This environment only supports MCP actions (ListToolsAction, CallToolAction).
+        Any other action type returns an error observation.
 
         Args:
-            action: EchoAction containing the message to echo
+            action: The action to execute
+            timeout_s: Optional timeout (unused)
+            **kwargs: Additional arguments
 
         Returns:
-            EchoObservation with the echoed message and its length
+            Observation with error for unknown action types
         """
-        self._state.step_count += 1
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={
+                "error": f"Unknown action type: {type(action).__name__}. "
+                "Use ListToolsAction or CallToolAction for MCP interactions."
+            },
+        )
 
-        message = action.message
-        length = len(message)
+    def step(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Execute a step in the environment.
 
-        # Simple reward: longer messages get higher rewards
-        reward = length * 0.1
+        Delegates to base class for MCP actions. Increments step count for all actions.
 
-        return EchoObservation(
-            echoed_message=message,
-            message_length=length,
-            done=False,
-            reward=reward,
-            metadata={"original_message": message, "step": self._state.step_count},
-        )
+        Args:
+            action: The MCP action to execute (ListToolsAction or CallToolAction)
+            timeout_s: Optional timeout for the action
+            **kwargs: Additional arguments
+
+        Returns:
+            Observation from the action execution
+        """
+        # Increment step count for all actions
+        self._state.step_count += 1
+
+        # Let the base class handle MCP actions and non-MCP routing
+        return super().step(action, timeout_s=timeout_s, **kwargs)
 
     @property
     def state(self) -> State: