Upload folder using huggingface_hub

Dockerfile

@@ -4,17 +4,24 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
-# Use the specified openenv-base image
-FROM ghcr.io/meta-pytorch/openenv-base:sha-7dd8148
+# Use the standard openenv base image
+# Built from: docker build -t openenv-base:latest -f src/core/containers/images/Dockerfile .
+# In GitHub Actions, this is overridden to use the GHCR base image
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ghcr.io/meta-pytorch/openenv-base:latest
 
 # Copy only what's needed for this environment
 COPY src/core/ /app/src/core/
 COPY src/envs/echo_env/ /app/src/envs/echo_env/
 
+# Copy README for web interface documentation
+COPY src/envs/echo_env/README.md /app/README.md
+
 # Health check
 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
     CMD curl -f http://localhost:8000/health || exit 1
 
 # Run the FastAPI server
-CMD ["uvicorn", "envs.echo_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]
 ENV ENABLE_WEB_INTERFACE=true
+
+CMD ["uvicorn", "envs.echo_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1,8 +1,8 @@
 ---
-title: echo_env
+title: Echo Environment Server
 emoji: 🔊
-colorFrom: green
-colorTo: indigo
+colorFrom: blue
+colorTo: yellow
 sdk: docker
 pinned: false
 app_port: 8000
@@ -11,40 +11,136 @@ tags:
   - openenv
 ---
 
-# Echo_env Environment Server
+# Echo Environment
 
-FastAPI server for echo_env environment powered by Meta's OpenEnv.
+A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
 
-## About
+## Quick Start
 
-This Space provides a containerized environment for echo_env interactions.
-Built with FastAPI and OpenEnv framework.
+The simplest way to use the Echo environment is through the `EchoEnv` class:
 
-## Web Interface
+```python
+from envs.echo_env import EchoAction, EchoEnv
 
-This deployment includes an interactive web interface for exploring the environment:
-- **HumanAgent Interface**: Interact with the environment using a web form
-- **State Observer**: Real-time view of environment state and action history
-- **Live Updates**: WebSocket-based real-time updates
+try:
+    # Create environment from Docker image
+    echo_env = EchoEnv.from_docker_image("echo-env:latest")
 
-Access the web interface at: `/web`
+    # Reset
+    result = echo_env.reset()
+    print(f"Reset: {result.observation.echoed_message}")
 
-## Echo Environment
+    # Send multiple messages
+    messages = ["Hello, World!", "Testing echo", "Final message"]
 
-Simple test environment that echoes back messages. Perfect for testing the OpenEnv APIs.
+    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}")
 
-### Usage
-Send a POST request to `/step` with:
-```json
-{
-  "message": "Hello World"
-}
+finally:
+    # Always clean up
+    echo_env.close()
 ```
 
-## API Documentation
+That's it! 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()`
 
-Visit `/docs` for interactive API documentation.
+## Building the Docker Image
 
-## Health Check
+Before using the environment, you need to build the Docker image:
 
-The environment provides a health check endpoint at `/health`.
+```bash
+# From project root
+docker build -t echo-env:latest -f src/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 envs.echo_env import EchoEnv
+
+# Connect to existing server
+echo_env = EchoEnv(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = echo_env.reset()
+result = echo_env.step(EchoAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, `echo_env.close()` 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 src/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
+```

src/core/README.md

@@ -0,0 +1,180 @@
+# <img width="35" height="35" alt="image" src="https://github.com/user-attachments/assets/2700a971-e5d6-4036-b03f-2f89c9791609" /> OpenEnv: Agentic Execution Environments
+
+An e2e framework for creating, deploying and using isolated execution environments for agentic RL training, built using Gymnasium style simple APIs. OpenEnv provides a standard for interacting with agentic execution environments via simple Gymnasium style APIs - step(), reset(), state(). Users of agentic execution environments can interact with the environment during RL training loops using these simple APIs.
+
+In addition to making it easier for researchers and RL framework writers, we also provide tools for environment creators making it easier for them to create richer environments and make them available over familar protocols like HTTP and packaged using canonical technologies like docker. Environment creators can use the OpenEnv framework to create environments that are isolated, secure, and easy to deploy and use.
+
+
+## Overview
+`openenv-core` provides the foundational building blocks for creating and interacting with containerized environments over HTTP. It enables you to build agent environments that can be deployed as Docker containers and accessed via a simple HTTP API.
+
+> ⚠️ **Early Development Warning** OpenEnv is currently in an experimental
+> stage. You should expect bugs, incomplete features, and APIs that may change
+> in future versions. The project welcomes bugfixes, but to make sure things are
+> well coordinated you should discuss any significant change before starting the
+> work. It's recommended that you signal your intention to contribute in the
+> issue tracker, either by filing a new issue or by claiming an existing one.
+
+
+# OpenEnv Core
+
+Core components for OpenEnv - a framework for building HTTP-based agentic environments.
+
+## Features
+
+- **HTTPEnvClient**: Generic HTTP client for interacting with remote environments
+- **HTTPEnvServer**: FastAPI-based server wrapper for exposing environments over HTTP
+- **Container Providers**: Pluggable architecture for running containers (Docker, Kubernetes, etc.)
+- **Type System**: Strongly-typed Action/Observation/State interfaces
+- **Web Interface**: Optional web UI for interacting with environments
+
+## Installation
+
+```bash
+pip install openenv-core
+```
+
+For development:
+```bash
+pip install openenv-core[dev]
+```
+
+## Quick Start
+
+### Creating an Environment Client
+
+```python
+from openenv_core import HTTPEnvClient, StepResult
+from dataclasses import dataclass
+
+@dataclass
+class MyAction:
+    text: str
+
+@dataclass
+class MyObservation:
+    response: str
+
+class MyEnvClient(HTTPEnvClient[MyAction, MyObservation]):
+    def _step_payload(self, action: MyAction) -> dict:
+        return {"text": action.text}
+
+    def _parse_result(self, payload: dict) -> StepResult[MyObservation]:
+        obs_data = payload["observation"]
+        return StepResult(
+            observation=MyObservation(**obs_data),
+            reward=payload.get("reward"),
+            done=payload.get("done", False)
+        )
+
+    def _parse_state(self, payload: dict) -> Any:
+        return payload
+
+# Use with Docker
+env = MyEnvClient.from_docker_image("my-env:latest")
+result = env.reset()
+step_result = env.step(MyAction(text="hello"))
+env.close()
+```
+
+### Creating an Environment Server
+
+```python
+from openenv_core.env_server import Environment, HTTPEnvServer, create_app
+from dataclasses import dataclass
+
+@dataclass
+class MyAction:
+    text: str
+
+@dataclass
+class MyObservation:
+    response: str
+    reward: float = 0.0
+    done: bool = False
+
+class MyEnvironment(Environment):
+    def reset(self) -> MyObservation:
+        return MyObservation(response="Ready")
+
+    def step(self, action: MyAction) -> MyObservation:
+        return MyObservation(
+            response=f"Echo: {action.text}",
+            reward=1.0,
+            done=False
+        )
+
+# Create FastAPI app
+env = MyEnvironment()
+app = create_app(env, MyAction, MyObservation)
+
+# Run with: uvicorn module:app --host 0.0.0.0 --port 8000
+```
+
+## Container Providers
+
+OpenEnv Core supports multiple container providers:
+
+### Local Docker Provider
+
+```python
+from openenv_core.containers.runtime import LocalDockerProvider
+
+provider = LocalDockerProvider()
+base_url = provider.start_container("my-env:latest")
+provider.wait_for_ready(base_url)
+# Use environment...
+provider.stop_container()
+```
+
+### Kubernetes Provider (Coming Soon)
+
+```python
+from openenv_core.containers.runtime import KubernetesProvider
+
+provider = KubernetesProvider(namespace="envs")
+base_url = provider.start_container("my-env:latest")
+# Use environment...
+provider.stop_container()
+```
+
+
+## API Reference
+
+### HTTPEnvClient
+
+Base class for environment clients with these abstract methods:
+
+- `_step_payload(action)`: Convert action to JSON
+- `_parse_result(payload)`: Parse response to StepResult
+- `_parse_state(payload)`: Parse state response
+
+### HTTPEnvServer
+
+Server wrapper with these methods:
+
+- `register_routes(app)`: Register endpoints on FastAPI app
+- `_deserialize_action(data)`: Convert JSON to Action
+- `_serialize_observation(obs)`: Convert Observation to JSON
+
+### Environment Interface
+
+Base interface for environment implementations:
+
+- `reset()`: Reset environment and return initial observation
+- `step(action)`: Execute action and return observation
+- `state`: Property returning current environment state
+
+## License
+
+This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please see the main OpenEnv repository for contribution guidelines.
+
+## Links
+
+- **Homepage**: https://github.com/facebookresearch/OpenEnv
+- **Documentation**: https://github.com/facebookresearch/OpenEnv/blob/main/README.md
+- **Bug Tracker**: https://github.com/facebookresearch/OpenEnv/issues

src/core/__init__.py

@@ -8,8 +8,8 @@
 
 # Re-export main components from submodules for convenience
 from .env_server import *
+from .client_types import StepResult
 from .http_env_client import HTTPEnvClient
-from .types import StepResult
 
 # Note: MCP module doesn't export anything yet
 

src/core/client_types.py

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

src/core/containers/runtime/providers.py

@@ -169,8 +169,12 @@ class LocalDockerProvider(ContainerProvider):
         cmd.append(image)
 
         # Run container
-        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
-        self._container_id = result.stdout.strip()
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+            self._container_id = result.stdout.strip()
+        except subprocess.CalledProcessError as e:
+            error_msg = f"Failed to start Docker container.\nCommand: {' '.join(cmd)}\nExit code: {e.returncode}\nStderr: {e.stderr}\nStdout: {e.stdout}"
+            raise RuntimeError(error_msg) from e
 
         # Wait a moment for container to start
         time.sleep(1)

src/core/http_env_client.py

@@ -12,11 +12,12 @@ Future hooks (commented below) for:
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any, Dict, Generic, Optional, Type, TypeVar
-from .containers.runtime import LocalDockerProvider
+from typing import Any, Dict, Generic, Optional, Type, TYPE_CHECKING, TypeVar
+
 import requests
 
-from .types import StepResult
+from .client_types import StepResult
+from .containers.runtime import LocalDockerProvider
 
 if TYPE_CHECKING:
     from .containers.runtime import ContainerProvider
@@ -45,6 +46,7 @@ class HTTPEnvClient(ABC, Generic[ActT, ObsT]):
         cls: Type[EnvClientT],
         image: str,
         provider: Optional["ContainerProvider"] = None,
+        **kwargs: Any,
     ) -> EnvClientT:
         """
         Create an environment client by spinning up a Docker container locally.
@@ -60,6 +62,8 @@ class HTTPEnvClient(ABC, Generic[ActT, ObsT]):
         Args:
             image: Docker image name to run (e.g., "echo-env:latest")
             provider: Container provider to use (defaults to LocalDockerProvider)
+            **kwargs: Additional arguments to pass to provider.start_container()
+                     (e.g., env_vars, port)
 
         Returns:
             An instance of the client class connected to the running container
@@ -71,6 +75,12 @@ class HTTPEnvClient(ABC, Generic[ActT, ObsT]):
             >>> # Create environment from image
             >>> env = CodingEnv.from_docker_image("coding-env:latest")
             >>>
+            >>> # Create environment with custom env vars
+            >>> env = CodingEnv.from_docker_image(
+            ...     "coding-env:latest",
+            ...     env_vars={"MY_VAR": "value"}
+            ... )
+            >>>
             >>> # Use the environment
             >>> result = env.reset()
             >>> print(result.observation)
@@ -86,8 +96,8 @@ class HTTPEnvClient(ABC, Generic[ActT, ObsT]):
         if provider is None:
             provider = LocalDockerProvider()
 
-        # 1. Start container
-        base_url = provider.start_container(image)
+        # 1. Start container with optional kwargs (e.g., env_vars, port)
+        base_url = provider.start_container(image, **kwargs)
 
         # 2. Wait for server to be ready
         provider.wait_for_ready(base_url)

src/core/pyproject.toml

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

src/core/tools/__init__.py

@@ -6,6 +6,11 @@
 
 """Core tools for code execution and other utilities."""
 
+from .git_server_client import GitServerClient, RepoInfo
 from .local_python_executor import PyExecutor
 
-__all__ = ["PyExecutor"]
+__all__ = [
+    "PyExecutor",
+    "GitServerClient",
+    "RepoInfo",
+]

src/core/tools/git_server_client.py

@@ -0,0 +1,362 @@
+#!/usr/bin/env python3
+"""
+Git Server Client for connecting to external Gitea instance.
+
+This module provides a lightweight client for interacting with a shared
+Gitea service, optimized for task-based isolation where multiple environment
+instances share the same Gitea server but have isolated workspaces.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlparse
+
+
+@dataclass
+class RepoInfo:
+    """Information about a repository."""
+
+    name: str
+    url: str
+    commit: str
+    clone_url: str
+
+
+class GitServerClient:
+    """
+    Client for connecting to an external Gitea server.
+
+    This client is optimized for task-based isolation where:
+    - Multiple tasks share the same Gitea instance
+    - Each task has its own isolated workspace
+    - Fast reset() via git operations (no server restart)
+    - Repos are pre-migrated to Gitea once
+
+    Args:
+        gitea_url: URL of the Gitea server (e.g., "http://gitea:3000")
+        username: Gitea username for authentication
+        password: Gitea password for authentication
+        workspace_dir: Local workspace directory for cloning repos
+
+    Example:
+        >>> # Connect to shared Gitea (credentials from environment)
+        >>> import os
+        >>> client = GitServerClient(
+        ...     gitea_url=os.getenv("GITEA_URL"),
+        ...     username=os.getenv("GITEA_USERNAME"),
+        ...     password=os.getenv("GITEA_PASSWORD")
+        ... )
+        >>> client.wait_for_ready()
+        >>> # Clone repo to workspace
+        >>> path = client.clone_to_workspace("my-repo", commit="abc123")
+        >>> # Fast reset to base state
+        >>> client.reset_workspace("my-repo", commit="abc123")
+    """
+
+    def __init__(
+        self,
+        gitea_url: str,
+        username: str,
+        password: str,
+        workspace_dir: str = "/workspace",
+    ):
+        """Initialize Git Server Client."""
+        self.gitea_url = gitea_url.rstrip("/")
+        self.username = username
+        self.password = password
+        self.workspace_dir = Path(workspace_dir)
+        self.is_ready = False
+
+        # Parse Gitea URL
+        parsed = urlparse(self.gitea_url)
+        self.domain = parsed.hostname or "localhost"
+        self.port = parsed.port or 3000
+
+        # Ensure workspace exists
+        os.makedirs(self.workspace_dir, exist_ok=True)
+
+        # Configure git credentials
+        self._configure_git()
+
+    def _configure_git(self):
+        """Configure git credentials for automatic authentication."""
+        home_dir = Path.home()
+
+        # Git config
+        git_config = f"""[user]
+    name = {self.username}
+    email = {self.username}@local.env
+[init]
+    defaultBranch = main
+[credential]
+    helper = store
+"""
+        gitconfig_path = home_dir / ".gitconfig"
+        gitconfig_path.write_text(git_config)
+
+        # Git credentials
+        git_credentials = f"http://{self.username}:{self.password}@{self.domain}:{self.port}\n"
+        gitcreds_path = home_dir / ".git-credentials"
+        gitcreds_path.write_text(git_credentials)
+        gitcreds_path.chmod(0o600)
+
+    def wait_for_ready(self, timeout: int = 30) -> bool:
+        """
+        Wait for Gitea server to be ready.
+
+        Args:
+            timeout: Maximum seconds to wait
+
+        Returns:
+            True if server is ready, False otherwise
+        """
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            try:
+                result = subprocess.run(
+                    ["curl", "-sf", f"{self.gitea_url}/"],
+                    capture_output=True,
+                    timeout=5,
+                )
+                if result.returncode == 0:
+                    self.is_ready = True
+                    return True
+            except subprocess.TimeoutExpired:
+                pass
+            except Exception:
+                pass
+
+            time.sleep(1)
+
+        return False
+
+    def list_repositories(self) -> list[dict[str, str]]:
+        """
+        List all repositories in Gitea.
+
+        Returns:
+            List of repository information dictionaries
+        """
+        if not self.is_ready:
+            raise RuntimeError("Gitea server is not ready")
+
+        result = subprocess.run(
+            [
+                "curl",
+                "-s",
+                f"{self.gitea_url}/api/v1/user/repos",
+                "-u",
+                f"{self.username}:{self.password}",
+            ],
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            return []
+
+        try:
+            repos = json.loads(result.stdout)
+            return [
+                {
+                    "name": repo["name"],
+                    "full_name": repo["full_name"],
+                    "clone_url": repo["clone_url"],
+                    "description": repo.get("description", ""),
+                }
+                for repo in repos
+            ]
+        except (json.JSONDecodeError, KeyError):
+            return []
+
+    def clone_to_workspace(
+        self, repo_name: str, target_dir: str | None = None, commit: str = "main"
+    ) -> str:
+        """
+        Clone a repository to the workspace at a specific commit.
+
+        This creates a fresh clone optimized for task isolation.
+
+        Args:
+            repo_name: Name of repository to clone
+            target_dir: Target directory name (defaults to repo_name)
+            commit: Commit hash or branch to checkout
+
+        Returns:
+            Path to cloned repository
+
+        Raises:
+            RuntimeError: If clone fails
+        """
+        if not self.is_ready:
+            raise RuntimeError("Gitea server is not ready")
+
+        target_dir = target_dir or repo_name
+        target_path = self.workspace_dir / target_dir
+
+        # Remove existing directory if present
+        if target_path.exists():
+            shutil.rmtree(target_path)
+
+        clone_url = f"{self.gitea_url}/{self.username}/{repo_name}.git"
+
+        # Clone repository
+        result = subprocess.run(
+            ["git", "clone", clone_url, str(target_path)],
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(f"Clone failed: {result.stderr}")
+
+        # Checkout specific commit
+        if commit != "main":
+            result = subprocess.run(
+                ["git", "checkout", commit],
+                cwd=str(target_path),
+                capture_output=True,
+                text=True,
+            )
+
+            if result.returncode != 0:
+                raise RuntimeError(f"Checkout failed: {result.stderr}")
+
+        return str(target_path)
+
+    def reset_workspace(self, repo_name: str, commit: str = "main") -> bool:
+        """
+        Fast reset of workspace to base state (optimized for task resets).
+
+        This is much faster than re-cloning. It:
+        1. Checks out the target commit
+        2. Resets to that commit (hard)
+        3. Cleans untracked files
+
+        Args:
+            repo_name: Name of repository (directory in workspace)
+            commit: Commit hash or branch to reset to
+
+        Returns:
+            True if reset successful
+
+        Raises:
+            RuntimeError: If reset fails
+        """
+        repo_path = self.workspace_dir / repo_name
+
+        if not repo_path.exists():
+            raise RuntimeError(f"Repository not found in workspace: {repo_name}")
+
+        # Fetch latest (in case commit is new)
+        subprocess.run(
+            ["git", "fetch", "--all"],
+            cwd=str(repo_path),
+            capture_output=True,
+        )
+
+        # Checkout and hard reset to commit
+        result = subprocess.run(
+            ["git", "checkout", commit],
+            cwd=str(repo_path),
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(f"Checkout failed: {result.stderr}")
+
+        result = subprocess.run(
+            ["git", "reset", "--hard", f"origin/{commit}" if commit != "main" else commit],
+            cwd=str(repo_path),
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            # Try without origin/ prefix
+            result = subprocess.run(
+                ["git", "reset", "--hard", commit],
+                cwd=str(repo_path),
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0:
+                raise RuntimeError(f"Reset failed: {result.stderr}")
+
+        # Clean untracked files and directories
+        subprocess.run(
+            ["git", "clean", "-fdx"],
+            cwd=str(repo_path),
+            capture_output=True,
+        )
+
+        return True
+
+    def execute_git_command(
+        self, command: str, working_dir: str = ""
+    ) -> tuple[int, str, str]:
+        """
+        Execute a git command in the workspace.
+
+        Args:
+            command: Git command to execute (without 'git' prefix)
+            working_dir: Working directory relative to workspace
+
+        Returns:
+            Tuple of (exit_code, stdout, stderr)
+        """
+        work_path = (
+            self.workspace_dir / working_dir if working_dir else self.workspace_dir
+        )
+
+        if not work_path.exists():
+            return (1, "", f"Working directory does not exist: {work_path}")
+
+        # Split command safely
+        cmd_parts = ["git"] + command.split()
+
+        result = subprocess.run(
+            cmd_parts,
+            cwd=str(work_path),
+            capture_output=True,
+            text=True,
+        )
+
+        return (result.returncode, result.stdout, result.stderr)
+
+    def get_current_commit(self, repo_name: str) -> str:
+        """
+        Get current commit hash of a workspace repository.
+
+        Args:
+            repo_name: Name of repository in workspace
+
+        Returns:
+            Commit hash
+        """
+        repo_path = self.workspace_dir / repo_name
+
+        if not repo_path.exists():
+            raise RuntimeError(f"Repository not found: {repo_name}")
+
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=str(repo_path),
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(f"Failed to get commit: {result.stderr}")
+
+        return result.stdout.strip()
+
+    def workspace_exists(self, repo_name: str) -> bool:
+        """Check if a repository exists in workspace."""
+        return (self.workspace_dir / repo_name).exists()

src/envs/echo_env/README.md

@@ -1,3 +1,16 @@
+---
+title: Echo Environment Server
+emoji: 🔊
+colorFrom: blue
+colorTo: yellow
+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.

src/envs/echo_env/client.py

@@ -13,9 +13,10 @@ over HTTP.
 
 from typing import Any, Dict
 
+from core.client_types import StepResult
+
 from core.env_server.types import State
 from core.http_env_client import HTTPEnvClient
-from core.types import StepResult
 
 from .models import EchoAction, EchoObservation