🤖 Deploy openspiel_env environment - 2025-10-19 22:32:50

.gitattributes

@@ -1,35 +0,0 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,43 @@
+# 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: First stage builds the base image
+FROM python:3.11-slim as base-builder
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies that all environments need
+RUN pip install --no-cache-dir \
+    fastapi>=0.104.0 \
+    "uvicorn[standard]>=0.24.0" \
+    requests>=2.25.0 \
+    wsproto>=1.0.0
+
+# Set working directory
+WORKDIR /app
+
+# Default environment variables
+ENV PYTHONPATH=/app/src
+ENV PYTHONUNBUFFERED=1
+
+# Second stage: Use the built base image and add environment-specific dependencies
+FROM base-builder
+
+
+# Copy only what's needed for this environment
+COPY src/core/ /app/src/core/
+COPY src/envs/openspiel_env/ /app/src/envs/openspiel_env/
+
+# 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.openspiel_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]
+ENV ENABLE_WEB_INTERFACE=true

README.md

@@ -1,10 +1,48 @@
 ---
-title: Openspiel Env
-emoji: 🐨
-colorFrom: pink
-colorTo: yellow
+title: Openspiel_env Environment Server
+emoji: 🐳
+colorFrom: blue
+colorTo: green
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Openspiel_env Environment Server
+
+FastAPI server for openspiel_env environment powered by Meta's OpenEnv.
+
+## About
+
+This Space provides a containerized environment for openspiel_env interactions.
+Built with FastAPI and OpenEnv framework.
+
+## Web Interface
+
+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
+
+Access the web interface at: `/web`
+
+## OpenSpiel Environment
+
+Provides access to OpenSpiel games for multi-agent reinforcement learning.
+
+### Usage
+Send a POST request to `/step` with:
+```json
+{
+  "action": 0
+}
+```
+
+## API Documentation
+
+Visit `/docs` for interactive API documentation.
+
+## Health Check
+
+The environment provides a health check endpoint at `/health`.

src/core/__init__.py

@@ -0,0 +1,19 @@
+# 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.
+
+"""Core components for agentic environments."""
+
+# Re-export main components from submodules for convenience
+from .env_server import *
+from .http_env_client import HTTPEnvClient
+from .types import StepResult
+
+# Note: MCP module doesn't export anything yet
+
+__all__ = [
+    "HTTPEnvClient",
+    "StepResult",
+]

src/core/containers/__init__.py

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

src/core/containers/images/Dockerfile

@@ -0,0 +1,46 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+#
+# OpenEnv Base Image
+#
+# This is the standard base image for all OpenEnv environment servers.
+# It includes the minimal dependencies needed to run HTTP environment servers.
+#
+# Build: docker build -t openenv-base:latest -f src/core/containers/images/Dockerfile .
+# Tag:   docker tag openenv-base:latest openenv-base:0.1.0
+#
+
+FROM python:3.11-slim
+
+# Set metadata
+LABEL maintainer="OpenEnv Team"
+LABEL description="Base image for OpenEnv based environment servers"
+LABEL version="0.1.0"
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies that all environments need
+RUN pip install --no-cache-dir \
+    fastapi>=0.104.0 \
+    "uvicorn[standard]>=0.24.0" \
+    requests>=2.25.0 \
+    wsproto>=1.0.0
+
+# Set working directory
+WORKDIR /app
+
+# Default environment variables
+ENV PYTHONPATH=/app/src
+ENV PYTHONUNBUFFERED=1
+
+# Default expose port (can be overridden)
+EXPOSE 8000
+
+# Note: CMD should be specified in child Dockerfiles

src/core/containers/images/README.md

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

src/core/containers/runtime/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Container runtime providers."""
+
+from .providers import ContainerProvider, KubernetesProvider, LocalDockerProvider
+
+__all__ = [
+    "ContainerProvider",
+    "LocalDockerProvider",
+    "KubernetesProvider",
+]

src/core/containers/runtime/providers.py

@@ -0,0 +1,289 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Container provider abstractions for running environment servers.
+
+This module provides a pluggable architecture for different container providers
+(local Docker, Kubernetes, cloud providers, etc.) to be used with HTTPEnvClient.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+
+
+class ContainerProvider(ABC):
+    """
+    Abstract base class for container providers.
+
+    Providers implement this interface to support different container platforms:
+    - LocalDockerProvider: Runs containers on local Docker daemon
+    - KubernetesProvider: Runs containers in Kubernetes cluster
+    - FargateProvider: Runs containers on AWS Fargate
+    - CloudRunProvider: Runs containers on Google Cloud Run
+
+    The provider manages a single container lifecycle and provides the base URL
+    for connecting to it.
+
+    Example:
+        >>> provider = LocalDockerProvider()
+        >>> base_url = provider.start_container("echo-env:latest")
+        >>> print(base_url)  # http://localhost:8000
+        >>> # Use the environment via base_url
+        >>> provider.stop_container()
+    """
+
+    @abstractmethod
+    def start_container(
+        self,
+        image: str,
+        port: Optional[int] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> str:
+        """
+        Start a container from the specified image.
+
+        Args:
+            image: Container image name (e.g., "echo-env:latest")
+            port: Port to expose (if None, provider chooses)
+            env_vars: Environment variables to pass to container
+            **kwargs: Provider-specific options
+
+        Returns:
+            Base URL to connect to the container (e.g., "http://localhost:8000")
+
+        Raises:
+            RuntimeError: If container fails to start
+        """
+        pass
+
+    @abstractmethod
+    def stop_container(self) -> None:
+        """
+        Stop and remove the running container.
+
+        This cleans up the container that was started by start_container().
+        """
+        pass
+
+    @abstractmethod
+    def wait_for_ready(self, base_url: str, timeout_s: float = 30.0) -> None:
+        """
+        Wait for the container to be ready to accept requests.
+
+        This typically polls the /health endpoint until it returns 200.
+
+        Args:
+            base_url: Base URL of the container
+            timeout_s: Maximum time to wait
+
+        Raises:
+            TimeoutError: If container doesn't become ready in time
+        """
+        pass
+
+
+class LocalDockerProvider(ContainerProvider):
+    """
+    Container provider for local Docker daemon.
+
+    This provider runs containers on the local machine using Docker.
+    Useful for development and testing.
+
+    Example:
+        >>> provider = LocalDockerProvider()
+        >>> base_url = provider.start_container("echo-env:latest")
+        >>> # Container running on http://localhost:<random-port>
+        >>> provider.stop_container()
+    """
+
+    def __init__(self):
+        """Initialize the local Docker provider."""
+        self._container_id: Optional[str] = None
+        self._container_name: Optional[str] = None
+
+        # Check if Docker is available
+        import subprocess
+
+        try:
+            subprocess.run(
+                ["docker", "version"],
+                check=True,
+                capture_output=True,
+                timeout=5,
+            )
+        except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+            raise RuntimeError(
+                "Docker is not available. Please install Docker Desktop or Docker Engine."
+            )
+
+    def start_container(
+        self,
+        image: str,
+        port: Optional[int] = None,
+        env_vars: Optional[Dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> str:
+        """
+        Start a Docker container locally.
+
+        Args:
+            image: Docker image name
+            port: Port to expose (if None, finds available port)
+            env_vars: Environment variables for the container
+            **kwargs: Additional Docker run options
+
+        Returns:
+            Base URL to connect to the container
+        """
+        import subprocess
+        import time
+
+        # Find available port if not specified
+        if port is None:
+            port = self._find_available_port()
+
+        # Generate container name
+        self._container_name = self._generate_container_name(image)
+
+        # Build docker run command
+        cmd = [
+            "docker", "run",
+            "-d",  # Detached
+            "--name", self._container_name,
+            "-p", f"{port}:8000",  # Map port
+        ]
+
+        # Add environment variables
+        if env_vars:
+            for key, value in env_vars.items():
+                cmd.extend(["-e", f"{key}={value}"])
+
+        # Add image
+        cmd.append(image)
+
+        # Run container
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+        self._container_id = result.stdout.strip()
+
+        # Wait a moment for container to start
+        time.sleep(1)
+
+        base_url = f"http://localhost:{port}"
+        return base_url
+
+    def stop_container(self) -> None:
+        """
+        Stop and remove the Docker container.
+        """
+        if self._container_id is None:
+            return
+
+        import subprocess
+
+        try:
+            # Stop container
+            subprocess.run(
+                ["docker", "stop", self._container_id],
+                capture_output=True,
+                check=True,
+                timeout=10,
+            )
+
+            # Remove container
+            subprocess.run(
+                ["docker", "rm", self._container_id],
+                capture_output=True,
+                check=True,
+                timeout=10,
+            )
+        except subprocess.CalledProcessError:
+            # Container might already be stopped/removed
+            pass
+        finally:
+            self._container_id = None
+            self._container_name = None
+
+    def wait_for_ready(self, base_url: str, timeout_s: float = 30.0) -> None:
+        """
+        Wait for container to be ready by polling /health endpoint.
+
+        Args:
+            base_url: Base URL of the container
+            timeout_s: Maximum time to wait
+
+        Raises:
+            TimeoutError: If container doesn't become ready
+        """
+        import time
+        import requests
+
+        start_time = time.time()
+        health_url = f"{base_url}/health"
+
+        while time.time() - start_time < timeout_s:
+            try:
+                response = requests.get(health_url, timeout=2.0)
+                if response.status_code == 200:
+                    return
+            except requests.RequestException:
+                pass
+
+            time.sleep(0.5)
+
+        raise TimeoutError(
+            f"Container at {base_url} did not become ready within {timeout_s}s"
+        )
+
+    def _find_available_port(self) -> int:
+        """
+        Find an available port on localhost.
+
+        Returns:
+            An available port number
+        """
+        import socket
+
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(("", 0))
+            s.listen(1)
+            port = s.getsockname()[1]
+        return port
+
+    def _generate_container_name(self, image: str) -> str:
+        """
+        Generate a unique container name based on image name and timestamp.
+
+        Args:
+            image: Docker image name
+
+        Returns:
+            A unique container name
+        """
+        import time
+
+        clean_image = image.split("/")[-1].split(":")[0]
+        timestamp = int(time.time() * 1000)
+        return f"{clean_image}-{timestamp}"
+
+
+class KubernetesProvider(ContainerProvider):
+    """
+    Container provider for Kubernetes clusters.
+
+    This provider creates pods in a Kubernetes cluster and exposes them
+    via services or port-forwarding.
+
+    Example:
+        >>> provider = KubernetesProvider(namespace="envtorch-dev")
+        >>> base_url = provider.start_container("echo-env:latest")
+        >>> # Pod running in k8s, accessible via service or port-forward
+        >>> provider.stop_container()
+    """
+    pass

src/core/containers/test_local_docker_provider.py

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

src/core/env_server/__init__.py

@@ -0,0 +1,35 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Core environment interfaces and types."""
+
+from .base_transforms import CompositeTransform, NullTransform
+from .http_server import HTTPEnvServer, create_app, create_fastapi_app
+from .interfaces import Environment, Message, ModelTokenizer, Transform
+from .types import Action, Observation, State
+from .web_interface import create_web_interface_app, WebInterfaceManager
+
+__all__ = [
+    # Core interfaces
+    "Environment",
+    "Transform",
+    "Message",
+    "ModelTokenizer",
+    # Types
+    "Action",
+    "Observation",
+    "State",
+    # Base transforms
+    "CompositeTransform",
+    "NullTransform",
+    # HTTP Server
+    "HTTPEnvServer",
+    "create_app",
+    "create_fastapi_app",
+    # Web Interface
+    "create_web_interface_app",
+    "WebInterfaceManager",
+]

src/core/env_server/base_transforms.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.
+
+"""Base transform implementations for composing environment-specific transforms."""
+
+from .interfaces import Transform
+from .types import Observation
+
+
+class CompositeTransform(Transform):
+    """Combines multiple transforms into a single transform."""
+
+    def __init__(self, transforms: list[Transform]):
+        self.transforms = transforms
+
+    def __call__(self, observation: Observation) -> Observation:
+        for transform in self.transforms:
+            observation = transform(observation)
+        return observation
+
+
+class NullTransform(Transform):
+    """Default transform that passes through unchanged."""
+
+    def __call__(self, observation: Observation) -> Observation:
+        return observation

src/core/env_server/http_server.py

@@ -0,0 +1,231 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+HTTP server wrapper for Environment instances.
+
+This module provides utilities to wrap any Environment subclass and expose it
+over HTTP endpoints that HTTPEnvClient can consume.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import asdict
+from typing import Any, Dict, Type
+
+from .interfaces import Environment
+from .types import Action, Observation
+from fastapi import Body, FastAPI
+
+class HTTPEnvServer:
+    """
+    HTTP server wrapper for Environment instances.
+
+    This class wraps an Environment and exposes its reset(), step(), and state
+    methods as HTTP endpoints compatible with HTTPEnvClient.
+
+    The server expects:
+    - Action deserialization: Converts JSON dict to Action subclass
+    - Observation serialization: Converts Observation subclass to JSON dict
+
+    Example:
+        >>> from core.env_server import HTTPEnvServer
+        >>> from envs.coding_env.server import CodeExecutionEnvironment
+        >>>
+        >>> env = CodeExecutionEnvironment()
+        >>> server = HTTPEnvServer(env)
+        >>>
+        >>> # Register routes with FastAPI
+        >>> from fastapi import FastAPI
+        >>> app = FastAPI()
+        >>> server.register_routes(app)
+    """
+
+    def __init__(
+        self,
+        env: Environment,
+        action_cls: Type[Action],
+        observation_cls: Type[Observation],
+    ):
+        """
+        Initialize HTTP server wrapper.
+
+        Args:
+            env: The Environment instance to wrap
+            action_cls: The Action subclass this environment expects
+            observation_cls: The Observation subclass this environment returns
+        """
+        self.env = env
+        self.action_cls = action_cls
+        self.observation_cls = observation_cls
+
+    def register_routes(self, app: Any) -> None:
+        """
+        Register HTTP routes on a FastAPI application.
+
+        Args:
+            app: FastAPI application instance
+        """
+
+        if not isinstance(app, FastAPI):
+            raise TypeError("app must be a FastAPI instance")
+
+        @app.post("/reset")
+        async def reset(request: Dict[str, Any] = Body(default={})) -> Dict[str, Any]:
+            """Reset endpoint - returns initial observation."""
+            # TODO: Handle seed, episode_id from request if provided
+            observation = self.env.reset()
+            return self._serialize_observation(observation)
+
+        @app.post("/step")
+        async def step(request: Dict[str, Any]) -> Dict[str, Any]:
+            """Step endpoint - executes action and returns observation."""
+            action_data = request.get("action", {})
+            # TODO: Handle timeout_s, request_id, episode_id from request if provided
+
+            # Deserialize action
+            action = self._deserialize_action(action_data)
+
+            # Execute step
+            observation = self.env.step(action)
+
+            # Return serialized observation
+            return self._serialize_observation(observation)
+
+        @app.get("/state")
+        async def get_state() -> Dict[str, Any]:
+            """State endpoint - returns current environment state."""
+            state = self.env.state
+            return asdict(state)
+
+        @app.get("/health")
+        async def health() -> Dict[str, str]:
+            """Health check endpoint."""
+            return {"status": "healthy"}
+
+
+    def _deserialize_action(self, action_data: Dict[str, Any]) -> Action:
+        """
+        Convert JSON dict to Action instance.
+
+        Args:
+            action_data: Dictionary containing action data
+
+        Returns:
+            Action instance
+
+        Note:
+            This is a simple implementation. Subclasses may need to override
+            for more complex deserialization logic.
+        """
+        # Remove metadata if present (it will be set via kw_only field)
+        metadata = action_data.pop("metadata", {})
+        action = self.action_cls(**action_data)
+        action.metadata = metadata
+        return action
+
+    def _serialize_observation(self, observation: Observation) -> Dict[str, Any]:
+        """
+        Convert Observation instance to JSON-compatible dict.
+
+        Args:
+            observation: Observation instance
+
+        Returns:
+            Dictionary compatible with HTTPEnvClient._parse_result()
+
+        The format matches what HTTPEnvClient expects:
+        {
+            "observation": {...},  # Observation fields
+            "reward": float | None,
+            "done": bool,
+        }
+        """
+        obs_dict = asdict(observation)
+
+        # Extract reward and done (these are part of StepResult on client side)
+        reward = obs_dict.pop("reward", None)
+        done = obs_dict.pop("done", False)
+        obs_dict.pop("metadata", None)  # Remove metadata from observation
+
+        # Return in HTTPEnvClient expected format
+        return {
+            "observation": obs_dict,
+            "reward": reward,
+            "done": done,
+        }
+
+def create_app(
+    env: Environment,
+    action_cls: Type[Action],
+    observation_cls: Type[Observation],
+) -> Any:
+    """
+    Create a FastAPI application with web interface enabled for Hugging Face deployments.
+    
+    This function checks for the ENABLE_WEB_INTERFACE environment variable to determine
+    whether to enable the web interface. 
+    
+    Args:
+        env: The Environment instance to serve
+        action_cls: The Action subclass this environment expects
+        observation_cls: The Observation subclass this environment returns
+        
+    Returns:
+        FastAPI application instance with or without web interface based on environment
+    """
+    # Check if web interface should be enabled
+    # This can be controlled via environment variable or build argument
+    enable_web = (
+        os.getenv("ENABLE_WEB_INTERFACE", "false").lower() in ("true", "1", "yes")
+    )
+
+    if enable_web:
+        # Import web interface only when needed
+        from .web_interface import create_web_interface_app
+        return create_web_interface_app(env, action_cls, observation_cls)
+    else:
+        # Use standard FastAPI app without web interface
+        return create_fastapi_app(env, action_cls, observation_cls)
+    
+
+def create_fastapi_app(
+    env: Environment,
+    action_cls: Type[Action],
+    observation_cls: Type[Observation],
+) -> Any:
+    """
+    Create a FastAPI application with routes for the given environment.
+
+    Args:
+        env: The Environment instance to serve
+        action_cls: The Action subclass this environment expects
+        observation_cls: The Observation subclass this environment returns
+
+    Returns:
+        FastAPI application instance with routes registered
+
+    Example:
+        >>> from envs.coding_env.server import CodeExecutionEnvironment
+        >>> from envs.coding_env.models import CodeAction, CodeObservation
+        >>>
+        >>> env = CodeExecutionEnvironment()
+        >>> app = create_fastapi_app(env, CodeAction, CodeObservation)
+        >>>
+        >>> # Run with: uvicorn module:app --host 0.0.0.0 --port 8000
+    """
+    try:
+        from fastapi import FastAPI
+    except ImportError:
+        raise ImportError(
+            "FastAPI is required. Install with: pip install fastapi uvicorn"
+        )
+
+    app = FastAPI(title="Environment HTTP Server")
+    server = HTTPEnvServer(env, action_cls, observation_cls)
+    server.register_routes(app)
+    return app

src/core/env_server/interfaces.py

@@ -0,0 +1,118 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+from abc import ABC, abstractmethod
+from typing import Any, Protocol, TypedDict
+
+from .types import Action, Observation, State
+
+
+class Message(TypedDict):
+    """A message in a conversation.
+
+    Compatible with Huggingface chat template format.
+    """
+
+    role: str
+    content: str
+
+
+class ModelTokenizer(Protocol):
+    """Protocol for tokenizers that support chat templates.
+
+    This protocol defines the interface that tokenizers must implement
+    to work with chat-based environments. It's compatible with
+    Huggingface transformers tokenizers.
+    """
+
+    def apply_chat_template(
+        self,
+        conversation: list[Message],
+        tokenize: bool = True,
+        return_tensors: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Apply a chat template to format and optionally tokenize a conversation.
+
+        Args:
+            conversation: List of message dictionaries with 'role' and 'content'
+            tokenize: Whether to tokenize the output
+            return_tensors: Format for returned tensors ('pt' for PyTorch)
+            **kwargs: Additional arguments
+
+        Returns:
+            Formatted and optionally tokenized conversation
+        """
+        ...
+
+    def decode(
+        self, token_ids: Any, skip_special_tokens: bool = False, **kwargs: Any
+    ) -> str:
+        """Decode token IDs back to text.
+
+        Args:
+            token_ids: Token IDs to decode
+            skip_special_tokens: Whether to skip special tokens in output
+            **kwargs: Additional arguments
+
+        Returns:
+            Decoded text string
+        """
+        ...
+
+
+class Transform(ABC):
+    """Transform observations to add rewards, metrics, or other modifications.
+
+    Transforms follow the TorchRL pattern where they take an observation
+    and return a (potentially modified) observation. This allows for
+    flexible reward computation and observation augmentation.
+    """
+
+    @abstractmethod
+    def __call__(self, observation: Observation) -> Observation:
+        """Transform an observation.
+
+        Args:
+            observation: The input observation
+
+        Returns:
+            The transformed observation
+        """
+        pass
+
+
+class Environment(ABC):
+    """Base class for all environment servers following Gym/Gymnasium API.
+
+    Args:
+        transform: Optional transform to apply to observations
+    """
+
+    def __init__(self, transform: Transform | None = None):
+        self.transform = transform
+
+    @abstractmethod
+    def reset(self) -> Observation:
+        """Reset the environment and return initial observation."""
+        pass
+
+    @abstractmethod
+    def step(self, action: Action) -> Observation:
+        """Take a step in the environment."""
+        pass
+
+    @property
+    @abstractmethod
+    def state(self) -> State:
+        """Get the current environment state."""
+        pass
+
+    def _apply_transform(self, observation: Observation) -> Observation:
+        """Apply transform if one is provided."""
+        if self.transform is not None:
+            return self.transform(observation)
+        return observation

src/core/env_server/types.py

@@ -0,0 +1,45 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+
+
+# Type aliases
+Scalar = Union[int, float, bool]
+
+
+@dataclass(kw_only=True)
+class Action:
+    """Base class for all environment actions."""
+
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(kw_only=True)
+class Observation:
+    """Base class for all environment observations."""
+
+    done: bool = False
+    reward: Union[bool, int, float, None] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class State:
+    """Base class for environment state."""
+
+    episode_id: Optional[str] = None
+    step_count: int = 0
+
+
+@dataclass
+class CodeExecResult:
+    """Result of code execution containing stdout, stderr, and exit code."""
+
+    stdout: str
+    stderr: str
+    exit_code: int

src/core/env_server/web_interface.py

@@ -0,0 +1,764 @@
+# 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.
+
+"""
+Web interface for OpenEnv environments.
+
+This module provides a web-based interface for interacting with OpenEnv environments,
+including a two-pane layout for HumanAgent interaction and state observation.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass
+from typing import Any, Dict, List, Optional, Type
+from datetime import datetime
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect, Request
+from fastapi.responses import HTMLResponse, FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+from .interfaces import Environment
+from .types import Action, Observation, State
+
+
+@dataclass
+class ActionLog:
+    """Log entry for an action taken."""
+    timestamp: str
+    action: Dict[str, Any]
+    observation: Dict[str, Any]
+    reward: Optional[float]
+    done: bool
+    step_count: int
+
+
+@dataclass
+class EpisodeState:
+    """Current episode state for the web interface."""
+    episode_id: Optional[str]
+    step_count: int
+    current_observation: Optional[Dict[str, Any]]
+    action_logs: List[ActionLog]
+    is_reset: bool = True
+
+
+class WebInterfaceManager:
+    """Manages the web interface for an environment."""
+    
+    def __init__(
+        self,
+        env: Environment,
+        action_cls: Type[Action],
+        observation_cls: Type[Observation],
+    ):
+        self.env = env
+        self.action_cls = action_cls
+        self.observation_cls = observation_cls
+        self.episode_state = EpisodeState(
+            episode_id=None,
+            step_count=0,
+            current_observation=None,
+            action_logs=[]
+        )
+        self.connected_clients: List[WebSocket] = []
+    
+    async def connect_websocket(self, websocket: WebSocket):
+        """Connect a new WebSocket client."""
+        await websocket.accept()
+        self.connected_clients.append(websocket)
+        
+        # Send current state to the new client
+        await self._send_state_update()
+    
+    async def disconnect_websocket(self, websocket: WebSocket):
+        """Disconnect a WebSocket client."""
+        if websocket in self.connected_clients:
+            self.connected_clients.remove(websocket)
+    
+    async def _send_state_update(self):
+        """Send current state to all connected clients."""
+        if not self.connected_clients:
+            return
+            
+        state_data = {
+            "type": "state_update",
+            "episode_state": asdict(self.episode_state)
+        }
+        
+        # Send to all connected clients
+        disconnected_clients = []
+        for client in self.connected_clients:
+            try:
+                await client.send_text(json.dumps(state_data))
+            except:
+                disconnected_clients.append(client)
+        
+        # Remove disconnected clients
+        for client in disconnected_clients:
+            self.connected_clients.remove(client)
+    
+    async def reset_environment(self) -> Dict[str, Any]:
+        """Reset the environment and update state."""
+        observation = self.env.reset()
+        state = self.env.state
+        
+        # Update episode state
+        self.episode_state.episode_id = state.episode_id
+        self.episode_state.step_count = 0
+        self.episode_state.current_observation = asdict(observation)
+        self.episode_state.action_logs = []
+        self.episode_state.is_reset = True
+        
+        # Send state update
+        await self._send_state_update()
+        
+        return {
+            "observation": asdict(observation),
+            "reward": observation.reward,
+            "done": observation.done,
+        }
+    
+    async def step_environment(self, action_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Execute a step in the environment and update state."""
+        # Deserialize action
+        action = self._deserialize_action(action_data)
+        
+        # Execute step
+        observation = self.env.step(action)
+        state = self.env.state
+        
+        # Create action log
+        action_log = ActionLog(
+            timestamp=datetime.now().isoformat(),
+            action=asdict(action),
+            observation=asdict(observation),
+            reward=observation.reward,
+            done=observation.done,
+            step_count=state.step_count
+        )
+        
+        # Update episode state
+        self.episode_state.episode_id = state.episode_id
+        self.episode_state.step_count = state.step_count
+        self.episode_state.current_observation = asdict(observation)
+        self.episode_state.action_logs.append(action_log)
+        self.episode_state.is_reset = False
+        
+        # Send state update
+        await self._send_state_update()
+        
+        return {
+            "observation": asdict(observation),
+            "reward": observation.reward,
+            "done": observation.done,
+        }
+    
+    def get_state(self) -> Dict[str, Any]:
+        """Get current environment state."""
+        state = self.env.state
+        return asdict(state)
+    
+    def _deserialize_action(self, action_data: Dict[str, Any]) -> Action:
+        """Convert JSON dict to Action instance."""
+        metadata = action_data.pop("metadata", {})
+        action = self.action_cls(**action_data)
+        action.metadata = metadata
+        return action
+
+
+def create_web_interface_app(
+    env: Environment,
+    action_cls: Type[Action],
+    observation_cls: Type[Observation],
+) -> FastAPI:
+    """
+    Create a FastAPI application with web interface for the given environment.
+    
+    Args:
+        env: The Environment instance to serve
+        action_cls: The Action subclass this environment expects
+        observation_cls: The Observation subclass this environment returns
+        
+    Returns:
+        FastAPI application instance with web interface
+    """
+    from .http_server import create_fastapi_app
+    
+    # Create the base environment app
+    app = create_fastapi_app(env, action_cls, observation_cls)
+    
+    # Create web interface manager
+    web_manager = WebInterfaceManager(env, action_cls, observation_cls)
+    
+    # Add web interface routes
+    @app.get("/web", response_class=HTMLResponse)
+    async def web_interface():
+        """Serve the web interface."""
+        return get_web_interface_html(action_cls)
+    
+    @app.websocket("/ws")
+    async def websocket_endpoint(websocket: WebSocket):
+        """WebSocket endpoint for real-time updates."""
+        await web_manager.connect_websocket(websocket)
+        try:
+            while True:
+                # Keep connection alive
+                await websocket.receive_text()
+        except WebSocketDisconnect:
+            await web_manager.disconnect_websocket(websocket)
+    
+    @app.post("/web/reset")
+    async def web_reset():
+        """Reset endpoint for web interface."""
+        return await web_manager.reset_environment()
+    
+    @app.post("/web/step")
+    async def web_step(request: Dict[str, Any]):
+        """Step endpoint for web interface."""
+        action_data = request.get("action", {})
+        return await web_manager.step_environment(action_data)
+    
+    @app.get("/web/state")
+    async def web_state():
+        """State endpoint for web interface."""
+        return web_manager.get_state()
+    
+    return app
+
+
+def get_web_interface_html(action_cls: Type[Action]) -> str:
+    """Generate the HTML for the web interface."""
+    
+    # Get action fields for dynamic form generation
+    action_fields = []
+    if hasattr(action_cls, '__dataclass_fields__'):
+        for field_name, field_info in action_cls.__dataclass_fields__.items():
+            if field_name != 'metadata':
+                field_type = field_info.type
+                if field_type == str:
+                    input_type = "text"
+                elif field_type == int:
+                    input_type = "number"
+                elif field_type == float:
+                    input_type = "number"
+                elif field_type == bool:
+                    input_type = "checkbox"
+                else:
+                    input_type = "text"
+                
+                action_fields.append({
+                    'name': field_name,
+                    'type': input_type,
+                    'required': field_info.default is field_info.default_factory
+                })
+    
+    return f"""
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>OpenEnv Web Interface</title>
+    <style>
+        * {{
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }}
+        
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            background-color: #f5f5f5;
+            height: 100vh;
+            overflow: hidden;
+        }}
+        
+        .container {{
+            display: flex;
+            height: 100vh;
+        }}
+        
+        .left-pane {{
+            width: 50%;
+            background: white;
+            border-right: 1px solid #e0e0e0;
+            display: flex;
+            flex-direction: column;
+        }}
+        
+        .right-pane {{
+            width: 50%;
+            background: #fafafa;
+            display: flex;
+            flex-direction: column;
+        }}
+        
+        .pane-header {{
+            padding: 20px;
+            border-bottom: 1px solid #e0e0e0;
+            background: #f8f9fa;
+            font-weight: 600;
+            font-size: 16px;
+        }}
+        
+        .pane-content {{
+            flex: 1;
+            padding: 20px;
+            overflow-y: auto;
+        }}
+        
+        .action-form {{
+            background: white;
+            border: 1px solid #e0e0e0;
+            border-radius: 8px;
+            padding: 20px;
+            margin-bottom: 20px;
+        }}
+        
+        .form-group {{
+            margin-bottom: 15px;
+        }}
+        
+        .form-group label {{
+            display: block;
+            margin-bottom: 5px;
+            font-weight: 500;
+            color: #333;
+        }}
+        
+        .form-group input, .form-group textarea {{
+            width: 100%;
+            padding: 8px 12px;
+            border: 1px solid #ddd;
+            border-radius: 4px;
+            font-size: 14px;
+        }}
+        
+        .form-group input:focus, .form-group textarea:focus {{
+            outline: none;
+            border-color: #007bff;
+            box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
+        }}
+        
+        .btn {{
+            background: #007bff;
+            color: white;
+            border: none;
+            padding: 10px 20px;
+            border-radius: 4px;
+            cursor: pointer;
+            font-size: 14px;
+            margin-right: 10px;
+            margin-bottom: 10px;
+        }}
+        
+        .btn:hover {{
+            background: #0056b3;
+        }}
+        
+        .btn:disabled {{
+            background: #6c757d;
+            cursor: not-allowed;
+        }}
+        
+        .btn-secondary {{
+            background: #6c757d;
+        }}
+        
+        .btn-secondary:hover {{
+            background: #545b62;
+        }}
+        
+        .state-display {{
+            background: white;
+            border: 1px solid #e0e0e0;
+            border-radius: 8px;
+            padding: 15px;
+            margin-bottom: 20px;
+        }}
+        
+        .state-item {{
+            margin-bottom: 8px;
+        }}
+        
+        .state-label {{
+            font-weight: 500;
+            color: #666;
+        }}
+        
+        .state-value {{
+            color: #333;
+            font-family: monospace;
+        }}
+        
+        .logs-container {{
+            background: white;
+            border: 1px solid #e0e0e0;
+            border-radius: 8px;
+            padding: 15px;
+            max-height: 400px;
+            overflow-y: auto;
+        }}
+        
+        .log-entry {{
+            border-bottom: 1px solid #f0f0f0;
+            padding: 10px 0;
+        }}
+        
+        .log-entry:last-child {{
+            border-bottom: none;
+        }}
+        
+        .log-timestamp {{
+            font-size: 12px;
+            color: #666;
+            margin-bottom: 5px;
+        }}
+        
+        .log-action {{
+            background: #e3f2fd;
+            padding: 8px;
+            border-radius: 4px;
+            margin-bottom: 5px;
+            font-family: monospace;
+            font-size: 12px;
+        }}
+        
+        .log-observation {{
+            background: #f3e5f5;
+            padding: 8px;
+            border-radius: 4px;
+            font-family: monospace;
+            font-size: 12px;
+        }}
+        
+        .log-reward {{
+            font-weight: 600;
+            color: #28a745;
+        }}
+        
+        .log-done {{
+            font-weight: 600;
+            color: #dc3545;
+        }}
+        
+        .status-indicator {{
+            display: inline-block;
+            width: 8px;
+            height: 8px;
+            border-radius: 50%;
+            margin-right: 8px;
+        }}
+        
+        .status-connected {{
+            background: #28a745;
+        }}
+        
+        .status-disconnected {{
+            background: #dc3545;
+        }}
+        
+        .json-display {{
+            background: #f8f9fa;
+            border: 1px solid #e9ecef;
+            border-radius: 4px;
+            padding: 10px;
+            font-family: monospace;
+            font-size: 12px;
+            white-space: pre-wrap;
+            max-height: 200px;
+            overflow-y: auto;
+        }}
+    </style>
+</head>
+<body>
+    <div class="container">
+        <!-- Left Pane: HumanAgent Interface -->
+        <div class="left-pane">
+            <div class="pane-header">
+                <span class="status-indicator status-disconnected" id="connection-status"></span>
+                HumanAgent Interface
+            </div>
+            <div class="pane-content">
+                <!-- Action Form -->
+                <div class="action-form">
+                    <h3>Take Action</h3>
+                    <form id="action-form">
+                        {_generate_action_form_fields(action_fields)}
+                        <button type="submit" class="btn" id="step-btn">Step</button>
+                    </form>
+                </div>
+                
+                <!-- Control Buttons -->
+                <div style="margin-bottom: 20px;">
+                    <button class="btn btn-secondary" id="reset-btn">Reset Environment</button>
+                    <button class="btn btn-secondary" id="state-btn">Get State</button>
+                </div>
+                
+                <!-- Current State Display -->
+                <div class="state-display">
+                    <h3>Current State</h3>
+                    <div id="current-state">
+                        <div class="state-item">
+                            <span class="state-label">Status:</span>
+                            <span class="state-value" id="env-status">Not initialized</span>
+                        </div>
+                        <div class="state-item">
+                            <span class="state-label">Episode ID:</span>
+                            <span class="state-value" id="episode-id">-</span>
+                        </div>
+                        <div class="state-item">
+                            <span class="state-label">Step Count:</span>
+                            <span class="state-value" id="step-count">0</span>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+        
+        <!-- Right Pane: State Observer -->
+        <div class="right-pane">
+            <div class="pane-header">
+                State Observer
+            </div>
+            <div class="pane-content">
+                <!-- Current Observation -->
+                <div class="state-display">
+                    <h3>Current Observation</h3>
+                    <div id="current-observation" class="json-display">
+                        No observation yet
+                    </div>
+                </div>
+                
+                <!-- Action Logs -->
+                <div class="logs-container">
+                    <h3>Action History</h3>
+                    <div id="action-logs">
+                        No actions taken yet
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <script>
+        class OpenEnvWebInterface {{
+            constructor() {{
+                this.ws = null;
+                this.isConnected = false;
+                this.init();
+            }}
+            
+            init() {{
+                this.connectWebSocket();
+                this.setupEventListeners();
+            }}
+            
+            connectWebSocket() {{
+                const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+                const wsUrl = `${{protocol}}//${{window.location.host}}/ws`;
+                
+                this.ws = new WebSocket(wsUrl);
+                
+                this.ws.onopen = () => {{
+                    this.isConnected = true;
+                    this.updateConnectionStatus(true);
+                    console.log('WebSocket connected');
+                }};
+                
+                this.ws.onmessage = (event) => {{
+                    const data = JSON.parse(event.data);
+                    if (data.type === 'state_update') {{
+                        this.updateUI(data.episode_state);
+                    }}
+                }};
+                
+                this.ws.onclose = () => {{
+                    this.isConnected = false;
+                    this.updateConnectionStatus(false);
+                    console.log('WebSocket disconnected');
+                    // Attempt to reconnect after 3 seconds
+                    setTimeout(() => this.connectWebSocket(), 3000);
+                }};
+                
+                this.ws.onerror = (error) => {{
+                    console.error('WebSocket error:', error);
+                }};
+            }}
+            
+            setupEventListeners() {{
+                // Action form submission
+                document.getElementById('action-form').addEventListener('submit', (e) => {{
+                    e.preventDefault();
+                    this.submitAction();
+                }});
+                
+                // Reset button
+                document.getElementById('reset-btn').addEventListener('click', () => {{
+                    this.resetEnvironment();
+                }});
+                
+                // State button
+                document.getElementById('state-btn').addEventListener('click', () => {{
+                    this.getState();
+                }});
+            }}
+            
+            async submitAction() {{
+                const formData = new FormData(document.getElementById('action-form'));
+                const action = {{}};
+                
+                // Collect form data
+                for (const [key, value] of formData.entries()) {{
+                    if (value !== '') {{
+                        action[key] = value;
+                    }}
+                }}
+                
+                try {{
+                    const response = await fetch('/web/step', {{
+                        method: 'POST',
+                        headers: {{ 'Content-Type': 'application/json' }},
+                        body: JSON.stringify({{ action }})
+                    }});
+                    
+                    if (!response.ok) {{
+                        throw new Error(`HTTP error! status: ${{response.status}}`);
+                    }}
+                    
+                    const result = await response.json();
+                    console.log('Step result:', result);
+                }} catch (error) {{
+                    console.error('Error submitting action:', error);
+                    alert('Error submitting action: ' + error.message);
+                }}
+            }}
+            
+            async resetEnvironment() {{
+                try {{
+                    const response = await fetch('/web/reset', {{
+                        method: 'POST',
+                        headers: {{ 'Content-Type': 'application/json' }}
+                    }});
+                    
+                    if (!response.ok) {{
+                        throw new Error(`HTTP error! status: ${{response.status}}`);
+                    }}
+                    
+                    const result = await response.json();
+                    console.log('Reset result:', result);
+                }} catch (error) {{
+                    console.error('Error resetting environment:', error);
+                    alert('Error resetting environment: ' + error.message);
+                }}
+            }}
+            
+            async getState() {{
+                try {{
+                    const response = await fetch('/web/state');
+                    const state = await response.json();
+                    console.log('Current state:', state);
+                    alert('Current state: ' + JSON.stringify(state, null, 2));
+                }} catch (error) {{
+                    console.error('Error getting state:', error);
+                    alert('Error getting state: ' + error.message);
+                }}
+            }}
+            
+            updateConnectionStatus(connected) {{
+                const indicator = document.getElementById('connection-status');
+                if (connected) {{
+                    indicator.className = 'status-indicator status-connected';
+                }} else {{
+                    indicator.className = 'status-indicator status-disconnected';
+                }}
+            }}
+            
+            updateUI(episodeState) {{
+                // Update current state
+                document.getElementById('env-status').textContent = 
+                    episodeState.is_reset ? 'Reset' : 'Running';
+                document.getElementById('episode-id').textContent = 
+                    episodeState.episode_id || '-';
+                document.getElementById('step-count').textContent = 
+                    episodeState.step_count.toString();
+                
+                // Update current observation
+                const observationDiv = document.getElementById('current-observation');
+                if (episodeState.current_observation) {{
+                    observationDiv.textContent = JSON.stringify(
+                        episodeState.current_observation, null, 2
+                    );
+                }} else {{
+                    observationDiv.textContent = 'No observation yet';
+                }}
+                
+                // Update action logs
+                const logsDiv = document.getElementById('action-logs');
+                if (episodeState.action_logs.length === 0) {{
+                    logsDiv.innerHTML = 'No actions taken yet';
+                }} else {{
+                    logsDiv.innerHTML = episodeState.action_logs.map(log => `
+                        <div class="log-entry">
+                            <div class="log-timestamp">${{log.timestamp}} (Step ${{log.step_count}})</div>
+                            <div class="log-action">Action: ${{JSON.stringify(log.action, null, 2)}}</div>
+                            <div class="log-observation">Observation: ${{JSON.stringify(log.observation, null, 2)}}</div>
+                            <div>
+                                <span class="log-reward">Reward: ${{log.reward !== null ? log.reward : 'None'}}</span>
+                                ${{log.done ? '<span class="log-done">DONE</span>' : ''}}
+                            </div>
+                        </div>
+                    `).join('');
+                }}
+            }}
+        }}
+        
+        // Initialize the web interface when the page loads
+        document.addEventListener('DOMContentLoaded', () => {{
+            new OpenEnvWebInterface();
+        }});
+    </script>
+</body>
+</html>
+    """.replace('{_generate_action_form_fields(action_fields)}', _generate_action_form_fields(action_fields))
+
+
+def _generate_action_form_fields(action_fields: List[Dict[str, Any]]) -> str:
+    """Generate HTML form fields for action input."""
+    if not action_fields:
+        return '<p>No action fields available</p>'
+    
+    fields_html = []
+    for field in action_fields:
+        if field['type'] == 'checkbox':
+            fields_html.append(f'''
+                <div class="form-group">
+                    <label>
+                        <input type="checkbox" name="{field['name']}" value="true">
+                        {field['name']}
+                    </label>
+                </div>
+            ''')
+        elif field['type'] == 'text' and 'message' in field['name'].lower():
+            fields_html.append(f'''
+                <div class="form-group">
+                    <label for="{field['name']}">{field['name']}:</label>
+                    <textarea name="{field['name']}" id="{field['name']}" rows="3" placeholder="Enter {field['name']}..."></textarea>
+                </div>
+            ''')
+        else:
+            fields_html.append(f'''
+                <div class="form-group">
+                    <label for="{field['name']}">{field['name']}:</label>
+                    <input type="{field['type']}" name="{field['name']}" id="{field['name']}" placeholder="Enter {field['name']}..." {"required" if field['required'] else ""}>
+                </div>
+            ''')
+    
+    return '\n'.join(fields_html)

src/core/http_env_client.py

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

src/core/tools/__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.
+
+"""Core tools for code execution and other utilities."""
+
+from .local_python_executor import PyExecutor
+
+__all__ = ["PyExecutor"]

src/core/tools/local_python_executor.py

@@ -0,0 +1,105 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Local Python Executor.
+
+This module provides functionality for executing Python code locally by wrapping
+the smolagents LocalPythonExecutor.
+"""
+
+from smolagents import LocalPythonExecutor
+
+from core.env_server.types import CodeExecResult
+
+
+class PyExecutor:
+    """
+    Wrapper around smolagents LocalPythonExecutor for executing Python code.
+
+    This class provides a simple interface to execute Python code in a subprocess
+    and capture the results including stdout, stderr, and exit code.
+
+    Args:
+        additional_imports: List of additional module imports to authorize.
+                          For example: ["numpy", "pandas", "matplotlib"]
+                          These will be added to the base authorized imports.
+
+    Example:
+        >>> # Basic usage with default imports
+        >>> executor = PyExecutor()
+        >>> result = executor.run("print('Hello, World!')")
+        >>> print(result.stdout)  # "Hello, World!\n"
+        >>> print(result.exit_code)  # 0
+        >>>
+        >>> # Usage with additional imports
+        >>> executor = PyExecutor(additional_imports=["numpy", "pandas"])
+        >>> result = executor.run("import numpy as np\\nprint(np.array([1, 2, 3]))")
+        >>> print(result.stdout)  # "[1 2 3]\n"
+    """
+
+    def __init__(self, additional_imports: list[str] | None = None):
+        """
+        Initialize the PyExecutor with a LocalPythonExecutor instance.
+
+        Args:
+            additional_imports: List of additional module names to authorize for import.
+                              Defaults to an empty list if not provided.
+        """
+        if additional_imports is None:
+            additional_imports = []
+        self._executor = LocalPythonExecutor(
+            additional_authorized_imports=additional_imports
+        )
+        # Initialize tools to make BASE_PYTHON_TOOLS available (including print)
+        self._executor.send_tools({})
+
+    def run(self, code: str) -> CodeExecResult:
+        """
+        Execute Python code and return the result.
+
+        Args:
+            code: Python code string to execute
+
+        Returns:
+            CodeExecResult containing stdout, stderr, and exit_code
+
+        Example:
+            >>> executor = PyExecutor()
+            >>> result = executor.run("x = 5 + 3\\nprint(x)")
+            >>> print(result.stdout)  # "8\n"
+            >>> print(result.exit_code)  # 0
+            >>>
+            >>> # Error handling
+            >>> result = executor.run("1 / 0")
+            >>> print(result.exit_code)  # 1
+            >>> print(result.stderr)  # Contains error message
+        """
+        try:
+            # Execute the code using LocalPythonExecutor
+            # LocalPythonExecutor returns a CodeOutput object with output, logs, is_final_answer
+            exec_result = self._executor(code)
+
+            # Extract the logs (which contain print outputs) as stdout
+            # The output field contains the return value of the code
+            stdout = exec_result.logs
+            stderr = ""
+            exit_code = 0  # Success
+
+            return CodeExecResult(
+                stdout=stdout,
+                stderr=stderr,
+                exit_code=exit_code,
+            )
+
+        except Exception as e:
+            # LocalPythonExecutor raises InterpreterError for various issues
+            # (syntax errors, forbidden operations, runtime errors, etc.)
+            return CodeExecResult(
+                stdout="",
+                stderr=str(e),
+                exit_code=1,  # Non-zero indicates error
+            )

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

@@ -0,0 +1,335 @@
+# OpenSpiel Environment
+
+Integration of OpenSpiel games with the OpenEnv framework. OpenSpiel (https://github.com/google-deepmind/open_spiel) is DeepMind's collection of 70+ game environments for RL research.
+
+## Supported Games
+
+This environment supports 6 games across different categories:
+
+### Single-Player Games (No Opponent)
+1. **Catch** - Move horizontally to catch a falling ball
+2. **Cliff Walking** - Navigate grid without falling off cliff (Sutton & Barto benchmark)
+3. **2048** - Classic tile-merging puzzle game
+4. **Blackjack** - Simplified blackjack (HIT/STAND only)
+
+### Multi-Player Games (with Bot Opponent)
+5. **Tic-Tac-Toe** - Classic 3x3 game
+6. **Kuhn Poker** - 2-player simplified poker (game theory benchmark)
+
+## Architecture
+
+```
+┌────────────────────────────────────┐
+│ RL Training Code (Client)          │
+│   OpenSpielEnv.step(action)        │
+└──────────────┬─────────────────────┘
+               │ HTTP
+┌──────────────▼─────────────────────┐
+│ FastAPI Server (Docker)            │
+│   OpenSpielEnvironment             │
+│     ├─ Wraps rl_environment.Env    │
+│     ├─ Agent controls player 0     │
+│     └─ Opponent: Random/Fixed      │
+└────────────────────────────────────┘
+```
+
+## Installation & Usage
+
+### Option 1: Local Development (without Docker)
+
+**Requirements:**
+- OpenSpiel must be installed (see https://github.com/google-deepmind/open_spiel)
+- Python 3.11+
+
+```python
+from envs.openspiel_env import OpenSpielEnv, OpenSpielAction
+
+# Start local server manually
+# python -m envs.openspiel_env.server.app
+
+# Connect to local server
+env = OpenSpielEnv(base_url="http://localhost:8000")
+
+# Reset environment
+result = env.reset()
+print(f"Initial state: {result.observation.info_state}")
+print(f"Legal actions: {result.observation.legal_actions}")
+
+# Take actions
+for _ in range(10):
+    action_id = result.observation.legal_actions[0]  # Choose first legal action
+    result = env.step(OpenSpielAction(action_id=action_id))
+    print(f"Reward: {result.reward}, Done: {result.done}")
+    if result.done:
+        break
+
+# Cleanup
+env.close()
+```
+
+### Option 2: Docker (Recommended)
+
+**Build Docker image:**
+
+```bash
+cd OpenEnv
+docker build -f src/envs/openspiel_env/server/Dockerfile -t openspiel-env:latest .
+```
+
+**Run specific games:**
+
+```bash
+# Catch (default)
+docker run -p 8000:8000 openspiel-env:latest
+
+# Tic-Tac-Toe with random opponent
+docker run -p 8000:8000 -e OPENSPIEL_GAME=tic_tac_toe openspiel-env:latest
+
+# Kuhn Poker
+docker run -p 8000:8000 -e OPENSPIEL_GAME=kuhn_poker openspiel-env:latest
+
+# 2048
+docker run -p 8000:8000 -e OPENSPIEL_GAME=2048 openspiel-env:latest
+```
+
+**Use with from_docker_image():**
+
+```python
+from envs.openspiel_env import OpenSpielEnv, OpenSpielAction
+
+# Automatically starts container
+env = OpenSpielEnv.from_docker_image("openspiel-env:latest")
+
+result = env.reset()
+result = env.step(OpenSpielAction(action_id=0))
+
+env.close()  # Stops container
+```
+
+## Game-Specific Information
+
+### 1. Catch
+- **Type**: Single-player
+- **Action Space**: 3 actions (left, stay, right)
+- **Observation**: 5x5 grid flattened (25 dimensions)
+- **Reward**: +1 for catching ball, 0 otherwise
+- **Episode Length**: ~10 steps
+
+```python
+env = OpenSpielEnv.from_docker_image("openspiel-env:latest")
+# Or set OPENSPIEL_GAME=catch
+```
+
+### 2. Tic-Tac-Toe
+- **Type**: 2-player turn-based, perfect information
+- **Players**: Agent (X) vs Random Bot (O)
+- **Action Space**: 9 positions
+- **Observation**: 27 dimensions (3x3 board + game state)
+- **Reward**: +1 win, -1 loss, 0 draw/mid-game
+
+```python
+# Set environment variable or run directly
+docker run -p 8000:8000 -e OPENSPIEL_GAME=tic_tac_toe openspiel-env:latest
+```
+
+### 3. Kuhn Poker
+- **Type**: 2-player turn-based, imperfect information
+- **Players**: Agent vs Random Bot
+- **Action Space**: 2 actions (pass/fold, bet/call)
+- **Observation**: 6 dimensions (card + betting history)
+- **Reward**: Pot winnings (typically -1, 0, +1, +2)
+- **Notes**: THE benchmark for imperfect-information RL
+
+```python
+docker run -p 8000:8000 -e OPENSPIEL_GAME=kuhn_poker openspiel-env:latest
+```
+
+### 4. Cliff Walking
+- **Type**: Single-player grid world
+- **Action Space**: 4 actions (up, down, left, right)
+- **Observation**: Position encoding
+- **Reward**: -1 per step, -100 for falling off cliff
+- **Notes**: Classic RL benchmark from Sutton & Barto
+
+```python
+docker run -p 8000:8000 -e OPENSPIEL_GAME=cliff_walking openspiel-env:latest
+```
+
+### 5. 2048
+- **Type**: Single-player puzzle
+- **Action Space**: 4 actions (up, down, left, right)
+- **Observation**: 4x4 grid with tile values
+- **Reward**: Points from merging tiles
+- **Notes**: Stochastic tile spawning
+
+```python
+docker run -p 8000:8000 -e OPENSPIEL_GAME=2048 openspiel-env:latest
+```
+
+### 6. Blackjack
+- **Type**: Single-player vs dealer
+- **Action Space**: 2 actions (HIT, STAND)
+- **Observation**: Player hand + dealer's visible card
+- **Reward**: +1 win, -1 loss, 0 draw
+- **Notes**: Simplified version, no double/split
+
+```python
+docker run -p 8000:8000 -e OPENSPIEL_GAME=blackjack openspiel-env:latest
+```
+
+## Configuration
+
+### Environment Variables
+
+- `OPENSPIEL_GAME`: Game name (default: "catch")
+- `OPENSPIEL_AGENT_PLAYER`: Player ID for agent (default: 0)
+- `OPENSPIEL_OPPONENT_POLICY`: Opponent policy for multi-player games
+  - `random`: Uniform random (default)
+  - `first`: Always picks first legal action
+  - `last`: Always picks last legal action
+
+### Example: Tic-Tac-Toe with Fixed Opponent
+
+```bash
+docker run -p 8000:8000 \
+  -e OPENSPIEL_GAME=tic_tac_toe \
+  -e OPENSPIEL_OPPONENT_POLICY=first \
+  openspiel-env:latest
+```
+
+## API Reference
+
+### OpenSpielAction
+
+```python
+@dataclass
+class OpenSpielAction(Action):
+    action_id: int                      # Action to take
+    game_name: str = "catch"            # Game name
+    game_params: Dict[str, Any] = {}    # Optional game parameters
+```
+
+### OpenSpielObservation
+
+```python
+@dataclass
+class OpenSpielObservation(Observation):
+    info_state: List[float]             # Agent's information state
+    legal_actions: List[int]            # Legal action IDs
+    game_phase: str                     # "initial", "playing", "terminal"
+    current_player_id: int              # Current player (-1 for simultaneous)
+    opponent_last_action: Optional[int] # Last opponent action (if available)
+    done: bool                          # Episode finished
+    reward: Optional[float]             # Reward for last action
+```
+
+### OpenSpielState
+
+```python
+@dataclass
+class OpenSpielState(State):
+    episode_id: str                     # Unique episode ID
+    step_count: int                     # Number of steps
+    game_name: str                      # Game name
+    agent_player: int                   # Agent's player ID
+    opponent_policy: str                # Opponent policy name
+    num_players: int                    # Total players
+```
+
+## Testing
+
+### Automated Testing (All 6 Games)
+
+**Quick test of all games in Docker:**
+```bash
+./test_docker_all_games.sh
+```
+
+This automated script will:
+- Build and run Docker containers for each game
+- Test reset, step, and state APIs
+- Verify episode completion
+- Report pass/fail for all 6 games
+
+**Expected output:**
+```
+========================================
+OpenSpiel Docker Integration Test
+========================================
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Testing: catch
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  🐳 Starting Docker container...
+  ⏳ Waiting for server to be ready...
+  ✓ Server ready (2s)
+  🎮 Running Python client test...
+  ✓ PASSED - Episode completed successfully
+
+[... tests all 6 games ...]
+
+========================================
+Test Summary
+========================================
+
+  ✓ catch
+  ✓ tic_tac_toe
+  ✓ kuhn_poker
+  ✓ cliff_walking
+  ✓ 2048
+  ✓ blackjack
+
+Total: 6 passed, 0 failed out of 6 games
+
+========================================
+All tests PASSED! 🎉
+========================================
+```
+
+### Manual Testing
+
+```bash
+# Local (requires OpenSpiel installed)
+python -m pytest src/envs/openspiel_env/
+
+# Docker build
+docker build -f src/envs/openspiel_env/server/Dockerfile -t openspiel-env:latest .
+
+# Run specific game
+docker run -p 8000:8000 openspiel-env:latest
+
+# Test from another terminal
+python3 examples/openspiel_simple.py
+```
+
+## Development
+
+### Adding New Games
+
+To add support for more OpenSpiel games:
+
+1. Verify the game works with `rl_environment.Environment`
+2. Test with different opponent policies if multi-player
+3. Document game-specific configuration
+4. Add example script
+
+## Limitations
+
+- **Simultaneous-move games**: Only agent_player=0 supported
+- **Multi-agent training**: Single agent only (no self-play yet)
+- **Opponent policies**: Random and fixed only (no MCTS yet)
+- **Build time**: Docker image takes ~5-10 minutes to build (compiles C++)
+
+## Future Work
+
+- MCTS opponent policies
+- Self-play support (multiple agents)
+- More games (Chess, Go, Poker Hold'em)
+- Faster build with pre-built OpenSpiel base image
+- Game-specific reward shaping options
+
+## References
+
+- [OpenSpiel Paper (2019)](https://arxiv.org/abs/1908.09453)
+- [OpenSpiel GitHub](https://github.com/google-deepmind/open_spiel)
+- [OpenSpiel Documentation](https://openspiel.readthedocs.io/)

src/envs/openspiel_env/__init__.py

@@ -0,0 +1,26 @@
+# 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.
+
+"""
+OpenSpiel Environment Integration.
+
+This module provides integration between OpenSpiel games and the OpenEnv framework.
+OpenSpiel (https://github.com/google-deepmind/open_spiel) is DeepMind's collection
+of environments and algorithms for research in RL in games.
+
+Supported games:
+- Catch (1P)
+- Tic-Tac-Toe (2P)
+- Kuhn Poker (2P, imperfect info)
+- Cliff Walking (1P)
+- 2048 (1P)
+- Blackjack (1P)
+"""
+
+from .client import OpenSpielEnv
+from .models import OpenSpielAction, OpenSpielObservation, OpenSpielState
+
+__all__ = ["OpenSpielEnv", "OpenSpielAction", "OpenSpielObservation", "OpenSpielState"]

src/envs/openspiel_env/client.py

@@ -0,0 +1,114 @@
+# 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.
+
+"""
+OpenSpielEnv HTTP Client.
+
+This module provides the client for connecting to an OpenSpiel Environment server
+over HTTP.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, TYPE_CHECKING
+
+from core.http_env_client import HTTPEnvClient
+from core.types import StepResult
+
+from .models import OpenSpielAction, OpenSpielObservation, OpenSpielState
+
+if TYPE_CHECKING:
+    from core.containers.runtime import ContainerProvider
+
+
+class OpenSpielEnv(HTTPEnvClient[OpenSpielAction, OpenSpielObservation]):
+    """
+    HTTP client for OpenSpiel Environment.
+
+    This client connects to an OpenSpielEnvironment HTTP server and provides
+    methods to interact with it: reset(), step(), and state access.
+
+    Example:
+        >>> # Connect to a running server
+        >>> client = OpenSpielEnv(base_url="http://localhost:8000")
+        >>> result = client.reset()
+        >>> print(result.observation.info_state)
+        >>>
+        >>> # Take an action
+        >>> result = client.step(OpenSpielAction(action_id=1, game_name="catch"))
+        >>> print(result.observation.reward)
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = OpenSpielEnv.from_docker_image("openspiel-env:latest")
+        >>> result = client.reset()
+        >>> result = client.step(OpenSpielAction(action_id=0))
+    """
+
+    def _step_payload(self, action: OpenSpielAction) -> Dict[str, Any]:
+        """
+        Convert OpenSpielAction to JSON payload for step request.
+
+        Args:
+            action: OpenSpielAction instance.
+
+        Returns:
+            Dictionary representation suitable for JSON encoding.
+        """
+        return {
+            "action_id": action.action_id,
+            "game_name": action.game_name,
+            "game_params": action.game_params,
+        }
+
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[OpenSpielObservation]:
+        """
+        Parse server response into StepResult[OpenSpielObservation].
+
+        Args:
+            payload: JSON response from server.
+
+        Returns:
+            StepResult with OpenSpielObservation.
+        """
+        obs_data = payload.get("observation", {})
+
+        observation = OpenSpielObservation(
+            info_state=obs_data.get("info_state", []),
+            legal_actions=obs_data.get("legal_actions", []),
+            game_phase=obs_data.get("game_phase", "playing"),
+            current_player_id=obs_data.get("current_player_id", 0),
+            opponent_last_action=obs_data.get("opponent_last_action"),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            metadata=obs_data.get("metadata", {}),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> OpenSpielState:
+        """
+        Parse server response into OpenSpielState object.
+
+        Args:
+            payload: JSON response from /state endpoint.
+
+        Returns:
+            OpenSpielState object with environment state information.
+        """
+        return OpenSpielState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            game_name=payload.get("game_name", "unknown"),
+            agent_player=payload.get("agent_player", 0),
+            opponent_policy=payload.get("opponent_policy", "random"),
+            game_params=payload.get("game_params", {}),
+            num_players=payload.get("num_players", 1),
+        )

src/envs/openspiel_env/docker_issue.md

@@ -0,0 +1 @@
+# port issue? fix proxy?

src/envs/openspiel_env/models.py

@@ -0,0 +1,76 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Data models for OpenSpiel Environment.
+
+This module defines the Action, Observation, and State types for OpenSpiel games.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from core.env_server import Action, Observation, State
+
+
+@dataclass
+class OpenSpielAction(Action):
+    """
+    Action for OpenSpiel environments.
+
+    Attributes:
+        action_id: The integer action ID to take (from legal_actions).
+        game_name: Name of the OpenSpiel game (e.g., "catch", "tic_tac_toe").
+        game_params: Optional game-specific parameters (e.g., {"rows": 8, "columns": 6}).
+    """
+    action_id: int
+    game_name: str = "catch"
+    game_params: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class OpenSpielObservation(Observation):
+    """
+    Observation from OpenSpiel environment.
+
+    This represents what the agent sees after taking an action.
+    For single-player games, this is straightforward.
+    For multi-player games, this is from the perspective of the agent player.
+
+    Attributes:
+        info_state: Information state tensor (list of floats) for the agent.
+                   This contains all information available to the agent.
+        legal_actions: List of legal action IDs the agent can take.
+        game_phase: String describing the current phase (e.g., "playing", "terminal").
+        current_player_id: ID of the current player (-1 for simultaneous, player ID otherwise).
+        opponent_last_action: Last action taken by opponent (if available, None otherwise).
+    """
+    info_state: List[float]
+    legal_actions: List[int]
+    game_phase: str = "playing"
+    current_player_id: int = 0
+    opponent_last_action: Optional[int] = None
+
+
+@dataclass
+class OpenSpielState(State):
+    """
+    State for OpenSpiel environment.
+
+    Attributes:
+        game_name: Name of the OpenSpiel game.
+        agent_player: Which player ID the agent controls (0 by default).
+        opponent_policy: Name of the opponent policy ("random", "fixed", etc.).
+        game_params: Game-specific parameters.
+        num_players: Total number of players in the game.
+    """
+    game_name: str = "catch"
+    agent_player: int = 0
+    opponent_policy: str = "random"
+    game_params: Dict[str, Any] = field(default_factory=dict)
+    num_players: int = 1

src/envs/openspiel_env/server/Dockerfile

@@ -0,0 +1,85 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build for OpenSpiel + OpenEnv
+# Stage 1: Build OpenSpiel C++ bindings
+# Using Python 3.11 to match envtorch-base
+FROM python:3.11 AS openspiel-builder
+
+# Avoid interactive prompts during build
+ENV DEBIAN_FRONTEND=noninteractive
+ENV TZ=UTC
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    clang \
+    cmake \
+    curl \
+    git \
+    sudo \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set up OpenSpiel build directory
+RUN mkdir /repo
+WORKDIR /repo
+
+# Clone OpenSpiel
+RUN git clone https://github.com/google-deepmind/open_spiel.git .
+
+# Run OpenSpiel's installation script (downloads C++ dependencies)
+RUN ./install.sh
+
+# Install Python dependencies
+RUN pip3 install --no-cache-dir --upgrade setuptools testresources importlib_metadata
+RUN pip3 install --no-cache-dir --upgrade -r requirements.txt cmake
+
+# Build OpenSpiel with Python 3.11
+RUN mkdir -p build
+WORKDIR /repo/build
+RUN cmake -DPython3_EXECUTABLE=$(which python3) -DCMAKE_CXX_COMPILER=$(which clang++) ../open_spiel
+RUN make -j$(nproc) pyspiel
+
+# Stage 2: Runtime image using published openenv-base
+# Uses the standardized base image from GitHub Container Registry
+# See: https://github.com/meta-pytorch/OpenEnv/pkgs/container/openenv-base
+FROM ghcr.io/meta-pytorch/openenv-base:latest
+
+# Copy OpenSpiel build artifacts from builder
+RUN mkdir -p /repo
+COPY --from=openspiel-builder /repo /repo
+
+# Install OpenSpiel Python requirements in runtime
+WORKDIR /repo
+RUN pip3 install --no-cache-dir --upgrade -r requirements.txt
+
+# Set Python path for OpenSpiel
+ENV PYTHONPATH=/repo:/repo/build/python:${PYTHONPATH}
+
+# Copy OpenEnv core (base image already set WORKDIR=/app)
+WORKDIR /app
+COPY src/core/ /app/src/core/
+
+# Copy OpenSpiel environment
+COPY src/envs/openspiel_env/ /app/src/envs/openspiel_env/
+
+# Extend Python path for OpenEnv (base image set PYTHONPATH=/app/src)
+# We prepend OpenSpiel paths
+ENV PYTHONPATH=/repo:/repo/build/python:/app/src
+
+# OpenSpiel-specific environment variables (can be overridden at runtime)
+ENV OPENSPIEL_GAME=catch
+ENV OPENSPIEL_AGENT_PLAYER=0
+ENV OPENSPIEL_OPPONENT_POLICY=random
+
+# Health check (curl is provided by envtorch-base)
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Note: EXPOSE 8000 already set by envtorch-base
+
+# Run the FastAPI server (uvicorn installed by envtorch-base)
+CMD ["uvicorn", "envs.openspiel_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

src/envs/openspiel_env/server/__init__.py

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

src/envs/openspiel_env/server/app.py

@@ -0,0 +1,55 @@
+# 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 OpenSpiel Environment.
+
+This module creates an HTTP server that exposes OpenSpiel games
+over HTTP endpoints, making them compatible with HTTPEnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn envs.openspiel_env.server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn envs.openspiel_env.server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    python -m envs.openspiel_env.server.app
+
+Environment variables:
+    OPENSPIEL_GAME: Game name to serve (default: "catch")
+    OPENSPIEL_AGENT_PLAYER: Agent player ID (default: 0)
+    OPENSPIEL_OPPONENT_POLICY: Opponent policy (default: "random")
+"""
+
+import os
+
+from core.env_server import create_app
+
+from ..models import OpenSpielAction, OpenSpielObservation
+from .openspiel_environment import OpenSpielEnvironment
+
+# Get game configuration from environment variables
+game_name = os.getenv("OPENSPIEL_GAME", "catch")
+agent_player = int(os.getenv("OPENSPIEL_AGENT_PLAYER", "0"))
+opponent_policy = os.getenv("OPENSPIEL_OPPONENT_POLICY", "random")
+
+# Create the environment instance
+env = OpenSpielEnvironment(
+    game_name=game_name,
+    agent_player=agent_player,
+    opponent_policy=opponent_policy,
+)
+
+# Create the FastAPI app with routes
+app = create_app(env, OpenSpielAction, OpenSpielObservation)
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)

src/envs/openspiel_env/server/build_docker.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# 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.
+
+# Script to build the OpenSpiel environment Docker image
+# Usage: ./build_docker.sh [tag]
+#
+# Note: Requires envtorch-base:latest to be built first.
+# See: src/core/containers/images/README.md
+
+set -e
+
+TAG="${1:-latest}"
+IMAGE_NAME="openspiel-env:${TAG}"
+
+echo "🐳 Building OpenSpiel Environment Docker Image"
+echo "================================================"
+echo "Image: $IMAGE_NAME"
+echo ""
+
+# Get script directory
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+# Navigate to OpenEnv root (4 levels up from server/)
+OPENENV_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+
+echo "📁 OpenEnv root: $OPENENV_ROOT"
+echo ""
+
+# Build OpenSpiel environment image
+# Note: Docker will automatically pull ghcr.io/meta-pytorch/openenv-base:latest if needed
+echo "⏳ Building (this may take 5-10 minutes due to OpenSpiel compilation)..."
+docker build \
+    -f "$SCRIPT_DIR/Dockerfile" \
+    -t "$IMAGE_NAME" \
+    "$OPENENV_ROOT"
+
+if [ $? -eq 0 ]; then
+    echo ""
+    echo "✅ Build successful!"
+    echo ""
+    echo "🚀 Run with different games:"
+    echo ""
+    echo "  # Catch (default)"
+    echo "  docker run -p 8000:8000 $IMAGE_NAME"
+    echo ""
+    echo "  # Tic-Tac-Toe"
+    echo "  docker run -p 8000:8000 -e OPENSPIEL_GAME=tic_tac_toe $IMAGE_NAME"
+    echo ""
+    echo "  # Kuhn Poker"
+    echo "  docker run -p 8000:8000 -e OPENSPIEL_GAME=kuhn_poker $IMAGE_NAME"
+    echo ""
+    echo "  # Cliff Walking"
+    echo "  docker run -p 8000:8000 -e OPENSPIEL_GAME=cliff_walking $IMAGE_NAME"
+    echo ""
+    echo "  # 2048"
+    echo "  docker run -p 8000:8000 -e OPENSPIEL_GAME=2048 $IMAGE_NAME"
+    echo ""
+    echo "  # Blackjack"
+    echo "  docker run -p 8000:8000 -e OPENSPIEL_GAME=blackjack $IMAGE_NAME"
+    echo ""
+else
+    echo ""
+    echo "❌ Build failed!"
+    exit 1
+fi

src/envs/openspiel_env/server/openspiel_environment.py

@@ -0,0 +1,266 @@
+# 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.
+
+"""
+OpenSpiel Environment Server Implementation.
+
+This module wraps OpenSpiel's rl_environment.Environment and exposes it
+via the OpenEnv Environment interface.
+"""
+
+import uuid
+from typing import Any, Dict
+
+from core.env_server import Action, Environment, Observation
+
+from ..models import OpenSpielAction, OpenSpielObservation, OpenSpielState
+from .opponent_policies import get_opponent_policy, OpponentPolicy
+
+# Import OpenSpiel
+try:
+    from open_spiel.python import rl_environment
+    import pyspiel
+except ImportError as e:
+    raise ImportError(
+        "OpenSpiel is not installed. "
+        "Please install it following instructions at: "
+        "https://github.com/google-deepmind/open_spiel"
+    ) from e
+
+
+class OpenSpielEnvironment(Environment):
+    """
+    OpenSpiel Environment wrapper for OpenEnv.
+
+    This environment wraps OpenSpiel games and provides a single-agent interface.
+    For multi-player games, the agent controls one player while opponent(s) use
+    a fixed policy (e.g., random).
+
+    Supported games:
+    - Single-player: catch, cliff_walking, 2048, blackjack
+    - Multi-player: tic_tac_toe, kuhn_poker
+
+    Args:
+        game_name: Name of the OpenSpiel game (e.g., "catch", "tic_tac_toe").
+        agent_player: Which player ID the agent controls (default 0).
+        opponent_policy: Policy for opponent players ("random", "first", etc.).
+        game_params: Optional game-specific parameters.
+
+    Example:
+        >>> env = OpenSpielEnvironment("catch")
+        >>> obs = env.reset()
+        >>> print(obs.info_state)  # Agent's observation
+        >>> obs = env.step(OpenSpielAction(action_id=1))
+        >>> print(obs.reward)
+    """
+
+    def __init__(
+        self,
+        game_name: str = "catch",
+        agent_player: int = 0,
+        opponent_policy: str = "random",
+        game_params: Dict[str, Any] | None = None,
+    ):
+        """Initialize OpenSpiel environment."""
+        super().__init__()
+
+        self.game_name = game_name
+        self.agent_player = agent_player
+        self.game_params = game_params or {}
+
+        # Create OpenSpiel environment
+        try:
+            self._ospiel_env = rl_environment.Environment(
+                game_name, **self.game_params
+            )
+        except Exception as e:
+            raise ValueError(
+                f"Failed to create OpenSpiel game '{game_name}': {e}"
+            ) from e
+
+        self.num_players = self._ospiel_env.num_players
+        self.is_turn_based = self._ospiel_env.is_turn_based
+
+        # Validate agent_player
+        if agent_player >= self.num_players:
+            raise ValueError(
+                f"agent_player={agent_player} >= num_players={self.num_players}"
+            )
+
+        # Set up opponent policy for multi-player games
+        self.opponent_policy_fn: OpponentPolicy | None = None
+        if self.num_players > 1:
+            self.opponent_policy_fn = get_opponent_policy(opponent_policy)
+
+        # Initialize state
+        self._state = OpenSpielState(
+            game_name=game_name,
+            agent_player=agent_player,
+            opponent_policy=opponent_policy,
+            game_params=self.game_params,
+            num_players=self.num_players,
+        )
+
+        # Track last opponent action for learning
+        self._last_opponent_action: int | None = None
+
+    def reset(self) -> Observation:
+        """
+        Reset the environment and return initial observation.
+
+        For multi-player games, this will auto-play opponent turns until
+        it's the agent's turn (or terminal state).
+
+        Returns:
+            Initial observation for the agent.
+        """
+        # Reset OpenSpiel environment
+        time_step = self._ospiel_env.reset()
+
+        # Reset state tracking
+        self._state.episode_id = str(uuid.uuid4())
+        self._state.step_count = 0
+        self._last_opponent_action = None
+
+        # Auto-play opponent turns until agent's turn
+        time_step = self._auto_play_opponents(time_step)
+
+        # Convert to OpenEnv observation
+        return self._make_observation(time_step)
+
+    def step(self, action: Action) -> Observation:
+        """
+        Execute agent's action and return resulting observation.
+
+        For multi-player games, this will:
+        1. Apply the agent's action
+        2. Auto-play opponent turns until it's the agent's turn again
+        3. Return the observation from the agent's perspective
+
+        Args:
+            action: OpenSpielAction containing the action_id to execute.
+
+        Returns:
+            Observation after action execution (and opponent turns if multi-player).
+
+        Raises:
+            ValueError: If action is not an OpenSpielAction.
+        """
+        if not isinstance(action, OpenSpielAction):
+            raise ValueError(f"Expected OpenSpielAction, got {type(action)}")
+
+        # Apply agent's action
+        if self.is_turn_based:
+            # Turn-based: single action
+            time_step = self._ospiel_env.step([action.action_id])
+        else:
+            # Simultaneous-move: need actions for all players
+            # For now, only support agent as player 0 in simultaneous games
+            if self.agent_player != 0:
+                raise NotImplementedError(
+                    "Simultaneous-move games only support agent_player=0"
+                )
+            # Get opponent actions
+            opponent_actions = []
+            for player_id in range(self.num_players):
+                if player_id == self.agent_player:
+                    opponent_actions.append(action.action_id)
+                else:
+                    legal_actions = time_step.observations["legal_actions"][player_id]
+                    opp_action = self.opponent_policy_fn.select_action(
+                        legal_actions, time_step.observations
+                    )
+                    opponent_actions.append(opp_action)
+            time_step = self._ospiel_env.step(opponent_actions)
+
+        self._state.step_count += 1
+
+        # Auto-play opponent turns (for turn-based games)
+        if self.is_turn_based:
+            time_step = self._auto_play_opponents(time_step)
+
+        # Convert to OpenEnv observation
+        return self._make_observation(time_step)
+
+    @property
+    def state(self) -> OpenSpielState:
+        """Get current environment state."""
+        return self._state
+
+    def _auto_play_opponents(self, time_step) -> Any:
+        """
+        Auto-play opponent turns until it's the agent's turn or game is terminal.
+
+        Args:
+            time_step: Current TimeStep from OpenSpiel environment.
+
+        Returns:
+            Updated TimeStep after opponent moves.
+        """
+        # Single-player games: nothing to do
+        if self.num_players == 1:
+            return time_step
+
+        # Multi-player games: play opponent turns
+        while (
+            not time_step.last()
+            and time_step.observations["current_player"] != self.agent_player
+        ):
+            current_player = time_step.observations["current_player"]
+            legal_actions = time_step.observations["legal_actions"][current_player]
+
+            # Select opponent action
+            opp_action = self.opponent_policy_fn.select_action(
+                legal_actions, time_step.observations
+            )
+            self._last_opponent_action = opp_action
+
+            # Apply opponent action
+            time_step = self._ospiel_env.step([opp_action])
+            self._state.step_count += 1
+
+        return time_step
+
+    def _make_observation(self, time_step) -> OpenSpielObservation:
+        """
+        Convert OpenSpiel TimeStep to OpenEnv Observation.
+
+        Args:
+            time_step: OpenSpiel TimeStep object.
+
+        Returns:
+            OpenSpielObservation for the agent.
+        """
+        # Extract agent's information
+        info_state = time_step.observations["info_state"][self.agent_player]
+        legal_actions = time_step.observations["legal_actions"][self.agent_player]
+        current_player_id = time_step.observations["current_player"]
+
+        # Determine game phase
+        if time_step.last():
+            game_phase = "terminal"
+        elif time_step.first():
+            game_phase = "initial"
+        else:
+            game_phase = "playing"
+
+        # Get reward for agent
+        reward = None
+        if time_step.rewards is not None:
+            reward = float(time_step.rewards[self.agent_player])
+
+        # Create observation
+        obs = OpenSpielObservation(
+            info_state=info_state.tolist() if hasattr(info_state, "tolist") else list(info_state),
+            legal_actions=legal_actions,
+            game_phase=game_phase,
+            current_player_id=current_player_id,
+            opponent_last_action=self._last_opponent_action,
+            done=time_step.last(),
+            reward=reward,
+        )
+
+        return obs

src/envs/openspiel_env/server/opponent_policies.py

@@ -0,0 +1,90 @@
+# 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.
+
+"""
+Opponent policies for multi-player OpenSpiel games.
+
+These policies are used to control non-agent players in multi-player games,
+allowing single-agent RL training against fixed or adaptive opponents.
+"""
+
+import random
+from typing import Any, Protocol
+
+
+class OpponentPolicy(Protocol):
+    """Protocol for opponent policies."""
+
+    def select_action(self, legal_actions: list[int], observations: dict[str, Any]) -> int:
+        """
+        Select an action for the opponent.
+
+        Args:
+            legal_actions: List of legal action IDs.
+            observations: Current observations from the environment.
+
+        Returns:
+            Selected action ID.
+        """
+        ...
+
+
+class RandomOpponent:
+    """Random opponent that selects uniformly from legal actions."""
+
+    def select_action(self, legal_actions: list[int], observations: dict[str, Any]) -> int:
+        """Select a random legal action."""
+        if not legal_actions:
+            raise ValueError("No legal actions available")
+        return random.choice(legal_actions)
+
+
+class FixedActionOpponent:
+    """Opponent that always selects the same action (e.g., first legal action)."""
+
+    def __init__(self, action_selector: str = "first"):
+        """
+        Initialize fixed action opponent.
+
+        Args:
+            action_selector: Which action to select ("first", "last", "middle").
+        """
+        self.action_selector = action_selector
+
+    def select_action(self, legal_actions: list[int], observations: dict[str, Any]) -> int:
+        """Select a fixed legal action based on selector."""
+        if not legal_actions:
+            raise ValueError("No legal actions available")
+
+        if self.action_selector == "first":
+            return legal_actions[0]
+        elif self.action_selector == "last":
+            return legal_actions[-1]
+        elif self.action_selector == "middle":
+            return legal_actions[len(legal_actions) // 2]
+        else:
+            return legal_actions[0]
+
+
+def get_opponent_policy(policy_name: str) -> OpponentPolicy:
+    """
+    Get an opponent policy by name.
+
+    Args:
+        policy_name: Name of the policy ("random", "first", "last", "middle").
+
+    Returns:
+        OpponentPolicy instance.
+
+    Raises:
+        ValueError: If policy_name is not recognized.
+    """
+    if policy_name == "random":
+        return RandomOpponent()
+    elif policy_name in ("first", "last", "middle"):
+        return FixedActionOpponent(action_selector=policy_name)
+    else:
+        raise ValueError(f"Unknown opponent policy: {policy_name}")

src/envs/openspiel_env/test_docker_all_games.sh

@@ -0,0 +1,152 @@
+#!/bin/bash
+# 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.
+
+# Automated test script for all OpenSpiel games in Docker
+# Usage: ./test_docker_all_games.sh
+
+set -e
+
+# Colors for output
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+IMAGE_NAME="openspiel-env:latest"
+CONTAINER_NAME="openspiel-test"
+PORT=8000
+HEALTH_CHECK_URL="http://localhost:${PORT}/health"
+MAX_WAIT=30
+
+# Games to test
+GAMES=("catch" "tic_tac_toe" "kuhn_poker" "cliff_walking" "2048" "blackjack")
+
+# Results tracking
+declare -a RESULTS
+PASSED=0
+FAILED=0
+
+echo -e "${BLUE}========================================${NC}"
+echo -e "${BLUE}OpenSpiel Docker Integration Test${NC}"
+echo -e "${BLUE}========================================${NC}"
+echo ""
+
+# Function to cleanup containers
+cleanup() {
+    echo -e "${YELLOW}Cleaning up containers...${NC}"
+    docker stop ${CONTAINER_NAME} 2>/dev/null || true
+    docker rm ${CONTAINER_NAME} 2>/dev/null || true
+}
+
+# Function to wait for server health
+wait_for_health() {
+    local game=$1
+    echo -e "  ⏳ Waiting for server to be ready..."
+
+    for i in $(seq 1 $MAX_WAIT); do
+        if curl -s -f ${HEALTH_CHECK_URL} > /dev/null 2>&1; then
+            echo -e "  ${GREEN}✓${NC} Server ready (${i}s)"
+            return 0
+        fi
+        sleep 1
+    done
+
+    echo -e "  ${RED}✗${NC} Server health check failed after ${MAX_WAIT}s"
+    return 1
+}
+
+# Function to test a game
+test_game() {
+    local game=$1
+    echo -e "\n${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo -e "${BLUE}Testing: ${game}${NC}"
+    echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+    # Stop any existing container
+    cleanup
+
+    # Start container with game
+    echo -e "  🐳 Starting Docker container..."
+    docker run -d \
+        --name ${CONTAINER_NAME} \
+        -p ${PORT}:8000 \
+        -e OPENSPIEL_GAME=${game} \
+        ${IMAGE_NAME} > /dev/null
+
+    # Wait for server to be ready
+    if ! wait_for_health ${game}; then
+        echo -e "  ${RED}✗ FAILED${NC} - Server did not start"
+        RESULTS+=("${game}:FAILED:Server did not start")
+        FAILED=$((FAILED + 1))
+        cleanup
+        return 1
+    fi
+
+    # Run Python client test
+    echo -e "  🎮 Running Python client test..."
+    if NO_PROXY=localhost,127.0.0.1 HTTP_PROXY= HTTPS_PROXY= \
+       PYTHONPATH=$PWD/src:$PYTHONPATH \
+       python3 examples/openspiel_simple.py > /tmp/test_${game}.log 2>&1; then
+
+        # Check if episode completed successfully
+        if grep -q "Episode finished!" /tmp/test_${game}.log; then
+            echo -e "  ${GREEN}✓ PASSED${NC} - Episode completed successfully"
+            RESULTS+=("${game}:PASSED")
+            PASSED=$((PASSED + 1))
+        else
+            echo -e "  ${RED}✗ FAILED${NC} - Episode did not complete"
+            RESULTS+=("${game}:FAILED:Episode incomplete")
+            FAILED=$((FAILED + 1))
+        fi
+    else
+        echo -e "  ${RED}✗ FAILED${NC} - Python client error"
+        RESULTS+=("${game}:FAILED:Client error")
+        FAILED=$((FAILED + 1))
+    fi
+
+    # Cleanup
+    cleanup
+}
+
+# Run tests for all games
+for game in "${GAMES[@]}"; do
+    test_game ${game}
+done
+
+# Print summary
+echo -e "\n${BLUE}========================================${NC}"
+echo -e "${BLUE}Test Summary${NC}"
+echo -e "${BLUE}========================================${NC}"
+echo ""
+
+for result in "${RESULTS[@]}"; do
+    IFS=':' read -r game status message <<< "$result"
+    if [ "$status" == "PASSED" ]; then
+        echo -e "  ${GREEN}✓${NC} ${game}"
+    else
+        echo -e "  ${RED}✗${NC} ${game} - ${message}"
+    fi
+done
+
+echo ""
+echo -e "Total: ${PASSED} passed, ${FAILED} failed out of ${#GAMES[@]} games"
+echo ""
+
+# Exit with appropriate code
+if [ $FAILED -eq 0 ]; then
+    echo -e "${GREEN}========================================${NC}"
+    echo -e "${GREEN}All tests PASSED! 🎉${NC}"
+    echo -e "${GREEN}========================================${NC}"
+    exit 0
+else
+    echo -e "${RED}========================================${NC}"
+    echo -e "${RED}Some tests FAILED${NC}"
+    echo -e "${RED}========================================${NC}"
+    exit 1
+fi