Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,35 @@
+# Dockerfile for Git Environment
+# Connects to an external shared Gitea service for task-based isolation
+# Optimized for fast resets and minimal resource usage
+
+# Use the standard openenv base image
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ghcr.io/meta-pytorch/openenv-base:latest
+
+# Install git and curl (no Gitea binary needed - connects to external service)
+RUN apt-get update && apt-get install -y \
+    git \
+    curl \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create workspace directory for git operations
+RUN mkdir -p /workspace && chmod 777 /workspace
+
+# Copy core and environment code
+COPY src/core/ /app/src/core/
+COPY envs/git_env/ /app/envs/git_env/
+
+# Environment variables for Gitea connection
+# These MUST be provided at runtime via -e flags or --env-file
+# See .env.example for required variables
+ENV WORKSPACE_DIR=/workspace
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+CMD ["uvicorn", "envs.git_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]
+
+ENV ENABLE_WEB_INTERFACE=true

README.md

@@ -1,10 +1,245 @@
 ---
-title: Git Env-v2-1-0
-emoji: 📈
-colorFrom: green
-colorTo: pink
+title: git_env Environment
 sdk: docker
-pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+  - openenv-v2.1.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# git_env Environment
+
+Space URL: `https://huggingface.co/spaces/openenv/git_env-v2-1-0`
+
+OpenEnv pinned ref: `v2.1.0`
+
+# Git Environment
+
+A Git server environment using Gitea that provides isolated Git repository management optimized for task-based RL training. Perfect for training agents on Git operations with fast reset capabilities.
+
+## Overview
+
+The Git Environment connects to a **shared external Gitea service** for optimal task-based isolation. **Perfect for**: RL training, task-based workflows, parallel execution
+
+### Architecture
+
+```
+┌────────────────────────────────────┐
+│ Shared Gitea (start once)          │
+│ Port 3000                          │
+│ - Pre-migrated repositories        │
+└──────────────┬─────────────────────┘
+               │ HTTP API
+      ┾────────┼────────┾
+      │        │        │
+  ┌───▼──┐ ┌──▼───┐ ┌──▼───┐
+  │Env 1 │ │Env 2 │ │Env 3 │
+  │Task A│ │Task B│ │Task A│
+  │@abc  │ │@def  │ │@abc  │
+  └──────┘ └──────┘ └──────┘
+  Isolated workspaces
+```
+
+## Quick Start
+
+```python
+from envs.git_env import GitAction, GitEnv
+
+# Create environment from Docker image
+git_env = GitEnv.from_docker_image("git-env:latest")
+
+# Reset environment
+result = git_env.reset()
+print(result.observation.message)
+
+# List available repositories (pre-migrated to shared Gitea)
+result = git_env.step(GitAction(action_type="list_repos"))
+for repo in result.observation.repos:
+    print(f"{repo['name']}: {repo['clone_url']}")
+
+# Clone to workspace
+result = git_env.step(GitAction(action_type="clone_repo", repo_name="OpenEnv"))
+print(result.observation.output)  # Cloned to: /workspace/OpenEnv
+
+# Execute git commands
+result = git_env.step(GitAction(
+    action_type="execute_git_command",
+    command="status",
+    working_dir="OpenEnv"
+))
+print(result.observation.output)
+
+# Cleanup
+git_env.close()
+```
+
+## Setup and Running the Example
+
+Complete setup (run these steps in order):
+
+```bash
+# 0. Configure environment variables
+cp .env.example .env
+# Edit .env and set your Gitea credentials if needed
+
+# 1. Start shared Gitea service (one-time)
+./scripts/setup_shared_gitea.sh
+
+# 2. Migrate a test repository to Gitea (one-time)
+docker exec openenv-gitea curl -X POST \
+  http://localhost:3000/api/v1/repos/migrate \
+  -u gitea:gitea123 \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "clone_addr": "https://github.com/meta-pytorch/OpenEnv",
+    "repo_name": "OpenEnv",
+    "repo_owner": "gitea",
+    "service": "github"
+  }'
+
+# 3. Build Docker images
+docker build -t openenv-base:latest -f src/openenv/core/containers/images/Dockerfile .
+docker build -t git-env:latest -f envs/git_env/server/Dockerfile .
+
+# 4. Install Python dependencies
+uv pip install -e .
+
+# 5. Run the example (loads credentials from .env)
+python3 examples/local_git_env.py
+```
+
+**Note**:
+- Steps 1-3 are one-time setup
+- Make sure `.env` file exists with your Gitea credentials
+- After initial setup, you only need step 5 to run the example
+
+## Environment Details
+
+### Actions
+
+**GitAction**: Unified action class for all Git operations
+
+```python
+@dataclass
+class GitAction(Action):
+    action_type: str           # Operation type
+    repo_name: str            # Repository name (for clone/execute)
+    target_dir: Optional[str] # Target directory (for clone)
+    command: str              # Git command (for execute)
+    working_dir: str          # Working directory (for execute)
+```
+
+**Supported action_type values:**
+
+#### "clone_repo" - Clone repository to workspace
+```python
+GitAction(action_type="clone_repo", repo_name="OpenEnv")
+GitAction(action_type="clone_repo", repo_name="OpenEnv", target_dir="custom-dir")
+```
+
+#### "list_repos" - List available repositories
+```python
+GitAction(action_type="list_repos")
+```
+
+#### "execute_git_command" - Execute git command
+```python
+GitAction(
+    action_type="execute_git_command",
+    command="status",
+    working_dir="OpenEnv"
+)
+```
+
+### Observation
+
+**GitObservation**: Contains results of Git operations
+
+```python
+@dataclass
+class GitObservation(Observation):
+    success: bool          # Whether operation succeeded
+    message: str           # Human-readable message
+    output: str            # Command output or detailed result
+    error: str             # Error message if failed
+    repos: list[dict]      # List of repositories (for list_repos)
+```
+
+### State
+
+**GitState**: Tracks environment state
+
+```python
+@dataclass
+class GitState(State):
+    episode_id: str           # Unique episode identifier
+    step_count: int           # Number of steps taken
+    gitea_ready: bool         # Whether Gitea is accessible
+    workspace_path: str       # Path to workspace directory
+```
+
+## Advanced: Task-Based Training
+
+For RL training scenarios where you need fast resets to specific repository states, you can configure task-specific base states in the environment. This is done by setting environment variables before starting containers:
+
+```bash
+# Example: Configure tasks for your training setup
+docker run \
+  -e GITEA_URL=http://host.docker.internal:3000 \
+  -e TASK_REPOS='{"bug_fix": ["my-repo", "abc123"], "feature": ["my-repo", "def456"]}' \
+  git-env:latest
+```
+
+Then in your training code, environments automatically reset to the configured state.
+
+See [`examples/local_git_env.py`](../../../examples/local_git_env.py) for complete working example.
+
+## Project Structure
+
+```
+git_env/
+├── README.md                      # This file
+├── __init__.py                    # Exports
+├── models.py                      # Action, Observation, State definitions
+├── client.py                      # GitEnv HTTP client
+├── docker-compose.gitea.yml       # Shared Gitea service
+└── server/
+    ├── __init__.py
+    ├── git_task_environment.py    # Task-optimized environment
+    ├── app.py                     # FastAPI application
+    └── Dockerfile                 # Lightweight container image
+```
+
+## Troubleshooting
+
+### Gitea Not Ready
+
+If environment can't connect to Gitea:
+1. Ensure Gitea is running: `docker ps | grep gitea`
+2. Check Gitea URL in environment: `GITEA_URL=http://gitea:3000`
+3. Verify network connectivity: `docker network ls | grep openenv`
+
+### Repository Not Found
+
+Ensure repository is migrated to Gitea:
+```bash
+# List repos
+curl -u gitea:gitea123 http://localhost:3000/api/v1/user/repos
+```
+
+### Slow Clone/Reset
+
+- First clone is slower (~5-10s) - downloads from Gitea
+- Subsequent resets are fast (<1s) - just git operations
+- Use task-based mode with `task_repos` for optimal performance
+
+
+## Security Notes
+
+- **Never commit `.env` file** - it contains credentials (already in .gitignore)
+- Use `.env.example` as a template and create your own `.env`
+- Gitea credentials are for local development only
+- For production, use proper secret management (Docker secrets, k8s secrets, etc.)
+- All workspaces are isolated per container
+- Only public repositories supported (no private repo auth)

__init__.py

@@ -0,0 +1,18 @@
+"""
+Git Environment - Git server with Gitea support.
+
+This environment connects to a shared Gitea service for task-based isolation,
+allowing agents to clone repositories, execute git commands, and manage workspaces.
+
+Note: Repository migration is done externally via Gitea API before environment use.
+"""
+
+from .client import GitEnv
+from .models import GitAction, GitObservation, GitState
+
+__all__ = [
+    "GitEnv",
+    "GitAction",
+    "GitObservation",
+    "GitState",
+]

client.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""
+GitEnv Client
+-------------
+Client-side wrapper for the Git environment server.
+
+This client maintains a persistent WebSocket connection to the environment
+server, enabling efficient multi-step interactions with lower latency.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_client import EnvClient
+
+from .models import GitAction, GitObservation, GitState
+
+if TYPE_CHECKING:
+    from openenv.core.containers.runtime import ContainerProvider
+
+
+class GitEnv(EnvClient[GitAction, GitObservation, GitState]):
+    """
+    Client for Git Environment with Gitea server.
+
+    This client maintains a persistent WebSocket connection to the environment
+    server, enabling efficient multi-step interactions for Git operations.
+
+    The environment connects to a shared external Gitea service. Repositories
+    must be pre-migrated to Gitea before use.
+
+    Example:
+        >>> # From Docker image
+        >>> client = GitEnv.from_docker_image("git-env:latest")
+        >>> try:
+        ...     result = client.reset()
+        ...
+        ...     # List available repositories
+        ...     from envs.git_env import GitAction
+        ...     result = client.step(GitAction(action_type="list_repos"))
+        ...     print(result.observation.repos)
+        ...
+        ...     # Clone repository to workspace
+        ...     result = client.step(GitAction(action_type="clone_repo", repo_name="OpenEnv"))
+        ...
+        ...     # Execute git commands
+        ...     result = client.step(GitAction(
+        ...         action_type="execute_git_command",
+        ...         command="status",
+        ...         working_dir="OpenEnv"
+        ...     ))
+        ... finally:
+        ...     client.close()
+    """
+
+    def _step_payload(self, action: GitAction) -> dict:
+        """
+        Convert action to payload for server's /step endpoint.
+
+        Args:
+            action: GitAction to send to server
+
+        Returns:
+            Dictionary payload for HTTP request
+        """
+        # Convert action to dictionary
+        payload = {
+            "action_type": action.action_type,
+        }
+
+        # Add type-specific fields for supported actions
+        if hasattr(action, "repo_name"):
+            payload["repo_name"] = action.repo_name
+        if hasattr(action, "target_dir"):
+            payload["target_dir"] = action.target_dir
+        if hasattr(action, "command"):
+            payload["command"] = action.command
+        if hasattr(action, "working_dir"):
+            payload["working_dir"] = action.working_dir
+
+        return payload
+
+    def _parse_result(self, payload: dict) -> StepResult[GitObservation]:
+        """
+        Parse server response into StepResult.
+
+        Args:
+            payload: JSON response from /step endpoint
+
+        Returns:
+            StepResult containing GitObservation
+        """
+        obs = GitObservation(**payload["observation"])
+        return StepResult(
+            observation=obs,
+            reward=payload.get("reward"),
+            done=bool(payload.get("done", False)),
+        )
+
+    def _parse_state(self, payload: dict) -> GitState:
+        """
+        Parse server response into GitState object.
+
+        Args:
+            payload: JSON response from /state endpoint
+
+        Returns:
+            GitState object with environment state
+        """
+        return GitState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            gitea_ready=payload.get("gitea_ready", False),
+            workspace_path=payload.get("workspace_path", "/workspace"),
+        )

docker-compose.gitea.yml

@@ -0,0 +1,49 @@
+# Docker Compose configuration for shared Gitea service
+# This runs a single Gitea instance that can be shared by multiple
+# Git environment containers for optimal task-based isolation.
+#
+# Usage:
+#   docker-compose -f docker-compose.gitea.yml up -d
+#
+# The Gitea service will be available at:
+#   - http://localhost:3000 (web interface)
+#   - http://gitea:3000 (from other containers on the same network)
+
+version: '3.8'
+
+services:
+  gitea:
+    image: gitea/gitea:1.24
+    container_name: openenv-gitea
+    hostname: gitea
+    environment:
+      - USER_UID=1000
+      - USER_GID=1000
+      - GITEA__database__DB_TYPE=sqlite3
+      - GITEA__database__PATH=/data/gitea/gitea.db
+      - GITEA__server__DOMAIN=gitea
+      - GITEA__server__HTTP_PORT=3000
+      - GITEA__server__ROOT_URL=http://gitea:3000/
+      - GITEA__server__OFFLINE_MODE=true
+    restart: unless-stopped
+    networks:
+      - openenv-network
+    ports:
+      - "3000:3000"
+    volumes:
+      - gitea-data:/data
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+
+networks:
+  openenv-network:
+    name: openenv-network
+    driver: bridge
+
+volumes:
+  gitea-data:
+    name: openenv-gitea-data

envs/git_env/README.md

@@ -0,0 +1,229 @@
+# Git Environment
+
+A Git server environment using Gitea that provides isolated Git repository management optimized for task-based RL training. Perfect for training agents on Git operations with fast reset capabilities.
+
+## Overview
+
+The Git Environment connects to a **shared external Gitea service** for optimal task-based isolation. **Perfect for**: RL training, task-based workflows, parallel execution
+
+### Architecture
+
+```
+┌────────────────────────────────────┐
+│ Shared Gitea (start once)          │
+│ Port 3000                          │
+│ - Pre-migrated repositories        │
+└──────────────┬─────────────────────┘
+               │ HTTP API
+      ┾────────┼────────┾
+      │        │        │
+  ┌───▼──┐ ┌──▼───┐ ┌──▼───┐
+  │Env 1 │ │Env 2 │ │Env 3 │
+  │Task A│ │Task B│ │Task A│
+  │@abc  │ │@def  │ │@abc  │
+  └──────┘ └──────┘ └──────┘
+  Isolated workspaces
+```
+
+## Quick Start
+
+```python
+from envs.git_env import GitAction, GitEnv
+
+# Create environment from Docker image
+git_env = GitEnv.from_docker_image("git-env:latest")
+
+# Reset environment
+result = git_env.reset()
+print(result.observation.message)
+
+# List available repositories (pre-migrated to shared Gitea)
+result = git_env.step(GitAction(action_type="list_repos"))
+for repo in result.observation.repos:
+    print(f"{repo['name']}: {repo['clone_url']}")
+
+# Clone to workspace
+result = git_env.step(GitAction(action_type="clone_repo", repo_name="OpenEnv"))
+print(result.observation.output)  # Cloned to: /workspace/OpenEnv
+
+# Execute git commands
+result = git_env.step(GitAction(
+    action_type="execute_git_command",
+    command="status",
+    working_dir="OpenEnv"
+))
+print(result.observation.output)
+
+# Cleanup
+git_env.close()
+```
+
+## Setup and Running the Example
+
+Complete setup (run these steps in order):
+
+```bash
+# 0. Configure environment variables
+cp .env.example .env
+# Edit .env and set your Gitea credentials if needed
+
+# 1. Start shared Gitea service (one-time)
+./scripts/setup_shared_gitea.sh
+
+# 2. Migrate a test repository to Gitea (one-time)
+docker exec openenv-gitea curl -X POST \
+  http://localhost:3000/api/v1/repos/migrate \
+  -u gitea:gitea123 \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "clone_addr": "https://github.com/meta-pytorch/OpenEnv",
+    "repo_name": "OpenEnv",
+    "repo_owner": "gitea",
+    "service": "github"
+  }'
+
+# 3. Build Docker images
+docker build -t openenv-base:latest -f src/openenv/core/containers/images/Dockerfile .
+docker build -t git-env:latest -f envs/git_env/server/Dockerfile .
+
+# 4. Install Python dependencies
+uv pip install -e .
+
+# 5. Run the example (loads credentials from .env)
+python3 examples/local_git_env.py
+```
+
+**Note**:
+- Steps 1-3 are one-time setup
+- Make sure `.env` file exists with your Gitea credentials
+- After initial setup, you only need step 5 to run the example
+
+## Environment Details
+
+### Actions
+
+**GitAction**: Unified action class for all Git operations
+
+```python
+@dataclass
+class GitAction(Action):
+    action_type: str           # Operation type
+    repo_name: str            # Repository name (for clone/execute)
+    target_dir: Optional[str] # Target directory (for clone)
+    command: str              # Git command (for execute)
+    working_dir: str          # Working directory (for execute)
+```
+
+**Supported action_type values:**
+
+#### "clone_repo" - Clone repository to workspace
+```python
+GitAction(action_type="clone_repo", repo_name="OpenEnv")
+GitAction(action_type="clone_repo", repo_name="OpenEnv", target_dir="custom-dir")
+```
+
+#### "list_repos" - List available repositories
+```python
+GitAction(action_type="list_repos")
+```
+
+#### "execute_git_command" - Execute git command
+```python
+GitAction(
+    action_type="execute_git_command",
+    command="status",
+    working_dir="OpenEnv"
+)
+```
+
+### Observation
+
+**GitObservation**: Contains results of Git operations
+
+```python
+@dataclass
+class GitObservation(Observation):
+    success: bool          # Whether operation succeeded
+    message: str           # Human-readable message
+    output: str            # Command output or detailed result
+    error: str             # Error message if failed
+    repos: list[dict]      # List of repositories (for list_repos)
+```
+
+### State
+
+**GitState**: Tracks environment state
+
+```python
+@dataclass
+class GitState(State):
+    episode_id: str           # Unique episode identifier
+    step_count: int           # Number of steps taken
+    gitea_ready: bool         # Whether Gitea is accessible
+    workspace_path: str       # Path to workspace directory
+```
+
+## Advanced: Task-Based Training
+
+For RL training scenarios where you need fast resets to specific repository states, you can configure task-specific base states in the environment. This is done by setting environment variables before starting containers:
+
+```bash
+# Example: Configure tasks for your training setup
+docker run \
+  -e GITEA_URL=http://host.docker.internal:3000 \
+  -e TASK_REPOS='{"bug_fix": ["my-repo", "abc123"], "feature": ["my-repo", "def456"]}' \
+  git-env:latest
+```
+
+Then in your training code, environments automatically reset to the configured state.
+
+See [`examples/local_git_env.py`](../../../examples/local_git_env.py) for complete working example.
+
+## Project Structure
+
+```
+git_env/
+├── README.md                      # This file
+├── __init__.py                    # Exports
+├── models.py                      # Action, Observation, State definitions
+├── client.py                      # GitEnv HTTP client
+├── docker-compose.gitea.yml       # Shared Gitea service
+└── server/
+    ├── __init__.py
+    ├── git_task_environment.py    # Task-optimized environment
+    ├── app.py                     # FastAPI application
+    └── Dockerfile                 # Lightweight container image
+```
+
+## Troubleshooting
+
+### Gitea Not Ready
+
+If environment can't connect to Gitea:
+1. Ensure Gitea is running: `docker ps | grep gitea`
+2. Check Gitea URL in environment: `GITEA_URL=http://gitea:3000`
+3. Verify network connectivity: `docker network ls | grep openenv`
+
+### Repository Not Found
+
+Ensure repository is migrated to Gitea:
+```bash
+# List repos
+curl -u gitea:gitea123 http://localhost:3000/api/v1/user/repos
+```
+
+### Slow Clone/Reset
+
+- First clone is slower (~5-10s) - downloads from Gitea
+- Subsequent resets are fast (<1s) - just git operations
+- Use task-based mode with `task_repos` for optimal performance
+
+
+## Security Notes
+
+- **Never commit `.env` file** - it contains credentials (already in .gitignore)
+- Use `.env.example` as a template and create your own `.env`
+- Gitea credentials are for local development only
+- For production, use proper secret management (Docker secrets, k8s secrets, etc.)
+- All workspaces are isolated per container
+- Only public repositories supported (no private repo auth)

envs/git_env/__init__.py

@@ -0,0 +1,18 @@
+"""
+Git Environment - Git server with Gitea support.
+
+This environment connects to a shared Gitea service for task-based isolation,
+allowing agents to clone repositories, execute git commands, and manage workspaces.
+
+Note: Repository migration is done externally via Gitea API before environment use.
+"""
+
+from .client import GitEnv
+from .models import GitAction, GitObservation, GitState
+
+__all__ = [
+    "GitEnv",
+    "GitAction",
+    "GitObservation",
+    "GitState",
+]

envs/git_env/client.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""
+GitEnv Client
+-------------
+Client-side wrapper for the Git environment server.
+
+This client maintains a persistent WebSocket connection to the environment
+server, enabling efficient multi-step interactions with lower latency.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_client import EnvClient
+
+from .models import GitAction, GitObservation, GitState
+
+if TYPE_CHECKING:
+    from openenv.core.containers.runtime import ContainerProvider
+
+
+class GitEnv(EnvClient[GitAction, GitObservation, GitState]):
+    """
+    Client for Git Environment with Gitea server.
+
+    This client maintains a persistent WebSocket connection to the environment
+    server, enabling efficient multi-step interactions for Git operations.
+
+    The environment connects to a shared external Gitea service. Repositories
+    must be pre-migrated to Gitea before use.
+
+    Example:
+        >>> # From Docker image
+        >>> client = GitEnv.from_docker_image("git-env:latest")
+        >>> try:
+        ...     result = client.reset()
+        ...
+        ...     # List available repositories
+        ...     from envs.git_env import GitAction
+        ...     result = client.step(GitAction(action_type="list_repos"))
+        ...     print(result.observation.repos)
+        ...
+        ...     # Clone repository to workspace
+        ...     result = client.step(GitAction(action_type="clone_repo", repo_name="OpenEnv"))
+        ...
+        ...     # Execute git commands
+        ...     result = client.step(GitAction(
+        ...         action_type="execute_git_command",
+        ...         command="status",
+        ...         working_dir="OpenEnv"
+        ...     ))
+        ... finally:
+        ...     client.close()
+    """
+
+    def _step_payload(self, action: GitAction) -> dict:
+        """
+        Convert action to payload for server's /step endpoint.
+
+        Args:
+            action: GitAction to send to server
+
+        Returns:
+            Dictionary payload for HTTP request
+        """
+        # Convert action to dictionary
+        payload = {
+            "action_type": action.action_type,
+        }
+
+        # Add type-specific fields for supported actions
+        if hasattr(action, "repo_name"):
+            payload["repo_name"] = action.repo_name
+        if hasattr(action, "target_dir"):
+            payload["target_dir"] = action.target_dir
+        if hasattr(action, "command"):
+            payload["command"] = action.command
+        if hasattr(action, "working_dir"):
+            payload["working_dir"] = action.working_dir
+
+        return payload
+
+    def _parse_result(self, payload: dict) -> StepResult[GitObservation]:
+        """
+        Parse server response into StepResult.
+
+        Args:
+            payload: JSON response from /step endpoint
+
+        Returns:
+            StepResult containing GitObservation
+        """
+        obs = GitObservation(**payload["observation"])
+        return StepResult(
+            observation=obs,
+            reward=payload.get("reward"),
+            done=bool(payload.get("done", False)),
+        )
+
+    def _parse_state(self, payload: dict) -> GitState:
+        """
+        Parse server response into GitState object.
+
+        Args:
+            payload: JSON response from /state endpoint
+
+        Returns:
+            GitState object with environment state
+        """
+        return GitState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            gitea_ready=payload.get("gitea_ready", False),
+            workspace_path=payload.get("workspace_path", "/workspace"),
+        )

envs/git_env/docker-compose.gitea.yml

@@ -0,0 +1,49 @@
+# Docker Compose configuration for shared Gitea service
+# This runs a single Gitea instance that can be shared by multiple
+# Git environment containers for optimal task-based isolation.
+#
+# Usage:
+#   docker-compose -f docker-compose.gitea.yml up -d
+#
+# The Gitea service will be available at:
+#   - http://localhost:3000 (web interface)
+#   - http://gitea:3000 (from other containers on the same network)
+
+version: '3.8'
+
+services:
+  gitea:
+    image: gitea/gitea:1.24
+    container_name: openenv-gitea
+    hostname: gitea
+    environment:
+      - USER_UID=1000
+      - USER_GID=1000
+      - GITEA__database__DB_TYPE=sqlite3
+      - GITEA__database__PATH=/data/gitea/gitea.db
+      - GITEA__server__DOMAIN=gitea
+      - GITEA__server__HTTP_PORT=3000
+      - GITEA__server__ROOT_URL=http://gitea:3000/
+      - GITEA__server__OFFLINE_MODE=true
+    restart: unless-stopped
+    networks:
+      - openenv-network
+    ports:
+      - "3000:3000"
+    volumes:
+      - gitea-data:/data
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+
+networks:
+  openenv-network:
+    name: openenv-network
+    driver: bridge
+
+volumes:
+  gitea-data:
+    name: openenv-gitea-data

envs/git_env/models.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+
+"""
+envs/git_env/models.py
+--------------------------------
+Action/Observation types for the Git environment with Gitea server.
+"""
+
+from __future__ import annotations
+
+from pydantic import Field
+from typing import Optional
+
+from openenv.core.env_server import Action, Observation, State
+
+
+class GitAction(Action):
+    """
+    Action for Git environment operations.
+
+    This unified action class supports multiple operation types:
+    - clone_repo: Clone a repository from Gitea to workspace
+    - list_repos: List all available repositories
+    - execute_git_command: Execute a git command in workspace
+
+    Attributes:
+        action_type: Type of operation ("clone_repo", "list_repos", "execute_git_command")
+        repo_name: Name of repository (for clone_repo, execute_git_command)
+        target_dir: Target directory for clone (optional)
+        command: Git command to execute (for execute_git_command)
+        working_dir: Working directory relative to workspace (for execute_git_command)
+    """
+
+    action_type: str = "list_repos"
+    repo_name: str = ""
+    target_dir: Optional[str] = None
+    command: str = ""
+    working_dir: str = ""
+
+
+class GitObservation(Observation):
+    """
+    Result of executing a Git action.
+
+    Attributes:
+        success: Whether the action was successful
+        message: Human-readable message about the result
+        output: Command output or detailed result
+        error: Error message if action failed
+        repos: List of repositories (for list_repos action)
+    """
+
+    success: bool = False
+    message: str = ""
+    output: str = ""
+    error: str = ""
+    repos: list[dict[str, str]] = Field(default_factory=list)
+
+
+class GitState(State):
+    """
+    State for Git environment.
+
+    Attributes:
+        episode_id: Unique identifier for the episode
+        step_count: Number of steps taken
+        gitea_ready: Whether Gitea server is accessible
+        workspace_path: Path to the workspace directory
+    """
+
+    gitea_ready: bool = False
+    workspace_path: str = "/workspace"

envs/git_env/server/Dockerfile

@@ -0,0 +1,33 @@
+# Dockerfile for Git Environment
+# Connects to an external shared Gitea service for task-based isolation
+# Optimized for fast resets and minimal resource usage
+
+# Use the standard openenv base image
+ARG BASE_IMAGE=openenv-base:latest
+FROM ${BASE_IMAGE}
+
+# Install git and curl (no Gitea binary needed - connects to external service)
+RUN apt-get update && apt-get install -y \
+    git \
+    curl \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create workspace directory for git operations
+RUN mkdir -p /workspace && chmod 777 /workspace
+
+# Copy core and environment code
+COPY src/core/ /app/src/core/
+COPY envs/git_env/ /app/envs/git_env/
+
+# Environment variables for Gitea connection
+# These MUST be provided at runtime via -e flags or --env-file
+# See .env.example for required variables
+ENV WORKSPACE_DIR=/workspace
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+CMD ["uvicorn", "envs.git_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

envs/git_env/server/app.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+
+"""
+FastAPI application for Git Environment.
+
+This module creates an HTTP server for the Git environment that connects
+to a shared external Gitea service for fast, isolated task resets.
+
+Environment variables (required):
+    GITEA_URL: URL of shared Gitea service
+    GITEA_USERNAME: Gitea username
+    GITEA_PASSWORD: Gitea password
+    WORKSPACE_DIR: Workspace directory (optional, default: /workspace)
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn envs.git_env.server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn envs.git_env.server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # With custom Gitea:
+    GITEA_URL=http://my-gitea:3000 uvicorn envs.git_env.server.app:app --host 0.0.0.0 --port 8000
+"""
+
+import os
+
+from openenv.core.env_server import create_app
+
+from ..models import GitAction, GitObservation
+from .git_task_environment import GitTaskEnvironment
+
+# Read configuration from environment variables
+gitea_url = os.getenv("GITEA_URL")
+gitea_username = os.getenv("GITEA_USERNAME")
+gitea_password = os.getenv("GITEA_PASSWORD")
+workspace_dir = os.getenv("WORKSPACE_DIR", "/workspace")
+
+# Validate required environment variables
+if not gitea_url:
+    raise RuntimeError("GITEA_URL environment variable is required")
+if not gitea_username:
+    raise RuntimeError("GITEA_USERNAME environment variable is required")
+if not gitea_password:
+    raise RuntimeError("GITEA_PASSWORD environment variable is required")
+
+
+# Factory function to create GitTaskEnvironment instances
+def create_git_environment():
+    """Factory function that creates GitTaskEnvironment with config."""
+    return GitTaskEnvironment(
+        gitea_url=gitea_url,
+        username=gitea_username,
+        password=gitea_password,
+        workspace_dir=workspace_dir,
+    )
+
+
+# Create the app with web interface and README integration
+# Pass the factory function instead of an instance for WebSocket session support
+app = create_app(create_git_environment, GitAction, GitObservation, env_name="git_env")
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)

envs/git_env/server/git_task_environment.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+
+"""
+Git Task Environment - Optimized for task-based isolation.
+
+This module provides an optimized Git environment for scenarios where:
+- Multiple tasks share the same base repository states
+- Tasks need fast reset() to reproducible states
+- Each task has an isolated workspace
+- A shared Gitea service provides repository storage
+"""
+
+import uuid
+
+from openenv.core.env_server import Action, Environment, Observation
+from openenv.core.tools import GitServerClient
+
+from ..models import GitAction, GitObservation, GitState
+
+
+class GitTaskEnvironment(Environment):
+    """
+    Git Environment optimized for task-based isolation.
+
+    This environment connects to a shared Gitea service and provides:
+    - Fast reset() via git operations (no server restart)
+    - Isolated workspace per environment instance
+    - Shared repository cache across tasks
+    - Reproducible base states from specific commits
+
+    Architecture:
+        Shared Gitea Service (external)
+            ↓
+        GitTaskEnvironment instances (many)
+            ↓
+        Isolated workspaces (/workspace)
+
+    Args:
+        gitea_url: URL of shared Gitea service (e.g., "http://gitea:3000")
+        username: Gitea username for authentication
+        password: Gitea password for authentication
+        workspace_dir: Directory for git operations (default: /workspace)
+        task_repos: Dict mapping task names to (repo_name, commit) tuples
+                   for pre-configuring task base states
+
+    Example (Basic):
+        >>> env = GitTaskEnvironment(gitea_url="http://localhost:3000")
+        >>> obs = env.reset()
+        >>> # Clone and work
+        >>> from ..models import GitAction
+        >>> obs = env.step(GitAction(action_type="clone_repo", repo_name="my-repo"))
+        >>> obs = env.step(GitAction(action_type="execute_git_command", command="status", working_dir="my-repo"))
+
+    Example (Task-based):
+        >>> # Pre-configure tasks with specific repo states
+        >>> env = GitTaskEnvironment(
+        ...     gitea_url="http://localhost:3000",
+        ...     task_repos={
+        ...         "task1": ("my-repo", "abc123"),  # Specific commit
+        ...         "task2": ("my-repo", "def456"),  # Different commit
+        ...     }
+        ... )
+        >>> # Reset to task1 base state
+        >>> obs = env.reset(task_id="task1")  # Fast! Just git reset
+        >>> # Work on task...
+        >>> # Reset to task2 base state
+        >>> obs = env.reset(task_id="task2")  # Fast reset to different state
+    """
+
+    def __init__(
+        self,
+        gitea_url: str,
+        username: str,
+        password: str,
+        workspace_dir: str = "/workspace",
+        task_repos: dict[str, tuple[str, str]] | None = None,
+    ):
+        """Initialize Git Task Environment."""
+        super().__init__()
+        self.workspace_dir = workspace_dir
+        self.task_repos = task_repos or {}
+
+        # Initialize Git server client (connects to external Gitea)
+        self._git_client = GitServerClient(
+            gitea_url=gitea_url,
+            username=username,
+            password=password,
+            workspace_dir=workspace_dir,
+        )
+
+        # Initialize state
+        self._state = GitState(workspace_path=workspace_dir)
+        self._current_task_id: str | None = None
+
+        # Wait for Gitea to be ready
+        if self._git_client.wait_for_ready():
+            self._state.gitea_ready = True
+        else:
+            print("Warning: Gitea server not ready")
+            self._state.gitea_ready = False
+
+    def reset(self, task_id: str | None = None) -> Observation:
+        """
+        Reset environment to clean state.
+
+        This is optimized for task-based workflows:
+        - If task_id specified and configured: fast reset to that task's base state
+        - If workspace exists: git reset --hard (very fast, <1s)
+        - Otherwise: clone from Gitea (slower, ~5-10s)
+
+        Args:
+            task_id: Optional task identifier for task-specific base states
+
+        Returns:
+            Initial observation indicating environment is ready
+        """
+        # Initialize fresh state
+        self._state = GitState(
+            episode_id=str(uuid.uuid4()),
+            step_count=0,
+            gitea_ready=self._git_client.is_ready,
+            workspace_path=self.workspace_dir,
+        )
+
+        self._current_task_id = task_id
+
+        # If task_id provided and configured, set up task base state
+        if task_id and task_id in self.task_repos:
+            repo_name, commit = self.task_repos[task_id]
+
+            try:
+                if self._git_client.workspace_exists(repo_name):
+                    # Fast path: workspace exists, just reset
+                    self._git_client.reset_workspace(repo_name, commit)
+                    message = f"Reset to task '{task_id}' base state (repo: {repo_name}@{commit})"
+                else:
+                    # Slower path: clone fresh
+                    self._git_client.clone_to_workspace(repo_name, commit=commit)
+                    message = f"Initialized task '{task_id}' (repo: {repo_name}@{commit})"
+
+                current_commit = self._git_client.get_current_commit(repo_name)
+
+                return GitObservation(
+                    success=True,
+                    message=message,
+                    output=f"Workspace: {self.workspace_dir}/{repo_name}\nCommit: {current_commit}\nTask: {task_id}",
+                )
+            except Exception as e:
+                return GitObservation(
+                    success=False,
+                    message=f"Failed to reset task '{task_id}'",
+                    error=str(e),
+                )
+
+        # Default reset: just ready state, no pre-configured repos
+        return GitObservation(
+            success=True,
+            message="Git task environment ready.",
+            output=f"Workspace: {self.workspace_dir}\nGitea: {self._git_client.gitea_url}\nUse GitAction with action_type='clone_repo' to clone repositories.",
+        )
+
+    def step(self, action: Action) -> Observation:
+        """
+        Execute a Git action and return observation.
+
+        Supported action types:
+        - "clone_repo": Clone repository to workspace
+        - "execute_git_command": Execute git command
+        - "list_repos": List available repositories
+
+        Args:
+            action: GitAction to execute
+
+        Returns:
+            GitObservation with execution results
+        """
+        if not isinstance(action, GitAction):
+            raise ValueError(f"Expected GitAction, got {type(action)}")
+
+        # Update step count
+        self._state.step_count += 1
+
+        # Route to appropriate handler based on action_type
+        try:
+            if action.action_type == "clone_repo":
+                return self._handle_clone_repo(action)
+            elif action.action_type == "list_repos":
+                return self._handle_list_repos(action)
+            elif action.action_type == "execute_git_command":
+                return self._handle_git_command(action)
+            else:
+                return GitObservation(
+                    success=False,
+                    message=f"Action not supported in task mode: {type(action).__name__}",
+                    error="Use shared Gitea for repository migration/creation",
+                )
+        except Exception as e:
+            return GitObservation(
+                success=False, message=f"Action failed: {str(e)}", error=str(e)
+            )
+
+    def _handle_clone_repo(self, action: GitAction) -> GitObservation:
+        """Handle repository clone action."""
+        try:
+            # Determine commit to use
+            commit = "main"  # Default
+
+            # If this repo is part of current task config, use that commit
+            if (
+                self._current_task_id
+                and self._current_task_id in self.task_repos
+            ):
+                task_repo, task_commit = self.task_repos[self._current_task_id]
+                if task_repo == action.repo_name:
+                    commit = task_commit
+
+            clone_path = self._git_client.clone_to_workspace(
+                action.repo_name, action.target_dir, commit=commit
+            )
+
+            return GitObservation(
+                success=True,
+                message=f"Successfully cloned {action.repo_name}",
+                output=f"Cloned to: {clone_path}\nCommit: {commit}",
+            )
+        except Exception as e:
+            return GitObservation(
+                success=False,
+                message=f"Failed to clone repository: {action.repo_name}",
+                error=str(e),
+            )
+
+    def _handle_list_repos(self, action: GitAction) -> GitObservation:
+        """Handle list repositories action."""
+        try:
+            repos = self._git_client.list_repositories()
+
+            # Format output
+            if not repos:
+                output = "No repositories available."
+            else:
+                output = "Available repositories:\n"
+                for repo in repos:
+                    output += f"  - {repo['name']}: {repo['clone_url']}\n"
+                    if repo.get("description"):
+                        output += f"    {repo['description']}\n"
+
+            return GitObservation(
+                success=True,
+                message=f"Found {len(repos)} repositories",
+                output=output,
+                repos=repos,
+            )
+        except Exception as e:
+            return GitObservation(
+                success=False, message="Failed to list repositories", error=str(e)
+            )
+
+    def _handle_git_command(self, action: GitAction) -> GitObservation:
+        """Handle git command execution action."""
+        try:
+            exit_code, stdout, stderr = self._git_client.execute_git_command(
+                action.command, action.working_dir
+            )
+
+            success = exit_code == 0
+            message = f"Git command {'succeeded' if success else 'failed'}"
+
+            return GitObservation(
+                success=success, message=message, output=stdout, error=stderr
+            )
+        except Exception as e:
+            return GitObservation(
+                success=False,
+                message=f"Failed to execute git command: {action.command}",
+                error=str(e),
+            )
+
+    @property
+    def state(self) -> GitState:
+        """Get current environment state."""
+        return self._state

models.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+
+"""
+envs/git_env/models.py
+--------------------------------
+Action/Observation types for the Git environment with Gitea server.
+"""
+
+from __future__ import annotations
+
+from pydantic import Field
+from typing import Optional
+
+from openenv.core.env_server import Action, Observation, State
+
+
+class GitAction(Action):
+    """
+    Action for Git environment operations.
+
+    This unified action class supports multiple operation types:
+    - clone_repo: Clone a repository from Gitea to workspace
+    - list_repos: List all available repositories
+    - execute_git_command: Execute a git command in workspace
+
+    Attributes:
+        action_type: Type of operation ("clone_repo", "list_repos", "execute_git_command")
+        repo_name: Name of repository (for clone_repo, execute_git_command)
+        target_dir: Target directory for clone (optional)
+        command: Git command to execute (for execute_git_command)
+        working_dir: Working directory relative to workspace (for execute_git_command)
+    """
+
+    action_type: str = "list_repos"
+    repo_name: str = ""
+    target_dir: Optional[str] = None
+    command: str = ""
+    working_dir: str = ""
+
+
+class GitObservation(Observation):
+    """
+    Result of executing a Git action.
+
+    Attributes:
+        success: Whether the action was successful
+        message: Human-readable message about the result
+        output: Command output or detailed result
+        error: Error message if action failed
+        repos: List of repositories (for list_repos action)
+    """
+
+    success: bool = False
+    message: str = ""
+    output: str = ""
+    error: str = ""
+    repos: list[dict[str, str]] = Field(default_factory=list)
+
+
+class GitState(State):
+    """
+    State for Git environment.
+
+    Attributes:
+        episode_id: Unique identifier for the episode
+        step_count: Number of steps taken
+        gitea_ready: Whether Gitea server is accessible
+        workspace_path: Path to the workspace directory
+    """
+
+    gitea_ready: bool = False
+    workspace_path: str = "/workspace"

pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-core"
+version = "0.2.0"
+description = "A unified framework for reinforcement learning environments"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    # Core shared dependencies - minimal set required for all environments
+    # Heavy dependencies (torch, numpy, smolagents, etc.) should be in
+    # individual environment pyproject.toml files
+    "fastapi>=0.104.0",
+    "pydantic>=2.0.0",
+    "uvicorn>=0.24.0",
+    "requests>=2.25.0",
+    # CLI dependencies
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "pyyaml>=6.0",
+    "huggingface_hub>=0.20.0",
+    "openai>=2.7.2",
+    "tomli>=2.3.0",
+    "tomli-w>=1.2.0",
+    "websockets>=15.0.1",
+    # MCP support
+    "fastmcp>=2.0.0",
+    # Web UI dependencies
+    "gradio>=4.0.0",
+]
+
+[project.optional-dependencies]
+core = [
+    "fastapi>=0.104.0",
+    "pydantic>=2.0.0",
+    "uvicorn>=0.24.0",
+    "requests>=2.25.0",
+    "websockets>=15.0.1",
+]
+cli = [
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "pyyaml>=6.0",
+    "huggingface_hub>=0.20.0",
+    "openai>=2.7.2",
+    "tomli>=2.3.0",
+    "tomli-w>=1.2.0",
+]
+all = [
+    "openenv-core[core]",
+    "openenv-core[cli]",
+]
+daytona = [
+    "daytona>=0.136.0",
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+openenv = "openenv.cli.__main__:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.package-data]
+"openenv.cli" = ["templates/**/*"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.coverage.run]
+omit = [
+    "openenv/cli/templates/**",
+    "**/templates/**",
+    "openenv/cli/__main__.py",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+markers = [
+    "docker: Tests that require Docker to be running",
+    "network: Tests that require network access (HuggingFace, etc.)",
+    "integration: Integration tests with external resources",
+]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "W"]
+ignore = [
+    "E402",  # Module level import not at top of file (needed for pytest.importorskip patterns)
+    "E501",  # Line too long (not enforced previously, would require large refactor)
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Context manager variables that are intentionally unused
+"tests/envs/test_websockets.py" = ["F841"]
+"tests/test_cli/test_push.py" = ["F841"]
+# Compatibility shim module
+"src/openenv_core/__init__.py" = ["F401"]

server/Dockerfile

@@ -0,0 +1,33 @@
+# Dockerfile for Git Environment
+# Connects to an external shared Gitea service for task-based isolation
+# Optimized for fast resets and minimal resource usage
+
+# Use the standard openenv base image
+ARG BASE_IMAGE=openenv-base:latest
+FROM ${BASE_IMAGE}
+
+# Install git and curl (no Gitea binary needed - connects to external service)
+RUN apt-get update && apt-get install -y \
+    git \
+    curl \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create workspace directory for git operations
+RUN mkdir -p /workspace && chmod 777 /workspace
+
+# Copy core and environment code
+COPY src/core/ /app/src/core/
+COPY envs/git_env/ /app/envs/git_env/
+
+# Environment variables for Gitea connection
+# These MUST be provided at runtime via -e flags or --env-file
+# See .env.example for required variables
+ENV WORKSPACE_DIR=/workspace
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+CMD ["uvicorn", "envs.git_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

server/app.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+
+"""
+FastAPI application for Git Environment.
+
+This module creates an HTTP server for the Git environment that connects
+to a shared external Gitea service for fast, isolated task resets.
+
+Environment variables (required):
+    GITEA_URL: URL of shared Gitea service
+    GITEA_USERNAME: Gitea username
+    GITEA_PASSWORD: Gitea password
+    WORKSPACE_DIR: Workspace directory (optional, default: /workspace)
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn envs.git_env.server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn envs.git_env.server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # With custom Gitea:
+    GITEA_URL=http://my-gitea:3000 uvicorn envs.git_env.server.app:app --host 0.0.0.0 --port 8000
+"""
+
+import os
+
+from openenv.core.env_server import create_app
+
+from ..models import GitAction, GitObservation
+from .git_task_environment import GitTaskEnvironment
+
+# Read configuration from environment variables
+gitea_url = os.getenv("GITEA_URL")
+gitea_username = os.getenv("GITEA_USERNAME")
+gitea_password = os.getenv("GITEA_PASSWORD")
+workspace_dir = os.getenv("WORKSPACE_DIR", "/workspace")
+
+# Validate required environment variables
+if not gitea_url:
+    raise RuntimeError("GITEA_URL environment variable is required")
+if not gitea_username:
+    raise RuntimeError("GITEA_USERNAME environment variable is required")
+if not gitea_password:
+    raise RuntimeError("GITEA_PASSWORD environment variable is required")
+
+
+# Factory function to create GitTaskEnvironment instances
+def create_git_environment():
+    """Factory function that creates GitTaskEnvironment with config."""
+    return GitTaskEnvironment(
+        gitea_url=gitea_url,
+        username=gitea_username,
+        password=gitea_password,
+        workspace_dir=workspace_dir,
+    )
+
+
+# Create the app with web interface and README integration
+# Pass the factory function instead of an instance for WebSocket session support
+app = create_app(create_git_environment, GitAction, GitObservation, env_name="git_env")
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)

server/git_task_environment.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+
+"""
+Git Task Environment - Optimized for task-based isolation.
+
+This module provides an optimized Git environment for scenarios where:
+- Multiple tasks share the same base repository states
+- Tasks need fast reset() to reproducible states
+- Each task has an isolated workspace
+- A shared Gitea service provides repository storage
+"""
+
+import uuid
+
+from openenv.core.env_server import Action, Environment, Observation
+from openenv.core.tools import GitServerClient
+
+from ..models import GitAction, GitObservation, GitState
+
+
+class GitTaskEnvironment(Environment):
+    """
+    Git Environment optimized for task-based isolation.
+
+    This environment connects to a shared Gitea service and provides:
+    - Fast reset() via git operations (no server restart)
+    - Isolated workspace per environment instance
+    - Shared repository cache across tasks
+    - Reproducible base states from specific commits
+
+    Architecture:
+        Shared Gitea Service (external)
+            ↓
+        GitTaskEnvironment instances (many)
+            ↓
+        Isolated workspaces (/workspace)
+
+    Args:
+        gitea_url: URL of shared Gitea service (e.g., "http://gitea:3000")
+        username: Gitea username for authentication
+        password: Gitea password for authentication
+        workspace_dir: Directory for git operations (default: /workspace)
+        task_repos: Dict mapping task names to (repo_name, commit) tuples
+                   for pre-configuring task base states
+
+    Example (Basic):
+        >>> env = GitTaskEnvironment(gitea_url="http://localhost:3000")
+        >>> obs = env.reset()
+        >>> # Clone and work
+        >>> from ..models import GitAction
+        >>> obs = env.step(GitAction(action_type="clone_repo", repo_name="my-repo"))
+        >>> obs = env.step(GitAction(action_type="execute_git_command", command="status", working_dir="my-repo"))
+
+    Example (Task-based):
+        >>> # Pre-configure tasks with specific repo states
+        >>> env = GitTaskEnvironment(
+        ...     gitea_url="http://localhost:3000",
+        ...     task_repos={
+        ...         "task1": ("my-repo", "abc123"),  # Specific commit
+        ...         "task2": ("my-repo", "def456"),  # Different commit
+        ...     }
+        ... )
+        >>> # Reset to task1 base state
+        >>> obs = env.reset(task_id="task1")  # Fast! Just git reset
+        >>> # Work on task...
+        >>> # Reset to task2 base state
+        >>> obs = env.reset(task_id="task2")  # Fast reset to different state
+    """
+
+    def __init__(
+        self,
+        gitea_url: str,
+        username: str,
+        password: str,
+        workspace_dir: str = "/workspace",
+        task_repos: dict[str, tuple[str, str]] | None = None,
+    ):
+        """Initialize Git Task Environment."""
+        super().__init__()
+        self.workspace_dir = workspace_dir
+        self.task_repos = task_repos or {}
+
+        # Initialize Git server client (connects to external Gitea)
+        self._git_client = GitServerClient(
+            gitea_url=gitea_url,
+            username=username,
+            password=password,
+            workspace_dir=workspace_dir,
+        )
+
+        # Initialize state
+        self._state = GitState(workspace_path=workspace_dir)
+        self._current_task_id: str | None = None
+
+        # Wait for Gitea to be ready
+        if self._git_client.wait_for_ready():
+            self._state.gitea_ready = True
+        else:
+            print("Warning: Gitea server not ready")
+            self._state.gitea_ready = False
+
+    def reset(self, task_id: str | None = None) -> Observation:
+        """
+        Reset environment to clean state.
+
+        This is optimized for task-based workflows:
+        - If task_id specified and configured: fast reset to that task's base state
+        - If workspace exists: git reset --hard (very fast, <1s)
+        - Otherwise: clone from Gitea (slower, ~5-10s)
+
+        Args:
+            task_id: Optional task identifier for task-specific base states
+
+        Returns:
+            Initial observation indicating environment is ready
+        """
+        # Initialize fresh state
+        self._state = GitState(
+            episode_id=str(uuid.uuid4()),
+            step_count=0,
+            gitea_ready=self._git_client.is_ready,
+            workspace_path=self.workspace_dir,
+        )
+
+        self._current_task_id = task_id
+
+        # If task_id provided and configured, set up task base state
+        if task_id and task_id in self.task_repos:
+            repo_name, commit = self.task_repos[task_id]
+
+            try:
+                if self._git_client.workspace_exists(repo_name):
+                    # Fast path: workspace exists, just reset
+                    self._git_client.reset_workspace(repo_name, commit)
+                    message = f"Reset to task '{task_id}' base state (repo: {repo_name}@{commit})"
+                else:
+                    # Slower path: clone fresh
+                    self._git_client.clone_to_workspace(repo_name, commit=commit)
+                    message = f"Initialized task '{task_id}' (repo: {repo_name}@{commit})"
+
+                current_commit = self._git_client.get_current_commit(repo_name)
+
+                return GitObservation(
+                    success=True,
+                    message=message,
+                    output=f"Workspace: {self.workspace_dir}/{repo_name}\nCommit: {current_commit}\nTask: {task_id}",
+                )
+            except Exception as e:
+                return GitObservation(
+                    success=False,
+                    message=f"Failed to reset task '{task_id}'",
+                    error=str(e),
+                )
+
+        # Default reset: just ready state, no pre-configured repos
+        return GitObservation(
+            success=True,
+            message="Git task environment ready.",
+            output=f"Workspace: {self.workspace_dir}\nGitea: {self._git_client.gitea_url}\nUse GitAction with action_type='clone_repo' to clone repositories.",
+        )
+
+    def step(self, action: Action) -> Observation:
+        """
+        Execute a Git action and return observation.
+
+        Supported action types:
+        - "clone_repo": Clone repository to workspace
+        - "execute_git_command": Execute git command
+        - "list_repos": List available repositories
+
+        Args:
+            action: GitAction to execute
+
+        Returns:
+            GitObservation with execution results
+        """
+        if not isinstance(action, GitAction):
+            raise ValueError(f"Expected GitAction, got {type(action)}")
+
+        # Update step count
+        self._state.step_count += 1
+
+        # Route to appropriate handler based on action_type
+        try:
+            if action.action_type == "clone_repo":
+                return self._handle_clone_repo(action)
+            elif action.action_type == "list_repos":
+                return self._handle_list_repos(action)
+            elif action.action_type == "execute_git_command":
+                return self._handle_git_command(action)
+            else:
+                return GitObservation(
+                    success=False,
+                    message=f"Action not supported in task mode: {type(action).__name__}",
+                    error="Use shared Gitea for repository migration/creation",
+                )
+        except Exception as e:
+            return GitObservation(
+                success=False, message=f"Action failed: {str(e)}", error=str(e)
+            )
+
+    def _handle_clone_repo(self, action: GitAction) -> GitObservation:
+        """Handle repository clone action."""
+        try:
+            # Determine commit to use
+            commit = "main"  # Default
+
+            # If this repo is part of current task config, use that commit
+            if (
+                self._current_task_id
+                and self._current_task_id in self.task_repos
+            ):
+                task_repo, task_commit = self.task_repos[self._current_task_id]
+                if task_repo == action.repo_name:
+                    commit = task_commit
+
+            clone_path = self._git_client.clone_to_workspace(
+                action.repo_name, action.target_dir, commit=commit
+            )
+
+            return GitObservation(
+                success=True,
+                message=f"Successfully cloned {action.repo_name}",
+                output=f"Cloned to: {clone_path}\nCommit: {commit}",
+            )
+        except Exception as e:
+            return GitObservation(
+                success=False,
+                message=f"Failed to clone repository: {action.repo_name}",
+                error=str(e),
+            )
+
+    def _handle_list_repos(self, action: GitAction) -> GitObservation:
+        """Handle list repositories action."""
+        try:
+            repos = self._git_client.list_repositories()
+
+            # Format output
+            if not repos:
+                output = "No repositories available."
+            else:
+                output = "Available repositories:\n"
+                for repo in repos:
+                    output += f"  - {repo['name']}: {repo['clone_url']}\n"
+                    if repo.get("description"):
+                        output += f"    {repo['description']}\n"
+
+            return GitObservation(
+                success=True,
+                message=f"Found {len(repos)} repositories",
+                output=output,
+                repos=repos,
+            )
+        except Exception as e:
+            return GitObservation(
+                success=False, message="Failed to list repositories", error=str(e)
+            )
+
+    def _handle_git_command(self, action: GitAction) -> GitObservation:
+        """Handle git command execution action."""
+        try:
+            exit_code, stdout, stderr = self._git_client.execute_git_command(
+                action.command, action.working_dir
+            )
+
+            success = exit_code == 0
+            message = f"Git command {'succeeded' if success else 'failed'}"
+
+            return GitObservation(
+                success=success, message=message, output=stdout, error=stderr
+            )
+        except Exception as e:
+            return GitObservation(
+                success=False,
+                message=f"Failed to execute git command: {action.command}",
+                error=str(e),
+            )
+
+    @property
+    def state(self) -> GitState:
+        """Get current environment state."""
+        return self._state

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.egg-info/PKG-INFO

@@ -0,0 +1,337 @@
+Metadata-Version: 2.4
+Name: openenv
+Version: 0.2.0
+Summary: A unified framework for reinforcement learning environments
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: huggingface_hub>=0.20.0
+Requires-Dist: openai>=2.7.2
+Requires-Dist: tomli>=2.3.0
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: websockets>=15.0.1
+Provides-Extra: core
+Requires-Dist: fastapi>=0.104.0; extra == "core"
+Requires-Dist: pydantic>=2.0.0; extra == "core"
+Requires-Dist: uvicorn>=0.24.0; extra == "core"
+Requires-Dist: requests>=2.25.0; extra == "core"
+Requires-Dist: websockets>=15.0.1; extra == "core"
+Provides-Extra: cli
+Requires-Dist: typer>=0.9.0; extra == "cli"
+Requires-Dist: rich>=13.0.0; extra == "cli"
+Requires-Dist: pyyaml>=6.0; extra == "cli"
+Requires-Dist: huggingface_hub>=0.20.0; extra == "cli"
+Requires-Dist: openai>=2.7.2; extra == "cli"
+Requires-Dist: tomli>=2.3.0; extra == "cli"
+Requires-Dist: tomli-w>=1.2.0; extra == "cli"
+Provides-Extra: all
+Requires-Dist: openenv[core]; extra == "all"
+Requires-Dist: openenv[cli]; extra == "all"
+Dynamic: license-file
+
+# <img width="35" height="35" alt="image" src="https://github.com/user-attachments/assets/2700a971-e5d6-4036-b03f-2f89c9791609" /> OpenEnv: Agentic Execution Environments
+
+An e2e framework for creating, deploying and using isolated execution environments for agentic RL training, built using Gymnasium style simple APIs.
+
+[![PyPI](https://img.shields.io/pypi/v/openenv?color=blue)](https://pypi.org/project/openenv/)
+[![Discord](https://img.shields.io/badge/Discord-OpenEnv-7289da?style=flat&logo=discord&logoColor=white)](https://discord.gg/YsTYBh6PD9)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/meta-pytorch/OpenEnv/blob/main/examples/OpenEnv_Tutorial.ipynb)
+[![Docs](https://img.shields.io/badge/Docs-Explore-blue?logo=readthedocs&logoColor=white)](https://meta-pytorch.org/OpenEnv/)
+
+---
+
+**🚀 Featured Example:** Train LLMs to play BlackJack using [torchforge](https://github.com/meta-pytorch/torchforge) (PyTorch's agentic RL framework): [`examples/grpo_blackjack/`](examples/grpo_blackjack/)
+
+## OpenEnv on partner platforms:
+
+- [Lightning AI Studio](https://lightning.ai/environments?section=featured)
+- [TRL example](https://huggingface.co/docs/trl/main/en/openenv)
+- [Unsloth Google Colab](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/OpenEnv_gpt_oss_(20B)_Reinforcement_Learning_2048_Game.ipynb)
+- [ART example](https://art.openpipe.ai/integrations/openenv-integration)
+- [Oumi example](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%20-%20OpenEnv%20GRPO%20with%20trl.ipynb)
+
+## Overview
+
+OpenEnv provides a standard for interacting with agentic execution environments via simple Gymnasium style APIs - `step()`, `reset()`, `state()`. Users of agentic execution environments can interact with the environment during RL training loops using these simple APIs.
+
+In addition to making it easier for researchers and RL framework writers, we also provide tools for environment creators making it easier for them to create richer environments and make them available over familiar protocols like HTTP and packaged using canonical technologies like docker. Environment creators can use the OpenEnv framework to create environments that are isolated, secure, and easy to deploy and use.
+
+The OpenEnv CLI (`openenv`) provides commands to initialize new environments and deploy them to Hugging Face Spaces.
+
+> ⚠️ **Early Development Warning** OpenEnv is currently in an experimental
+> stage. You should expect bugs, incomplete features, and APIs that may change
+> in future versions. The project welcomes bugfixes, but to make sure things are
+> well coordinated you should discuss any significant change before starting the
+> work. It's recommended that you signal your intention to contribute in the
+> issue tracker, either by filing a new issue or by claiming an existing one.
+
+### RFCs
+
+Below is a list of active and historical RFCs for OpenEnv. RFCs are proposals for major changes or features. Please review and contribute!
+
+- [RFC 001: Baseline API and Interface Specifications](https://github.com/meta-pytorch/OpenEnv/pull/26)
+
+## Architecture
+
+### Component Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Client Application                   │
+│  ┌────────────────┐              ┌──────────────────┐   │
+│  │  EchoEnv       │              │  CodingEnv       │   │
+│  │ (HTTPEnvClient)│              ��  (HTTPEnvClient) │   │
+│  └────────┬───────┘              └────────┬─────────┘   │
+└───────────┼───────────────────────────────┼─────────────┘
+            │ HTTP                          │ HTTP
+            │ (reset, step, state)          │
+┌───────────▼───────────────────────────────▼─────────────┐
+│              Docker Containers (Isolated)               │
+│  ┌──────────────────────┐    ┌──────────────────────┐   │
+│  │ FastAPI Server       │    │ FastAPI Server       │   │
+│  │   EchoEnvironment    │    │ PythonCodeActEnv     │   │
+│  │ (Environment base)   │    │ (Environment base)   │   │
+│  └──────────────────────┘    └──────────────────────┘   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Core Components
+
+#### 1. Web Interface
+
+OpenEnv includes a built-in web interface for interactive environment exploration and debugging. The web interface provides:
+
+- **Two-Pane Layout**: HumanAgent interaction on the left, state observation on the right
+- **Real-time Updates**: WebSocket-based live updates without page refresh
+- **Dynamic Forms**: Automatically generated action forms based on environment Action types
+- **Action History**: Complete log of all actions taken and their results
+
+The web interface is **conditionally enabled** based on environment variables:
+
+- **Local Development**: Disabled by default for lightweight development
+- **Manual Override**: Enable with `ENABLE_WEB_INTERFACE=true`
+
+To use the web interface:
+
+```python
+from openenv.core.env_server import create_web_interface_app
+from your_env.models import YourAction, YourObservation
+from your_env.server.your_environment import YourEnvironment
+
+env = YourEnvironment()
+app = create_web_interface_app(env, YourAction, YourObservation)
+```
+
+When enabled, open `http://localhost:8000/web` in your browser to interact with the environment.
+
+#### 2. Environment (Server-Side)
+Base class for implementing environment logic:
+- **`reset()`**: Initialize a new episode, returns initial `Observation`
+- **`step(action)`**: Execute an `Action`, returns resulting `Observation`
+- **`state()`**: Access episode metadata (`State` with episode_id, step_count, etc.)
+
+#### 3. HTTPEnvClient (Client-Side)
+Base class for HTTP communication:
+- Handles HTTP requests to environment server
+- Contains a utility to spin up a docker container locally for the corresponding environment
+- Type-safe action/observation parsing
+
+#### 4. Container Providers
+Manage container deployment:
+- `LocalDockerProvider`: Run containers on local Docker daemon
+- `KubernetesProvider`: Deploy to K8s clusters (future)
+
+#### 5. Models
+Type-safe data structures:
+- `Action`: Base class for environment actions
+- `Observation`: Base class for environment observations
+- `State`: Episode state tracking
+- `StepResult`: Combines observation, reward, done flag
+
+## Project Structure
+
+### For Environment Creators
+
+Use the CLI to quickly scaffold a new environment:
+
+```bash
+openenv init my_env
+```
+
+This creates the following structure:
+
+```
+my_env/
+├── .dockerignore        # Docker build exclusions
+├── __init__.py           # Export YourAction, YourObservation, YourEnv
+├── models.py             # Define Action, Observation, State dataclasses
+├── client.py             # Implement YourEnv(HTTPEnvClient)
+├── README.md             # Document your environment
+├── openenv.yaml          # Environment manifest
+├── pyproject.toml        # Dependencies and package configuration
+├── outputs/              # Runtime outputs (logs, evals) - gitignored
+│   ├── logs/
+│   └── evals/
+└── server/
+    ├── your_environment.py  # Implement YourEnvironment(Environment)
+    ├── app.py               # Create FastAPI app
+    ├── requirements.txt     # Dependencies for Docker (can be generated)
+    └── Dockerfile           # Define container image
+```
+
+#### Dependency Management
+
+OpenEnv uses `pyproject.toml` as the primary dependency specification:
+
+- **Environment-level `pyproject.toml`**: Each environment defines its own dependencies
+- **Root-level `pyproject.toml`**: Contains shared core dependencies (fastapi, pydantic, uvicorn)
+- **Server `requirements.txt`**: Can be auto-generated from `pyproject.toml` for Docker builds
+
+**Development Workflow:**
+
+```bash
+# Install environment in editable mode
+cd my_env
+pip install -e .
+
+# Or using uv (faster)
+uv pip install -e .
+
+# Run server locally without Docker
+uv run server --host 0.0.0.0 --port 8000
+```
+
+**Benefits:**
+- ✅ **Client-side extensions**: Modify client classes locally without repo changes
+- ✅ **Better dependency management**: Clear separation between environments
+- ✅ **Flexible workflows**: Use pip, uv, or Docker for different scenarios
+- ✅ **CI/CD ready**: Automated dependency generation and validation
+
+See [`envs/README.md`](envs/README.md) for a complete guide on building environments.
+
+### For Environment Users
+
+To use an environment:
+1. Import from `envs.your_env`: `from envs.echo_env import EchoAction, EchoEnv`
+2. Create client: `client = EchoEnv.from_docker_image("echo-env:latest")`
+3. Interact: `client.reset()`, `client.step(action)`, `client.state()`
+4. Cleanup: `client.close()`
+
+See example scripts in `examples/` directory.
+
+## CLI Commands
+
+The OpenEnv CLI provides commands to manage environments:
+
+- **`openenv init <env_name>`** - Initialize a new environment from template
+- **`openenv push [--repo-id <repo>] [--private]`** - Deploy environment to Hugging Face Spaces
+
+### Quick Start
+
+```bash
+# Create a new environment
+openenv init my_game_env
+
+# Deploy to Hugging Face (will prompt for login if needed)
+cd my_game_env
+openenv push
+```
+
+For detailed options: `openenv init --help` and `openenv push --help`.
+
+## Design Principles
+
+1. **Separation of Concerns**: Clear client-server boundaries
+2. **Type Safety**: Strongly-typed actions, observations, and state
+3. **Container Isolation**: Each environment runs in its own container
+4. **Simple APIs**: Minimal, intuitive interfaces
+
+## Quick Start
+
+### Using the Echo Environment(Example)
+
+```python
+from envs.echo_env import EchoAction, EchoEnv
+
+# Automatically start container and connect
+client = EchoEnv.from_docker_image("echo-env:latest")
+
+# Reset the environment
+result = client.reset()
+print(result.observation.echoed_message)  # "Echo environment ready!"
+
+# Send messages
+result = client.step(EchoAction(message="Hello, World!"))
+print(result.observation.echoed_message)  # "Hello, World!"
+print(result.reward)  # 1.3 (based on message length)
+
+# Cleanup
+client.close()  # Stops and removes container
+```
+
+## Requirements
+
+- Python 3.11+
+- Docker Desktop or Docker Engine
+- FastAPI >= 0.104.0
+- Uvicorn >= 0.24.0
+- Requests >= 2.25.0
+- smolagents (for coding environment)
+
+## Supported RL Tools
+The goal of this project is to support a broad set of open and closed tools to help standardize the agentic RL community. If you have a project that supports OpenEnv environments, please put up a PR to add your tool name along with a link to your documentation.
+
+### torchforge
+See GRPO BlackJack training example: [`examples/grpo_blackjack/`](examples/grpo_blackjack/)
+
+### TRL
+See the [TRL example](https://huggingface.co/docs/trl/main/en/openenv) on how to integrate OpenEnv environments with GRPO training.
+
+### Unsloth
+See the 2048 game example based on gpt-oss: [Colab notebook](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/OpenEnv_gpt_oss_(20B)_Reinforcement_Learning_2048_Game.ipynb)
+
+### SkyRL
+See the [SkyRL example](https://skyrl.readthedocs.io/en/latest/examples/openenv.html) on how to train on OpenEnv environments with SkyRL.
+
+### ART
+See the [ART example](https://art.openpipe.ai/integrations/openenv-integration) on how OpenEnv environments can be used to train models with ART.
+
+### Oumi
+See the [Oumi example](https://github.com/oumi-ai/oumi/blob/main/notebooks/Oumi%20-%20OpenEnv%20GRPO%20with%20trl.ipynb) on how OpenEnv environments can be used to train models with Oumi.
+
+## Example Environments
+
+### Echo Environment
+A simple environment that echoes back messages with metadata. Perfect for:
+- Testing the HTTP server infrastructure
+- Learning the framework basics
+- Verifying container deployment
+
+See: [`envs/echo_env/README.md`](envs/echo_env/README.md)
+
+### Coding Environment
+Executes arbitrary Python code in a sandboxed environment. Features:
+- Safe code execution using smolagents
+- Capture stdout, stderr, and exit codes
+- Persistent execution context within episodes
+- Error handling with detailed messages
+
+See: [`envs/coding_env/README.md`](envs/coding_env/README.md)
+
+## Community Support & Acknowledgments
+This is an open and community-centric project. If you would like to add your name here, please put up a pull request and tag @jspisak for review. Ty!!
+
+Supporters include: Meta-PyTorch, Hugging Face, [Patronus AI](https://patronus.ai), [Surge AI](https://surgehq.ai), [LastMile AI](https://www.lastmileai.dev), Unsloth AI, Reflection AI, vLLM, SkyRL (UC-Berkeley), LightningAI, Axolotl AI, Stanford Scaling Intelligence Lab, Mithril, [OpenMined](https://openmined.org/), [Fleet AI](https://fleetai.com), [Halluminate](https://halluminate.ai/), [Turing](https://www.turing.com/) ..
+
+And we'd also like to acknowledge the team at Farama Foundation as the OpenEnv API was heavily inspired by the work you all have done on Gymnasium. Cheers!
+
+## License
+
+BSD 3-Clause License (see [LICENSE](./LICENSE) file)

src/openenv.egg-info/SOURCES.txt

@@ -0,0 +1,142 @@
+LICENSE
+README.md
+pyproject.toml
+envs/atari_env/__init__.py
+envs/atari_env/client.py
+envs/atari_env/models.py
+envs/atari_env/server/__init__.py
+envs/atari_env/server/app.py
+envs/atari_env/server/atari_environment.py
+envs/browsergym_env/__init__.py
+envs/browsergym_env/client.py
+envs/browsergym_env/models.py
+envs/browsergym_env/server/__init__.py
+envs/browsergym_env/server/app.py
+envs/browsergym_env/server/browsergym_environment.py
+envs/chat_env/__init__.py
+envs/chat_env/client.py
+envs/chat_env/models.py
+envs/chat_env/server/__init__.py
+envs/chat_env/server/app.py
+envs/chat_env/server/chat_environment.py
+envs/chat_env/server/test_chat_env.py
+envs/coding_env/__init__.py
+envs/coding_env/client.py
+envs/coding_env/models.py
+envs/coding_env/server/__init__.py
+envs/coding_env/server/app.py
+envs/coding_env/server/python_codeact_env.py
+envs/coding_env/server/python_executor.py
+envs/coding_env/server/transforms.py
+envs/connect4_env/__init__.py
+envs/connect4_env/client.py
+envs/connect4_env/models.py
+envs/connect4_env/server/__init__.py
+envs/connect4_env/server/app.py
+envs/connect4_env/server/connect4_environment.py
+envs/dipg_safety_env/__init__.py
+envs/dipg_safety_env/client.py
+envs/dipg_safety_env/models.py
+envs/dipg_safety_env/server/__init__.py
+envs/dipg_safety_env/server/app.py
+envs/dipg_safety_env/server/dipg_environment.py
+envs/echo_env/__init__.py
+envs/echo_env/client.py
+envs/echo_env/models.py
+envs/echo_env/build/lib/server/__init__.py
+envs/echo_env/build/lib/server/app.py
+envs/echo_env/build/lib/server/echo_environment.py
+envs/echo_env/server/__init__.py
+envs/echo_env/server/app.py
+envs/echo_env/server/echo_environment.py
+envs/finrl_env/__init__.py
+envs/finrl_env/client.py
+envs/finrl_env/models.py
+envs/finrl_env/server/__init__.py
+envs/finrl_env/server/app.py
+envs/finrl_env/server/finrl_environment.py
+envs/git_env/__init__.py
+envs/git_env/client.py
+envs/git_env/models.py
+envs/git_env/server/__init__.py
+envs/git_env/server/app.py
+envs/git_env/server/git_task_environment.py
+envs/openspiel_env/__init__.py
+envs/openspiel_env/client.py
+envs/openspiel_env/models.py
+envs/openspiel_env/server/__init__.py
+envs/openspiel_env/server/app.py
+envs/openspiel_env/server/openspiel_environment.py
+envs/openspiel_env/server/opponent_policies.py
+envs/play/build/lib/server/__init__.py
+envs/play/build/lib/server/app.py
+envs/play/build/lib/server/play_environment.py
+envs/sumo_rl_env/__init__.py
+envs/sumo_rl_env/client.py
+envs/sumo_rl_env/models.py
+envs/sumo_rl_env/server/__init__.py
+envs/sumo_rl_env/server/app.py
+envs/sumo_rl_env/server/sumo_environment.py
+envs/textarena_env/__init__.py
+envs/textarena_env/client.py
+envs/textarena_env/models.py
+envs/textarena_env/rewards.py
+envs/textarena_env/build/lib/server/__init__.py
+envs/textarena_env/build/lib/server/app.py
+envs/textarena_env/build/lib/server/environment.py
+envs/textarena_env/server/__init__.py
+envs/textarena_env/server/app.py
+envs/textarena_env/server/environment.py
+src/openenv/__init__.py
+src/openenv.egg-info/PKG-INFO
+src/openenv.egg-info/SOURCES.txt
+src/openenv.egg-info/dependency_links.txt
+src/openenv.egg-info/entry_points.txt
+src/openenv.egg-info/requires.txt
+src/openenv.egg-info/top_level.txt
+src/openenv/cli/__init__.py
+src/openenv/cli/__main__.py
+src/openenv/cli/_cli_utils.py
+src/openenv/cli/_validation.py
+src/openenv/cli/commands/__init__.py
+src/openenv/cli/commands/build.py
+src/openenv/cli/commands/init.py
+src/openenv/cli/commands/push.py
+src/openenv/cli/commands/serve.py
+src/openenv/cli/commands/validate.py
+src/openenv/cli/templates/__init__.py
+src/openenv/cli/templates/__pycache__/__init__.cpython-311.pyc
+src/openenv/cli/templates/__pycache__/__init__.cpython-313.pyc
+src/openenv/cli/templates/openenv_env/README.md
+src/openenv/cli/templates/openenv_env/__init__.py
+src/openenv/cli/templates/openenv_env/client.py
+src/openenv/cli/templates/openenv_env/models.py
+src/openenv/cli/templates/openenv_env/openenv.yaml
+src/openenv/cli/templates/openenv_env/pyproject.toml
+src/openenv/cli/templates/openenv_env/server/Dockerfile
+src/openenv/cli/templates/openenv_env/server/__ENV_NAME___environment.py
+src/openenv/cli/templates/openenv_env/server/__init__.py
+src/openenv/cli/templates/openenv_env/server/app.py
+src/openenv/cli/templates/openenv_env/server/requirements.txt
+src/openenv/core/__init__.py
+src/openenv/core/client_types.py
+src/openenv/core/env_client.py
+src/openenv/core/utils.py
+src/openenv/core/containers/__init__.py
+src/openenv/core/containers/test_local_docker_provider.py
+src/openenv/core/containers/runtime/__init__.py
+src/openenv/core/containers/runtime/providers.py
+src/openenv/core/containers/runtime/uv_provider.py
+src/openenv/core/env_server/__init__.py
+src/openenv/core/env_server/base_transforms.py
+src/openenv/core/env_server/exceptions.py
+src/openenv/core/env_server/http_server.py
+src/openenv/core/env_server/interfaces.py
+src/openenv/core/env_server/route_config.py
+src/openenv/core/env_server/serialization.py
+src/openenv/core/env_server/types.py
+src/openenv/core/env_server/web_interface.py
+src/openenv/core/tools/__init__.py
+src/openenv/core/tools/git_server_client.py
+src/openenv/core/tools/local_python_executor.py
+src/openenv_core/__init__.py

src/openenv.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

src/openenv.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openenv = openenv.cli.__main__:main

src/openenv.egg-info/requires.txt

@@ -0,0 +1,32 @@
+fastapi>=0.104.0
+pydantic>=2.0.0
+uvicorn>=0.24.0
+requests>=2.25.0
+typer>=0.9.0
+rich>=13.0.0
+pyyaml>=6.0
+huggingface_hub>=0.20.0
+openai>=2.7.2
+tomli>=2.3.0
+tomli-w>=1.2.0
+websockets>=15.0.1
+
+[all]
+openenv[core]
+openenv[cli]
+
+[cli]
+typer>=0.9.0
+rich>=13.0.0
+pyyaml>=6.0
+huggingface_hub>=0.20.0
+openai>=2.7.2
+tomli>=2.3.0
+tomli-w>=1.2.0
+
+[core]
+fastapi>=0.104.0
+pydantic>=2.0.0
+uvicorn>=0.24.0
+requests>=2.25.0
+websockets>=15.0.1

src/openenv.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+openenv
+openenv_core

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),
+        )

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

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

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

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