Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* 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
+assets/unity_3dball.gif filter=lfs diff=lfs merge=lfs -text
+assets/unity_pushblock.gif filter=lfs diff=lfs merge=lfs -text
+envs/unity_env/assets/unity_3dball.gif filter=lfs diff=lfs merge=lfs -text
+envs/unity_env/assets/unity_pushblock.gif filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,44 @@
+# Unity ML-Agents cache (binaries are downloaded here)
+.mlagents-cache/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# ml-agents source (when developing locally)
+ml-agents/

Dockerfile

@@ -0,0 +1,68 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build for Unity ML-Agents environment
+# Uses pip for package installation (no virtual environment)
+# Note: Using Python 3.10.12 specifically because ml-agents requires >=3.10.1,<=3.10.12
+# Note: Unity binaries are x86_64 only, so we force linux/amd64 platform
+
+FROM --platform=linux/amd64 python:3.10.12-slim AS builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy environment code
+COPY . /app/env
+
+WORKDIR /app/env
+
+# Install dependencies using pip
+# Note: mlagents packages are installed from git source via pyproject.toml
+RUN pip install --upgrade pip && \
+    pip install --no-cache-dir -e .
+
+# Final runtime stage
+FROM --platform=linux/amd64 python:3.10.12-slim
+
+WORKDIR /app
+
+# Install runtime dependencies (curl for healthcheck)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy installed packages from builder
+COPY --from=builder /usr/local/lib/python3.10/site-packages /usr/local/lib/python3.10/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy the environment code
+COPY . /app/env
+
+# Create cache directory for Unity binaries
+RUN mkdir -p /root/.mlagents-cache
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=60s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Note: Longer start period (60s) because Unity environment download may take time on first run
+
+# Run the FastAPI server
+# Note: workers=1 because Unity environments are not thread-safe
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]
+
+ENV ENABLE_WEB_INTERFACE=true

README.md

@@ -1,10 +1,635 @@
 ---
-title: Unity Env-v2-1-0
-emoji: 🏆
-colorFrom: indigo
-colorTo: yellow
+title: Unity Environment Server
+emoji: 🌐
+colorFrom: blue
+colorTo: green
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+  - Unity
+  - MlAgents
+  - MlAgentsUnity
+  - MlAgentsEnv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Hugging Face Space Deployment
+
+This Space is built from OpenEnv environment `unity_env`.
+
+- Space URL: `https://huggingface.co/spaces/openenv/unity_env-v2-1-0`
+- OpenEnv pinned ref: `v2.1.0`
+- Hub tag: `openenv`
+
+### Connecting from Code
+
+```python
+from envs.unity_env import Env
+
+env = Env(base_url="https://huggingface.co/spaces/openenv/unity_env-v2-1-0")
+```
+
+<!--
+Copyright (c) Meta Platforms, Inc. and affiliates.
+All rights reserved.
+This source code is licensed under the BSD-style license found in the
+LICENSE file in the root directory of this source tree.
+-->
+
+
+# Unity ML-Agents Environment
+
+OpenEnv wrapper for [Unity ML-Agents](https://github.com/Unity-Technologies/ml-agents) environments. This environment provides access to Unity's reinforcement learning environments through a standardized HTTP/WebSocket interface.
+
+<div align="center">
+  <img src="assets/unity_pushblock.gif" alt="PushBlock" width="400"/>
+  <img src="assets/unity_3dball.gif" alt="3DBall" width="400"/>
+</div>
+
+## Supported Environments
+
+| Environment | Action Type | Description |
+|------------|-------------|-------------|
+| **PushBlock** | Discrete (7) | Push a block to a goal position |
+| **3DBall** | Continuous (2) | Balance a ball on a platform |
+| **3DBallHard** | Continuous (2) | Harder version of 3DBall |
+| **GridWorld** | Discrete (5) | Navigate a grid to find goals |
+| **Basic** | Discrete (3) | Simple left/right movement |
+
+More environments may be available depending on the ML-Agents registry version.
+
+## Installation
+
+### Option 1: Non-Docker Installation (Local Development)
+
+#### Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+#### Install from OpenEnv Repository
+
+```bash
+# Clone the OpenEnv repository (if not already done)
+git clone https://github.com/your-org/OpenEnv.git
+cd OpenEnv
+
+# Install the unity_env package with dependencies
+cd envs/unity_env
+uv pip install -e .
+
+# Or with pip
+pip install -e .
+```
+
+#### Install Dependencies Only
+
+```bash
+cd envs/unity_env
+
+# Using uv (recommended)
+uv sync
+
+# Or using pip
+pip install -r requirements.txt  # if available
+pip install mlagents-envs numpy pillow fastapi uvicorn pydantic
+```
+
+#### Verify Installation
+
+```bash
+# Test the installation
+cd envs/unity_env
+python -c "from client import UnityEnv; print('Installation successful!')"
+```
+
+**Note:** The first run will download Unity environment binaries (~500MB). These are cached in `~/.mlagents-cache/` for future use.
+
+### Option 2: Docker Installation
+
+#### Prerequisites
+
+- Docker installed and running
+- Python 3.10+ (for running the client)
+
+#### Build the Docker Image
+
+```bash
+cd envs/unity_env
+
+# Build the Docker image
+docker build -f server/Dockerfile -t unity-env:latest .
+
+# Verify the build
+docker images | grep unity-env
+```
+
+**Note for Apple Silicon (M1/M2/M3/M4) users:** Docker mode is **not supported** on Apple Silicon because Unity's Mono runtime crashes under x86_64 emulation. Use **direct mode** (`--direct`) or **server mode** (`--url`) instead, which run native macOS binaries. See [Troubleshooting](#docker-mode-fails-on-apple-silicon-m1m2m3m4) for details.
+
+#### Run the Docker Container
+
+```bash
+# Run with default settings (graphics enabled, 800x600)
+docker run -p 8000:8000 unity-env:latest
+
+# Run with custom settings
+docker run -p 8000:8000 \
+  -e UNITY_NO_GRAPHICS=0 \
+  -e UNITY_WIDTH=1280 \
+  -e UNITY_HEIGHT=720 \
+  -e UNITY_TIME_SCALE=1.0 \
+  unity-env:latest
+
+# Run in headless mode (faster for training)
+docker run -p 8000:8000 \
+  -e UNITY_NO_GRAPHICS=1 \
+  -e UNITY_TIME_SCALE=20 \
+  unity-env:latest
+
+# Run with persistent cache (avoid re-downloading binaries)
+docker run -p 8000:8000 \
+  -v ~/.mlagents-cache:/root/.mlagents-cache \
+  unity-env:latest
+```
+
+#### Install Client Dependencies
+
+To connect to the Docker container, install the client on your host machine:
+
+```bash
+cd envs/unity_env
+pip install requests websockets
+```
+
+## Quick Start
+
+### Option 1: Direct Mode (Fastest for Testing)
+
+Run the Unity environment directly without a server:
+
+```bash
+# From the OpenEnv repository root:
+
+# Run with graphics (default: 1280x720)
+python examples/unity_simple.py --direct
+
+# Run with custom window size
+python examples/unity_simple.py --direct --width 800 --height 600
+
+# Run headless (faster for training)
+python examples/unity_simple.py --direct --no-graphics --time-scale 20
+
+# Run 3DBall environment
+python examples/unity_simple.py --direct --env 3DBall --episodes 5
+```
+
+### Option 2: Server Mode
+
+Start the server and connect with a client:
+
+```bash
+# Terminal 1: Start the server (graphics enabled by default)
+cd envs/unity_env
+uv run uvicorn server.app:app --host 0.0.0.0 --port 8000
+
+# Terminal 2: Run the example client (from repo root)
+python examples/unity_simple.py --url http://localhost:8000
+python examples/unity_simple.py --url http://localhost:8000 --env 3DBall --episodes 5
+```
+
+### Option 3: Docker Mode
+
+Run via Docker container (auto-starts and connects):
+
+```bash
+# Build the Docker image first
+cd envs/unity_env
+docker build -f server/Dockerfile -t unity-env:latest .
+
+# Run examples from repo root:
+cd ../..
+
+# Run with default settings
+python examples/unity_simple.py --docker
+
+# Run with custom window size
+python examples/unity_simple.py --docker --width 1280 --height 720
+
+# Run headless (faster for training)
+python examples/unity_simple.py --docker --no-graphics --time-scale 20
+
+# Run 3DBall for 10 episodes
+python examples/unity_simple.py --docker --env 3DBall --episodes 10
+
+# Use a custom Docker image
+python examples/unity_simple.py --docker --docker-image my-unity-env:v1
+```
+
+## Example Scripts
+
+### Basic Usage Examples
+
+#### 1. Direct Mode - Quick Testing
+
+```bash
+# Run PushBlock with graphics (default)
+python examples/unity_simple.py --direct
+
+# Output:
+# ============================================================
+# Unity ML-Agents Environment - Direct Mode
+# ============================================================
+# Environment: PushBlock
+# Episodes: 3
+# Max steps: 500
+# Window size: 1280x720
+# Graphics: Enabled
+# ...
+```
+
+#### 2. Direct Mode - Training Configuration
+
+```bash
+# Headless mode with fast simulation (20x speed)
+python examples/unity_simple.py --direct --no-graphics --time-scale 20 --episodes 10 --max-steps 1000
+
+# This is ideal for training - no graphics overhead, faster simulation
+```
+
+#### 3. Direct Mode - 3DBall with Custom Window
+
+```bash
+# Run 3DBall (continuous actions) with larger window
+python examples/unity_simple.py --direct --env 3DBall --width 1280 --height 720 --episodes 5
+```
+
+#### 4. Docker Mode - Production-like Testing
+
+```bash
+# Build the image first
+cd envs/unity_env
+docker build -f server/Dockerfile -t unity-env:latest .
+
+# Run via Docker with graphics
+python examples/unity_simple.py --docker --width 1280 --height 720
+
+# Run via Docker in headless mode for training
+python examples/unity_simple.py --docker --no-graphics --time-scale 20 --episodes 20
+```
+
+#### 5. Server Mode - Separate Server and Client
+
+```bash
+# Terminal 1: Start server with specific settings
+UNITY_WIDTH=1280 UNITY_HEIGHT=720 uv run uvicorn server.app:app --port 8000
+
+# Terminal 2: Connect and run episodes
+python examples/unity_simple.py --url http://localhost:8000 --env PushBlock --episodes 5
+python examples/unity_simple.py --url http://localhost:8000 --env 3DBall --episodes 5
+```
+
+#### 6. Alternating Environments
+
+```bash
+# Run alternating episodes between PushBlock and 3DBall
+python examples/unity_simple.py --direct --env both --episodes 6
+# Episodes 1,3,5 = PushBlock; Episodes 2,4,6 = 3DBall
+```
+
+### Command Line Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--direct` | - | Run environment directly (no server) |
+| `--docker` | - | Run via Docker container |
+| `--url` | localhost:8000 | Server URL for server mode |
+| `--docker-image` | unity-env:latest | Docker image name |
+| `--env` | PushBlock | Environment: PushBlock, 3DBall, both |
+| `--episodes` | 3 | Number of episodes |
+| `--max-steps` | 500 | Max steps per episode |
+| `--width` | 1280 | Window width in pixels |
+| `--height` | 720 | Window height in pixels |
+| `--no-graphics` | - | Headless mode (faster) |
+| `--time-scale` | 1.0 | Simulation speed multiplier |
+| `--quality-level` | 5 | Graphics quality 0-5 |
+| `--quiet` | - | Reduce output verbosity |
+
+## Python Client Usage
+
+### Connect to Server
+
+```python
+from envs.unity_env import UnityEnv, UnityAction
+
+# Connect to the server
+with UnityEnv(base_url="http://localhost:8000") as client:
+    # Reset to PushBlock environment
+    result = client.reset(env_id="PushBlock")
+    print(f"Observation dims: {len(result.observation.vector_observations)}")
+
+    # Take actions
+    for _ in range(100):
+        # PushBlock actions: 0=noop, 1=forward, 2=backward,
+        # 3=rotate_left, 4=rotate_right, 5=strafe_left, 6=strafe_right
+        action = UnityAction(discrete_actions=[1])  # Move forward
+        result = client.step(action)
+        print(f"Reward: {result.reward}, Done: {result.done}")
+
+        if result.done:
+            result = client.reset()
+```
+
+### Connect via Docker
+
+```python
+from envs.unity_env import UnityEnv, UnityAction
+
+# Automatically start Docker container and connect
+client = UnityEnv.from_docker_image(
+    "unity-env:latest",
+    environment={
+        "UNITY_NO_GRAPHICS": "0",
+        "UNITY_WIDTH": "1280",
+        "UNITY_HEIGHT": "720",
+    }
+)
+
+try:
+    result = client.reset(env_id="PushBlock")
+    for _ in range(100):
+        action = UnityAction(discrete_actions=[1])
+        result = client.step(action)
+finally:
+    client.close()
+```
+
+### Switch Environments Dynamically
+
+```python
+# Start with PushBlock
+result = client.reset(env_id="PushBlock")
+# ... train on PushBlock ...
+
+# Switch to 3DBall (continuous actions)
+result = client.reset(env_id="3DBall")
+action = UnityAction(continuous_actions=[0.5, -0.3])
+result = client.step(action)
+```
+
+### Direct Mode (Embedded Server)
+
+```python
+from envs.unity_env.client import UnityEnv
+from envs.unity_env.models import UnityAction
+
+# Create client with embedded local server (no separate server needed)
+client = UnityEnv.from_direct(
+    env_id="PushBlock",
+    no_graphics=False,  # Show graphics window
+    width=1280,
+    height=720,
+    time_scale=1.0,
+)
+
+try:
+    result = client.reset()
+    print(f"Observation: {len(result.observation.vector_observations)} dimensions")
+
+    for step in range(100):
+        action = UnityAction(discrete_actions=[1])  # Move forward
+        result = client.step(action)
+        print(f"Step {step}: reward={result.reward}, done={result.done}")
+
+        if result.done:
+            result = client.reset()
+finally:
+    client.close()
+```
+
+## Action Spaces
+
+### PushBlock (Discrete)
+
+7 discrete actions:
+- `0`: No operation
+- `1`: Move forward
+- `2`: Move backward
+- `3`: Rotate left
+- `4`: Rotate right
+- `5`: Strafe left
+- `6`: Strafe right
+
+```python
+action = UnityAction(discrete_actions=[1])  # Move forward
+```
+
+### 3DBall (Continuous)
+
+2 continuous actions in range [-1, 1]:
+- Action 0: X-axis rotation
+- Action 1: Z-axis rotation
+
+```python
+action = UnityAction(continuous_actions=[0.5, -0.3])
+```
+
+## Observations
+
+All environments provide vector observations. The size depends on the environment:
+
+- **PushBlock**: 70 dimensions (14 ray-casts detecting walls/goals/blocks)
+- **3DBall**: 8 dimensions (rotation and ball position/velocity)
+- **GridWorld**: Visual observations (grid view)
+
+```python
+result = client.reset()
+obs = result.observation
+
+# Access observations
+print(f"Vector obs: {obs.vector_observations}")
+print(f"Behavior: {obs.behavior_name}")
+print(f"Action spec: {obs.action_spec_info}")
+```
+
+### Visual Observations (Optional)
+
+Some environments support visual observations. Enable with `include_visual=True`:
+
+```python
+result = client.reset(include_visual=True)
+if result.observation.visual_observations:
+    # Base64-encoded PNG images
+    for img_b64 in result.observation.visual_observations:
+        # Decode and use the image
+        import base64
+        img_bytes = base64.b64decode(img_b64)
+```
+
+## Configuration
+
+### Direct Mode Arguments
+
+When using `UnityEnv.from_direct()` to run with an embedded server:
+
+```python
+from envs.unity_env.client import UnityEnv
+
+client = UnityEnv.from_direct(
+    env_id="PushBlock",      # Unity environment to load
+    no_graphics=False,       # False = show graphics window
+    width=1280,              # Window width in pixels
+    height=720,              # Window height in pixels
+    time_scale=1.0,          # Simulation speed (20.0 for fast training)
+    quality_level=5,         # Graphics quality 0-5
+    port=8765,               # Port for embedded server
+)
+```
+
+### Environment Variables
+
+For Docker deployment, configure via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `UNITY_ENV_ID` | PushBlock | Default Unity environment |
+| `UNITY_NO_GRAPHICS` | 0 | Set to 1 for headless mode |
+| `UNITY_WIDTH` | 1280 | Window width in pixels |
+| `UNITY_HEIGHT` | 720 | Window height in pixels |
+| `UNITY_TIME_SCALE` | 1.0 | Simulation speed multiplier |
+| `UNITY_QUALITY_LEVEL` | 5 | Graphics quality 0-5 |
+| `UNITY_CACHE_DIR` | ~/.mlagents-cache | Binary cache directory |
+
+## Environment State
+
+Access detailed environment information:
+
+```python
+state = client.state()
+print(f"Environment: {state.env_id}")
+print(f"Episode ID: {state.episode_id}")
+print(f"Step count: {state.step_count}")
+print(f"Available envs: {state.available_envs}")
+print(f"Action spec: {state.action_spec}")
+print(f"Observation spec: {state.observation_spec}")
+```
+
+## Troubleshooting
+
+### Docker Mode Fails on Apple Silicon (M1/M2/M3/M4)
+
+**Symptom:** When running with `--docker` on Apple Silicon Macs, you see an error like:
+
+```
+Error running with Docker: Server error: The Unity environment took too long to respond...
+```
+
+Or in Docker logs:
+
+```
+* Assertion: should not be reached at tramp-amd64.c:605
+Environment shut down with return code -6 (SIGABRT)
+```
+
+**Cause:** Unity ML-Agents binaries are x86_64 (Intel) only. When Docker runs the x86_64 Linux container on Apple Silicon, it uses QEMU emulation. The Mono runtime inside Unity has architecture-specific code that crashes under emulation.
+
+**Solutions:**
+
+1. **Use Direct Mode** (recommended for macOS):
+   ```bash
+   python examples/unity_simple.py --direct --no-graphics
+   ```
+   Direct mode downloads native macOS binaries which work on Apple Silicon.
+
+2. **Use Server Mode** with a local server:
+   ```bash
+   # Terminal 1: Start server (uses native macOS binaries)
+   uvicorn server.app:app --host 0.0.0.0 --port 8000
+
+   # Terminal 2: Run client
+   python examples/unity_simple.py --url http://localhost:8000
+   ```
+
+3. **Use an x86_64 Linux machine** for Docker mode:
+   The Docker image works correctly on native x86_64 Linux machines (cloud VMs, dedicated servers, etc.).
+
+### First Run is Slow
+
+The first run downloads Unity binaries (~500MB). This is normal and only happens once. Binaries are cached in `~/.mlagents-cache/`.
+
+### Graphics Not Showing
+
+- Ensure `--no-graphics` is NOT set
+- On Linux, ensure X11 is available
+- For Docker, you may need to set up X11 forwarding
+
+### Docker Container Fails to Start
+
+```bash
+# Check Docker logs
+docker logs <container_id>
+
+# Ensure the image is built
+docker images | grep unity-env
+
+# Rebuild if necessary
+cd envs/unity_env
+docker build -f server/Dockerfile -t unity-env:latest .
+```
+
+### Import Errors
+
+```bash
+# Ensure you're in the correct directory
+cd envs/unity_env
+
+# Install dependencies
+uv sync
+# or
+pip install -e .
+```
+
+### mlagents-envs Installation Issues
+
+The `mlagents-envs` and `mlagents` packages are installed from source by default (via the GitHub repository). If you encounter issues or want to install manually:
+
+```bash
+# Clone the ml-agents repository
+git clone https://github.com/Unity-Technologies/ml-agents.git
+cd ml-agents
+
+# Install mlagents-envs from source
+pip install -e ./ml-agents-envs
+
+# Install the full ml-agents package
+pip install -e ./ml-agents
+```
+
+This approach is useful when:
+- You need to modify the mlagents source code
+- You want to use a specific branch or commit
+- The git dependency in pyproject.toml is causing issues
+
+## Caveats
+
+1. **First Run Download**: Unity binaries (~500MB) are downloaded on first use
+2. **Platform-Specific**: Binaries are platform-specific (macOS, Linux, Windows)
+3. **Apple Silicon + Docker**: Docker mode does not work on Apple Silicon Macs due to x86_64 emulation issues with Unity's Mono runtime. Use direct mode or server mode instead.
+4. **Single Worker**: Unity environments are not thread-safe; use `workers=1`
+5. **Graphics Mode**: Some features require X11/display for graphics mode
+6. **Multi-Agent**: Currently uses first agent only; full multi-agent support planned
+
+## Dependencies
+
+- `mlagents-envs` (installed from source via git)
+- `mlagents` (installed from source via git)
+- `numpy>=1.20.0`
+- `pillow>=9.0.0` (for visual observations)
+- `openenv-core[core]>=0.2.0`
+
+## References
+
+- [Unity ML-Agents Documentation](https://docs.unity3d.com/Packages/com.unity.ml-agents@4.0/manual/index.html)
+- [ML-Agents GitHub](https://github.com/Unity-Technologies/ml-agents)
+- [Example Environments](https://docs.unity3d.com/Packages/com.unity.ml-agents@4.0/manual/Learning-Environment-Examples.html)

__init__.py

@@ -0,0 +1,12 @@
+# 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.
+
+"""Unity ML-Agents Environment for OpenEnv."""
+
+from .client import UnityEnv
+from .models import UnityAction, UnityObservation, UnityState
+
+__all__ = ["UnityAction", "UnityObservation", "UnityState", "UnityEnv"]

client.py

@@ -0,0 +1,428 @@
+# 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.
+
+"""
+Unity ML-Agents Environment Client.
+
+This module provides the client for connecting to a Unity ML-Agents
+Environment server via WebSocket for persistent sessions.
+"""
+
+from typing import Any, Dict, List, Optional
+
+# Support multiple import scenarios
+try:
+    # In-repo imports (when running from OpenEnv repository root)
+    from openenv.core.client_types import StepResult
+    from openenv.core.env_client import EnvClient
+
+    from .models import UnityAction, UnityObservation, UnityState
+except ImportError:
+    # openenv from pip
+    from openenv.core.client_types import StepResult
+    from openenv.core.env_client import EnvClient
+
+    try:
+        # Direct execution from envs/unity_env/ directory
+        from models import UnityAction, UnityObservation, UnityState
+    except ImportError:
+        try:
+            # Package installed as unity_env
+            from unity_env.models import UnityAction, UnityObservation, UnityState
+        except ImportError:
+            # Running from OpenEnv root with envs prefix
+            from envs.unity_env.models import UnityAction, UnityObservation, UnityState
+
+
+class UnityEnv(EnvClient[UnityAction, UnityObservation, UnityState]):
+    """
+    Client for Unity ML-Agents environments.
+
+    This client maintains a persistent WebSocket connection to the environment
+    server, enabling efficient multi-step interactions with lower latency.
+    Each client instance has its own dedicated environment session on the server.
+
+    Note: Unity environments can take 30-60+ seconds to initialize on first reset
+    (downloading binaries, starting Unity process). The client is configured with
+    longer ping timeouts to handle this.
+
+    Supported Unity Environments:
+    - PushBlock: Push a block to a goal (discrete actions: 7)
+    - 3DBall: Balance a ball on a platform (continuous actions: 2)
+    - 3DBallHard: Harder version of 3DBall
+    - GridWorld: Navigate a grid to find goals
+    - Basic: Simple movement task
+    - And more from the ML-Agents registry
+
+    Example:
+        >>> # Connect to a running server
+        >>> with UnityEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(f"Vector obs: {len(result.observation.vector_observations)} dims")
+        ...
+        ...     # Take action (PushBlock: 1=forward)
+        ...     result = client.step(UnityAction(discrete_actions=[1]))
+        ...     print(f"Reward: {result.reward}")
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = UnityEnv.from_docker_image("unity-env:latest")
+        >>> try:
+        ...     result = client.reset(env_id="3DBall")
+        ...     result = client.step(UnityAction(continuous_actions=[0.5, -0.3]))
+        ... finally:
+        ...     client.close()
+
+    Example switching environments:
+        >>> client = UnityEnv(base_url="http://localhost:8000")
+        >>> # Start with PushBlock
+        >>> result = client.reset(env_id="PushBlock")
+        >>> # ... train on PushBlock ...
+        >>> # Switch to 3DBall
+        >>> result = client.reset(env_id="3DBall")
+        >>> # ... train on 3DBall ...
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        connect_timeout_s: float = 10.0,
+        message_timeout_s: float = 180.0,  # 3 minutes for slow Unity initialization
+        provider: Optional[Any] = None,
+    ):
+        """
+        Initialize Unity environment client.
+
+        Uses longer default timeouts than the base EnvClient because Unity
+        environments can take 30-60+ seconds to initialize on first reset.
+
+        Args:
+            base_url: Base URL of the environment server (http:// or ws://).
+            connect_timeout_s: Timeout for establishing WebSocket connection
+            message_timeout_s: Timeout for receiving responses (default 3 min for Unity)
+            provider: Optional container/runtime provider for lifecycle management.
+        """
+        super().__init__(
+            base_url=base_url,
+            connect_timeout_s=connect_timeout_s,
+            message_timeout_s=message_timeout_s,
+            provider=provider,
+        )
+
+    def connect(self) -> "UnityEnv":
+        """
+        Establish WebSocket connection to the server.
+
+        Overrides the default connection to use longer ping timeouts,
+        since Unity environments can take 30-60+ seconds to initialize.
+
+        Returns:
+            self for method chaining
+
+        Raises:
+            ConnectionError: If connection cannot be established
+        """
+        from websockets.sync.client import connect as ws_connect
+
+        if self._ws is not None:
+            return self
+
+        try:
+            # Use longer ping_timeout for Unity (60s) since environment
+            # initialization can block the server for a while
+            self._ws = ws_connect(
+                self._ws_url,
+                open_timeout=self._connect_timeout,
+                ping_timeout=120,  # 2 minutes for slow Unity initialization
+                ping_interval=30,  # Send pings every 30 seconds
+                close_timeout=30,
+            )
+        except Exception as e:
+            raise ConnectionError(f"Failed to connect to {self._ws_url}: {e}") from e
+
+        return self
+
+    def _step_payload(self, action: UnityAction) -> Dict:
+        """
+        Convert UnityAction to JSON payload for step request.
+
+        Args:
+            action: UnityAction instance
+
+        Returns:
+            Dictionary representation suitable for JSON encoding
+        """
+        payload: Dict[str, Any] = {}
+
+        if action.discrete_actions is not None:
+            payload["discrete_actions"] = action.discrete_actions
+
+        if action.continuous_actions is not None:
+            payload["continuous_actions"] = action.continuous_actions
+
+        if action.metadata:
+            payload["metadata"] = action.metadata
+
+        return payload
+
+    def _parse_result(self, payload: Dict) -> StepResult[UnityObservation]:
+        """
+        Parse server response into StepResult[UnityObservation].
+
+        Args:
+            payload: JSON response from server
+
+        Returns:
+            StepResult with UnityObservation
+        """
+        obs_data = payload.get("observation", {})
+
+        observation = UnityObservation(
+            vector_observations=obs_data.get("vector_observations", []),
+            visual_observations=obs_data.get("visual_observations"),
+            behavior_name=obs_data.get("behavior_name", ""),
+            action_spec_info=obs_data.get("action_spec_info", {}),
+            observation_spec_info=obs_data.get("observation_spec_info", {}),
+            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) -> UnityState:
+        """
+        Parse server response into UnityState object.
+
+        Args:
+            payload: JSON response from /state endpoint
+
+        Returns:
+            UnityState object with environment information
+        """
+        return UnityState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            env_id=payload.get("env_id", ""),
+            behavior_name=payload.get("behavior_name", ""),
+            action_spec=payload.get("action_spec", {}),
+            observation_spec=payload.get("observation_spec", {}),
+            available_envs=payload.get("available_envs", []),
+        )
+
+    def reset(
+        self,
+        env_id: Optional[str] = None,
+        include_visual: bool = False,
+        **kwargs,
+    ) -> StepResult[UnityObservation]:
+        """
+        Reset the environment.
+
+        Args:
+            env_id: Optionally switch to a different Unity environment.
+                Available: PushBlock, 3DBall, 3DBallHard, GridWorld, Basic
+            include_visual: If True, include visual observations in response.
+            **kwargs: Additional arguments passed to server.
+
+        Returns:
+            StepResult with initial observation.
+        """
+        reset_kwargs = dict(kwargs)
+        if env_id is not None:
+            reset_kwargs["env_id"] = env_id
+        reset_kwargs["include_visual"] = include_visual
+
+        return super().reset(**reset_kwargs)
+
+    @staticmethod
+    def available_environments() -> List[str]:
+        """
+        List commonly available Unity environments.
+
+        Note: The actual list may vary based on the ML-Agents registry version.
+        Use state.available_envs after connecting for the authoritative list.
+
+        Returns:
+            List of environment identifiers.
+        """
+        return [
+            "PushBlock",
+            "3DBall",
+            "3DBallHard",
+            "GridWorld",
+            "Basic",
+            "VisualPushBlock",
+        ]
+
+    @classmethod
+    def from_direct(
+        cls,
+        env_id: str = "PushBlock",
+        no_graphics: bool = False,
+        width: int = 1280,
+        height: int = 720,
+        time_scale: float = 1.0,
+        quality_level: int = 5,
+        port: int = 8765,
+    ) -> "UnityEnv":
+        """
+        Create a Unity environment client with an embedded local server.
+
+        This method starts a local uvicorn server in a subprocess and returns
+        a client connected to it. This provides the convenience of direct mode
+        while maintaining the client-server separation.
+
+        Note: The first call will download Unity binaries (~500MB) which may
+        take several minutes. Binaries are cached for subsequent runs.
+
+        Args:
+            env_id: Default Unity environment to use (PushBlock, 3DBall, etc.)
+            no_graphics: If True, run Unity in headless mode (faster for training)
+            width: Window width in pixels (default: 1280)
+            height: Window height in pixels (default: 720)
+            time_scale: Simulation speed multiplier (default: 1.0, use 20.0 for fast training)
+            quality_level: Graphics quality 0-5 (default: 5)
+            port: Port for the local server (default: 8765)
+
+        Returns:
+            UnityEnv client connected to the local server
+
+        Example:
+            >>> # Quick start with direct mode
+            >>> client = UnityEnv.from_direct(no_graphics=True, time_scale=20)
+            >>> try:
+            ...     result = client.reset(env_id="PushBlock")
+            ...     for _ in range(100):
+            ...         result = client.step(UnityAction(discrete_actions=[1]))
+            ... finally:
+            ...     client.close()
+
+            >>> # With custom settings
+            >>> client = UnityEnv.from_direct(
+            ...     env_id="3DBall",
+            ...     no_graphics=True,
+            ...     time_scale=20,
+            ...     port=9000
+            ... )
+        """
+        import os
+        import subprocess
+        import sys
+        import time
+
+        import requests
+
+        # Find the project root and server module
+        # Try to locate the server module
+        try:
+            from pathlib import Path
+
+            # Get the directory containing this file
+            client_dir = Path(__file__).parent
+            server_app = "envs.unity_env.server.app:app"
+            cwd = client_dir.parent.parent  # OpenEnv root
+
+            # Check if we're in the envs/unity_env directory structure
+            if not (cwd / "envs" / "unity_env" / "server" / "app.py").exists():
+                # Try alternative paths
+                if (client_dir / "server" / "app.py").exists():
+                    server_app = "server.app:app"
+                    cwd = client_dir
+        except Exception:
+            server_app = "envs.unity_env.server.app:app"
+            cwd = None
+
+        # Set up environment variables for Unity configuration
+        env = {
+            **os.environ,
+            "UNITY_ENV_ID": env_id,
+            "UNITY_NO_GRAPHICS": "1" if no_graphics else "0",
+            "UNITY_WIDTH": str(width),
+            "UNITY_HEIGHT": str(height),
+            "UNITY_TIME_SCALE": str(time_scale),
+            "UNITY_QUALITY_LEVEL": str(quality_level),
+            # Bypass proxy for localhost
+            "NO_PROXY": "localhost,127.0.0.1",
+            "no_proxy": "localhost,127.0.0.1",
+        }
+
+        # Add src to PYTHONPATH if needed
+        if cwd:
+            src_path = str(cwd / "src")
+            existing_path = env.get("PYTHONPATH", "")
+            env["PYTHONPATH"] = f"{src_path}:{cwd}:{existing_path}" if existing_path else f"{src_path}:{cwd}"
+
+        # Start the server
+        cmd = [
+            sys.executable,
+            "-m",
+            "uvicorn",
+            server_app,
+            "--host",
+            "127.0.0.1",
+            "--port",
+            str(port),
+        ]
+
+        server_process = subprocess.Popen(
+            cmd,
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            cwd=str(cwd) if cwd else None,
+        )
+
+        # Wait for server to become healthy
+        base_url = f"http://127.0.0.1:{port}"
+        healthy = False
+        for _ in range(30):  # Wait up to 30 seconds
+            try:
+                response = requests.get(
+                    f"{base_url}/health",
+                    timeout=2,
+                    proxies={"http": None, "https": None},
+                )
+                if response.status_code == 200:
+                    healthy = True
+                    break
+            except requests.exceptions.RequestException:
+                pass
+            time.sleep(1)
+
+        if not healthy:
+            server_process.kill()
+            raise RuntimeError(
+                f"Failed to start local Unity server on port {port}. "
+                "Check that the port is available and dependencies are installed."
+            )
+
+        # Create a provider to manage the subprocess lifecycle
+        class DirectModeProvider:
+            """Provider that manages the embedded server subprocess."""
+
+            def __init__(self, process: subprocess.Popen):
+                self._process = process
+
+            def stop(self):
+                """Stop the embedded server."""
+                if self._process:
+                    self._process.terminate()
+                    try:
+                        self._process.wait(timeout=10)
+                    except subprocess.TimeoutExpired:
+                        self._process.kill()
+                    self._process = None
+
+        provider = DirectModeProvider(server_process)
+
+        # Create and return the client
+        client = cls(base_url=base_url, provider=provider)
+        return client

envs/unity_env/.gitignore

@@ -0,0 +1,44 @@
+# Unity ML-Agents cache (binaries are downloaded here)
+.mlagents-cache/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# ml-agents source (when developing locally)
+ml-agents/

envs/unity_env/README.md

@@ -0,0 +1,619 @@
+---
+title: Unity Environment Server
+emoji: 🌐
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+  - Unity
+  - MlAgents
+  - MlAgentsUnity
+  - MlAgentsEnv
+---
+
+<!--
+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.
+-->
+
+
+# Unity ML-Agents Environment
+
+OpenEnv wrapper for [Unity ML-Agents](https://github.com/Unity-Technologies/ml-agents) environments. This environment provides access to Unity's reinforcement learning environments through a standardized HTTP/WebSocket interface.
+
+<div align="center">
+  <img src="assets/unity_pushblock.gif" alt="PushBlock" width="400"/>
+  <img src="assets/unity_3dball.gif" alt="3DBall" width="400"/>
+</div>
+
+## Supported Environments
+
+| Environment | Action Type | Description |
+|------------|-------------|-------------|
+| **PushBlock** | Discrete (7) | Push a block to a goal position |
+| **3DBall** | Continuous (2) | Balance a ball on a platform |
+| **3DBallHard** | Continuous (2) | Harder version of 3DBall |
+| **GridWorld** | Discrete (5) | Navigate a grid to find goals |
+| **Basic** | Discrete (3) | Simple left/right movement |
+
+More environments may be available depending on the ML-Agents registry version.
+
+## Installation
+
+### Option 1: Non-Docker Installation (Local Development)
+
+#### Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+#### Install from OpenEnv Repository
+
+```bash
+# Clone the OpenEnv repository (if not already done)
+git clone https://github.com/your-org/OpenEnv.git
+cd OpenEnv
+
+# Install the unity_env package with dependencies
+cd envs/unity_env
+uv pip install -e .
+
+# Or with pip
+pip install -e .
+```
+
+#### Install Dependencies Only
+
+```bash
+cd envs/unity_env
+
+# Using uv (recommended)
+uv sync
+
+# Or using pip
+pip install -r requirements.txt  # if available
+pip install mlagents-envs numpy pillow fastapi uvicorn pydantic
+```
+
+#### Verify Installation
+
+```bash
+# Test the installation
+cd envs/unity_env
+python -c "from client import UnityEnv; print('Installation successful!')"
+```
+
+**Note:** The first run will download Unity environment binaries (~500MB). These are cached in `~/.mlagents-cache/` for future use.
+
+### Option 2: Docker Installation
+
+#### Prerequisites
+
+- Docker installed and running
+- Python 3.10+ (for running the client)
+
+#### Build the Docker Image
+
+```bash
+cd envs/unity_env
+
+# Build the Docker image
+docker build -f server/Dockerfile -t unity-env:latest .
+
+# Verify the build
+docker images | grep unity-env
+```
+
+**Note for Apple Silicon (M1/M2/M3/M4) users:** Docker mode is **not supported** on Apple Silicon because Unity's Mono runtime crashes under x86_64 emulation. Use **direct mode** (`--direct`) or **server mode** (`--url`) instead, which run native macOS binaries. See [Troubleshooting](#docker-mode-fails-on-apple-silicon-m1m2m3m4) for details.
+
+#### Run the Docker Container
+
+```bash
+# Run with default settings (graphics enabled, 800x600)
+docker run -p 8000:8000 unity-env:latest
+
+# Run with custom settings
+docker run -p 8000:8000 \
+  -e UNITY_NO_GRAPHICS=0 \
+  -e UNITY_WIDTH=1280 \
+  -e UNITY_HEIGHT=720 \
+  -e UNITY_TIME_SCALE=1.0 \
+  unity-env:latest
+
+# Run in headless mode (faster for training)
+docker run -p 8000:8000 \
+  -e UNITY_NO_GRAPHICS=1 \
+  -e UNITY_TIME_SCALE=20 \
+  unity-env:latest
+
+# Run with persistent cache (avoid re-downloading binaries)
+docker run -p 8000:8000 \
+  -v ~/.mlagents-cache:/root/.mlagents-cache \
+  unity-env:latest
+```
+
+#### Install Client Dependencies
+
+To connect to the Docker container, install the client on your host machine:
+
+```bash
+cd envs/unity_env
+pip install requests websockets
+```
+
+## Quick Start
+
+### Option 1: Direct Mode (Fastest for Testing)
+
+Run the Unity environment directly without a server:
+
+```bash
+# From the OpenEnv repository root:
+
+# Run with graphics (default: 1280x720)
+python examples/unity_simple.py --direct
+
+# Run with custom window size
+python examples/unity_simple.py --direct --width 800 --height 600
+
+# Run headless (faster for training)
+python examples/unity_simple.py --direct --no-graphics --time-scale 20
+
+# Run 3DBall environment
+python examples/unity_simple.py --direct --env 3DBall --episodes 5
+```
+
+### Option 2: Server Mode
+
+Start the server and connect with a client:
+
+```bash
+# Terminal 1: Start the server (graphics enabled by default)
+cd envs/unity_env
+uv run uvicorn server.app:app --host 0.0.0.0 --port 8000
+
+# Terminal 2: Run the example client (from repo root)
+python examples/unity_simple.py --url http://localhost:8000
+python examples/unity_simple.py --url http://localhost:8000 --env 3DBall --episodes 5
+```
+
+### Option 3: Docker Mode
+
+Run via Docker container (auto-starts and connects):
+
+```bash
+# Build the Docker image first
+cd envs/unity_env
+docker build -f server/Dockerfile -t unity-env:latest .
+
+# Run examples from repo root:
+cd ../..
+
+# Run with default settings
+python examples/unity_simple.py --docker
+
+# Run with custom window size
+python examples/unity_simple.py --docker --width 1280 --height 720
+
+# Run headless (faster for training)
+python examples/unity_simple.py --docker --no-graphics --time-scale 20
+
+# Run 3DBall for 10 episodes
+python examples/unity_simple.py --docker --env 3DBall --episodes 10
+
+# Use a custom Docker image
+python examples/unity_simple.py --docker --docker-image my-unity-env:v1
+```
+
+## Example Scripts
+
+### Basic Usage Examples
+
+#### 1. Direct Mode - Quick Testing
+
+```bash
+# Run PushBlock with graphics (default)
+python examples/unity_simple.py --direct
+
+# Output:
+# ============================================================
+# Unity ML-Agents Environment - Direct Mode
+# ============================================================
+# Environment: PushBlock
+# Episodes: 3
+# Max steps: 500
+# Window size: 1280x720
+# Graphics: Enabled
+# ...
+```
+
+#### 2. Direct Mode - Training Configuration
+
+```bash
+# Headless mode with fast simulation (20x speed)
+python examples/unity_simple.py --direct --no-graphics --time-scale 20 --episodes 10 --max-steps 1000
+
+# This is ideal for training - no graphics overhead, faster simulation
+```
+
+#### 3. Direct Mode - 3DBall with Custom Window
+
+```bash
+# Run 3DBall (continuous actions) with larger window
+python examples/unity_simple.py --direct --env 3DBall --width 1280 --height 720 --episodes 5
+```
+
+#### 4. Docker Mode - Production-like Testing
+
+```bash
+# Build the image first
+cd envs/unity_env
+docker build -f server/Dockerfile -t unity-env:latest .
+
+# Run via Docker with graphics
+python examples/unity_simple.py --docker --width 1280 --height 720
+
+# Run via Docker in headless mode for training
+python examples/unity_simple.py --docker --no-graphics --time-scale 20 --episodes 20
+```
+
+#### 5. Server Mode - Separate Server and Client
+
+```bash
+# Terminal 1: Start server with specific settings
+UNITY_WIDTH=1280 UNITY_HEIGHT=720 uv run uvicorn server.app:app --port 8000
+
+# Terminal 2: Connect and run episodes
+python examples/unity_simple.py --url http://localhost:8000 --env PushBlock --episodes 5
+python examples/unity_simple.py --url http://localhost:8000 --env 3DBall --episodes 5
+```
+
+#### 6. Alternating Environments
+
+```bash
+# Run alternating episodes between PushBlock and 3DBall
+python examples/unity_simple.py --direct --env both --episodes 6
+# Episodes 1,3,5 = PushBlock; Episodes 2,4,6 = 3DBall
+```
+
+### Command Line Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--direct` | - | Run environment directly (no server) |
+| `--docker` | - | Run via Docker container |
+| `--url` | localhost:8000 | Server URL for server mode |
+| `--docker-image` | unity-env:latest | Docker image name |
+| `--env` | PushBlock | Environment: PushBlock, 3DBall, both |
+| `--episodes` | 3 | Number of episodes |
+| `--max-steps` | 500 | Max steps per episode |
+| `--width` | 1280 | Window width in pixels |
+| `--height` | 720 | Window height in pixels |
+| `--no-graphics` | - | Headless mode (faster) |
+| `--time-scale` | 1.0 | Simulation speed multiplier |
+| `--quality-level` | 5 | Graphics quality 0-5 |
+| `--quiet` | - | Reduce output verbosity |
+
+## Python Client Usage
+
+### Connect to Server
+
+```python
+from envs.unity_env import UnityEnv, UnityAction
+
+# Connect to the server
+with UnityEnv(base_url="http://localhost:8000") as client:
+    # Reset to PushBlock environment
+    result = client.reset(env_id="PushBlock")
+    print(f"Observation dims: {len(result.observation.vector_observations)}")
+
+    # Take actions
+    for _ in range(100):
+        # PushBlock actions: 0=noop, 1=forward, 2=backward,
+        # 3=rotate_left, 4=rotate_right, 5=strafe_left, 6=strafe_right
+        action = UnityAction(discrete_actions=[1])  # Move forward
+        result = client.step(action)
+        print(f"Reward: {result.reward}, Done: {result.done}")
+
+        if result.done:
+            result = client.reset()
+```
+
+### Connect via Docker
+
+```python
+from envs.unity_env import UnityEnv, UnityAction
+
+# Automatically start Docker container and connect
+client = UnityEnv.from_docker_image(
+    "unity-env:latest",
+    environment={
+        "UNITY_NO_GRAPHICS": "0",
+        "UNITY_WIDTH": "1280",
+        "UNITY_HEIGHT": "720",
+    }
+)
+
+try:
+    result = client.reset(env_id="PushBlock")
+    for _ in range(100):
+        action = UnityAction(discrete_actions=[1])
+        result = client.step(action)
+finally:
+    client.close()
+```
+
+### Switch Environments Dynamically
+
+```python
+# Start with PushBlock
+result = client.reset(env_id="PushBlock")
+# ... train on PushBlock ...
+
+# Switch to 3DBall (continuous actions)
+result = client.reset(env_id="3DBall")
+action = UnityAction(continuous_actions=[0.5, -0.3])
+result = client.step(action)
+```
+
+### Direct Mode (Embedded Server)
+
+```python
+from envs.unity_env.client import UnityEnv
+from envs.unity_env.models import UnityAction
+
+# Create client with embedded local server (no separate server needed)
+client = UnityEnv.from_direct(
+    env_id="PushBlock",
+    no_graphics=False,  # Show graphics window
+    width=1280,
+    height=720,
+    time_scale=1.0,
+)
+
+try:
+    result = client.reset()
+    print(f"Observation: {len(result.observation.vector_observations)} dimensions")
+
+    for step in range(100):
+        action = UnityAction(discrete_actions=[1])  # Move forward
+        result = client.step(action)
+        print(f"Step {step}: reward={result.reward}, done={result.done}")
+
+        if result.done:
+            result = client.reset()
+finally:
+    client.close()
+```
+
+## Action Spaces
+
+### PushBlock (Discrete)
+
+7 discrete actions:
+- `0`: No operation
+- `1`: Move forward
+- `2`: Move backward
+- `3`: Rotate left
+- `4`: Rotate right
+- `5`: Strafe left
+- `6`: Strafe right
+
+```python
+action = UnityAction(discrete_actions=[1])  # Move forward
+```
+
+### 3DBall (Continuous)
+
+2 continuous actions in range [-1, 1]:
+- Action 0: X-axis rotation
+- Action 1: Z-axis rotation
+
+```python
+action = UnityAction(continuous_actions=[0.5, -0.3])
+```
+
+## Observations
+
+All environments provide vector observations. The size depends on the environment:
+
+- **PushBlock**: 70 dimensions (14 ray-casts detecting walls/goals/blocks)
+- **3DBall**: 8 dimensions (rotation and ball position/velocity)
+- **GridWorld**: Visual observations (grid view)
+
+```python
+result = client.reset()
+obs = result.observation
+
+# Access observations
+print(f"Vector obs: {obs.vector_observations}")
+print(f"Behavior: {obs.behavior_name}")
+print(f"Action spec: {obs.action_spec_info}")
+```
+
+### Visual Observations (Optional)
+
+Some environments support visual observations. Enable with `include_visual=True`:
+
+```python
+result = client.reset(include_visual=True)
+if result.observation.visual_observations:
+    # Base64-encoded PNG images
+    for img_b64 in result.observation.visual_observations:
+        # Decode and use the image
+        import base64
+        img_bytes = base64.b64decode(img_b64)
+```
+
+## Configuration
+
+### Direct Mode Arguments
+
+When using `UnityEnv.from_direct()` to run with an embedded server:
+
+```python
+from envs.unity_env.client import UnityEnv
+
+client = UnityEnv.from_direct(
+    env_id="PushBlock",      # Unity environment to load
+    no_graphics=False,       # False = show graphics window
+    width=1280,              # Window width in pixels
+    height=720,              # Window height in pixels
+    time_scale=1.0,          # Simulation speed (20.0 for fast training)
+    quality_level=5,         # Graphics quality 0-5
+    port=8765,               # Port for embedded server
+)
+```
+
+### Environment Variables
+
+For Docker deployment, configure via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `UNITY_ENV_ID` | PushBlock | Default Unity environment |
+| `UNITY_NO_GRAPHICS` | 0 | Set to 1 for headless mode |
+| `UNITY_WIDTH` | 1280 | Window width in pixels |
+| `UNITY_HEIGHT` | 720 | Window height in pixels |
+| `UNITY_TIME_SCALE` | 1.0 | Simulation speed multiplier |
+| `UNITY_QUALITY_LEVEL` | 5 | Graphics quality 0-5 |
+| `UNITY_CACHE_DIR` | ~/.mlagents-cache | Binary cache directory |
+
+## Environment State
+
+Access detailed environment information:
+
+```python
+state = client.state()
+print(f"Environment: {state.env_id}")
+print(f"Episode ID: {state.episode_id}")
+print(f"Step count: {state.step_count}")
+print(f"Available envs: {state.available_envs}")
+print(f"Action spec: {state.action_spec}")
+print(f"Observation spec: {state.observation_spec}")
+```
+
+## Troubleshooting
+
+### Docker Mode Fails on Apple Silicon (M1/M2/M3/M4)
+
+**Symptom:** When running with `--docker` on Apple Silicon Macs, you see an error like:
+
+```
+Error running with Docker: Server error: The Unity environment took too long to respond...
+```
+
+Or in Docker logs:
+
+```
+* Assertion: should not be reached at tramp-amd64.c:605
+Environment shut down with return code -6 (SIGABRT)
+```
+
+**Cause:** Unity ML-Agents binaries are x86_64 (Intel) only. When Docker runs the x86_64 Linux container on Apple Silicon, it uses QEMU emulation. The Mono runtime inside Unity has architecture-specific code that crashes under emulation.
+
+**Solutions:**
+
+1. **Use Direct Mode** (recommended for macOS):
+   ```bash
+   python examples/unity_simple.py --direct --no-graphics
+   ```
+   Direct mode downloads native macOS binaries which work on Apple Silicon.
+
+2. **Use Server Mode** with a local server:
+   ```bash
+   # Terminal 1: Start server (uses native macOS binaries)
+   uvicorn server.app:app --host 0.0.0.0 --port 8000
+
+   # Terminal 2: Run client
+   python examples/unity_simple.py --url http://localhost:8000
+   ```
+
+3. **Use an x86_64 Linux machine** for Docker mode:
+   The Docker image works correctly on native x86_64 Linux machines (cloud VMs, dedicated servers, etc.).
+
+### First Run is Slow
+
+The first run downloads Unity binaries (~500MB). This is normal and only happens once. Binaries are cached in `~/.mlagents-cache/`.
+
+### Graphics Not Showing
+
+- Ensure `--no-graphics` is NOT set
+- On Linux, ensure X11 is available
+- For Docker, you may need to set up X11 forwarding
+
+### Docker Container Fails to Start
+
+```bash
+# Check Docker logs
+docker logs <container_id>
+
+# Ensure the image is built
+docker images | grep unity-env
+
+# Rebuild if necessary
+cd envs/unity_env
+docker build -f server/Dockerfile -t unity-env:latest .
+```
+
+### Import Errors
+
+```bash
+# Ensure you're in the correct directory
+cd envs/unity_env
+
+# Install dependencies
+uv sync
+# or
+pip install -e .
+```
+
+### mlagents-envs Installation Issues
+
+The `mlagents-envs` and `mlagents` packages are installed from source by default (via the GitHub repository). If you encounter issues or want to install manually:
+
+```bash
+# Clone the ml-agents repository
+git clone https://github.com/Unity-Technologies/ml-agents.git
+cd ml-agents
+
+# Install mlagents-envs from source
+pip install -e ./ml-agents-envs
+
+# Install the full ml-agents package
+pip install -e ./ml-agents
+```
+
+This approach is useful when:
+- You need to modify the mlagents source code
+- You want to use a specific branch or commit
+- The git dependency in pyproject.toml is causing issues
+
+## Caveats
+
+1. **First Run Download**: Unity binaries (~500MB) are downloaded on first use
+2. **Platform-Specific**: Binaries are platform-specific (macOS, Linux, Windows)
+3. **Apple Silicon + Docker**: Docker mode does not work on Apple Silicon Macs due to x86_64 emulation issues with Unity's Mono runtime. Use direct mode or server mode instead.
+4. **Single Worker**: Unity environments are not thread-safe; use `workers=1`
+5. **Graphics Mode**: Some features require X11/display for graphics mode
+6. **Multi-Agent**: Currently uses first agent only; full multi-agent support planned
+
+## Dependencies
+
+- `mlagents-envs` (installed from source via git)
+- `mlagents` (installed from source via git)
+- `numpy>=1.20.0`
+- `pillow>=9.0.0` (for visual observations)
+- `openenv-core[core]>=0.2.0`
+
+## References
+
+- [Unity ML-Agents Documentation](https://docs.unity3d.com/Packages/com.unity.ml-agents@4.0/manual/index.html)
+- [ML-Agents GitHub](https://github.com/Unity-Technologies/ml-agents)
+- [Example Environments](https://docs.unity3d.com/Packages/com.unity.ml-agents@4.0/manual/Learning-Environment-Examples.html)

envs/unity_env/__init__.py

@@ -0,0 +1,12 @@
+# 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.
+
+"""Unity ML-Agents Environment for OpenEnv."""
+
+from .client import UnityEnv
+from .models import UnityAction, UnityObservation, UnityState
+
+__all__ = ["UnityAction", "UnityObservation", "UnityState", "UnityEnv"]

envs/unity_env/client.py

@@ -0,0 +1,428 @@
+# 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.
+
+"""
+Unity ML-Agents Environment Client.
+
+This module provides the client for connecting to a Unity ML-Agents
+Environment server via WebSocket for persistent sessions.
+"""
+
+from typing import Any, Dict, List, Optional
+
+# Support multiple import scenarios
+try:
+    # In-repo imports (when running from OpenEnv repository root)
+    from openenv.core.client_types import StepResult
+    from openenv.core.env_client import EnvClient
+
+    from .models import UnityAction, UnityObservation, UnityState
+except ImportError:
+    # openenv from pip
+    from openenv.core.client_types import StepResult
+    from openenv.core.env_client import EnvClient
+
+    try:
+        # Direct execution from envs/unity_env/ directory
+        from models import UnityAction, UnityObservation, UnityState
+    except ImportError:
+        try:
+            # Package installed as unity_env
+            from unity_env.models import UnityAction, UnityObservation, UnityState
+        except ImportError:
+            # Running from OpenEnv root with envs prefix
+            from envs.unity_env.models import UnityAction, UnityObservation, UnityState
+
+
+class UnityEnv(EnvClient[UnityAction, UnityObservation, UnityState]):
+    """
+    Client for Unity ML-Agents environments.
+
+    This client maintains a persistent WebSocket connection to the environment
+    server, enabling efficient multi-step interactions with lower latency.
+    Each client instance has its own dedicated environment session on the server.
+
+    Note: Unity environments can take 30-60+ seconds to initialize on first reset
+    (downloading binaries, starting Unity process). The client is configured with
+    longer ping timeouts to handle this.
+
+    Supported Unity Environments:
+    - PushBlock: Push a block to a goal (discrete actions: 7)
+    - 3DBall: Balance a ball on a platform (continuous actions: 2)
+    - 3DBallHard: Harder version of 3DBall
+    - GridWorld: Navigate a grid to find goals
+    - Basic: Simple movement task
+    - And more from the ML-Agents registry
+
+    Example:
+        >>> # Connect to a running server
+        >>> with UnityEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(f"Vector obs: {len(result.observation.vector_observations)} dims")
+        ...
+        ...     # Take action (PushBlock: 1=forward)
+        ...     result = client.step(UnityAction(discrete_actions=[1]))
+        ...     print(f"Reward: {result.reward}")
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = UnityEnv.from_docker_image("unity-env:latest")
+        >>> try:
+        ...     result = client.reset(env_id="3DBall")
+        ...     result = client.step(UnityAction(continuous_actions=[0.5, -0.3]))
+        ... finally:
+        ...     client.close()
+
+    Example switching environments:
+        >>> client = UnityEnv(base_url="http://localhost:8000")
+        >>> # Start with PushBlock
+        >>> result = client.reset(env_id="PushBlock")
+        >>> # ... train on PushBlock ...
+        >>> # Switch to 3DBall
+        >>> result = client.reset(env_id="3DBall")
+        >>> # ... train on 3DBall ...
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        connect_timeout_s: float = 10.0,
+        message_timeout_s: float = 180.0,  # 3 minutes for slow Unity initialization
+        provider: Optional[Any] = None,
+    ):
+        """
+        Initialize Unity environment client.
+
+        Uses longer default timeouts than the base EnvClient because Unity
+        environments can take 30-60+ seconds to initialize on first reset.
+
+        Args:
+            base_url: Base URL of the environment server (http:// or ws://).
+            connect_timeout_s: Timeout for establishing WebSocket connection
+            message_timeout_s: Timeout for receiving responses (default 3 min for Unity)
+            provider: Optional container/runtime provider for lifecycle management.
+        """
+        super().__init__(
+            base_url=base_url,
+            connect_timeout_s=connect_timeout_s,
+            message_timeout_s=message_timeout_s,
+            provider=provider,
+        )
+
+    def connect(self) -> "UnityEnv":
+        """
+        Establish WebSocket connection to the server.
+
+        Overrides the default connection to use longer ping timeouts,
+        since Unity environments can take 30-60+ seconds to initialize.
+
+        Returns:
+            self for method chaining
+
+        Raises:
+            ConnectionError: If connection cannot be established
+        """
+        from websockets.sync.client import connect as ws_connect
+
+        if self._ws is not None:
+            return self
+
+        try:
+            # Use longer ping_timeout for Unity (60s) since environment
+            # initialization can block the server for a while
+            self._ws = ws_connect(
+                self._ws_url,
+                open_timeout=self._connect_timeout,
+                ping_timeout=120,  # 2 minutes for slow Unity initialization
+                ping_interval=30,  # Send pings every 30 seconds
+                close_timeout=30,
+            )
+        except Exception as e:
+            raise ConnectionError(f"Failed to connect to {self._ws_url}: {e}") from e
+
+        return self
+
+    def _step_payload(self, action: UnityAction) -> Dict:
+        """
+        Convert UnityAction to JSON payload for step request.
+
+        Args:
+            action: UnityAction instance
+
+        Returns:
+            Dictionary representation suitable for JSON encoding
+        """
+        payload: Dict[str, Any] = {}
+
+        if action.discrete_actions is not None:
+            payload["discrete_actions"] = action.discrete_actions
+
+        if action.continuous_actions is not None:
+            payload["continuous_actions"] = action.continuous_actions
+
+        if action.metadata:
+            payload["metadata"] = action.metadata
+
+        return payload
+
+    def _parse_result(self, payload: Dict) -> StepResult[UnityObservation]:
+        """
+        Parse server response into StepResult[UnityObservation].
+
+        Args:
+            payload: JSON response from server
+
+        Returns:
+            StepResult with UnityObservation
+        """
+        obs_data = payload.get("observation", {})
+
+        observation = UnityObservation(
+            vector_observations=obs_data.get("vector_observations", []),
+            visual_observations=obs_data.get("visual_observations"),
+            behavior_name=obs_data.get("behavior_name", ""),
+            action_spec_info=obs_data.get("action_spec_info", {}),
+            observation_spec_info=obs_data.get("observation_spec_info", {}),
+            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) -> UnityState:
+        """
+        Parse server response into UnityState object.
+
+        Args:
+            payload: JSON response from /state endpoint
+
+        Returns:
+            UnityState object with environment information
+        """
+        return UnityState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            env_id=payload.get("env_id", ""),
+            behavior_name=payload.get("behavior_name", ""),
+            action_spec=payload.get("action_spec", {}),
+            observation_spec=payload.get("observation_spec", {}),
+            available_envs=payload.get("available_envs", []),
+        )
+
+    def reset(
+        self,
+        env_id: Optional[str] = None,
+        include_visual: bool = False,
+        **kwargs,
+    ) -> StepResult[UnityObservation]:
+        """
+        Reset the environment.
+
+        Args:
+            env_id: Optionally switch to a different Unity environment.
+                Available: PushBlock, 3DBall, 3DBallHard, GridWorld, Basic
+            include_visual: If True, include visual observations in response.
+            **kwargs: Additional arguments passed to server.
+
+        Returns:
+            StepResult with initial observation.
+        """
+        reset_kwargs = dict(kwargs)
+        if env_id is not None:
+            reset_kwargs["env_id"] = env_id
+        reset_kwargs["include_visual"] = include_visual
+
+        return super().reset(**reset_kwargs)
+
+    @staticmethod
+    def available_environments() -> List[str]:
+        """
+        List commonly available Unity environments.
+
+        Note: The actual list may vary based on the ML-Agents registry version.
+        Use state.available_envs after connecting for the authoritative list.
+
+        Returns:
+            List of environment identifiers.
+        """
+        return [
+            "PushBlock",
+            "3DBall",
+            "3DBallHard",
+            "GridWorld",
+            "Basic",
+            "VisualPushBlock",
+        ]
+
+    @classmethod
+    def from_direct(
+        cls,
+        env_id: str = "PushBlock",
+        no_graphics: bool = False,
+        width: int = 1280,
+        height: int = 720,
+        time_scale: float = 1.0,
+        quality_level: int = 5,
+        port: int = 8765,
+    ) -> "UnityEnv":
+        """
+        Create a Unity environment client with an embedded local server.
+
+        This method starts a local uvicorn server in a subprocess and returns
+        a client connected to it. This provides the convenience of direct mode
+        while maintaining the client-server separation.
+
+        Note: The first call will download Unity binaries (~500MB) which may
+        take several minutes. Binaries are cached for subsequent runs.
+
+        Args:
+            env_id: Default Unity environment to use (PushBlock, 3DBall, etc.)
+            no_graphics: If True, run Unity in headless mode (faster for training)
+            width: Window width in pixels (default: 1280)
+            height: Window height in pixels (default: 720)
+            time_scale: Simulation speed multiplier (default: 1.0, use 20.0 for fast training)
+            quality_level: Graphics quality 0-5 (default: 5)
+            port: Port for the local server (default: 8765)
+
+        Returns:
+            UnityEnv client connected to the local server
+
+        Example:
+            >>> # Quick start with direct mode
+            >>> client = UnityEnv.from_direct(no_graphics=True, time_scale=20)
+            >>> try:
+            ...     result = client.reset(env_id="PushBlock")
+            ...     for _ in range(100):
+            ...         result = client.step(UnityAction(discrete_actions=[1]))
+            ... finally:
+            ...     client.close()
+
+            >>> # With custom settings
+            >>> client = UnityEnv.from_direct(
+            ...     env_id="3DBall",
+            ...     no_graphics=True,
+            ...     time_scale=20,
+            ...     port=9000
+            ... )
+        """
+        import os
+        import subprocess
+        import sys
+        import time
+
+        import requests
+
+        # Find the project root and server module
+        # Try to locate the server module
+        try:
+            from pathlib import Path
+
+            # Get the directory containing this file
+            client_dir = Path(__file__).parent
+            server_app = "envs.unity_env.server.app:app"
+            cwd = client_dir.parent.parent  # OpenEnv root
+
+            # Check if we're in the envs/unity_env directory structure
+            if not (cwd / "envs" / "unity_env" / "server" / "app.py").exists():
+                # Try alternative paths
+                if (client_dir / "server" / "app.py").exists():
+                    server_app = "server.app:app"
+                    cwd = client_dir
+        except Exception:
+            server_app = "envs.unity_env.server.app:app"
+            cwd = None
+
+        # Set up environment variables for Unity configuration
+        env = {
+            **os.environ,
+            "UNITY_ENV_ID": env_id,
+            "UNITY_NO_GRAPHICS": "1" if no_graphics else "0",
+            "UNITY_WIDTH": str(width),
+            "UNITY_HEIGHT": str(height),
+            "UNITY_TIME_SCALE": str(time_scale),
+            "UNITY_QUALITY_LEVEL": str(quality_level),
+            # Bypass proxy for localhost
+            "NO_PROXY": "localhost,127.0.0.1",
+            "no_proxy": "localhost,127.0.0.1",
+        }
+
+        # Add src to PYTHONPATH if needed
+        if cwd:
+            src_path = str(cwd / "src")
+            existing_path = env.get("PYTHONPATH", "")
+            env["PYTHONPATH"] = f"{src_path}:{cwd}:{existing_path}" if existing_path else f"{src_path}:{cwd}"
+
+        # Start the server
+        cmd = [
+            sys.executable,
+            "-m",
+            "uvicorn",
+            server_app,
+            "--host",
+            "127.0.0.1",
+            "--port",
+            str(port),
+        ]
+
+        server_process = subprocess.Popen(
+            cmd,
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            cwd=str(cwd) if cwd else None,
+        )
+
+        # Wait for server to become healthy
+        base_url = f"http://127.0.0.1:{port}"
+        healthy = False
+        for _ in range(30):  # Wait up to 30 seconds
+            try:
+                response = requests.get(
+                    f"{base_url}/health",
+                    timeout=2,
+                    proxies={"http": None, "https": None},
+                )
+                if response.status_code == 200:
+                    healthy = True
+                    break
+            except requests.exceptions.RequestException:
+                pass
+            time.sleep(1)
+
+        if not healthy:
+            server_process.kill()
+            raise RuntimeError(
+                f"Failed to start local Unity server on port {port}. "
+                "Check that the port is available and dependencies are installed."
+            )
+
+        # Create a provider to manage the subprocess lifecycle
+        class DirectModeProvider:
+            """Provider that manages the embedded server subprocess."""
+
+            def __init__(self, process: subprocess.Popen):
+                self._process = process
+
+            def stop(self):
+                """Stop the embedded server."""
+                if self._process:
+                    self._process.terminate()
+                    try:
+                        self._process.wait(timeout=10)
+                    except subprocess.TimeoutExpired:
+                        self._process.kill()
+                    self._process = None
+
+        provider = DirectModeProvider(server_process)
+
+        # Create and return the client
+        client = cls(base_url=base_url, provider=provider)
+        return client

envs/unity_env/models.py

@@ -0,0 +1,164 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Data models for the Unity ML-Agents Environment.
+
+The Unity environment wraps Unity ML-Agents environments (PushBlock, 3DBall,
+GridWorld, etc.) providing a unified interface for reinforcement learning.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import Field
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.types import Action, Observation, State
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.types import Action, Observation, State
+
+
+class UnityAction(Action):
+    """
+    Action for Unity ML-Agents environments.
+
+    Supports both discrete and continuous action spaces. Unity environments
+    may use either or both types of actions:
+
+    - Discrete actions: Integer indices for categorical choices
+      (e.g., movement direction: 0=forward, 1=backward, 2=left, 3=right)
+    - Continuous actions: Float values typically in [-1, 1] range
+      (e.g., joint rotations, force magnitudes)
+
+    Example (PushBlock - discrete):
+        >>> action = UnityAction(discrete_actions=[3])  # Rotate left
+
+    Example (Walker - continuous):
+        >>> action = UnityAction(continuous_actions=[0.5, -0.3, 0.0, ...])
+
+    Attributes:
+        discrete_actions: List of discrete action indices for each action branch.
+            For PushBlock: [0-6] where 0=noop, 1=forward, 2=backward,
+            3=rotate_left, 4=rotate_right, 5=strafe_left, 6=strafe_right
+        continuous_actions: List of continuous action values, typically in [-1, 1].
+        metadata: Additional action parameters.
+    """
+
+    discrete_actions: Optional[List[int]] = Field(
+        default=None,
+        description="Discrete action indices for each action branch",
+    )
+    continuous_actions: Optional[List[float]] = Field(
+        default=None,
+        description="Continuous action values, typically in [-1, 1] range",
+    )
+
+
+class UnityObservation(Observation):
+    """
+    Observation from Unity ML-Agents environments.
+
+    Contains vector observations (sensor readings) and optionally visual
+    observations (rendered images). Most Unity environments provide vector
+    observations; visual observations are optional and must be requested.
+
+    Attributes:
+        vector_observations: Flattened array of all vector observations.
+            Size and meaning depends on the specific environment.
+            For PushBlock: 70 values from 14 ray-casts detecting walls/goals/blocks.
+        visual_observations: Optional list of base64-encoded images (PNG format).
+            Only included when include_visual=True in reset/step.
+        behavior_name: Name of the Unity behavior (agent type).
+        action_spec_info: Information about the action space for this environment.
+        observation_spec_info: Information about the observation space.
+    """
+
+    vector_observations: List[float] = Field(
+        default_factory=list,
+        description="Flattened vector observations from the environment",
+    )
+    visual_observations: Optional[List[str]] = Field(
+        default=None,
+        description="Base64-encoded PNG images (when include_visual=True)",
+    )
+    behavior_name: str = Field(
+        default="",
+        description="Name of the Unity behavior/agent type",
+    )
+    action_spec_info: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Information about the action space",
+    )
+    observation_spec_info: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Information about the observation space",
+    )
+
+
+class UnityState(State):
+    """
+    Extended state for Unity ML-Agents environments.
+
+    Provides additional metadata about the currently loaded environment,
+    including action and observation space specifications.
+
+    Attributes:
+        episode_id: Unique identifier for the current episode.
+        step_count: Number of steps taken in the current episode.
+        env_id: Identifier of the currently loaded Unity environment.
+        behavior_name: Name of the Unity behavior (agent type).
+        action_spec: Detailed specification of the action space.
+        observation_spec: Detailed specification of the observation space.
+        available_envs: List of available environment identifiers.
+    """
+
+    env_id: str = Field(
+        default="PushBlock",
+        description="Identifier of the loaded Unity environment",
+    )
+    behavior_name: str = Field(
+        default="",
+        description="Name of the Unity behavior/agent type",
+    )
+    action_spec: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Specification of the action space",
+    )
+    observation_spec: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Specification of the observation space",
+    )
+    available_envs: List[str] = Field(
+        default_factory=list,
+        description="List of available Unity environments",
+    )
+
+
+# Available Unity environments from the ML-Agents registry
+# These are pre-built environments that can be downloaded automatically
+AVAILABLE_UNITY_ENVIRONMENTS = [
+    "PushBlock",
+    "3DBall",
+    "3DBallHard",
+    "GridWorld",
+    "Basic",
+    "VisualPushBlock",
+    # Note: More environments may be available in newer versions of ML-Agents
+]
+
+# Action descriptions for PushBlock (most commonly used example)
+PUSHBLOCK_ACTIONS = {
+    0: "noop",
+    1: "forward",
+    2: "backward",
+    3: "rotate_left",
+    4: "rotate_right",
+    5: "strafe_left",
+    6: "strafe_right",
+}

envs/unity_env/openenv.yaml

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

envs/unity_env/pyproject.toml

@@ -0,0 +1,45 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-unity-env"
+version = "0.1.0"
+description = "Unity ML-Agents Environment for OpenEnv - wraps Unity environments like PushBlock, 3DBall, GridWorld"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv dependencies (installed from git for latest features)
+    "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git@v2.1.0",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0.0",
+    "uvicorn>=0.24.0",
+    "requests>=2.31.0",
+    # Unity ML-Agents dependencies (installed from source for latest features)
+    "mlagents-envs @ git+https://github.com/Unity-Technologies/ml-agents.git#subdirectory=ml-agents-envs",
+    # "mlagents @ git+https://github.com/Unity-Technologies/ml-agents.git#subdirectory=ml-agents",
+    "numpy>=1.20.0",
+    # Optional: for visual observations
+    "pillow>=9.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m unity_env.server.app
+server = "unity_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["unity_env", "unity_env.server"]
+package-dir = { "unity_env" = ".", "unity_env.server" = "server" }

envs/unity_env/server/Dockerfile

@@ -0,0 +1,66 @@
+# 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 Unity ML-Agents environment
+# Uses pip for package installation (no virtual environment)
+# Note: Using Python 3.10.12 specifically because ml-agents requires >=3.10.1,<=3.10.12
+# Note: Unity binaries are x86_64 only, so we force linux/amd64 platform
+
+FROM --platform=linux/amd64 python:3.10.12-slim AS builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy environment code
+COPY . /app/env
+
+WORKDIR /app/env
+
+# Install dependencies using pip
+# Note: mlagents packages are installed from git source via pyproject.toml
+RUN pip install --upgrade pip && \
+    pip install --no-cache-dir -e .
+
+# Final runtime stage
+FROM --platform=linux/amd64 python:3.10.12-slim
+
+WORKDIR /app
+
+# Install runtime dependencies (curl for healthcheck)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy installed packages from builder
+COPY --from=builder /usr/local/lib/python3.10/site-packages /usr/local/lib/python3.10/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy the environment code
+COPY . /app/env
+
+# Create cache directory for Unity binaries
+RUN mkdir -p /root/.mlagents-cache
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=60s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Note: Longer start period (60s) because Unity environment download may take time on first run
+
+# Run the FastAPI server
+# Note: workers=1 because Unity environments are not thread-safe
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

envs/unity_env/server/__init__.py

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

envs/unity_env/server/app.py

@@ -0,0 +1,84 @@
+# 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 Unity ML-Agents Environment.
+
+This module creates an HTTP server that exposes Unity ML-Agents environments
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 1
+
+    # Or run directly:
+    uv run --project . server
+
+Note: Unity environments are not thread-safe, so use workers=1.
+"""
+
+# Support multiple import scenarios
+try:
+    # In-repo imports (when running from OpenEnv repository root)
+    from openenv.core.env_server.http_server import create_app
+
+    from ..models import UnityAction, UnityObservation
+    from .unity_environment import UnityMLAgentsEnvironment
+except ImportError:
+    # openenv from pip
+    from openenv.core.env_server.http_server import create_app
+
+    try:
+        # Direct execution from envs/unity_env/ directory
+        import sys
+        from pathlib import Path
+
+        # Add parent directory to path for direct execution
+        _parent = str(Path(__file__).parent.parent)
+        if _parent not in sys.path:
+            sys.path.insert(0, _parent)
+        from models import UnityAction, UnityObservation
+        from server.unity_environment import UnityMLAgentsEnvironment
+    except ImportError:
+        try:
+            # Package installed as unity_env
+            from unity_env.models import UnityAction, UnityObservation
+            from unity_env.server.unity_environment import UnityMLAgentsEnvironment
+        except ImportError:
+            # Running from OpenEnv root with envs prefix
+            from envs.unity_env.models import UnityAction, UnityObservation
+            from envs.unity_env.server.unity_environment import UnityMLAgentsEnvironment
+
+# Create the app with web interface
+# Pass the class (factory) instead of an instance for WebSocket session support
+app = create_app(
+    UnityMLAgentsEnvironment,
+    UnityAction,
+    UnityObservation,
+    env_name="unity_env",
+)
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.unity_env.server.app
+        openenv serve unity_env
+    """
+    import uvicorn
+
+    # Note: workers=1 because Unity environments are not thread-safe
+    uvicorn.run(app, host="0.0.0.0", port=8000, workers=1)
+
+
+if __name__ == "__main__":
+    main()

envs/unity_env/server/unity_environment.py

@@ -0,0 +1,554 @@
+# 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.
+
+"""
+Unity ML-Agents Environment Implementation.
+
+Wraps Unity ML-Agents environments (PushBlock, 3DBall, GridWorld, etc.)
+with the OpenEnv interface for standardized reinforcement learning.
+"""
+
+import base64
+import glob
+import hashlib
+import io
+import os
+from pathlib import Path
+from sys import platform
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+import numpy as np
+
+# Support multiple import scenarios
+try:
+    # In-repo imports (when running from OpenEnv repository root)
+    from openenv.core.env_server.interfaces import Environment
+
+    from ..models import UnityAction, UnityObservation, UnityState
+except ImportError:
+    # openenv from pip
+    from openenv.core.env_server.interfaces import Environment
+
+    try:
+        # Direct execution from envs/unity_env/ directory (imports from parent)
+        import sys
+        from pathlib import Path
+
+        # Add parent directory to path for direct execution
+        _parent = str(Path(__file__).parent.parent)
+        if _parent not in sys.path:
+            sys.path.insert(0, _parent)
+        from models import UnityAction, UnityObservation, UnityState
+    except ImportError:
+        try:
+            # Package installed as unity_env
+            from unity_env.models import UnityAction, UnityObservation, UnityState
+        except ImportError:
+            # Running from OpenEnv root with envs prefix
+            from envs.unity_env.models import UnityAction, UnityObservation, UnityState
+
+
+# Persistent cache directory to avoid re-downloading environment binaries
+PERSISTENT_CACHE_DIR = os.path.join(str(Path.home()), ".mlagents-cache")
+
+
+def get_cached_binary_path(cache_dir: str, name: str, url: str) -> Optional[str]:
+    """Check if binary is cached and return its path."""
+    if platform == "darwin":
+        extension = "*.app"
+    elif platform in ("linux", "linux2"):
+        extension = "*.x86_64"
+    elif platform == "win32":
+        extension = "*.exe"
+    else:
+        return None
+
+    bin_dir = os.path.join(cache_dir, "binaries")
+    url_hash = "-" + hashlib.md5(url.encode()).hexdigest()
+    search_path = os.path.join(bin_dir, name + url_hash, "**", extension)
+
+    candidates = glob.glob(search_path, recursive=True)
+    for c in candidates:
+        if "UnityCrashHandler64" not in c:
+            return c
+    return None
+
+
+class UnityMLAgentsEnvironment(Environment):
+    """
+    Wraps Unity ML-Agents environments with the OpenEnv interface.
+
+    This environment supports all Unity ML-Agents registry environments
+    including PushBlock, 3DBall, GridWorld, and more. Environments are
+    automatically downloaded on first use.
+
+    Features:
+    - Dynamic environment switching via reset(env_id="...")
+    - Support for both discrete and continuous action spaces
+    - Optional visual observations (base64-encoded images)
+    - Persistent caching to avoid re-downloading binaries
+    - Headless mode for faster training (no_graphics=True)
+
+    Example:
+        >>> env = UnityMLAgentsEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.vector_observations)
+        >>>
+        >>> # Take a random action
+        >>> obs = env.step(UnityAction(discrete_actions=[1]))  # Move forward
+        >>> print(obs.reward)
+
+    Example with different environment:
+        >>> env = UnityMLAgentsEnvironment(env_id="3DBall")
+        >>> obs = env.reset()
+        >>>
+        >>> # Or switch environment on reset
+        >>> obs = env.reset(env_id="PushBlock")
+    """
+
+    # Each WebSocket session gets its own environment instance
+    SUPPORTS_CONCURRENT_SESSIONS = False
+
+    def __init__(
+        self,
+        env_id: Optional[str] = None,
+        no_graphics: Optional[bool] = None,
+        time_scale: Optional[float] = None,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        quality_level: Optional[int] = None,
+        cache_dir: Optional[str] = None,
+    ):
+        """
+        Initialize the Unity ML-Agents environment.
+
+        Configuration can be provided via constructor arguments or environment
+        variables. Environment variables are used when constructor arguments
+        are not provided (useful for Docker deployment).
+
+        Args:
+            env_id: Identifier of the Unity environment to load.
+                Available: PushBlock, 3DBall, 3DBallHard, GridWorld, Basic
+                Env var: UNITY_ENV_ID (default: PushBlock)
+            no_graphics: If True, run in headless mode (faster training).
+                Env var: UNITY_NO_GRAPHICS (0 or 1, default: 0 = graphics enabled)
+            time_scale: Simulation speed multiplier.
+                Env var: UNITY_TIME_SCALE (default: 1.0)
+            width: Window width in pixels (when graphics enabled).
+                Env var: UNITY_WIDTH (default: 1280)
+            height: Window height in pixels (when graphics enabled).
+                Env var: UNITY_HEIGHT (default: 720)
+            quality_level: Graphics quality 0-5 (when graphics enabled).
+                Env var: UNITY_QUALITY_LEVEL (default: 5)
+            cache_dir: Directory to cache downloaded environment binaries.
+                Env var: UNITY_CACHE_DIR (default: ~/.mlagents-cache)
+        """
+        # Initialize cleanup-critical attributes first (for __del__ safety)
+        self._unity_env = None
+        self._behavior_name = None
+        self._behavior_spec = None
+        self._engine_channel = None
+
+        # Read from environment variables with defaults, allow constructor override
+        self._env_id = env_id or os.environ.get("UNITY_ENV_ID", "PushBlock")
+
+        # Handle no_graphics: default is False (graphics enabled)
+        if no_graphics is not None:
+            self._no_graphics = no_graphics
+        else:
+            env_no_graphics = os.environ.get("UNITY_NO_GRAPHICS", "0")
+            self._no_graphics = env_no_graphics.lower() in ("1", "true", "yes")
+
+        self._time_scale = (
+            time_scale
+            if time_scale is not None
+            else float(os.environ.get("UNITY_TIME_SCALE", "1.0"))
+        )
+        self._width = (
+            width
+            if width is not None
+            else int(os.environ.get("UNITY_WIDTH", "1280"))
+        )
+        self._height = (
+            height
+            if height is not None
+            else int(os.environ.get("UNITY_HEIGHT", "720"))
+        )
+        self._quality_level = (
+            quality_level
+            if quality_level is not None
+            else int(os.environ.get("UNITY_QUALITY_LEVEL", "5"))
+        )
+        self._cache_dir = cache_dir or os.environ.get(
+            "UNITY_CACHE_DIR", PERSISTENT_CACHE_DIR
+        )
+        self._include_visual = False
+
+        # State tracking
+        self._state = UnityState(
+            episode_id=str(uuid4()),
+            step_count=0,
+            env_id=self._env_id,
+        )
+
+        # Ensure cache directory exists
+        os.makedirs(self._cache_dir, exist_ok=True)
+
+    def _load_environment(self, env_id: str) -> None:
+        """Load or switch to a Unity environment."""
+        # Close existing environment if any
+        if self._unity_env is not None:
+            try:
+                self._unity_env.close()
+            except Exception:
+                pass
+
+        # Import ML-Agents components
+        try:
+            from mlagents_envs.base_env import ActionTuple
+            from mlagents_envs.registry import default_registry
+            from mlagents_envs.registry.remote_registry_entry import RemoteRegistryEntry
+            from mlagents_envs.side_channel.engine_configuration_channel import (
+                EngineConfigurationChannel,
+            )
+        except ImportError as e:
+            raise ImportError(
+                "mlagents-envs is required. Install with: pip install mlagents-envs"
+            ) from e
+
+        # Create engine configuration channel
+        self._engine_channel = EngineConfigurationChannel()
+
+        # Check if environment is in registry
+        if env_id not in default_registry:
+            available = list(default_registry.keys())
+            raise ValueError(
+                f"Environment '{env_id}' not found. Available: {available}"
+            )
+
+        # Get registry entry and create with persistent cache
+        entry = default_registry[env_id]
+
+        # Create a new entry with our persistent cache directory
+        persistent_entry = RemoteRegistryEntry(
+            identifier=entry.identifier,
+            expected_reward=entry.expected_reward,
+            description=entry.description,
+            linux_url=getattr(entry, "_linux_url", None),
+            darwin_url=getattr(entry, "_darwin_url", None),
+            win_url=getattr(entry, "_win_url", None),
+            additional_args=getattr(entry, "_add_args", []),
+            tmp_dir=self._cache_dir,
+        )
+
+        # Create the environment
+        self._unity_env = persistent_entry.make(
+            no_graphics=self._no_graphics,
+            side_channels=[self._engine_channel],
+        )
+
+        # Configure engine settings
+        if not self._no_graphics:
+            self._engine_channel.set_configuration_parameters(
+                width=self._width,
+                height=self._height,
+                quality_level=self._quality_level,
+                time_scale=self._time_scale,
+            )
+        else:
+            self._engine_channel.set_configuration_parameters(
+                time_scale=self._time_scale
+            )
+
+        # Get behavior info
+        if not self._unity_env.behavior_specs:
+            self._unity_env.step()
+
+        self._behavior_name = list(self._unity_env.behavior_specs.keys())[0]
+        self._behavior_spec = self._unity_env.behavior_specs[self._behavior_name]
+
+        # Update state
+        self._env_id = env_id
+        self._state.env_id = env_id
+        self._state.behavior_name = self._behavior_name
+        self._state.action_spec = self._get_action_spec_info()
+        self._state.observation_spec = self._get_observation_spec_info()
+        self._state.available_envs = list(default_registry.keys())
+
+    def _get_action_spec_info(self) -> Dict[str, Any]:
+        """Get information about the action space."""
+        spec = self._behavior_spec.action_spec
+        return {
+            "is_discrete": spec.is_discrete(),
+            "is_continuous": spec.is_continuous(),
+            "discrete_size": spec.discrete_size,
+            "discrete_branches": list(spec.discrete_branches) if spec.is_discrete() else [],
+            "continuous_size": spec.continuous_size,
+        }
+
+    def _get_observation_spec_info(self) -> Dict[str, Any]:
+        """Get information about the observation space."""
+        specs = self._behavior_spec.observation_specs
+        obs_info = []
+        for i, spec in enumerate(specs):
+            obs_info.append({
+                "index": i,
+                "shape": list(spec.shape),
+                "dimension_property": str(spec.dimension_property),
+                "observation_type": str(spec.observation_type),
+            })
+        return {"observations": obs_info, "count": len(specs)}
+
+    def _get_observation(
+        self,
+        decision_steps=None,
+        terminal_steps=None,
+        reward: float = 0.0,
+        done: bool = False,
+    ) -> UnityObservation:
+        """Convert Unity observation to UnityObservation."""
+        vector_obs = []
+        visual_obs = []
+
+        # Determine which steps to use
+        if terminal_steps is not None and len(terminal_steps) > 0:
+            steps = terminal_steps
+            done = True
+            # Get reward from terminal step
+            if len(terminal_steps.agent_id) > 0:
+                reward = float(terminal_steps[terminal_steps.agent_id[0]].reward)
+        elif decision_steps is not None and len(decision_steps) > 0:
+            steps = decision_steps
+            # Get reward from decision step
+            if len(decision_steps.agent_id) > 0:
+                reward = float(decision_steps[decision_steps.agent_id[0]].reward)
+        else:
+            # No agents, return empty observation
+            return UnityObservation(
+                vector_observations=[],
+                visual_observations=None,
+                behavior_name=self._behavior_name or "",
+                done=done,
+                reward=reward,
+                action_spec_info=self._state.action_spec,
+                observation_spec_info=self._state.observation_spec,
+            )
+
+        # Process observations from first agent
+        for obs in steps.obs:
+            if len(obs.shape) == 2:
+                # Vector observation (agents, features)
+                vector_obs.extend(obs[0].tolist())
+            elif len(obs.shape) == 4 and self._include_visual:
+                # Visual observation (agents, height, width, channels)
+                img_array = (obs[0] * 255).astype(np.uint8)
+                # Encode as base64 PNG
+                try:
+                    from PIL import Image
+                    img = Image.fromarray(img_array)
+                    buffer = io.BytesIO()
+                    img.save(buffer, format="PNG")
+                    img_b64 = base64.b64encode(buffer.getvalue()).decode("utf-8")
+                    visual_obs.append(img_b64)
+                except ImportError:
+                    # PIL not available, skip visual observations
+                    pass
+
+        return UnityObservation(
+            vector_observations=vector_obs,
+            visual_observations=visual_obs if visual_obs else None,
+            behavior_name=self._behavior_name or "",
+            done=done,
+            reward=reward,
+            action_spec_info=self._state.action_spec,
+            observation_spec_info=self._state.observation_spec,
+        )
+
+    def reset(
+        self,
+        env_id: Optional[str] = None,
+        seed: Optional[int] = None,
+        include_visual: bool = False,
+        **kwargs,
+    ) -> UnityObservation:
+        """
+        Reset the environment and return initial observation.
+
+        Args:
+            env_id: Optionally switch to a different Unity environment.
+            seed: Random seed (not fully supported by Unity ML-Agents).
+            include_visual: If True, include visual observations in output.
+            **kwargs: Additional arguments (ignored).
+
+        Returns:
+            UnityObservation with initial state.
+        """
+        self._include_visual = include_visual
+
+        # Load or switch environment if needed
+        target_env = env_id or self._env_id
+        if self._unity_env is None or target_env != self._env_id:
+            self._load_environment(target_env)
+
+        # Reset the environment
+        self._unity_env.reset()
+
+        # Update state
+        self._state = UnityState(
+            episode_id=str(uuid4()),
+            step_count=0,
+            env_id=self._env_id,
+            behavior_name=self._behavior_name,
+            action_spec=self._state.action_spec,
+            observation_spec=self._state.observation_spec,
+            available_envs=self._state.available_envs,
+        )
+
+        # Get initial observation
+        decision_steps, terminal_steps = self._unity_env.get_steps(self._behavior_name)
+
+        return self._get_observation(
+            decision_steps=decision_steps,
+            terminal_steps=terminal_steps,
+            reward=0.0,
+            done=False,
+        )
+
+    def step(self, action: UnityAction) -> UnityObservation:
+        """
+        Execute one step in the environment.
+
+        Args:
+            action: UnityAction with discrete and/or continuous actions.
+
+        Returns:
+            UnityObservation with new state, reward, and done flag.
+        """
+        if self._unity_env is None:
+            raise RuntimeError("Environment not initialized. Call reset() first.")
+
+        from mlagents_envs.base_env import ActionTuple
+
+        # Get current decision steps to know how many agents
+        decision_steps, terminal_steps = self._unity_env.get_steps(self._behavior_name)
+
+        # Check if episode already ended
+        if len(terminal_steps) > 0:
+            return self._get_observation(
+                decision_steps=decision_steps,
+                terminal_steps=terminal_steps,
+                done=True,
+            )
+
+        n_agents = len(decision_steps)
+        if n_agents == 0:
+            # No agents need decisions, just step
+            self._unity_env.step()
+            self._state.step_count += 1
+            decision_steps, terminal_steps = self._unity_env.get_steps(self._behavior_name)
+            return self._get_observation(
+                decision_steps=decision_steps,
+                terminal_steps=terminal_steps,
+            )
+
+        # Build action tuple
+        action_tuple = ActionTuple()
+
+        # Handle discrete actions
+        if action.discrete_actions is not None:
+            discrete = np.array([action.discrete_actions] * n_agents, dtype=np.int32)
+            # Ensure correct shape (n_agents, n_branches)
+            if discrete.ndim == 1:
+                discrete = discrete.reshape(n_agents, -1)
+            action_tuple.add_discrete(discrete)
+        elif self._behavior_spec.action_spec.is_discrete():
+            # Default to no-op (action 0)
+            n_branches = self._behavior_spec.action_spec.discrete_size
+            discrete = np.zeros((n_agents, n_branches), dtype=np.int32)
+            action_tuple.add_discrete(discrete)
+
+        # Handle continuous actions
+        if action.continuous_actions is not None:
+            continuous = np.array([action.continuous_actions] * n_agents, dtype=np.float32)
+            if continuous.ndim == 1:
+                continuous = continuous.reshape(n_agents, -1)
+            action_tuple.add_continuous(continuous)
+        elif self._behavior_spec.action_spec.is_continuous():
+            # Default to zero actions
+            n_continuous = self._behavior_spec.action_spec.continuous_size
+            continuous = np.zeros((n_agents, n_continuous), dtype=np.float32)
+            action_tuple.add_continuous(continuous)
+
+        # Set actions and step
+        self._unity_env.set_actions(self._behavior_name, action_tuple)
+        self._unity_env.step()
+        self._state.step_count += 1
+
+        # Get new observation
+        decision_steps, terminal_steps = self._unity_env.get_steps(self._behavior_name)
+
+        return self._get_observation(
+            decision_steps=decision_steps,
+            terminal_steps=terminal_steps,
+        )
+
+    async def reset_async(
+        self,
+        env_id: Optional[str] = None,
+        seed: Optional[int] = None,
+        include_visual: bool = False,
+        **kwargs,
+    ) -> UnityObservation:
+        """
+        Async version of reset - runs in a thread to avoid blocking the event loop.
+
+        Unity ML-Agents environments can take 10-60+ seconds to initialize.
+        Running in a thread allows the event loop to continue processing
+        WebSocket keepalive pings during this time.
+        """
+        import asyncio
+
+        return await asyncio.to_thread(
+            self.reset,
+            env_id=env_id,
+            seed=seed,
+            include_visual=include_visual,
+            **kwargs,
+        )
+
+    async def step_async(self, action: UnityAction) -> UnityObservation:
+        """
+        Async version of step - runs in a thread to avoid blocking the event loop.
+
+        Although step() is usually fast, running in a thread ensures
+        the event loop remains responsive.
+        """
+        import asyncio
+
+        return await asyncio.to_thread(self.step, action)
+
+    @property
+    def state(self) -> UnityState:
+        """Get the current environment state."""
+        return self._state
+
+    def close(self) -> None:
+        """Close the Unity environment."""
+        unity_env = getattr(self, "_unity_env", None)
+        if unity_env is not None:
+            try:
+                unity_env.close()
+            except Exception:
+                pass
+            self._unity_env = None
+
+    def __del__(self):
+        """Cleanup on deletion."""
+        try:
+            self.close()
+        except Exception:
+            pass

models.py

@@ -0,0 +1,164 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Data models for the Unity ML-Agents Environment.
+
+The Unity environment wraps Unity ML-Agents environments (PushBlock, 3DBall,
+GridWorld, etc.) providing a unified interface for reinforcement learning.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import Field
+
+# Support both in-repo and standalone imports
+try:
+    # In-repo imports (when running from OpenEnv repository)
+    from openenv.core.env_server.types import Action, Observation, State
+except ImportError:
+    # Standalone imports (when environment is standalone with openenv from pip)
+    from openenv.core.env_server.types import Action, Observation, State
+
+
+class UnityAction(Action):
+    """
+    Action for Unity ML-Agents environments.
+
+    Supports both discrete and continuous action spaces. Unity environments
+    may use either or both types of actions:
+
+    - Discrete actions: Integer indices for categorical choices
+      (e.g., movement direction: 0=forward, 1=backward, 2=left, 3=right)
+    - Continuous actions: Float values typically in [-1, 1] range
+      (e.g., joint rotations, force magnitudes)
+
+    Example (PushBlock - discrete):
+        >>> action = UnityAction(discrete_actions=[3])  # Rotate left
+
+    Example (Walker - continuous):
+        >>> action = UnityAction(continuous_actions=[0.5, -0.3, 0.0, ...])
+
+    Attributes:
+        discrete_actions: List of discrete action indices for each action branch.
+            For PushBlock: [0-6] where 0=noop, 1=forward, 2=backward,
+            3=rotate_left, 4=rotate_right, 5=strafe_left, 6=strafe_right
+        continuous_actions: List of continuous action values, typically in [-1, 1].
+        metadata: Additional action parameters.
+    """
+
+    discrete_actions: Optional[List[int]] = Field(
+        default=None,
+        description="Discrete action indices for each action branch",
+    )
+    continuous_actions: Optional[List[float]] = Field(
+        default=None,
+        description="Continuous action values, typically in [-1, 1] range",
+    )
+
+
+class UnityObservation(Observation):
+    """
+    Observation from Unity ML-Agents environments.
+
+    Contains vector observations (sensor readings) and optionally visual
+    observations (rendered images). Most Unity environments provide vector
+    observations; visual observations are optional and must be requested.
+
+    Attributes:
+        vector_observations: Flattened array of all vector observations.
+            Size and meaning depends on the specific environment.
+            For PushBlock: 70 values from 14 ray-casts detecting walls/goals/blocks.
+        visual_observations: Optional list of base64-encoded images (PNG format).
+            Only included when include_visual=True in reset/step.
+        behavior_name: Name of the Unity behavior (agent type).
+        action_spec_info: Information about the action space for this environment.
+        observation_spec_info: Information about the observation space.
+    """
+
+    vector_observations: List[float] = Field(
+        default_factory=list,
+        description="Flattened vector observations from the environment",
+    )
+    visual_observations: Optional[List[str]] = Field(
+        default=None,
+        description="Base64-encoded PNG images (when include_visual=True)",
+    )
+    behavior_name: str = Field(
+        default="",
+        description="Name of the Unity behavior/agent type",
+    )
+    action_spec_info: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Information about the action space",
+    )
+    observation_spec_info: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Information about the observation space",
+    )
+
+
+class UnityState(State):
+    """
+    Extended state for Unity ML-Agents environments.
+
+    Provides additional metadata about the currently loaded environment,
+    including action and observation space specifications.
+
+    Attributes:
+        episode_id: Unique identifier for the current episode.
+        step_count: Number of steps taken in the current episode.
+        env_id: Identifier of the currently loaded Unity environment.
+        behavior_name: Name of the Unity behavior (agent type).
+        action_spec: Detailed specification of the action space.
+        observation_spec: Detailed specification of the observation space.
+        available_envs: List of available environment identifiers.
+    """
+
+    env_id: str = Field(
+        default="PushBlock",
+        description="Identifier of the loaded Unity environment",
+    )
+    behavior_name: str = Field(
+        default="",
+        description="Name of the Unity behavior/agent type",
+    )
+    action_spec: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Specification of the action space",
+    )
+    observation_spec: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Specification of the observation space",
+    )
+    available_envs: List[str] = Field(
+        default_factory=list,
+        description="List of available Unity environments",
+    )
+
+
+# Available Unity environments from the ML-Agents registry
+# These are pre-built environments that can be downloaded automatically
+AVAILABLE_UNITY_ENVIRONMENTS = [
+    "PushBlock",
+    "3DBall",
+    "3DBallHard",
+    "GridWorld",
+    "Basic",
+    "VisualPushBlock",
+    # Note: More environments may be available in newer versions of ML-Agents
+]
+
+# Action descriptions for PushBlock (most commonly used example)
+PUSHBLOCK_ACTIONS = {
+    0: "noop",
+    1: "forward",
+    2: "backward",
+    3: "rotate_left",
+    4: "rotate_right",
+    5: "strafe_left",
+    6: "strafe_right",
+}

openenv.yaml

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

pyproject.toml

@@ -0,0 +1,45 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-unity-env"
+version = "0.1.0"
+description = "Unity ML-Agents Environment for OpenEnv - wraps Unity environments like PushBlock, 3DBall, GridWorld"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv dependencies (installed from git for latest features)
+    "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git@v2.1.0",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0.0",
+    "uvicorn>=0.24.0",
+    "requests>=2.31.0",
+    # Unity ML-Agents dependencies (installed from source for latest features)
+    "mlagents-envs @ git+https://github.com/Unity-Technologies/ml-agents.git#subdirectory=ml-agents-envs",
+    # "mlagents @ git+https://github.com/Unity-Technologies/ml-agents.git#subdirectory=ml-agents",
+    "numpy>=1.20.0",
+    # Optional: for visual observations
+    "pillow>=9.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m unity_env.server.app
+server = "unity_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["unity_env", "unity_env.server"]
+package-dir = { "unity_env" = ".", "unity_env.server" = "server" }

server/Dockerfile

@@ -0,0 +1,66 @@
+# 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 Unity ML-Agents environment
+# Uses pip for package installation (no virtual environment)
+# Note: Using Python 3.10.12 specifically because ml-agents requires >=3.10.1,<=3.10.12
+# Note: Unity binaries are x86_64 only, so we force linux/amd64 platform
+
+FROM --platform=linux/amd64 python:3.10.12-slim AS builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy environment code
+COPY . /app/env
+
+WORKDIR /app/env
+
+# Install dependencies using pip
+# Note: mlagents packages are installed from git source via pyproject.toml
+RUN pip install --upgrade pip && \
+    pip install --no-cache-dir -e .
+
+# Final runtime stage
+FROM --platform=linux/amd64 python:3.10.12-slim
+
+WORKDIR /app
+
+# Install runtime dependencies (curl for healthcheck)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy installed packages from builder
+COPY --from=builder /usr/local/lib/python3.10/site-packages /usr/local/lib/python3.10/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy the environment code
+COPY . /app/env
+
+# Create cache directory for Unity binaries
+RUN mkdir -p /root/.mlagents-cache
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=60s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Note: Longer start period (60s) because Unity environment download may take time on first run
+
+# Run the FastAPI server
+# Note: workers=1 because Unity environments are not thread-safe
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

server/__init__.py

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

server/app.py

@@ -0,0 +1,84 @@
+# 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 Unity ML-Agents Environment.
+
+This module creates an HTTP server that exposes Unity ML-Agents environments
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 1
+
+    # Or run directly:
+    uv run --project . server
+
+Note: Unity environments are not thread-safe, so use workers=1.
+"""
+
+# Support multiple import scenarios
+try:
+    # In-repo imports (when running from OpenEnv repository root)
+    from openenv.core.env_server.http_server import create_app
+
+    from ..models import UnityAction, UnityObservation
+    from .unity_environment import UnityMLAgentsEnvironment
+except ImportError:
+    # openenv from pip
+    from openenv.core.env_server.http_server import create_app
+
+    try:
+        # Direct execution from envs/unity_env/ directory
+        import sys
+        from pathlib import Path
+
+        # Add parent directory to path for direct execution
+        _parent = str(Path(__file__).parent.parent)
+        if _parent not in sys.path:
+            sys.path.insert(0, _parent)
+        from models import UnityAction, UnityObservation
+        from server.unity_environment import UnityMLAgentsEnvironment
+    except ImportError:
+        try:
+            # Package installed as unity_env
+            from unity_env.models import UnityAction, UnityObservation
+            from unity_env.server.unity_environment import UnityMLAgentsEnvironment
+        except ImportError:
+            # Running from OpenEnv root with envs prefix
+            from envs.unity_env.models import UnityAction, UnityObservation
+            from envs.unity_env.server.unity_environment import UnityMLAgentsEnvironment
+
+# Create the app with web interface
+# Pass the class (factory) instead of an instance for WebSocket session support
+app = create_app(
+    UnityMLAgentsEnvironment,
+    UnityAction,
+    UnityObservation,
+    env_name="unity_env",
+)
+
+
+def main():
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        python -m envs.unity_env.server.app
+        openenv serve unity_env
+    """
+    import uvicorn
+
+    # Note: workers=1 because Unity environments are not thread-safe
+    uvicorn.run(app, host="0.0.0.0", port=8000, workers=1)
+
+
+if __name__ == "__main__":
+    main()

server/unity_environment.py

@@ -0,0 +1,554 @@
+# 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.
+
+"""
+Unity ML-Agents Environment Implementation.
+
+Wraps Unity ML-Agents environments (PushBlock, 3DBall, GridWorld, etc.)
+with the OpenEnv interface for standardized reinforcement learning.
+"""
+
+import base64
+import glob
+import hashlib
+import io
+import os
+from pathlib import Path
+from sys import platform
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+import numpy as np
+
+# Support multiple import scenarios
+try:
+    # In-repo imports (when running from OpenEnv repository root)
+    from openenv.core.env_server.interfaces import Environment
+
+    from ..models import UnityAction, UnityObservation, UnityState
+except ImportError:
+    # openenv from pip
+    from openenv.core.env_server.interfaces import Environment
+
+    try:
+        # Direct execution from envs/unity_env/ directory (imports from parent)
+        import sys
+        from pathlib import Path
+
+        # Add parent directory to path for direct execution
+        _parent = str(Path(__file__).parent.parent)
+        if _parent not in sys.path:
+            sys.path.insert(0, _parent)
+        from models import UnityAction, UnityObservation, UnityState
+    except ImportError:
+        try:
+            # Package installed as unity_env
+            from unity_env.models import UnityAction, UnityObservation, UnityState
+        except ImportError:
+            # Running from OpenEnv root with envs prefix
+            from envs.unity_env.models import UnityAction, UnityObservation, UnityState
+
+
+# Persistent cache directory to avoid re-downloading environment binaries
+PERSISTENT_CACHE_DIR = os.path.join(str(Path.home()), ".mlagents-cache")
+
+
+def get_cached_binary_path(cache_dir: str, name: str, url: str) -> Optional[str]:
+    """Check if binary is cached and return its path."""
+    if platform == "darwin":
+        extension = "*.app"
+    elif platform in ("linux", "linux2"):
+        extension = "*.x86_64"
+    elif platform == "win32":
+        extension = "*.exe"
+    else:
+        return None
+
+    bin_dir = os.path.join(cache_dir, "binaries")
+    url_hash = "-" + hashlib.md5(url.encode()).hexdigest()
+    search_path = os.path.join(bin_dir, name + url_hash, "**", extension)
+
+    candidates = glob.glob(search_path, recursive=True)
+    for c in candidates:
+        if "UnityCrashHandler64" not in c:
+            return c
+    return None
+
+
+class UnityMLAgentsEnvironment(Environment):
+    """
+    Wraps Unity ML-Agents environments with the OpenEnv interface.
+
+    This environment supports all Unity ML-Agents registry environments
+    including PushBlock, 3DBall, GridWorld, and more. Environments are
+    automatically downloaded on first use.
+
+    Features:
+    - Dynamic environment switching via reset(env_id="...")
+    - Support for both discrete and continuous action spaces
+    - Optional visual observations (base64-encoded images)
+    - Persistent caching to avoid re-downloading binaries
+    - Headless mode for faster training (no_graphics=True)
+
+    Example:
+        >>> env = UnityMLAgentsEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.vector_observations)
+        >>>
+        >>> # Take a random action
+        >>> obs = env.step(UnityAction(discrete_actions=[1]))  # Move forward
+        >>> print(obs.reward)
+
+    Example with different environment:
+        >>> env = UnityMLAgentsEnvironment(env_id="3DBall")
+        >>> obs = env.reset()
+        >>>
+        >>> # Or switch environment on reset
+        >>> obs = env.reset(env_id="PushBlock")
+    """
+
+    # Each WebSocket session gets its own environment instance
+    SUPPORTS_CONCURRENT_SESSIONS = False
+
+    def __init__(
+        self,
+        env_id: Optional[str] = None,
+        no_graphics: Optional[bool] = None,
+        time_scale: Optional[float] = None,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        quality_level: Optional[int] = None,
+        cache_dir: Optional[str] = None,
+    ):
+        """
+        Initialize the Unity ML-Agents environment.
+
+        Configuration can be provided via constructor arguments or environment
+        variables. Environment variables are used when constructor arguments
+        are not provided (useful for Docker deployment).
+
+        Args:
+            env_id: Identifier of the Unity environment to load.
+                Available: PushBlock, 3DBall, 3DBallHard, GridWorld, Basic
+                Env var: UNITY_ENV_ID (default: PushBlock)
+            no_graphics: If True, run in headless mode (faster training).
+                Env var: UNITY_NO_GRAPHICS (0 or 1, default: 0 = graphics enabled)
+            time_scale: Simulation speed multiplier.
+                Env var: UNITY_TIME_SCALE (default: 1.0)
+            width: Window width in pixels (when graphics enabled).
+                Env var: UNITY_WIDTH (default: 1280)
+            height: Window height in pixels (when graphics enabled).
+                Env var: UNITY_HEIGHT (default: 720)
+            quality_level: Graphics quality 0-5 (when graphics enabled).
+                Env var: UNITY_QUALITY_LEVEL (default: 5)
+            cache_dir: Directory to cache downloaded environment binaries.
+                Env var: UNITY_CACHE_DIR (default: ~/.mlagents-cache)
+        """
+        # Initialize cleanup-critical attributes first (for __del__ safety)
+        self._unity_env = None
+        self._behavior_name = None
+        self._behavior_spec = None
+        self._engine_channel = None
+
+        # Read from environment variables with defaults, allow constructor override
+        self._env_id = env_id or os.environ.get("UNITY_ENV_ID", "PushBlock")
+
+        # Handle no_graphics: default is False (graphics enabled)
+        if no_graphics is not None:
+            self._no_graphics = no_graphics
+        else:
+            env_no_graphics = os.environ.get("UNITY_NO_GRAPHICS", "0")
+            self._no_graphics = env_no_graphics.lower() in ("1", "true", "yes")
+
+        self._time_scale = (
+            time_scale
+            if time_scale is not None
+            else float(os.environ.get("UNITY_TIME_SCALE", "1.0"))
+        )
+        self._width = (
+            width
+            if width is not None
+            else int(os.environ.get("UNITY_WIDTH", "1280"))
+        )
+        self._height = (
+            height
+            if height is not None
+            else int(os.environ.get("UNITY_HEIGHT", "720"))
+        )
+        self._quality_level = (
+            quality_level
+            if quality_level is not None
+            else int(os.environ.get("UNITY_QUALITY_LEVEL", "5"))
+        )
+        self._cache_dir = cache_dir or os.environ.get(
+            "UNITY_CACHE_DIR", PERSISTENT_CACHE_DIR
+        )
+        self._include_visual = False
+
+        # State tracking
+        self._state = UnityState(
+            episode_id=str(uuid4()),
+            step_count=0,
+            env_id=self._env_id,
+        )
+
+        # Ensure cache directory exists
+        os.makedirs(self._cache_dir, exist_ok=True)
+
+    def _load_environment(self, env_id: str) -> None:
+        """Load or switch to a Unity environment."""
+        # Close existing environment if any
+        if self._unity_env is not None:
+            try:
+                self._unity_env.close()
+            except Exception:
+                pass
+
+        # Import ML-Agents components
+        try:
+            from mlagents_envs.base_env import ActionTuple
+            from mlagents_envs.registry import default_registry
+            from mlagents_envs.registry.remote_registry_entry import RemoteRegistryEntry
+            from mlagents_envs.side_channel.engine_configuration_channel import (
+                EngineConfigurationChannel,
+            )
+        except ImportError as e:
+            raise ImportError(
+                "mlagents-envs is required. Install with: pip install mlagents-envs"
+            ) from e
+
+        # Create engine configuration channel
+        self._engine_channel = EngineConfigurationChannel()
+
+        # Check if environment is in registry
+        if env_id not in default_registry:
+            available = list(default_registry.keys())
+            raise ValueError(
+                f"Environment '{env_id}' not found. Available: {available}"
+            )
+
+        # Get registry entry and create with persistent cache
+        entry = default_registry[env_id]
+
+        # Create a new entry with our persistent cache directory
+        persistent_entry = RemoteRegistryEntry(
+            identifier=entry.identifier,
+            expected_reward=entry.expected_reward,
+            description=entry.description,
+            linux_url=getattr(entry, "_linux_url", None),
+            darwin_url=getattr(entry, "_darwin_url", None),
+            win_url=getattr(entry, "_win_url", None),
+            additional_args=getattr(entry, "_add_args", []),
+            tmp_dir=self._cache_dir,
+        )
+
+        # Create the environment
+        self._unity_env = persistent_entry.make(
+            no_graphics=self._no_graphics,
+            side_channels=[self._engine_channel],
+        )
+
+        # Configure engine settings
+        if not self._no_graphics:
+            self._engine_channel.set_configuration_parameters(
+                width=self._width,
+                height=self._height,
+                quality_level=self._quality_level,
+                time_scale=self._time_scale,
+            )
+        else:
+            self._engine_channel.set_configuration_parameters(
+                time_scale=self._time_scale
+            )
+
+        # Get behavior info
+        if not self._unity_env.behavior_specs:
+            self._unity_env.step()
+
+        self._behavior_name = list(self._unity_env.behavior_specs.keys())[0]
+        self._behavior_spec = self._unity_env.behavior_specs[self._behavior_name]
+
+        # Update state
+        self._env_id = env_id
+        self._state.env_id = env_id
+        self._state.behavior_name = self._behavior_name
+        self._state.action_spec = self._get_action_spec_info()
+        self._state.observation_spec = self._get_observation_spec_info()
+        self._state.available_envs = list(default_registry.keys())
+
+    def _get_action_spec_info(self) -> Dict[str, Any]:
+        """Get information about the action space."""
+        spec = self._behavior_spec.action_spec
+        return {
+            "is_discrete": spec.is_discrete(),
+            "is_continuous": spec.is_continuous(),
+            "discrete_size": spec.discrete_size,
+            "discrete_branches": list(spec.discrete_branches) if spec.is_discrete() else [],
+            "continuous_size": spec.continuous_size,
+        }
+
+    def _get_observation_spec_info(self) -> Dict[str, Any]:
+        """Get information about the observation space."""
+        specs = self._behavior_spec.observation_specs
+        obs_info = []
+        for i, spec in enumerate(specs):
+            obs_info.append({
+                "index": i,
+                "shape": list(spec.shape),
+                "dimension_property": str(spec.dimension_property),
+                "observation_type": str(spec.observation_type),
+            })
+        return {"observations": obs_info, "count": len(specs)}
+
+    def _get_observation(
+        self,
+        decision_steps=None,
+        terminal_steps=None,
+        reward: float = 0.0,
+        done: bool = False,
+    ) -> UnityObservation:
+        """Convert Unity observation to UnityObservation."""
+        vector_obs = []
+        visual_obs = []
+
+        # Determine which steps to use
+        if terminal_steps is not None and len(terminal_steps) > 0:
+            steps = terminal_steps
+            done = True
+            # Get reward from terminal step
+            if len(terminal_steps.agent_id) > 0:
+                reward = float(terminal_steps[terminal_steps.agent_id[0]].reward)
+        elif decision_steps is not None and len(decision_steps) > 0:
+            steps = decision_steps
+            # Get reward from decision step
+            if len(decision_steps.agent_id) > 0:
+                reward = float(decision_steps[decision_steps.agent_id[0]].reward)
+        else:
+            # No agents, return empty observation
+            return UnityObservation(
+                vector_observations=[],
+                visual_observations=None,
+                behavior_name=self._behavior_name or "",
+                done=done,
+                reward=reward,
+                action_spec_info=self._state.action_spec,
+                observation_spec_info=self._state.observation_spec,
+            )
+
+        # Process observations from first agent
+        for obs in steps.obs:
+            if len(obs.shape) == 2:
+                # Vector observation (agents, features)
+                vector_obs.extend(obs[0].tolist())
+            elif len(obs.shape) == 4 and self._include_visual:
+                # Visual observation (agents, height, width, channels)
+                img_array = (obs[0] * 255).astype(np.uint8)
+                # Encode as base64 PNG
+                try:
+                    from PIL import Image
+                    img = Image.fromarray(img_array)
+                    buffer = io.BytesIO()
+                    img.save(buffer, format="PNG")
+                    img_b64 = base64.b64encode(buffer.getvalue()).decode("utf-8")
+                    visual_obs.append(img_b64)
+                except ImportError:
+                    # PIL not available, skip visual observations
+                    pass
+
+        return UnityObservation(
+            vector_observations=vector_obs,
+            visual_observations=visual_obs if visual_obs else None,
+            behavior_name=self._behavior_name or "",
+            done=done,
+            reward=reward,
+            action_spec_info=self._state.action_spec,
+            observation_spec_info=self._state.observation_spec,
+        )
+
+    def reset(
+        self,
+        env_id: Optional[str] = None,
+        seed: Optional[int] = None,
+        include_visual: bool = False,
+        **kwargs,
+    ) -> UnityObservation:
+        """
+        Reset the environment and return initial observation.
+
+        Args:
+            env_id: Optionally switch to a different Unity environment.
+            seed: Random seed (not fully supported by Unity ML-Agents).
+            include_visual: If True, include visual observations in output.
+            **kwargs: Additional arguments (ignored).
+
+        Returns:
+            UnityObservation with initial state.
+        """
+        self._include_visual = include_visual
+
+        # Load or switch environment if needed
+        target_env = env_id or self._env_id
+        if self._unity_env is None or target_env != self._env_id:
+            self._load_environment(target_env)
+
+        # Reset the environment
+        self._unity_env.reset()
+
+        # Update state
+        self._state = UnityState(
+            episode_id=str(uuid4()),
+            step_count=0,
+            env_id=self._env_id,
+            behavior_name=self._behavior_name,
+            action_spec=self._state.action_spec,
+            observation_spec=self._state.observation_spec,
+            available_envs=self._state.available_envs,
+        )
+
+        # Get initial observation
+        decision_steps, terminal_steps = self._unity_env.get_steps(self._behavior_name)
+
+        return self._get_observation(
+            decision_steps=decision_steps,
+            terminal_steps=terminal_steps,
+            reward=0.0,
+            done=False,
+        )
+
+    def step(self, action: UnityAction) -> UnityObservation:
+        """
+        Execute one step in the environment.
+
+        Args:
+            action: UnityAction with discrete and/or continuous actions.
+
+        Returns:
+            UnityObservation with new state, reward, and done flag.
+        """
+        if self._unity_env is None:
+            raise RuntimeError("Environment not initialized. Call reset() first.")
+
+        from mlagents_envs.base_env import ActionTuple
+
+        # Get current decision steps to know how many agents
+        decision_steps, terminal_steps = self._unity_env.get_steps(self._behavior_name)
+
+        # Check if episode already ended
+        if len(terminal_steps) > 0:
+            return self._get_observation(
+                decision_steps=decision_steps,
+                terminal_steps=terminal_steps,
+                done=True,
+            )
+
+        n_agents = len(decision_steps)
+        if n_agents == 0:
+            # No agents need decisions, just step
+            self._unity_env.step()
+            self._state.step_count += 1
+            decision_steps, terminal_steps = self._unity_env.get_steps(self._behavior_name)
+            return self._get_observation(
+                decision_steps=decision_steps,
+                terminal_steps=terminal_steps,
+            )
+
+        # Build action tuple
+        action_tuple = ActionTuple()
+
+        # Handle discrete actions
+        if action.discrete_actions is not None:
+            discrete = np.array([action.discrete_actions] * n_agents, dtype=np.int32)
+            # Ensure correct shape (n_agents, n_branches)
+            if discrete.ndim == 1:
+                discrete = discrete.reshape(n_agents, -1)
+            action_tuple.add_discrete(discrete)
+        elif self._behavior_spec.action_spec.is_discrete():
+            # Default to no-op (action 0)
+            n_branches = self._behavior_spec.action_spec.discrete_size
+            discrete = np.zeros((n_agents, n_branches), dtype=np.int32)
+            action_tuple.add_discrete(discrete)
+
+        # Handle continuous actions
+        if action.continuous_actions is not None:
+            continuous = np.array([action.continuous_actions] * n_agents, dtype=np.float32)
+            if continuous.ndim == 1:
+                continuous = continuous.reshape(n_agents, -1)
+            action_tuple.add_continuous(continuous)
+        elif self._behavior_spec.action_spec.is_continuous():
+            # Default to zero actions
+            n_continuous = self._behavior_spec.action_spec.continuous_size
+            continuous = np.zeros((n_agents, n_continuous), dtype=np.float32)
+            action_tuple.add_continuous(continuous)
+
+        # Set actions and step
+        self._unity_env.set_actions(self._behavior_name, action_tuple)
+        self._unity_env.step()
+        self._state.step_count += 1
+
+        # Get new observation
+        decision_steps, terminal_steps = self._unity_env.get_steps(self._behavior_name)
+
+        return self._get_observation(
+            decision_steps=decision_steps,
+            terminal_steps=terminal_steps,
+        )
+
+    async def reset_async(
+        self,
+        env_id: Optional[str] = None,
+        seed: Optional[int] = None,
+        include_visual: bool = False,
+        **kwargs,
+    ) -> UnityObservation:
+        """
+        Async version of reset - runs in a thread to avoid blocking the event loop.
+
+        Unity ML-Agents environments can take 10-60+ seconds to initialize.
+        Running in a thread allows the event loop to continue processing
+        WebSocket keepalive pings during this time.
+        """
+        import asyncio
+
+        return await asyncio.to_thread(
+            self.reset,
+            env_id=env_id,
+            seed=seed,
+            include_visual=include_visual,
+            **kwargs,
+        )
+
+    async def step_async(self, action: UnityAction) -> UnityObservation:
+        """
+        Async version of step - runs in a thread to avoid blocking the event loop.
+
+        Although step() is usually fast, running in a thread ensures
+        the event loop remains responsive.
+        """
+        import asyncio
+
+        return await asyncio.to_thread(self.step, action)
+
+    @property
+    def state(self) -> UnityState:
+        """Get the current environment state."""
+        return self._state
+
+    def close(self) -> None:
+        """Close the Unity environment."""
+        unity_env = getattr(self, "_unity_env", None)
+        if unity_env is not None:
+            try:
+                unity_env.close()
+            except Exception:
+                pass
+            self._unity_env = None
+
+    def __del__(self):
+        """Cleanup on deletion."""
+        try:
+            self.close()
+        except Exception:
+            pass

src/__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.
+
+"""EnvTorch: Standardized agentic execution environments."""

src/openenv/__init__.py

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

src/openenv/auto/__init__.py

@@ -0,0 +1,39 @@
+# 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 Auto Module
+===================
+
+Provides HuggingFace-style auto-discovery API for OpenEnv environments.
+
+This module enables automatic environment and action class loading without
+manual imports:
+
+    >>> from openenv import AutoEnv, AutoAction
+    >>>
+    >>> # Load environment from installed package or HuggingFace Hub
+    >>> env = AutoEnv.from_name("coding-env")
+    >>>
+    >>> # Get action class
+    >>> CodeAction = AutoAction.from_name("coding")
+    >>> action = CodeAction(code="print('Hello!')")
+
+Classes:
+    AutoEnv: Automatic environment client selection and instantiation
+    AutoAction: Automatic action class selection
+
+The auto-discovery system works by:
+1. Discovering installed openenv-* packages via importlib.metadata
+2. Loading environment manifests (openenv.yaml) from package resources
+3. Supporting HuggingFace Hub repositories for remote environments
+4. Caching discovery results for performance
+"""
+
+from .auto_action import AutoAction
+from .auto_env import AutoEnv
+
+__all__ = ["AutoEnv", "AutoAction"]

src/openenv/auto/_discovery.py

@@ -0,0 +1,584 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Environment Auto-Discovery System
+==================================
+
+This module provides automatic discovery of OpenEnv environments by:
+1. Discovering installed openenv-* packages using importlib.metadata
+2. Loading manifests (openenv.yaml) from package resources
+3. Caching results for performance
+4. Supporting HuggingFace Hub downloads
+
+This enables AutoEnv to work without coupling to src/envs/ directory.
+"""
+
+import importlib
+import importlib.metadata
+import importlib.resources
+import json
+import logging
+import re
+import tempfile
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Dict, Optional, Type, Any
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class EnvironmentInfo:
+    """
+    Rich information about a discovered environment.
+
+    Attributes:
+        env_key: Environment key (e.g., "echo", "coding")
+        name: Full environment name (e.g., "echo_env")
+        package_name: Package name (e.g., "openenv-echo_env")
+        version: Version string
+        description: Human-readable description
+        client_module_path: Full module path to client (e.g., "echo_env.client")
+        client_class_name: Client class name (e.g., "EchoEnv")
+        action_class_name: Action class name (e.g., "EchoAction")
+        observation_class_name: Observation class name (e.g., "EchoObservation")
+        default_image: Default Docker image name (e.g., "echo-env:latest")
+        spec_version: OpenEnv spec version (from openenv.yaml)
+        manifest: Original manifest data
+    """
+
+    env_key: str
+    name: str
+    package_name: str
+    version: str
+    description: str
+    client_module_path: str
+    client_class_name: str
+    action_class_name: str
+    observation_class_name: str
+    default_image: str
+    spec_version: Optional[int] = None
+    manifest: Optional[Dict[str, Any]] = None
+
+    def get_client_class(self) -> Type:
+        """
+        Dynamically import and return the client class.
+
+        Returns:
+            Client class (e.g., EchoEnv)
+
+        Raises:
+            ImportError: If module or class cannot be imported
+        """
+        try:
+            module = importlib.import_module(self.client_module_path)
+            return getattr(module, self.client_class_name)
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import {self.client_class_name} from {self.client_module_path}: {e}\n"
+                f"Make sure the package '{self.package_name}' is installed: "
+                f"pip install {self.package_name}"
+            ) from e
+        except AttributeError as e:
+            raise ImportError(
+                f"Class {self.client_class_name} not found in {self.client_module_path}: {e}"
+            ) from e
+
+    def get_action_class(self) -> Type:
+        """
+        Dynamically import and return the action class.
+
+        Returns:
+            Action class (e.g., EchoAction)
+
+        Raises:
+            ImportError: If module or class cannot be imported
+        """
+        try:
+            module = importlib.import_module(self.client_module_path)
+            return getattr(module, self.action_class_name)
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import {self.action_class_name} from {self.client_module_path}: {e}\n"
+                f"Make sure the package '{self.package_name}' is installed: "
+                f"pip install {self.package_name}"
+            ) from e
+        except AttributeError as e:
+            raise ImportError(
+                f"Class {self.action_class_name} not found in {self.client_module_path}: {e}"
+            ) from e
+
+    def get_observation_class(self) -> Type:
+        """
+        Dynamically import and return the observation class.
+
+        Returns:
+            Observation class (e.g., EchoObservation)
+
+        Raises:
+            ImportError: If module or class cannot be imported
+        """
+        try:
+            module = importlib.import_module(self.client_module_path)
+            return getattr(module, self.observation_class_name)
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import {self.observation_class_name} from {self.client_module_path}: {e}\n"
+                f"Make sure the package '{self.package_name}' is installed: "
+                f"pip install {self.package_name}"
+            ) from e
+        except AttributeError as e:
+            raise ImportError(
+                f"Class {self.observation_class_name} not found in {self.client_module_path}: {e}"
+            ) from e
+
+
+def _normalize_env_name(name: str) -> str:
+    """
+    Normalize environment name to standard format.
+
+    Args:
+        name: Input name (e.g., "echo", "echo-env", "echo_env")
+
+    Returns:
+        Normalized name (e.g., "echo_env")
+
+    Examples:
+        >>> _normalize_env_name("echo")
+        'echo_env'
+        >>> _normalize_env_name("echo-env")
+        'echo_env'
+        >>> _normalize_env_name("echo_env")
+        'echo_env'
+    """
+    # Remove common suffixes
+    name = re.sub(r"[-_]env$", "", name)
+    # Convert hyphens to underscores
+    name = name.replace("-", "_")
+    # Add _env suffix if not present
+    if not name.endswith("_env"):
+        name = f"{name}_env"
+    return name
+
+
+def _is_hub_url(name: str) -> bool:
+    """
+    Check if name is a HuggingFace Hub URL or repo ID.
+
+    Args:
+        name: Input name
+
+    Returns:
+        True if it looks like a Hub URL
+
+    Examples:
+        >>> _is_hub_url("meta-pytorch/echo_env")
+        True
+        >>> _is_hub_url("https://huggingface.co/meta-pytorch/echo_env")
+        True
+        >>> _is_hub_url("echo")
+        False
+    """
+    # Contains org/repo pattern or huggingface.co domain
+    return "/" in name or "huggingface.co" in name
+
+
+def _infer_class_name(env_name: str, class_type: str) -> str:
+    """
+    Infer class name from environment name using simple conventions.
+
+    Args:
+        env_name: Environment name (e.g., "echo_env")
+        class_type: Type of class ("client", "action", "observation")
+
+    Returns:
+        Inferred class name
+
+    Examples:
+        >>> _infer_class_name("echo_env", "client")
+        'EchoEnv'
+        >>> _infer_class_name("echo_env", "action")
+        'EchoAction'
+    """
+    # Remove _env suffix for base name
+    base_name = env_name.replace("_env", "")
+
+    # Convert to PascalCase
+    pascal_name = "".join(word.capitalize() for word in base_name.split("_"))
+
+    # Add suffix based on type
+    if class_type == "client":
+        return f"{pascal_name}Env"
+    elif class_type == "action":
+        return f"{pascal_name}Action"
+    elif class_type == "observation":
+        return f"{pascal_name}Observation"
+    else:
+        raise ValueError(f"Unknown class type: {class_type}")
+
+
+def _load_manifest_from_package(
+    package_name: str, module_name: str
+) -> Optional[Dict[str, Any]]:
+    """
+    Load openenv.yaml manifest from an installed package.
+
+    Args:
+        package_name: Package name (e.g., "openenv-echo_env")
+        module_name: Module name (e.g., "echo_env")
+
+    Returns:
+        Parsed manifest dictionary, or None if not found
+
+    """
+    try:
+        # Try to read openenv.yaml from package
+        if hasattr(importlib.resources, "files"):
+            # Python 3.9+
+            package_files = importlib.resources.files(module_name)
+            if (package_files / "openenv.yaml").is_file():
+                manifest_text = (package_files / "openenv.yaml").read_text()
+                return yaml.safe_load(manifest_text)
+        else:
+            # Python 3.7-3.8 fallback
+            with importlib.resources.open_text(module_name, "openenv.yaml") as f:
+                return yaml.safe_load(f)
+    except (FileNotFoundError, ModuleNotFoundError, AttributeError):
+        logger.debug(f"No openenv.yaml found in {module_name}")
+        return None
+    except Exception as e:
+        logger.warning(f"Failed to load openenv.yaml from {module_name}: {e}")
+        return None
+
+
+def _create_env_info_from_package(
+    package_name: str, module_name: str, version: str
+) -> Optional[EnvironmentInfo]:
+    """
+    Create EnvironmentInfo from an installed package.
+
+    Args:
+        package_name: Package name (e.g., "openenv-echo_env")
+        module_name: Module name (e.g., "echo_env")
+        version: Package version
+
+    Returns:
+        EnvironmentInfo instance, or None if invalid
+    """
+    # Load manifest
+    manifest = _load_manifest_from_package(package_name, module_name)
+
+    # Get environment name
+    if manifest and "name" in manifest:
+        env_name = manifest["name"]
+    else:
+        # Infer from module name
+        env_name = module_name
+
+    # Normalize to ensure _env suffix
+    if not env_name.endswith("_env"):
+        env_name = f"{env_name}_env"
+
+    # Determine env_key (e.g., "echo_env" → "echo")
+    env_key = env_name.replace("_env", "") if env_name.endswith("_env") else env_name
+
+    # Get description
+    description = (
+        manifest.get("description", f"{env_name} environment")
+        if manifest
+        else f"{env_name} environment"
+    )
+
+    # Get spec version
+    spec_version = manifest.get("spec_version") if manifest else None
+
+    # Determine class names
+    # Check if manifest has custom class names (custom format)
+    if manifest and "action" in manifest and "observation" in manifest:
+        # Custom format (like coding_env)
+        client_class_name = _infer_class_name(env_name, "client")
+        action_class_name = manifest.get(
+            "action", _infer_class_name(env_name, "action")
+        )
+        observation_class_name = manifest.get(
+            "observation", _infer_class_name(env_name, "observation")
+        )
+    else:
+        # Use conventions
+        client_class_name = _infer_class_name(env_name, "client")
+        action_class_name = _infer_class_name(env_name, "action")
+        observation_class_name = _infer_class_name(env_name, "observation")
+
+    # Module path is just module_name.client
+    client_module_path = f"{module_name}.client"
+
+    # Determine default Docker image name
+    image_name = env_name.replace("_", "-")
+    default_image = f"{image_name}:latest"
+
+    return EnvironmentInfo(
+        env_key=env_key,
+        name=env_name,
+        package_name=package_name,
+        version=version,
+        description=description,
+        client_module_path=client_module_path,
+        client_class_name=client_class_name,
+        action_class_name=action_class_name,
+        observation_class_name=observation_class_name,
+        default_image=default_image,
+        spec_version=spec_version,
+        manifest=manifest,
+    )
+
+
+class EnvironmentDiscovery:
+    """
+    Auto-discovery system for OpenEnv environments using installed packages.
+
+    This class discovers installed openenv-* packages and loads their metadata.
+    """
+
+    def __init__(self):
+        """Initialize discovery system."""
+        self._cache: Optional[Dict[str, EnvironmentInfo]] = None
+        self._cache_file = Path(tempfile.gettempdir()) / "openenv_discovery_cache.json"
+
+    def _discover_installed_packages(self) -> Dict[str, EnvironmentInfo]:
+        """
+        Discover all installed openenv-* packages.
+
+        Returns:
+            Dictionary mapping env_key to EnvironmentInfo
+        """
+        environments = {}
+
+        # Invalidate import caches to ensure we pick up newly installed packages
+        importlib.invalidate_caches()
+
+        # Get all installed packages
+        try:
+            distributions = importlib.metadata.distributions()
+        except Exception as e:
+            logger.warning(f"Failed to get installed packages: {e}")
+            return environments
+
+        # Filter for openenv-* packages (exclude openenv-core)
+        for dist in distributions:
+            package_name = dist.metadata["Name"]
+
+            if not package_name.startswith("openenv-"):
+                continue
+
+            if package_name == "openenv-core":
+                continue
+
+            # Get module name (e.g., "openenv-echo_env" → "echo_env")
+            module_name = package_name.replace("openenv-", "").replace("-", "_")
+
+            # Get version
+            version = dist.version
+
+            try:
+                # Create environment info
+                env_info = _create_env_info_from_package(
+                    package_name, module_name, version
+                )
+
+                if env_info:
+                    environments[env_info.env_key] = env_info
+                    logger.debug(
+                        f"Discovered environment: {env_info.env_key} ({package_name})"
+                    )
+
+            except Exception as e:
+                logger.warning(f"Failed to load environment from {package_name}: {e}")
+                continue
+
+        return environments
+
+    def _load_cache(self) -> Optional[Dict[str, EnvironmentInfo]]:
+        """
+        Load cached discovery results.
+
+        Returns:
+            Dictionary of env_key -> EnvironmentInfo, or None if cache invalid
+        """
+        if not self._cache_file.exists():
+            return None
+
+        try:
+            with open(self._cache_file, "r") as f:
+                cache_data = json.load(f)
+
+            # Reconstruct EnvironmentInfo objects
+            cache = {}
+            for env_key, env_data in cache_data.items():
+                cache[env_key] = EnvironmentInfo(**env_data)
+
+            return cache
+        except Exception as e:
+            logger.warning(f"Failed to load discovery cache: {e}")
+            return None
+
+    def _save_cache(self, environments: Dict[str, EnvironmentInfo]) -> None:
+        """
+        Save discovery results to cache.
+
+        Args:
+            environments: Dictionary of env_key -> EnvironmentInfo
+        """
+        try:
+            cache_data = {}
+            for env_key, env_info in environments.items():
+                cache_data[env_key] = asdict(env_info)
+
+            with open(self._cache_file, "w") as f:
+                json.dump(cache_data, f, indent=2)
+
+        except Exception as e:
+            logger.warning(f"Failed to save discovery cache: {e}")
+
+    def discover(self, use_cache: bool = True) -> Dict[str, EnvironmentInfo]:
+        """
+        Discover all installed OpenEnv environments.
+
+        Args:
+            use_cache: If True, try to load from cache first
+
+        Returns:
+            Dictionary mapping env_key to EnvironmentInfo
+
+        Examples:
+            >>> discovery = EnvironmentDiscovery()
+            >>> envs = discovery.discover()
+            >>> print(envs.keys())
+            dict_keys(['echo', 'coding', ...])
+        """
+        # Try to load from memory cache first
+        if use_cache and self._cache is not None:
+            return self._cache
+
+        # Try to load from file cache
+        if use_cache:
+            cached = self._load_cache()
+            if cached is not None:
+                self._cache = cached
+                return self._cache
+
+        # Discover from installed packages
+        environments = self._discover_installed_packages()
+
+        # Save to cache
+        self._save_cache(environments)
+        self._cache = environments
+
+        return environments
+
+    def get_environment(self, env_key: str) -> Optional[EnvironmentInfo]:
+        """
+        Get information about a specific environment.
+
+        Args:
+            env_key: Environment key (e.g., "echo", "coding")
+
+        Returns:
+            EnvironmentInfo if found, None otherwise
+
+        Examples:
+            >>> discovery = EnvironmentDiscovery()
+            >>> env = discovery.get_environment("echo")
+            >>> print(env.client_class_name)
+            'EchoEnv'
+        """
+        environments = self.discover()
+        return environments.get(env_key)
+
+    def get_environment_by_name(self, name: str) -> Optional[EnvironmentInfo]:
+        """
+        Get environment info by flexible name matching.
+
+        Args:
+            name: Environment name (e.g., "echo", "echo-env", "echo_env")
+
+        Returns:
+            EnvironmentInfo if found, None otherwise
+        """
+        # Normalize name to env_key
+        normalized = _normalize_env_name(name)
+        env_key = normalized.replace("_env", "")
+
+        return self.get_environment(env_key)
+
+    def list_environments(self) -> None:
+        """
+        Print a formatted list of all discovered environments.
+
+        Examples:
+            >>> discovery = EnvironmentDiscovery()
+            >>> discovery.list_environments()
+            Available OpenEnv Environments:
+            ----------------------------------------------------------------------
+              echo           : Echo Environment (v0.1.0) - openenv-echo_env
+              coding         : Coding Environment (v0.1.0) - openenv-coding_env
+              ...
+        """
+        environments = self.discover()
+
+        print("Available OpenEnv Environments:")
+        print("-" * 70)
+
+        if not environments:
+            print("  No OpenEnv environments found.")
+            print("  Install environments with: pip install openenv-<env-name>")
+        else:
+            for env_key in sorted(environments.keys()):
+                env = environments[env_key]
+                print(f"  {env_key:<15}: {env.description} (v{env.version})")
+                print(f"                   Package: {env.package_name}")
+
+        print("-" * 70)
+        print(f"Total: {len(environments)} environments")
+
+    def clear_cache(self) -> None:
+        """Clear the discovery cache."""
+        if self._cache_file.exists():
+            self._cache_file.unlink()
+        self._cache = None
+
+
+# Global discovery instance
+_global_discovery: Optional[EnvironmentDiscovery] = None
+
+
+def get_discovery() -> EnvironmentDiscovery:
+    """
+    Get or create the global discovery instance.
+
+    Returns:
+        Global EnvironmentDiscovery instance
+
+    Examples:
+        >>> discovery = get_discovery()
+        >>> envs = discovery.discover()
+    """
+    global _global_discovery
+
+    if _global_discovery is None:
+        _global_discovery = EnvironmentDiscovery()
+
+    return _global_discovery
+
+
+def reset_discovery() -> None:
+    """Reset the global discovery instance (useful for testing)."""
+    global _global_discovery
+    if _global_discovery is not None:
+        _global_discovery.clear_cache()
+    _global_discovery = None

src/openenv/auto/auto_action.py

@@ -0,0 +1,276 @@
+# 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.
+
+"""
+AutoAction - Automatic Action Class Selection
+==============================================
+
+AutoAction provides a HuggingFace-style API for automatically retrieving the
+correct Action class from installed packages or HuggingFace Hub.
+
+This module simplifies working with environment actions by automatically
+detecting and returning the appropriate Action class without requiring
+manual imports.
+
+Example:
+    >>> from openenv import AutoEnv, AutoAction
+    >>>
+    >>> # Get Action class from environment name
+    >>> CodeAction = AutoAction.from_env("coding")
+    >>> action = CodeAction(code="print('Hello!')")
+    >>>
+    >>> # From HuggingFace Hub
+    >>> CodeAction = AutoAction.from_env("meta-pytorch/coding-env")
+    >>>
+    >>> # Use with AutoEnv
+    >>> env = AutoEnv.from_env("coding-env")
+    >>> result = env.step(action)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Type, Dict, Any
+
+from ._discovery import get_discovery, _is_hub_url
+from .auto_env import AutoEnv
+
+logger = logging.getLogger(__name__)
+
+
+class AutoAction:
+    """
+    AutoAction automatically retrieves the correct Action class based on
+    environment names or HuggingFace Hub repositories.
+
+    This class follows the HuggingFace AutoModel pattern, making it easy to
+    get the right Action class without needing to know which module to import.
+
+    The class provides factory methods that look up the Action class and
+    return the class (not an instance) for you to instantiate.
+
+    Example:
+        >>> # From installed package
+        >>> CodeAction = AutoAction.from_env("coding")
+        >>> action = CodeAction(code="print('test')")
+        >>>
+        >>> # From HuggingFace Hub
+        >>> CodeAction = AutoAction.from_env("meta-pytorch/coding-env")
+        >>> action = CodeAction(code="print('test')")
+        >>>
+        >>> # Use with AutoEnv for a complete workflow
+        >>> env = AutoEnv.from_env("coding-env")
+        >>> ActionClass = AutoAction.from_env("coding-env")
+        >>> action = ActionClass(code="print('Hello, AutoAction!')")
+        >>> result = env.step(action)
+
+    Note:
+        AutoAction is not meant to be instantiated directly. Use the class
+        method from_env() instead.
+    """
+
+    def __init__(self):
+        """AutoAction should not be instantiated directly. Use class methods instead."""
+        raise TypeError(
+            "AutoAction is a factory class and should not be instantiated directly. "
+            "Use AutoAction.from_hub() or AutoAction.from_env() instead."
+        )
+
+    @classmethod
+    def from_env(cls, name: str, skip_install: bool = False) -> Type:
+        """
+        Get the Action class from environment name or HuggingFace Hub repository.
+
+        This method automatically:
+        1. Checks if the name is a HuggingFace Hub URL/repo ID
+        2. If Hub: downloads and installs the environment package
+        3. If local: looks up the installed openenv-* package
+        4. Imports and returns the Action class
+
+        Args:
+            name: Environment name or HuggingFace Hub repo ID
+                  Examples:
+                  - "coding" / "coding-env" / "coding_env"
+                  - "meta-pytorch/coding-env" (Hub repo ID)
+                  - "https://huggingface.co/meta-pytorch/coding-env" (Hub URL)
+            skip_install: If True, skip package installation and return
+                GenericAction class instead. Use this when working with
+                GenericEnvClient to avoid installing remote packages.
+
+        Returns:
+            Action class (not an instance!). Returns GenericAction when
+            skip_install=True.
+
+        Raises:
+            ValueError: If environment not found (only when skip_install=False)
+            ImportError: If environment package is not installed (only when skip_install=False)
+
+        Examples:
+            >>> # From installed package
+            >>> CodeAction = AutoAction.from_env("coding-env")
+            >>> action = CodeAction(code="print('Hello!')")
+            >>>
+            >>> # From HuggingFace Hub
+            >>> CodeAction = AutoAction.from_env("meta-pytorch/coding-env")
+            >>> action = CodeAction(code="print('Hello!')")
+            >>>
+            >>> # Skip installation, use GenericAction (for GenericEnvClient)
+            >>> ActionClass = AutoAction.from_env("user/repo", skip_install=True)
+            >>> action = ActionClass(code="print('Hello!')")  # Returns GenericAction
+            >>>
+            >>> # Different name formats
+            >>> EchoAction = AutoAction.from_env("echo")
+            >>> EchoAction = AutoAction.from_env("echo-env")
+            >>> EchoAction = AutoAction.from_env("echo_env")
+        """
+        # If skip_install is True, return GenericAction without any package lookup
+        if skip_install:
+            from openenv.core.generic_client import GenericAction
+
+            logger.info(
+                f"Returning GenericAction for '{name}' (skip_install=True). "
+                f"Use keyword arguments to create actions: GenericAction(code='...')"
+            )
+            return GenericAction
+
+        # Check if it's a HuggingFace Hub URL or repo ID
+        if _is_hub_url(name):
+            # Ensure package is installed (reuse AutoEnv logic, downloads only if needed)
+            env_name = AutoEnv._ensure_package_from_hub(name)
+        else:
+            env_name = name
+
+        # Get environment info from discovery
+        discovery = get_discovery()
+        env_info = discovery.get_environment_by_name(env_name)
+
+        if not env_info:
+            # Environment not found - provide helpful error message
+            available_envs = discovery.discover()
+
+            if not available_envs:
+                raise ValueError(
+                    "No OpenEnv environments found.\n"
+                    "Install an environment with: pip install openenv-<env-name>\n"
+                    "Or specify a HuggingFace Hub repository: AutoAction.from_env('openenv/echo_env')"
+                )
+
+            # Try to suggest similar environment names
+            from difflib import get_close_matches
+
+            env_keys = list(available_envs.keys())
+            suggestions = get_close_matches(env_name, env_keys, n=3, cutoff=0.6)
+
+            error_msg = f"Unknown environment '{env_name}'.\n"
+            if suggestions:
+                error_msg += f"Did you mean: {', '.join(suggestions)}?\n"
+            error_msg += f"Available environments: {', '.join(sorted(env_keys))}"
+
+            raise ValueError(error_msg)
+
+        # Get the action class
+        try:
+            action_class = env_info.get_action_class()
+            return action_class
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import action class for '{env_name}'.\n"
+                f"Package '{env_info.package_name}' appears to be installed but the module cannot be imported.\n"
+                f"Try reinstalling: pip install --force-reinstall {env_info.package_name}\n"
+                f"Original error: {e}"
+            ) from e
+
+    @classmethod
+    def from_hub(cls, env_name: str, skip_install: bool = False) -> Type:
+        """
+        Get the Action class from environment name.
+
+        This is an alias for from_env() for backward compatibility and clarity.
+
+        Args:
+            env_name: Environment name (e.g., "coding", "echo")
+            skip_install: If True, skip package installation and return
+                GenericAction class instead.
+
+        Returns:
+            Action class (not an instance!)
+
+        Examples:
+            >>> CodeAction = AutoAction.from_hub("coding")
+            >>> action = CodeAction(code="print('Hello!')")
+        """
+        return cls.from_env(env_name, skip_install=skip_install)
+
+    @classmethod
+    def get_action_info(cls, name: str) -> Dict[str, Any]:
+        """
+        Get detailed information about an action class.
+
+        Args:
+            name: Environment name
+
+        Returns:
+            Dictionary with action class metadata
+
+        Raises:
+            ValueError: If environment not found
+
+        Examples:
+            >>> info = AutoAction.get_action_info("coding")
+            >>> print(info['action_class'])
+            'CodingAction'
+            >>> print(info['module'])
+            'coding_env.client'
+        """
+        discovery = get_discovery()
+        env_info = discovery.get_environment_by_name(name)
+
+        if not env_info:
+            raise ValueError(f"Unknown environment: {name}")
+
+        return {
+            "env_key": env_info.env_key,
+            "env_name": env_info.name,
+            "package": env_info.package_name,
+            "action_class": env_info.action_class_name,
+            "observation_class": env_info.observation_class_name,
+            "module": env_info.client_module_path,
+        }
+
+    @classmethod
+    def list_actions(cls) -> None:
+        """
+        Print a formatted list of all available action classes.
+
+        This discovers all installed openenv-* packages and displays
+        their action class information in a user-friendly format.
+
+        Examples:
+            >>> AutoAction.list_actions()
+            Available Action Classes:
+            ----------------------------------------------------------------------
+              echo           : EchoAction (from openenv-echo-env)
+              coding         : CodingAction (from openenv-coding_env)
+            ----------------------------------------------------------------------
+            Total: 2 action classes
+        """
+        discovery = get_discovery()
+        environments = discovery.discover()
+
+        print("Available Action Classes:")
+        print("-" * 70)
+
+        if not environments:
+            print("  No OpenEnv environments found.")
+            print("  Install environments with: pip install openenv-<env-name>")
+        else:
+            for env_key in sorted(environments.keys()):
+                env = environments[env_key]
+                print(f"  {env_key:<15}: {env.action_class_name}")
+                print(f"                   Package: {env.package_name}")
+
+        print("-" * 70)
+        print(f"Total: {len(environments)} action classes")

src/openenv/auto/auto_env.py

@@ -0,0 +1,896 @@
+# 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.
+
+"""
+AutoEnv - Automatic Environment Selection
+==========================================
+
+AutoEnv provides a HuggingFace-style API for automatically selecting and
+instantiating the correct environment client from installed packages or
+HuggingFace Hub.
+
+This module simplifies environment creation by automatically detecting the
+environment type from the name and instantiating the appropriate client class.
+
+Example:
+    >>> from openenv import AutoEnv, AutoAction
+    >>>
+    >>> # From installed package
+    >>> env = AutoEnv.from_env("coding-env")
+    >>>
+    >>> # From HuggingFace Hub
+    >>> env = AutoEnv.from_env("meta-pytorch/coding-env")
+    >>>
+    >>> # With configuration
+    >>> env = AutoEnv.from_env("coding", env_vars={"DEBUG": "1"})
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+import shutil
+import subprocess
+import sys
+import requests
+from typing import Any, Optional, TYPE_CHECKING, Dict
+
+from ._discovery import get_discovery, _is_hub_url
+from openenv.core.utils import run_async_safely
+
+
+if TYPE_CHECKING:
+    from openenv.core.containers.runtime import ContainerProvider
+    from openenv.core.env_client import EnvClient
+
+logger = logging.getLogger(__name__)
+
+# Cache for repo ID → env_name mapping to avoid redundant downloads
+_hub_env_name_cache: Dict[str, str] = {}
+
+# Environment variable to skip user confirmation for remote installs
+OPENENV_TRUST_REMOTE_CODE = "OPENENV_TRUST_REMOTE_CODE"
+
+
+def _has_uv() -> bool:
+    """Check if uv is available in the system."""
+    return shutil.which("uv") is not None
+
+
+def _get_pip_command() -> list[str]:
+    """
+    Get the appropriate pip command (uv pip or pip).
+
+    Returns:
+        List of command parts for pip installation
+    """
+    if _has_uv():
+        return ["uv", "pip"]
+    return [sys.executable, "-m", "pip"]
+
+
+def _confirm_remote_install(repo_id: str) -> bool:
+    """
+    Ask user for confirmation before installing remote code.
+
+    This is a security measure since we're executing code from the internet.
+
+    Args:
+        repo_id: The HuggingFace repo ID being installed
+
+    Returns:
+        True if user confirms, False otherwise
+    """
+    # Check environment variable for automated/CI environments
+    if os.environ.get(OPENENV_TRUST_REMOTE_CODE, "").lower() in ("1", "true", "yes"):
+        logger.info("Skipping confirmation (OPENENV_TRUST_REMOTE_CODE is set)")
+        return True
+
+    # Check if we're in an interactive terminal
+    if not sys.stdin.isatty():
+        logger.warning(
+            "Cannot prompt for confirmation in non-interactive mode. "
+            "Set OPENENV_TRUST_REMOTE_CODE=1 to allow remote installs."
+        )
+        return False
+
+    print(f"\n{'=' * 60}")
+    print("⚠️  SECURITY WARNING: Remote Code Installation")
+    print(f"{'=' * 60}")
+    print("You are about to install code from a remote repository:")
+    print(f"  Repository: {repo_id}")
+    print(f"  Source: https://huggingface.co/spaces/{repo_id}")
+    print("\nThis will execute code from the internet on your machine.")
+    print("Only proceed if you trust the source.")
+    print(f"{'=' * 60}\n")
+
+    try:
+        response = input("Do you want to proceed? [y/N]: ").strip().lower()
+        return response in ("y", "yes")
+    except (EOFError, KeyboardInterrupt):
+        print("\nInstallation cancelled.")
+        return False
+
+
+class AutoEnv:
+    """
+    AutoEnv automatically selects and instantiates the correct environment client
+    based on environment names or HuggingFace Hub repositories.
+
+    This class follows the HuggingFace AutoModel pattern, making it easy to work
+    with different environments without needing to import specific client classes.
+
+    The class provides factory methods that:
+    1. Check if name is a HuggingFace Hub URL/repo ID
+    2. If Hub: download and install the environment package
+    3. If local: look up the installed openenv-* package
+    4. Import and instantiate the client class
+
+    Example:
+        >>> # From installed package
+        >>> env = AutoEnv.from_env("coding-env")
+        >>>
+        >>> # From HuggingFace Hub
+        >>> env = AutoEnv.from_env("meta-pytorch/coding-env")
+        >>>
+        >>> # List available environments
+        >>> AutoEnv.list_environments()
+
+    Note:
+        AutoEnv is not meant to be instantiated directly. Use the class method
+        from_env() instead.
+    """
+
+    def __init__(self):
+        """AutoEnv should not be instantiated directly. Use class methods instead."""
+        raise TypeError(
+            "AutoEnv is a factory class and should not be instantiated directly. "
+            "Use AutoEnv.from_hub() or AutoEnv.from_env() instead."
+        )
+
+    @classmethod
+    def _resolve_space_url(cls, repo_id: str) -> str:
+        """
+        Resolve HuggingFace Space repo ID to Space URL.
+
+        Args:
+            repo_id: HuggingFace repo ID (e.g., "wukaixingxp/coding-env-test")
+
+        Returns:
+            Space URL (e.g., "https://wukaixingxp-coding-env-test.hf.space")
+
+        Examples:
+            >>> AutoEnv._resolve_space_url("wukaixingxp/coding-env-test")
+            'https://wukaixingxp-coding-env-test.hf.space'
+        """
+        # Clean up repo_id if it's a full URL
+        if "huggingface.co" in repo_id:
+            # Extract org/repo from URL
+            # https://huggingface.co/wukaixingxp/coding-env-test -> wukaixingxp/coding-env-test
+            parts = repo_id.split("/")
+            if len(parts) >= 2:
+                repo_id = f"{parts[-2]}/{parts[-1]}"
+
+        # Convert user/space-name to user-space-name.hf.space
+        space_slug = repo_id.replace("/", "-")
+        return f"https://{space_slug}.hf.space"
+
+    @classmethod
+    def _is_local_url(cls, url: str) -> bool:
+        """
+        Check if a URL points to a local server.
+
+        Args:
+            url: URL to check
+
+        Returns:
+            True if URL is localhost or 127.0.0.1, False otherwise
+
+        Examples:
+            >>> AutoEnv._is_local_url("http://localhost:8000")
+            True
+            >>> AutoEnv._is_local_url("http://127.0.0.1:8000")
+            True
+            >>> AutoEnv._is_local_url("https://example.com")
+            False
+        """
+        url_lower = url.lower()
+        return "localhost" in url_lower or "127.0.0.1" in url_lower
+
+    @classmethod
+    def _check_server_availability(cls, base_url: str, timeout: float = 2.0) -> bool:
+        """
+        Check if a server at the given URL is running and accessible.
+
+        Args:
+            base_url: Server base URL to check
+            timeout: Request timeout in seconds
+
+        Returns:
+            True if server is accessible, False otherwise
+
+        Examples:
+            >>> AutoEnv._check_server_availability("http://localhost:8000")
+            True  # if server is running
+        """
+        try:
+            # Bypass proxy for localhost to avoid proxy issues
+            proxies = None
+            if cls._is_local_url(base_url):
+                proxies = {"http": None, "https": None}
+
+            # Try to access the health endpoint
+            response = requests.get(
+                f"{base_url}/health", timeout=timeout, proxies=proxies
+            )
+            if response.status_code == 200:
+                return True
+
+            # If health endpoint doesn't exist, try root endpoint
+            response = requests.get(base_url, timeout=timeout, proxies=proxies)
+            return response.status_code == 200
+        except (requests.RequestException, Exception) as e:
+            logger.debug(f"Server {base_url} not accessible: {e}")
+            return False
+
+    @classmethod
+    def _check_space_availability(cls, space_url: str, timeout: float = 5.0) -> bool:
+        """
+        Check if HuggingFace Space is running and accessible.
+
+        Args:
+            space_url: Space URL to check
+            timeout: Request timeout in seconds
+
+        Returns:
+            True if Space is accessible, False otherwise
+
+        Examples:
+            >>> AutoEnv._check_space_availability("https://wukaixingxp-coding-env-test.hf.space")
+            True
+        """
+        try:
+            # Try to access the health endpoint
+            response = requests.get(f"{space_url}/health", timeout=timeout)
+            if response.status_code == 200:
+                return True
+
+            # If health endpoint doesn't exist, try root endpoint
+            response = requests.get(space_url, timeout=timeout)
+            return response.status_code == 200
+        except (requests.RequestException, Exception) as e:
+            logger.debug(f"Space {space_url} not accessible: {e}")
+            return False
+
+    @classmethod
+    def _get_hub_git_url(cls, repo_id: str) -> str:
+        """
+        Get the git URL for a HuggingFace Space.
+
+        Args:
+            repo_id: HuggingFace repo ID (e.g., "wukaixingxp/coding-env-test")
+
+        Returns:
+            Git URL for pip installation (e.g., "git+https://huggingface.co/spaces/wukaixingxp/coding-env-test")
+        """
+        # Clean up repo_id if it's a full URL
+        if "huggingface.co" in repo_id:
+            parts = repo_id.split("/")
+            if len(parts) >= 2:
+                repo_id = f"{parts[-2]}/{parts[-1]}"
+
+        return f"git+https://huggingface.co/spaces/{repo_id}"
+
+    @classmethod
+    def _install_from_hub(cls, repo_id: str, trust_remote_code: bool = False) -> str:
+        """
+        Install environment package directly from HuggingFace Hub using git+.
+
+        This is the preferred method as it avoids downloading the entire repo
+        and uses pip/uv's native git support.
+
+        Args:
+            repo_id: HuggingFace repo ID (e.g., "wukaixingxp/coding-env-test")
+            trust_remote_code: If True, skip user confirmation
+
+        Returns:
+            Package name that was installed
+
+        Raises:
+            ValueError: If installation fails or user declines
+        """
+        # Security check - confirm with user before installing remote code
+        if not trust_remote_code and not _confirm_remote_install(repo_id):
+            raise ValueError(
+                "Installation cancelled by user.\n"
+                "To allow remote installs without prompting, set OPENENV_TRUST_REMOTE_CODE=1"
+            )
+
+        git_url = cls._get_hub_git_url(repo_id)
+        pip_cmd = _get_pip_command()
+        pip_name = "uv pip" if pip_cmd[0] == "uv" else "pip"
+
+        logger.info(f"Installing from HuggingFace Space using {pip_name}: {repo_id}")
+        logger.info(f"Command: {' '.join(pip_cmd)} install {git_url}")
+
+        try:
+            result = subprocess.run(
+                [*pip_cmd, "install", git_url],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+
+            # Try to extract package name from pip output
+            # Look for "Successfully installed <package-name>-<version>"
+            for line in result.stdout.split("\n"):
+                if "Successfully installed" in line:
+                    # Parse package name from the line
+                    parts = line.replace("Successfully installed", "").strip().split()
+                    for part in parts:
+                        if part.startswith("openenv-"):
+                            # Remove version suffix (e.g., "openenv-coding_env-0.1.0" -> "openenv-coding_env")
+                            # Check if last segment looks like a version number
+                            last_segment = part.rsplit("-", 1)[-1]
+                            if last_segment.replace(".", "").isdigit():
+                                package_name = "-".join(part.rsplit("-", 1)[:-1])
+                            else:
+                                package_name = part
+                            logger.info(f"Successfully installed: {package_name}")
+                            return package_name
+
+            # Fallback: try to determine package name from repo_id
+            # Convention: repo name like "coding-env-test" -> package "openenv-coding_env"
+            env_name = repo_id.split("/")[-1]  # Get repo name from "user/repo"
+            env_name = env_name.replace("-", "_")
+            if not env_name.endswith("_env"):
+                env_name = f"{env_name}_env"
+            package_name = f"openenv-{env_name}"
+
+            logger.info(f"Installed (inferred package name): {package_name}")
+            return package_name
+
+        except subprocess.CalledProcessError as e:
+            error_msg = e.stderr or e.stdout or str(e)
+            raise ValueError(
+                f"Failed to install environment from HuggingFace Space: {repo_id}\n"
+                f"Command: {' '.join(pip_cmd)} install {git_url}\n"
+                f"Error: {error_msg}\n"
+                f"Make sure the repository exists and contains a valid Python package."
+            ) from e
+
+    @classmethod
+    def _is_package_installed(cls, package_name: str) -> bool:
+        """
+        Check if a package is already installed.
+
+        Args:
+            package_name: Package name (e.g., "openenv-coding_env")
+
+        Returns:
+            True if installed, False otherwise
+        """
+        try:
+            import importlib.metadata
+
+            importlib.metadata.distribution(package_name)
+            return True
+        except importlib.metadata.PackageNotFoundError:
+            return False
+
+    @classmethod
+    def _ensure_package_from_hub(
+        cls, name: str, trust_remote_code: bool = False
+    ) -> str:
+        """
+        Ensure package from HuggingFace Hub is installed.
+
+        Uses git+ URLs for direct installation without downloading the entire repo.
+        Prompts user for confirmation before installing remote code.
+
+        Args:
+            name: HuggingFace repo ID (e.g., "wukaixingxp/coding-env-test")
+            trust_remote_code: If True, skip user confirmation
+
+        Returns:
+            Environment name (e.g., "coding_env")
+        """
+        global _hub_env_name_cache
+
+        # Check if we already resolved this repo ID
+        if name in _hub_env_name_cache:
+            env_name = _hub_env_name_cache[name]
+            logger.debug(f"Using cached env name for {name}: {env_name}")
+            return env_name
+
+        # Try to infer expected package name from repo ID
+        # Convention: repo "user/coding-env" -> package "openenv-coding_env"
+        repo_name = name.split("/")[-1] if "/" in name else name
+        expected_env_name = repo_name.replace("-", "_")
+        if not expected_env_name.endswith("_env"):
+            expected_env_name = f"{expected_env_name}_env"
+        expected_package_name = f"openenv-{expected_env_name}"
+
+        # Check if already installed
+        if cls._is_package_installed(expected_package_name):
+            logger.info(f"Package already installed: {expected_package_name}")
+            # Clear and refresh discovery cache to make sure it's detected
+            get_discovery().clear_cache()
+            get_discovery().discover(use_cache=False)
+            # Cache the result
+            _hub_env_name_cache[name] = expected_env_name
+            return expected_env_name
+
+        # Not installed, install using git+ URL
+        logger.info(f"Package not found locally, installing from Hub: {name}")
+
+        # Track existing packages before installation
+        get_discovery().clear_cache()
+        existing_envs = set(get_discovery().discover(use_cache=False).keys())
+
+        # Install the package
+        cls._install_from_hub(name, trust_remote_code=trust_remote_code)
+
+        # Clear discovery cache to pick up the newly installed package
+        try:
+            importlib.invalidate_caches()
+        except Exception:
+            pass
+        get_discovery().clear_cache()
+        discovered_envs = get_discovery().discover(use_cache=False)
+
+        # Find the newly installed environment by comparing before/after
+        new_envs = set(discovered_envs.keys()) - existing_envs
+
+        if new_envs:
+            # Use the first newly discovered environment
+            env_name = next(iter(new_envs))
+            logger.info(f"Found newly installed environment: '{env_name}'")
+        else:
+            # Fallback: try to find by matching module patterns
+            # Look for any env that might match the repo name pattern
+            repo_name = name.split("/")[-1] if "/" in name else name
+            repo_base = (
+                repo_name.replace("-", "_").replace("_env", "").replace("_test", "")
+            )
+
+            env_name = None
+            for env_key, env_info in discovered_envs.items():
+                # Check if env_key is a prefix/substring match
+                if env_key in repo_base or repo_base.startswith(env_key):
+                    env_name = env_key
+                    logger.info(
+                        f"Found matching environment '{env_name}' for repo '{name}'"
+                    )
+                    break
+
+            if env_name is None:
+                # Last resort: use inferred name from repo
+                env_name = repo_name.replace("-", "_")
+                if not env_name.endswith("_env"):
+                    env_name = f"{env_name}_env"
+                # Strip to get env_key
+                env_name = env_name.replace("_env", "")
+                logger.warning(
+                    f"Could not find newly installed environment for repo '{name}', "
+                    f"using inferred name: {env_name}"
+                )
+
+        # Cache the result to avoid redundant installs
+        _hub_env_name_cache[name] = env_name
+
+        return env_name
+
+    @classmethod
+    def from_env(
+        cls,
+        name: str,
+        base_url: Optional[str] = None,
+        docker_image: Optional[str] = None,
+        container_provider: Optional[ContainerProvider] = None,
+        wait_timeout: float = 30.0,
+        env_vars: Optional[Dict[str, str]] = None,
+        trust_remote_code: bool = False,
+        skip_install: bool = False,
+        **kwargs: Any,
+    ) -> "EnvClient":
+        """
+        Create an environment client from a name or HuggingFace Hub repository.
+
+        This method automatically:
+        1. Checks if the name is a HuggingFace Hub URL/repo ID
+        2. If Hub: installs the environment package using git+ URL
+        3. If local: looks up the installed openenv-* package
+        4. Imports the client class and instantiates it
+
+        Args:
+            name: Environment name or HuggingFace Hub repo ID
+                  Examples:
+                  - "coding" / "coding-env" / "coding_env"
+                  - "meta-pytorch/coding-env" (Hub repo ID)
+                  - "https://huggingface.co/meta-pytorch/coding-env" (Hub URL)
+            base_url: Optional base URL for HTTP connection
+            docker_image: Optional Docker image name (overrides default)
+            container_provider: Optional container provider
+            wait_timeout: Timeout for container startup (seconds)
+            env_vars: Optional environment variables for the container
+            trust_remote_code: If True, skip user confirmation when installing
+                from HuggingFace Hub. Can also be set via OPENENV_TRUST_REMOTE_CODE
+                environment variable.
+            skip_install: If True, skip package installation and return a
+                GenericEnvClient for remote environments. Useful when you only
+                want to connect to a running server without installing any
+                remote code. When True:
+                - If base_url is provided: connects directly using GenericEnvClient
+                - If HF Space is running: connects to Space using GenericEnvClient
+                - If HF Space is not running: uses Docker from HF registry
+            **kwargs: Additional arguments passed to the client class
+
+        Returns:
+            Instance of the environment client class
+
+        Raises:
+            ValueError: If environment not found or cannot be loaded
+            ImportError: If environment package is not installed
+
+        Examples:
+            >>> # From installed package
+            >>> env = AutoEnv.from_env("coding-env")
+            >>>
+            >>> # From HuggingFace Hub
+            >>> env = AutoEnv.from_env("meta-pytorch/coding-env")
+            >>>
+            >>> # With custom Docker image
+            >>> env = AutoEnv.from_env("coding", docker_image="my-coding-env:v2")
+            >>>
+            >>> # With environment variables
+            >>> env = AutoEnv.from_env(
+            ...     "dipg",
+            ...     env_vars={"DIPG_DATASET_PATH": "/data/dipg"}
+            ... )
+            >>>
+            >>> # Skip package installation, use GenericEnvClient
+            >>> env = AutoEnv.from_env(
+            ...     "user/my-env",
+            ...     skip_install=True
+            ... )
+        """
+        from openenv.core import GenericEnvClient
+
+        # Handle skip_install mode - return GenericEnvClient without package installation
+        if skip_install:
+            # If base_url is provided, connect directly
+            if base_url:
+                if cls._check_server_availability(base_url):
+                    logger.info(
+                        f"Using GenericEnvClient for {base_url} (skip_install=True)"
+                    )
+                    return GenericEnvClient(base_url=base_url, **kwargs)
+                else:
+                    raise ConnectionError(
+                        f"Server not available at {base_url}. "
+                        f"Please ensure the server is running."
+                    )
+
+            # If it's a Hub URL, try to connect to Space or use Docker
+            if _is_hub_url(name):
+                space_url = cls._resolve_space_url(name)
+                logger.info(f"Checking if HuggingFace Space is accessible: {space_url}")
+
+                if cls._check_space_availability(space_url):
+                    logger.info(
+                        f"Using GenericEnvClient for Space {space_url} (skip_install=True)"
+                    )
+                    return GenericEnvClient(base_url=space_url, **kwargs)
+                else:
+                    # Space not running, use Docker from HF registry
+                    logger.info(
+                        f"Space not running at {space_url}, "
+                        f"using GenericEnvClient with HF Docker registry"
+                    )
+                    return run_async_safely(
+                        GenericEnvClient.from_env(
+                            name,
+                            use_docker=True,
+                            provider=container_provider,
+                            env_vars=env_vars or {},
+                            **kwargs,
+                        )
+                    )
+
+            # For local environments with skip_install, we need docker_image
+            if docker_image:
+                logger.info(
+                    f"Using GenericEnvClient with Docker image {docker_image} "
+                    f"(skip_install=True)"
+                )
+                return run_async_safely(
+                    GenericEnvClient.from_docker_image(
+                        image=docker_image,
+                        provider=container_provider,
+                        wait_timeout=wait_timeout,
+                        env_vars=env_vars or {},
+                        **kwargs,
+                    )
+                )
+            else:
+                raise ValueError(
+                    f"Cannot use skip_install=True for local environment '{name}' "
+                    f"without providing base_url or docker_image. "
+                    f"For local environments, either:\n"
+                    f"  1. Provide base_url to connect to a running server\n"
+                    f"  2. Provide docker_image to start a container\n"
+                    f"  3. Set skip_install=False to use the installed package"
+                )
+
+        # Check if it's a HuggingFace Hub URL or repo ID
+        if _is_hub_url(name):
+            # Try to connect to Space directly first
+            space_url = cls._resolve_space_url(name)
+            logger.info(f"Checking if HuggingFace Space is accessible: {space_url}")
+
+            space_is_available = cls._check_space_availability(space_url)
+
+            if space_is_available and base_url is None:
+                # Space is accessible! We'll connect directly without Docker
+                logger.info(f"Space is accessible at: {space_url}")
+                logger.info("Installing package for client code (no Docker needed)...")
+
+                # Ensure package is installed (uses git+ URL)
+                env_name = cls._ensure_package_from_hub(
+                    name, trust_remote_code=trust_remote_code
+                )
+
+                # Set base_url to connect to remote Space
+                base_url = space_url
+                logger.info("Will connect to remote Space (no local Docker)")
+            else:
+                # Space not accessible or user provided explicit base_url
+                if not space_is_available:
+                    logger.info(f"Space not accessible at {space_url}")
+                    logger.info("Falling back to local Docker mode...")
+
+                # Ensure package is installed (uses git+ URL)
+                env_name = cls._ensure_package_from_hub(
+                    name, trust_remote_code=trust_remote_code
+                )
+        else:
+            env_name = name
+
+        # Get environment info from discovery
+        discovery = get_discovery()
+        env_info = discovery.get_environment_by_name(env_name)
+
+        if not env_info:
+            # Environment not found - provide helpful error message
+            available_envs = discovery.discover()
+
+            if not available_envs:
+                raise ValueError(
+                    "No OpenEnv environments found.\n"
+                    "Install an environment with: pip install openenv-<env-name>\n"
+                    "Or specify a HuggingFace Hub repository: AutoEnv.from_env('openenv/echo_env')"
+                )
+
+            # Try to suggest similar environment names
+            from difflib import get_close_matches
+
+            env_keys = list(available_envs.keys())
+            suggestions = get_close_matches(env_name, env_keys, n=3, cutoff=0.6)
+
+            error_msg = f"Unknown environment '{env_name}'.\n"
+            if suggestions:
+                error_msg += f"Did you mean: {', '.join(suggestions)}?\n"
+            error_msg += f"Available environments: {', '.join(sorted(env_keys))}"
+
+            raise ValueError(error_msg)
+
+        # Get the client class
+        try:
+            client_class = env_info.get_client_class()
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import environment client for '{env_name}'.\n"
+                f"Package '{env_info.package_name}' appears to be installed but the module cannot be imported.\n"
+                f"Try reinstalling: pip install --force-reinstall {env_info.package_name}\n"
+                f"Original error: {e}"
+            ) from e
+
+        # Determine Docker image to use
+        if docker_image is None:
+            docker_image = env_info.default_image
+
+        # Create client instance
+        try:
+            if base_url:
+                # Check if the server at base_url is available
+                is_local = cls._is_local_url(base_url)
+                server_available = cls._check_server_availability(base_url)
+
+                if server_available:
+                    # Server is running, connect directly
+                    logger.info(
+                        f"✅ Server available at {base_url}, connecting directly"
+                    )
+                    return client_class(base_url=base_url, provider=None, **kwargs)
+                elif is_local:
+                    # Local server not running, auto-start Docker container
+                    logger.info(f"❌ Server not available at {base_url}")
+                    logger.info(f"🐳 Auto-starting Docker container: {docker_image}")
+                    return run_async_safely(
+                        client_class.from_docker_image(
+                            image=docker_image,
+                            provider=container_provider,
+                            wait_timeout=wait_timeout,
+                            env_vars=env_vars or {},
+                            **kwargs,
+                        )
+                    )
+                else:
+                    # Remote server not available, cannot auto-start
+                    raise ConnectionError(
+                        f"Remote server not available at {base_url}. "
+                        f"Please ensure the server is running."
+                    )
+            else:
+                # No base_url provided, start new Docker container
+                return run_async_safely(
+                    client_class.from_docker_image(
+                        image=docker_image,
+                        provider=container_provider,
+                        wait_timeout=wait_timeout,
+                        env_vars=env_vars or {},
+                        **kwargs,
+                    )
+                )
+        except Exception as e:
+            raise ValueError(
+                f"Failed to create environment client for '{env_name}'.\n"
+                f"Client class: {client_class.__name__}\n"
+                f"Docker image: {docker_image}\n"
+                f"Error: {e}"
+            ) from e
+
+    @classmethod
+    def from_hub(
+        cls,
+        name: str,
+        base_url: Optional[str] = None,
+        docker_image: Optional[str] = None,
+        container_provider: Optional["ContainerProvider"] = None,
+        wait_timeout: float = 30.0,
+        env_vars: Optional[Dict[str, str]] = None,
+        trust_remote_code: bool = False,
+        skip_install: bool = False,
+        **kwargs: Any,
+    ) -> "EnvClient":
+        """
+        Create an environment client from a name or HuggingFace Hub repository.
+
+        This is an alias for from_env() for backward compatibility.
+
+        Args:
+            name: Environment name or HuggingFace Hub repo ID
+            base_url: Optional base URL for HTTP connection
+            docker_image: Optional Docker image name (overrides default)
+            container_provider: Optional container provider
+            wait_timeout: Timeout for container startup (seconds)
+            env_vars: Optional environment variables for the container
+            trust_remote_code: If True, skip user confirmation when installing
+                from HuggingFace Hub
+            skip_install: If True, skip package installation and return a
+                GenericEnvClient for remote environments
+            **kwargs: Additional arguments passed to the client class
+
+        Returns:
+            Instance of the environment client class
+
+        Examples:
+            >>> env = AutoEnv.from_hub("coding-env")
+            >>> env = AutoEnv.from_hub("meta-pytorch/coding-env")
+        """
+        return cls.from_env(
+            name=name,
+            base_url=base_url,
+            docker_image=docker_image,
+            container_provider=container_provider,
+            wait_timeout=wait_timeout,
+            env_vars=env_vars,
+            trust_remote_code=trust_remote_code,
+            skip_install=skip_install,
+            **kwargs,
+        )
+
+    @classmethod
+    def get_env_class(cls, name: str):
+        """
+        Get the environment client class without instantiating it.
+
+        Args:
+            name: Environment name
+
+        Returns:
+            The environment client class
+
+        Raises:
+            ValueError: If environment not found
+
+        Examples:
+            >>> CodingEnv = AutoEnv.get_env_class("coding")
+            >>> # Now you can instantiate it yourself
+            >>> env = CodingEnv(base_url="http://localhost:8000")
+        """
+        discovery = get_discovery()
+        env_info = discovery.get_environment_by_name(name)
+
+        if not env_info:
+            raise ValueError(f"Unknown environment: {name}")
+
+        return env_info.get_client_class()
+
+    @classmethod
+    def get_env_info(cls, name: str) -> Dict[str, Any]:
+        """
+        Get detailed information about an environment.
+
+        Args:
+            name: Environment name
+
+        Returns:
+            Dictionary with environment metadata
+
+        Raises:
+            ValueError: If environment not found
+
+        Examples:
+            >>> info = AutoEnv.get_env_info("coding")
+            >>> print(info['description'])
+            'Coding environment for OpenEnv'
+            >>> print(info['default_image'])
+            'coding-env:latest'
+        """
+        discovery = get_discovery()
+        env_info = discovery.get_environment_by_name(name)
+
+        if not env_info:
+            raise ValueError(f"Unknown environment: {name}")
+
+        return {
+            "env_key": env_info.env_key,
+            "name": env_info.name,
+            "package": env_info.package_name,
+            "version": env_info.version,
+            "description": env_info.description,
+            "env_class": env_info.client_class_name,
+            "action_class": env_info.action_class_name,
+            "observation_class": env_info.observation_class_name,
+            "module": env_info.client_module_path,
+            "default_image": env_info.default_image,
+            "spec_version": env_info.spec_version,
+        }
+
+    @classmethod
+    def list_environments(cls) -> None:
+        """
+        Print a formatted list of all available environments.
+
+        This discovers all installed openenv-* packages and displays
+        their metadata in a user-friendly format.
+
+        Examples:
+            >>> AutoEnv.list_environments()
+            Available OpenEnv Environments:
+            ----------------------------------------------------------------------
+              echo           : Echo Environment (v0.1.0)
+                               Package: openenv-echo-env
+              coding         : Coding Environment (v0.1.0)
+                               Package: openenv-coding_env
+            ----------------------------------------------------------------------
+            Total: 2 environments
+        """
+        discovery = get_discovery()
+        discovery.list_environments()

src/openenv/cli/__init__.py

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

src/openenv/cli/__main__.py

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

src/openenv/cli/_cli_utils.py

@@ -0,0 +1,79 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""CLI utilities for OpenEnv command-line interface."""
+
+from pathlib import Path
+from typing import List
+
+from rich.console import Console
+
+# Create a console instance for CLI output
+console = Console()
+
+
+def validate_env_structure(env_dir: Path, strict: bool = False) -> List[str]:
+    """
+    Validate that the directory follows OpenEnv environment structure.
+
+    Args:
+        env_dir: Path to environment directory
+        strict: If True, enforce all optional requirements
+
+    Returns:
+        List of validation warnings (empty if all checks pass)
+
+    Raises:
+        FileNotFoundError: If required files are missing
+    """
+    warnings = []
+
+    # Required files
+    required_files = [
+        "openenv.yaml",
+        "__init__.py",
+        "client.py",
+        "models.py",
+        "README.md",
+    ]
+
+    for file in required_files:
+        if not (env_dir / file).exists():
+            raise FileNotFoundError(f"Required file missing: {file}")
+
+    # Dockerfile: must exist in server/ or at env root
+    has_root_dockerfile = (env_dir / "Dockerfile").exists()
+    has_server_dockerfile = (env_dir / "server" / "Dockerfile").exists()
+
+    if not has_root_dockerfile and not has_server_dockerfile:
+        raise FileNotFoundError(
+            "Required file missing: server/Dockerfile or Dockerfile at env root"
+        )
+
+    # When no root Dockerfile, require the traditional server/ layout
+    if not has_root_dockerfile:
+        server_dir = env_dir / "server"
+        if not server_dir.exists() or not server_dir.is_dir():
+            raise FileNotFoundError("Required directory missing: server/")
+
+        for file in ["server/__init__.py", "server/app.py"]:
+            if not (env_dir / file).exists():
+                raise FileNotFoundError(f"Required file missing: {file}")
+
+    # Check for dependency management (pyproject.toml required)
+    has_pyproject = (env_dir / "pyproject.toml").exists()
+
+    if not has_pyproject:
+        raise FileNotFoundError(
+            "No dependency specification found. 'pyproject.toml' is required."
+        )
+
+    # Warnings for recommended structure
+
+    if not (env_dir / "outputs").exists():
+        warnings.append("Recommended directory missing: outputs/")
+
+    return warnings

src/openenv/cli/_validation.py

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

src/openenv/cli/commands/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""OpenEnv CLI commands."""
+
+from . import build, fork, init, push, serve, validate
+
+__all__ = ["build", "fork", "init", "push", "serve", "validate"]

src/openenv/cli/commands/build.py

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

src/openenv/cli/commands/fork.py

@@ -0,0 +1,197 @@
+# 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.
+
+"""Fork (duplicate) a Hugging Face Space using the Hub API."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from huggingface_hub import HfApi, login, whoami
+
+from .._cli_utils import console
+
+app = typer.Typer(
+    help="Fork (duplicate) an OpenEnv environment on Hugging Face to your account"
+)
+
+
+def _parse_key_value(s: str) -> tuple[str, str]:
+    """Parse KEY=VALUE string. Raises BadParameter if no '='."""
+    if "=" not in s:
+        raise typer.BadParameter(
+            f"Expected KEY=VALUE format, got: {s!r}. "
+            "Use --set-env KEY=VALUE or --set-secret KEY=VALUE"
+        )
+    key, _, value = s.partition("=")
+    key = key.strip()
+    if not key:
+        raise typer.BadParameter(f"Empty key in: {s!r}")
+    return key, value.strip()
+
+
+def _ensure_hf_authenticated() -> str:
+    """Ensure user is authenticated with Hugging Face. Returns username."""
+    try:
+        user_info = whoami()
+        if isinstance(user_info, dict):
+            username = (
+                user_info.get("name")
+                or user_info.get("fullname")
+                or user_info.get("username")
+            )
+        else:
+            username = (
+                getattr(user_info, "name", None)
+                or getattr(user_info, "fullname", None)
+                or getattr(user_info, "username", None)
+            )
+        if not username:
+            raise ValueError("Could not extract username from whoami response")
+        console.print(f"[bold green]✓[/bold green] Authenticated as: {username}")
+        return username
+    except Exception:
+        console.print(
+            "[bold yellow]Not authenticated with Hugging Face. Please login...[/bold yellow]"
+        )
+        try:
+            login()
+            user_info = whoami()
+            if isinstance(user_info, dict):
+                username = (
+                    user_info.get("name")
+                    or user_info.get("fullname")
+                    or user_info.get("username")
+                )
+            else:
+                username = (
+                    getattr(user_info, "name", None)
+                    or getattr(user_info, "fullname", None)
+                    or getattr(user_info, "username", None)
+                )
+            if not username:
+                raise ValueError("Could not extract username from whoami response")
+            console.print(f"[bold green]✓[/bold green] Authenticated as: {username}")
+            return username
+        except Exception as e:
+            raise typer.BadParameter(
+                f"Hugging Face authentication failed: {e}. Please run login manually."
+            ) from e
+
+
+@app.command()
+def fork(
+    source_space: Annotated[
+        str,
+        typer.Argument(
+            help="Source Space ID in format 'owner/space-name' (e.g. org/my-openenv-space)"
+        ),
+    ],
+    repo_id: Annotated[
+        str | None,
+        typer.Option(
+            "--repo-id",
+            "-r",
+            help="Target repo ID for the fork (default: created under your account with same name)",
+        ),
+    ] = None,
+    private: Annotated[
+        bool,
+        typer.Option("--private", help="Create the forked Space as private"),
+    ] = False,
+    set_env: Annotated[
+        list[str],
+        typer.Option(
+            "--set-env",
+            "-e",
+            help="Set Space variable (public). Can be repeated. Format: KEY=VALUE",
+        ),
+    ] = [],
+    set_secret: Annotated[
+        list[str],
+        typer.Option(
+            "--set-secret",
+            "--secret",
+            "-s",
+            help="Set Space secret. Can be repeated. Format: KEY=VALUE",
+        ),
+    ] = [],
+    hardware: Annotated[
+        str | None,
+        typer.Option(
+            "--hardware",
+            "-H",
+            help="Request hardware (e.g. t4-medium, cpu-basic). See Hub docs for options.",
+        ),
+    ] = None,
+) -> None:
+    """
+    Fork (duplicate) a Hugging Face Space to your account using the Hub API.
+
+    Uses the Hugging Face duplicate_space API. You can set environment variables
+    and secrets, and request hardware/storage/sleep time at creation time.
+
+    Examples:
+        $ openenv fork owner/source-space
+        $ openenv fork owner/source-space --private
+        $ openenv fork owner/source-space --repo-id myuser/my-fork
+        $ openenv fork owner/source-space --set-env MODEL_ID=user/model --set-secret HF_TOKEN=hf_xxx
+        $ openenv fork owner/source-space --hardware t4-medium
+    """
+    if "/" not in source_space or source_space.count("/") != 1:
+        raise typer.BadParameter(
+            f"Invalid source Space ID: {source_space!r}. Expected format: 'owner/space-name'"
+        )
+
+    _ensure_hf_authenticated()
+    api = HfApi()
+
+    # Build kwargs for duplicate_space (only pass what we have)
+    dup_kwargs: dict = {
+        "from_id": source_space,
+        "private": private,
+    }
+    if set_env:
+        dup_kwargs["variables"] = [
+            {"key": k, "value": v} for k, v in (_parse_key_value(x) for x in set_env)
+        ]
+    if set_secret:
+        dup_kwargs["secrets"] = [
+            {"key": k, "value": v} for k, v in (_parse_key_value(x) for x in set_secret)
+        ]
+    # HF API requires hardware when duplicating; default to free cpu-basic
+    dup_kwargs["hardware"] = hardware if hardware is not None else "cpu-basic"
+    if repo_id is not None:
+        if "/" not in repo_id or repo_id.count("/") != 1:
+            raise typer.BadParameter(
+                f"Invalid --repo-id: {repo_id!r}. Expected format: 'username/repo-name'"
+            )
+        dup_kwargs["to_id"] = repo_id
+
+    console.print(f"[bold cyan]Forking Space {source_space}...[/bold cyan]")
+    try:
+        result = api.duplicate_space(**dup_kwargs)
+    except Exception as e:
+        console.print(f"[bold red]✗[/bold red] Fork failed: {e}")
+        raise typer.Exit(1) from e
+
+    # result is RepoUrl (str-like) or similar; get repo_id for display
+    if hasattr(result, "repo_id"):
+        new_repo_id = result.repo_id
+    elif isinstance(result, str):
+        # URL like https://huggingface.co/spaces/owner/name -> owner/name
+        if "/spaces/" in result:
+            new_repo_id = result.split("/spaces/")[-1].rstrip("/")
+        else:
+            new_repo_id = result
+    else:
+        new_repo_id = getattr(result, "repo_id", str(result))
+
+    console.print("[bold green]✓[/bold green] Space forked successfully")
+    console.print(
+        f"[bold]Space URL:[/bold] https://huggingface.co/spaces/{new_repo_id}"
+    )

src/openenv/cli/commands/init.py

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

src/openenv/cli/commands/push.py

@@ -0,0 +1,718 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Push an OpenEnv environment to Hugging Face Spaces."""
+
+from __future__ import annotations
+
+import shutil
+import sys
+import tempfile
+from fnmatch import fnmatch
+from pathlib import Path
+from typing import Annotated
+
+import typer
+import yaml
+from huggingface_hub import HfApi, login, whoami
+
+from .._cli_utils import console, validate_env_structure
+
+app = typer.Typer(help="Push an OpenEnv environment to Hugging Face Spaces")
+
+
+DEFAULT_PUSH_IGNORE_PATTERNS = [".*", "__pycache__", "*.pyc"]
+
+
+def _path_matches_pattern(relative_path: Path, pattern: str) -> bool:
+    """Return True if a relative path matches an exclude pattern."""
+    normalized_pattern = pattern.strip()
+    if normalized_pattern.startswith("!"):
+        return False
+
+    while normalized_pattern.startswith("./"):
+        normalized_pattern = normalized_pattern[2:]
+
+    if normalized_pattern.startswith("/"):
+        normalized_pattern = normalized_pattern[1:]
+
+    if not normalized_pattern:
+        return False
+
+    posix_path = relative_path.as_posix()
+    pattern_candidates = [normalized_pattern]
+    if normalized_pattern.startswith("**/"):
+        # Gitignore-style "**/" can also match directly at the root.
+        pattern_candidates.append(normalized_pattern[3:])
+
+    # Support directory patterns such as "artifacts/" and "**/outputs/".
+    if normalized_pattern.endswith("/"):
+        dir_pattern_candidates: list[str] = []
+        for candidate in pattern_candidates:
+            base = candidate.rstrip("/")
+            if not base:
+                continue
+            dir_pattern_candidates.extend([base, f"{base}/*"])
+
+        return any(
+            fnmatch(posix_path, candidate) for candidate in dir_pattern_candidates
+        )
+
+    # Match both full relative path and basename for convenience.
+    return any(
+        fnmatch(posix_path, candidate) for candidate in pattern_candidates
+    ) or any(fnmatch(relative_path.name, candidate) for candidate in pattern_candidates)
+
+
+def _should_exclude_path(relative_path: Path, ignore_patterns: list[str]) -> bool:
+    """Return True when the path should be excluded from staging/upload."""
+    return any(
+        _path_matches_pattern(relative_path, pattern) for pattern in ignore_patterns
+    )
+
+
+def _read_ignore_file(ignore_path: Path) -> tuple[list[str], int]:
+    """Read ignore patterns from a file and return (patterns, ignored_negations)."""
+    patterns: list[str] = []
+    ignored_negations = 0
+
+    for line in ignore_path.read_text().splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped.startswith("!"):
+            ignored_negations += 1
+            continue
+        patterns.append(stripped)
+
+    return patterns, ignored_negations
+
+
+def _load_ignore_patterns(env_dir: Path, exclude_file: str | None) -> list[str]:
+    """Load ignore patterns from defaults and an optional ignore file."""
+    patterns = list(DEFAULT_PUSH_IGNORE_PATTERNS)
+    ignored_negations = 0
+
+    def _merge_ignore_file(ignore_path: Path, *, source_label: str) -> None:
+        nonlocal ignored_negations
+        file_patterns, skipped_negations = _read_ignore_file(ignore_path)
+        patterns.extend(file_patterns)
+        ignored_negations += skipped_negations
+        console.print(
+            f"[bold green]✓[/bold green] Loaded {len(file_patterns)} ignore patterns from {source_label}: {ignore_path}"
+        )
+
+    # Optional source: explicit exclude file from CLI.
+    if exclude_file:
+        ignore_path = Path(exclude_file)
+        if not ignore_path.is_absolute():
+            ignore_path = env_dir / ignore_path
+        ignore_path = ignore_path.resolve()
+
+        if not ignore_path.exists() or not ignore_path.is_file():
+            raise typer.BadParameter(
+                f"Exclude file not found or not a file: {ignore_path}"
+            )
+
+        _merge_ignore_file(ignore_path, source_label="--exclude")
+
+    # Keep stable order while removing duplicates.
+    patterns = list(dict.fromkeys(patterns))
+
+    if ignored_negations > 0:
+        console.print(
+            f"[bold yellow]⚠[/bold yellow] Skipped {ignored_negations} negated ignore patterns ('!') because negation is not supported for push excludes"
+        )
+
+    return patterns
+
+
+def _copytree_ignore_factory(env_dir: Path, ignore_patterns: list[str]):
+    """Build a shutil.copytree ignore callback from path-based patterns."""
+
+    def _ignore(path: str, names: list[str]) -> set[str]:
+        current_dir = Path(path)
+        ignored: set[str] = set()
+
+        for name in names:
+            candidate = current_dir / name
+            try:
+                relative_path = candidate.relative_to(env_dir)
+            except ValueError:
+                # candidate is not under env_dir (e.g. symlink or
+                # copytree root differs from env_dir); skip filtering.
+                continue
+            if _should_exclude_path(relative_path, ignore_patterns):
+                ignored.add(name)
+
+        return ignored
+
+    return _ignore
+
+
+def _validate_openenv_directory(directory: Path) -> tuple[str, dict]:
+    """
+    Validate that the directory is an OpenEnv environment.
+
+    Returns:
+        Tuple of (env_name, manifest_data)
+    """
+    # Use the comprehensive validation function
+    try:
+        warnings = validate_env_structure(directory)
+        for warning in warnings:
+            console.print(f"[bold yellow]⚠[/bold yellow] {warning}")
+    except FileNotFoundError as e:
+        raise typer.BadParameter(f"Invalid OpenEnv environment structure: {e}") from e
+
+    # Load and validate manifest
+    manifest_path = directory / "openenv.yaml"
+    try:
+        with open(manifest_path, "r") as f:
+            manifest = yaml.safe_load(f)
+    except Exception as e:
+        raise typer.BadParameter(f"Failed to parse openenv.yaml: {e}") from e
+
+    if not isinstance(manifest, dict):
+        raise typer.BadParameter("openenv.yaml must be a YAML dictionary")
+
+    env_name = manifest.get("name")
+    if not env_name:
+        raise typer.BadParameter("openenv.yaml must contain a 'name' field")
+
+    return env_name, manifest
+
+
+def _ensure_hf_authenticated() -> str:
+    """
+    Ensure user is authenticated with Hugging Face.
+
+    Returns:
+        Username of authenticated user
+    """
+    try:
+        # Try to get current user
+        user_info = whoami()
+        # Handle both dict and object return types
+        if isinstance(user_info, dict):
+            username = (
+                user_info.get("name")
+                or user_info.get("fullname")
+                or user_info.get("username")
+            )
+        else:
+            # If it's an object, try to get name attribute
+            username = (
+                getattr(user_info, "name", None)
+                or getattr(user_info, "fullname", None)
+                or getattr(user_info, "username", None)
+            )
+
+        if not username:
+            raise ValueError("Could not extract username from whoami response")
+
+        console.print(f"[bold green]✓[/bold green] Authenticated as: {username}")
+        return username
+    except Exception:
+        # Not authenticated, prompt for login
+        console.print(
+            "[bold yellow]Not authenticated with Hugging Face. Please login...[/bold yellow]"
+        )
+
+        try:
+            login()
+            # Verify login worked
+            user_info = whoami()
+            # Handle both dict and object return types
+            if isinstance(user_info, dict):
+                username = (
+                    user_info.get("name")
+                    or user_info.get("fullname")
+                    or user_info.get("username")
+                )
+            else:
+                username = (
+                    getattr(user_info, "name", None)
+                    or getattr(user_info, "fullname", None)
+                    or getattr(user_info, "username", None)
+                )
+
+            if not username:
+                raise ValueError("Could not extract username from whoami response")
+
+            console.print(f"[bold green]✓[/bold green] Authenticated as: {username}")
+            return username
+        except Exception as e:
+            raise typer.BadParameter(
+                f"Hugging Face authentication failed: {e}. Please run login manually."
+            ) from e
+
+
+def _prepare_staging_directory(
+    env_dir: Path,
+    env_name: str,
+    staging_dir: Path,
+    ignore_patterns: list[str],
+    base_image: str | None = None,
+    enable_interface: bool = True,
+) -> None:
+    """
+    Prepare files for deployment.
+
+    This includes:
+    - Copying necessary files
+    - Modifying Dockerfile to optionally enable web interface and update base image
+    - Ensuring README has proper HF frontmatter (if interface enabled)
+    """
+    # Create staging directory structure
+    staging_dir.mkdir(parents=True, exist_ok=True)
+
+    # Copy all files from env directory
+    copy_ignore = _copytree_ignore_factory(env_dir, ignore_patterns)
+    for item in env_dir.iterdir():
+        relative_path = item.relative_to(env_dir)
+        if _should_exclude_path(relative_path, ignore_patterns):
+            continue
+
+        dest = staging_dir / item.name
+        if item.is_dir():
+            shutil.copytree(item, dest, dirs_exist_ok=True, ignore=copy_ignore)
+        else:
+            shutil.copy2(item, dest)
+
+    # Dockerfile must be at repo root for Hugging Face. Prefer root if present
+    # (it was copied there); otherwise move server/Dockerfile to root.
+    dockerfile_server_path = staging_dir / "server" / "Dockerfile"
+    dockerfile_root_path = staging_dir / "Dockerfile"
+    dockerfile_path: Path | None = None
+
+    if dockerfile_root_path.exists():
+        dockerfile_path = dockerfile_root_path
+    elif dockerfile_server_path.exists():
+        dockerfile_server_path.rename(dockerfile_root_path)
+        console.print(
+            "[bold cyan]Moved Dockerfile to repository root for deployment[/bold cyan]"
+        )
+        dockerfile_path = dockerfile_root_path
+
+    # Modify Dockerfile to optionally enable web interface and update base image
+    if dockerfile_path and dockerfile_path.exists():
+        dockerfile_content = dockerfile_path.read_text()
+        lines = dockerfile_content.split("\n")
+        new_lines = []
+        cmd_found = False
+        base_image_updated = False
+        web_interface_env_exists = "ENABLE_WEB_INTERFACE" in dockerfile_content
+        last_instruction = None
+
+        for line in lines:
+            stripped = line.strip()
+            token = stripped.split(maxsplit=1)[0] if stripped else ""
+            current_instruction = token.upper()
+
+            is_healthcheck_continuation = last_instruction == "HEALTHCHECK"
+
+            # Update base image if specified
+            if base_image and stripped.startswith("FROM") and not base_image_updated:
+                new_lines.append(f"FROM {base_image}")
+                base_image_updated = True
+                last_instruction = "FROM"
+                continue
+
+            if (
+                stripped.startswith("CMD")
+                and not cmd_found
+                and not web_interface_env_exists
+                and enable_interface
+                and not is_healthcheck_continuation
+            ):
+                new_lines.append("ENV ENABLE_WEB_INTERFACE=true")
+                cmd_found = True
+
+            new_lines.append(line)
+
+            if current_instruction:
+                last_instruction = current_instruction
+
+        if not cmd_found and not web_interface_env_exists and enable_interface:
+            new_lines.append("ENV ENABLE_WEB_INTERFACE=true")
+
+        if base_image and not base_image_updated:
+            new_lines.insert(0, f"FROM {base_image}")
+
+        dockerfile_path.write_text("\n".join(new_lines))
+
+        changes = []
+        if base_image and base_image_updated:
+            changes.append("updated base image")
+        if enable_interface and not web_interface_env_exists:
+            changes.append("enabled web interface")
+        if changes:
+            console.print(
+                f"[bold green]✓[/bold green] Updated Dockerfile: {', '.join(changes)}"
+            )
+    else:
+        console.print(
+            "[bold yellow]⚠[/bold yellow] No Dockerfile at server/ or repo root"
+        )
+
+    # Ensure README has proper HF frontmatter (only if interface enabled)
+    if enable_interface:
+        readme_path = staging_dir / "README.md"
+        if readme_path.exists():
+            readme_content = readme_path.read_text()
+            if "base_path: /web" not in readme_content:
+                # Check if frontmatter exists
+                if readme_content.startswith("---"):
+                    # Add base_path to existing frontmatter
+                    lines = readme_content.split("\n")
+                    new_lines = []
+                    _in_frontmatter = True
+                    for i, line in enumerate(lines):
+                        new_lines.append(line)
+                        if line.strip() == "---" and i > 0:
+                            # End of frontmatter, add base_path before this line
+                            if "base_path:" not in "\n".join(new_lines):
+                                new_lines.insert(-1, "base_path: /web")
+                            _in_frontmatter = False
+                    readme_path.write_text("\n".join(new_lines))
+                else:
+                    # No frontmatter, add it
+                    frontmatter = f"""---
+title: {env_name.replace("_", " ").title()} Environment Server
+emoji: 🔊
+colorFrom: '#00C9FF'
+colorTo: '#1B2845'
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+"""
+                    readme_path.write_text(frontmatter + readme_content)
+                console.print(
+                    "[bold green]✓[/bold green] Updated README with HF Space frontmatter"
+                )
+        else:
+            console.print("[bold yellow]⚠[/bold yellow] No README.md found")
+
+
+def _create_hf_space(
+    repo_id: str,
+    api: HfApi,
+    private: bool = False,
+) -> None:
+    """Create a Hugging Face Space if it doesn't exist."""
+    console.print(f"[bold cyan]Creating/verifying space: {repo_id}[/bold cyan]")
+
+    try:
+        api.create_repo(
+            repo_id=repo_id,
+            repo_type="space",
+            space_sdk="docker",
+            private=private,
+            exist_ok=True,
+        )
+        console.print(f"[bold green]✓[/bold green] Space {repo_id} is ready")
+    except Exception as e:
+        # Space might already exist, which is okay with exist_ok=True
+        # But if there's another error, log it
+        console.print(f"[bold yellow]⚠[/bold yellow] Space creation: {e}")
+
+
+def _upload_to_hf_space(
+    repo_id: str,
+    staging_dir: Path,
+    api: HfApi,
+    ignore_patterns: list[str],
+    private: bool = False,
+    create_pr: bool = False,
+    commit_message: str | None = None,
+) -> None:
+    """Upload files to Hugging Face Space."""
+    if create_pr:
+        console.print(
+            f"[bold cyan]Uploading files to {repo_id} (will open a Pull Request)...[/bold cyan]"
+        )
+    else:
+        console.print(f"[bold cyan]Uploading files to {repo_id}...[/bold cyan]")
+
+    upload_kwargs: dict = {
+        "folder_path": str(staging_dir),
+        "repo_id": repo_id,
+        "repo_type": "space",
+        "create_pr": create_pr,
+        "ignore_patterns": ignore_patterns,
+    }
+    if commit_message:
+        upload_kwargs["commit_message"] = commit_message
+
+    try:
+        result = api.upload_folder(**upload_kwargs)
+        console.print("[bold green]✓[/bold green] Upload completed successfully")
+        if create_pr and result is not None and hasattr(result, "pr_url"):
+            console.print(f"[bold]Pull request:[/bold] {result.pr_url}")
+        console.print(
+            f"[bold]Space URL:[/bold] https://huggingface.co/spaces/{repo_id}"
+        )
+    except Exception as e:
+        console.print(f"[bold red]✗[/bold red] Upload failed: {e}")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def push(
+    directory: Annotated[
+        str | None,
+        typer.Argument(
+            help="Directory containing the OpenEnv environment (default: current directory)"
+        ),
+    ] = None,
+    repo_id: Annotated[
+        str | None,
+        typer.Option(
+            "--repo-id",
+            "-r",
+            help="Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)",
+        ),
+    ] = None,
+    base_image: Annotated[
+        str | None,
+        typer.Option(
+            "--base-image",
+            "-b",
+            help="Base Docker image to use (overrides Dockerfile FROM)",
+        ),
+    ] = None,
+    interface: Annotated[
+        bool,
+        typer.Option(
+            "--interface",
+            help="Enable web interface (default: True if no registry specified)",
+        ),
+    ] = None,
+    no_interface: Annotated[
+        bool,
+        typer.Option(
+            "--no-interface",
+            help="Disable web interface",
+        ),
+    ] = False,
+    registry: Annotated[
+        str | None,
+        typer.Option(
+            "--registry",
+            help="Custom registry URL (e.g., docker.io/username). Disables web interface by default.",
+        ),
+    ] = None,
+    private: Annotated[
+        bool,
+        typer.Option(
+            "--private",
+            help="Deploy the space as private",
+        ),
+    ] = False,
+    create_pr: Annotated[
+        bool,
+        typer.Option(
+            "--create-pr",
+            help="Create a Pull Request instead of pushing to the default branch",
+        ),
+    ] = False,
+    exclude: Annotated[
+        str | None,
+        typer.Option(
+            "--exclude",
+            help="Optional additional ignore file with newline-separated glob patterns to exclude from Hugging Face uploads",
+        ),
+    ] = None,
+) -> None:
+    """
+    Push an OpenEnv environment to Hugging Face Spaces or a custom Docker registry.
+
+    This command:
+    1. Validates that the directory is an OpenEnv environment (openenv.yaml present)
+    2. Builds and pushes to Hugging Face Spaces or custom Docker registry
+    3. Optionally enables web interface for deployment
+
+    The web interface is enabled by default when pushing to HuggingFace Spaces,
+    but disabled by default when pushing to a custom Docker registry.
+
+    Examples:
+        # Push to HuggingFace Spaces from current directory (web interface enabled)
+        $ cd my_env
+        $ openenv push
+
+        # Push to HuggingFace repo and open a Pull Request
+        $ openenv push my-org/my-env --create-pr
+        $ openenv push --repo-id my-org/my-env --create-pr
+
+        # Push to HuggingFace without web interface
+        $ openenv push --no-interface
+
+        # Push to Docker Hub
+        $ openenv push --registry docker.io/myuser
+
+        # Push to GitHub Container Registry
+        $ openenv push --registry ghcr.io/myorg
+
+        # Push to custom registry with web interface
+        $ openenv push --registry myregistry.io/path1/path2 --interface
+
+        # Push to specific HuggingFace repo
+        $ openenv push --repo-id my-org/my-env
+
+        # Push privately with custom base image
+        $ openenv push --private --base-image ghcr.io/meta-pytorch/openenv-base:latest
+    """
+    # Handle interface flag logic
+    if no_interface and interface:
+        console.print(
+            "[bold red]Error:[/bold red] Cannot specify both --interface and --no-interface",
+            file=sys.stderr,
+        )
+        raise typer.Exit(1)
+
+    # Determine if web interface should be enabled
+    if no_interface:
+        enable_interface = False
+    elif interface is not None:
+        enable_interface = interface
+    elif registry is not None:
+        # Custom registry: disable interface by default
+        enable_interface = False
+    else:
+        # HuggingFace: enable interface by default
+        enable_interface = True
+
+    # Determine directory
+    if directory:
+        env_dir = Path(directory).resolve()
+    else:
+        env_dir = Path.cwd().resolve()
+
+    if not env_dir.exists() or not env_dir.is_dir():
+        raise typer.BadParameter(f"Directory does not exist: {env_dir}")
+
+    # Check for openenv.yaml to confirm this is an environment directory
+    openenv_yaml = env_dir / "openenv.yaml"
+    if not openenv_yaml.exists():
+        console.print(
+            f"[bold red]Error:[/bold red] Not an OpenEnv environment directory (missing openenv.yaml): {env_dir}",
+        )
+        console.print(
+            "[yellow]Hint:[/yellow] Run this command from the environment root directory",
+        )
+        raise typer.Exit(1)
+
+    # Validate OpenEnv environment
+    console.print(
+        f"[bold cyan]Validating OpenEnv environment in {env_dir}...[/bold cyan]"
+    )
+    env_name, manifest = _validate_openenv_directory(env_dir)
+    console.print(f"[bold green]✓[/bold green] Found OpenEnv environment: {env_name}")
+
+    # Handle custom registry push
+    if registry:
+        console.print("[bold cyan]Preparing to push to custom registry...[/bold cyan]")
+        if enable_interface:
+            console.print("[bold cyan]Web interface will be enabled[/bold cyan]")
+
+        # Import build functions
+        from .build import _build_docker_image, _push_docker_image
+
+        # Prepare build args for custom registry deployment
+        build_args = {}
+        if enable_interface:
+            build_args["ENABLE_WEB_INTERFACE"] = "true"
+
+        # Build Docker image from the environment directory
+        tag = f"{registry}/{env_name}"
+        console.print(f"[bold cyan]Building Docker image: {tag}[/bold cyan]")
+
+        success = _build_docker_image(
+            env_path=env_dir,
+            tag=tag,
+            build_args=build_args if build_args else None,
+        )
+
+        if not success:
+            console.print("[bold red]✗ Docker build failed[/bold red]")
+            raise typer.Exit(1)
+
+        console.print("[bold green]✓ Docker build successful[/bold green]")
+
+        # Push to registry
+        console.print(f"[bold cyan]Pushing to registry: {registry}[/bold cyan]")
+
+        success = _push_docker_image(
+            tag, registry=None
+        )  # Tag already includes registry
+
+        if not success:
+            console.print("[bold red]✗ Docker push failed[/bold red]")
+            raise typer.Exit(1)
+
+        console.print("\n[bold green]✓ Deployment complete![/bold green]")
+        console.print(f"[bold]Image:[/bold] {tag}")
+        return
+
+    ignore_patterns = _load_ignore_patterns(env_dir, exclude)
+
+    # Ensure authentication for HuggingFace
+    username = _ensure_hf_authenticated()
+
+    # Determine repo_id
+    if not repo_id:
+        repo_id = f"{username}/{env_name}"
+
+    # Validate repo_id format
+    if "/" not in repo_id or repo_id.count("/") != 1:
+        raise typer.BadParameter(
+            f"Invalid repo-id format: {repo_id}. Expected format: 'username/repo-name'"
+        )
+
+    # Initialize Hugging Face API
+    api = HfApi()
+
+    # Prepare staging directory
+    deployment_type = (
+        "with web interface" if enable_interface else "without web interface"
+    )
+    console.print(
+        f"[bold cyan]Preparing files for Hugging Face deployment ({deployment_type})...[/bold cyan]"
+    )
+    with tempfile.TemporaryDirectory() as tmpdir:
+        staging_dir = Path(tmpdir) / "staging"
+        _prepare_staging_directory(
+            env_dir,
+            env_name,
+            staging_dir,
+            ignore_patterns=ignore_patterns,
+            base_image=base_image,
+            enable_interface=enable_interface,
+        )
+
+        # Create/verify space (no-op if exists; needed when pushing to own new repo)
+        if not create_pr:
+            _create_hf_space(repo_id, api, private=private)
+        # When create_pr we rely on upload_folder to create branch and PR
+
+        # Upload files
+        _upload_to_hf_space(
+            repo_id,
+            staging_dir,
+            api,
+            private=private,
+            create_pr=create_pr,
+            ignore_patterns=ignore_patterns,
+        )
+
+        console.print("\n[bold green]✓ Deployment complete![/bold green]")
+        console.print(f"Visit your space at: https://huggingface.co/spaces/{repo_id}")

src/openenv/cli/commands/serve.py

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

src/openenv/cli/commands/validate.py

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

src/openenv/cli/templates/__init__.py

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

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

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

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

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

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

@@ -0,0 +1,16 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""__ENV_TITLE_NAME__ Environment."""
+
+from .client import __ENV_CLASS_NAME__Env
+from .models import __ENV_CLASS_NAME__Action, __ENV_CLASS_NAME__Observation
+
+__all__ = [
+    "__ENV_CLASS_NAME__Action",
+    "__ENV_CLASS_NAME__Observation",
+    "__ENV_CLASS_NAME__Env",
+]

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

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