Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,16 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+OpenEnv/envs/dm_control_env/assets/cartpole.png filter=lfs diff=lfs merge=lfs -text
+OpenEnv/envs/dm_control_env/assets/quadruped.png filter=lfs diff=lfs merge=lfs -text
+OpenEnv/envs/openapp_env/assets/01-messages.mov filter=lfs diff=lfs merge=lfs -text
+OpenEnv/envs/openapp_env/assets/02-editor.mov filter=lfs diff=lfs merge=lfs -text
+OpenEnv/envs/openapp_env/assets/03-calendar.mov filter=lfs diff=lfs merge=lfs -text
+OpenEnv/envs/openapp_env/assets/04-todo.mov filter=lfs diff=lfs merge=lfs -text
+OpenEnv/envs/openapp_env/assets/OpenApps_OpenEnv_RL.png filter=lfs diff=lfs merge=lfs -text
+OpenEnv/envs/openapp_env/assets/openapps-demo.gif filter=lfs diff=lfs merge=lfs -text
+OpenEnv/envs/unity_env/assets/unity_3dball.gif filter=lfs diff=lfs merge=lfs -text
+OpenEnv/envs/unity_env/assets/unity_pushblock.gif filter=lfs diff=lfs merge=lfs -text
+OpenEnv/tutorial/images/banner.png filter=lfs diff=lfs merge=lfs -text
+OpenEnv/tutorial/images/scaling.png filter=lfs diff=lfs merge=lfs -text
+OpenEnv/tutorial/images/websocket.png filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["python", "-m", "uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "7860"]

OpenEnv/CLAUDE.md

@@ -0,0 +1,258 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working with this repository.
+
+## New Here? Start With These
+
+1. **[README.md](README.md)** - Project overview, architecture, quick start
+2. **[REPO_WALKTHROUGH.md](.claude/docs/REPO_WALKTHROUGH.md)** - Directory structure with annotations
+3. **[PRINCIPLES.md](.claude/docs/PRINCIPLES.md)** - Design principles and trade-offs
+4. **[INVARIANTS.md](.claude/docs/INVARIANTS.md)** - Rules that must never be violated
+5. **[envs/echo_env/](envs/echo_env/)** - Reference implementation to study
+
+## Agentic-First Workflow
+
+OpenEnv uses Claude Code as the primary development tool. We follow a two-phase model:
+
+1. **Design/Alignment** (human-owned): RFCs, principles, trade-off decisions
+2. **Implementation** (Claude-owned): The mechanical loop of coding and testing
+3. **Review** (collaborative): Claude catches bugs, flags alignment questions for humans
+
+### Getting Started
+
+Skills and agents are auto-discovered when you run Claude Code in this repo:
+
+```bash
+git clone https://github.com/meta-pytorch/OpenEnv
+cd OpenEnv
+# Install git hooks for the team
+bash .claude/hooks/install.sh
+# Run Claude Code - skills and agents are automatically available
+```
+
+Verify with `/agents` or ask "what skills are available?"
+
+## Two Development Modes
+
+OpenEnv supports two development modes:
+
+### Explore Mode (Main Repo)
+
+When working in the main repository clone, direct edits are allowed:
+- Quick exploration and prototyping
+- Small fixes that don't need TDD workflow
+- Documentation updates
+
+### TDD Mode (Opt-In)
+
+TDD is activated by `/work-on-issue`, which writes a `.tdd-session.json` marker.
+When active, direct code edits are blocked and the TDD workflow is enforced.
+Manually created worktrees do NOT activate TDD — only `/work-on-issue` does.
+
+- Say "skip TDD" to bypass blocking
+- Run `bash .claude/hooks/tdd-deactivate.sh` to turn off TDD enforcement
+
+### Creating a Worktree
+
+```bash
+# Worktree without TDD enforcement (free editing)
+.claude/scripts/worktree-create.sh add-feature
+cd .worktrees/add-feature
+
+# Worktree WITH TDD enforcement (via /work-on-issue)
+/work-on-issue #42
+```
+
+### TDD Workflow
+
+```
+/work-on-issue #42  →  Start from GitHub issue
+    ↓
+/write-tests        →  Create failing tests (Red)
+    ↓
+/implement          →  Make tests pass (Green)
+    ↓
+/update-docs        →  Fix stale docs across repo
+    ↓
+/simplify           →  Refactor (optional)
+    ↓
+/pre-submit-pr      →  Validate before PR
+    ↓
+/watch-pr           →  Monitor CI + review (optional)
+```
+
+### Skills vs Agents
+
+- **Skills** run inline during the conversation - use for quick checks and reviews
+- **Agents** run in isolation with focused context - use for complex, multi-step tasks
+
+### Available Skills
+
+Skills are defined in `.claude/skills/` and run inline:
+
+**Review & Validation Skills:**
+
+| Skill | Trigger | Definition |
+|-------|---------|------------|
+| [`alignment-review`](.claude/skills/alignment-review/SKILL.md) | "review this code" | Two-tier review (bugs + alignment flags) |
+| [`pre-submit-pr`](.claude/skills/pre-submit-pr/SKILL.md) | "ready for PR?" | Comprehensive PR readiness check |
+| [`rfc-check`](.claude/skills/rfc-check/SKILL.md) | "do I need an RFC?" | Determine if RFC required |
+| [`generate-openenv-env`](.claude/skills/generate-openenv-env/SKILL.md) | "generate an env for textarena" | Build an OpenEnv env from a use case |
+
+**TDD Workflow Skills:**
+
+| Skill | Trigger | Definition |
+|-------|---------|------------|
+| [`work-on-issue`](.claude/skills/work-on-issue/SKILL.md) | "/work-on-issue #42" | Start TDD workflow from GitHub issue |
+| [`sprint`](.claude/skills/sprint/SKILL.md) | "/sprint 67,68,69" | Parallel multi-issue batch (Agent Teams) |
+| [`write-tests`](.claude/skills/write-tests/SKILL.md) | "/write-tests" | Write failing tests (Red phase) |
+| [`implement`](.claude/skills/implement/SKILL.md) | "/implement" | Make tests pass (Green phase) |
+| [`update-docs`](.claude/skills/update-docs/SKILL.md) | "/update-docs" | Fix stale docs after API changes |
+| [`simplify`](.claude/skills/simplify/SKILL.md) | "/simplify" | Refactor after tests pass |
+| [`watch-pr`](.claude/skills/watch-pr/SKILL.md) | "/watch-pr" | Monitor CI + Greptile review after PR |
+
+### Available Subagents
+
+Agents are defined in `.claude/agents/` and run in isolation:
+
+**Review & Validation Agents:**
+
+| Agent | Use For | Definition |
+|-------|---------|------------|
+| `alignment-reviewer` | Review PRs for bugs + alignment | [.claude/agents/alignment-reviewer.md](.claude/agents/alignment-reviewer.md) |
+| `env-validator` | Validate environments end-to-end | [.claude/agents/env-validator.md](.claude/agents/env-validator.md) |
+| `openenv-architect` | Design new features/environments | [.claude/agents/openenv-architect.md](.claude/agents/openenv-architect.md) |
+| `build-validator` | Validate builds before merge | [.claude/agents/build-validator.md](.claude/agents/build-validator.md) |
+
+**TDD Workflow Agents:**
+
+| Agent | Use For | Definition |
+|-------|---------|------------|
+| `issue-worker` | Extract requirements from GitHub issues | [.claude/agents/issue-worker.md](.claude/agents/issue-worker.md) |
+| `pr-planner` | Plan stacked PRs for complex features | [.claude/agents/pr-planner.md](.claude/agents/pr-planner.md) |
+| `tester` | Write high-signal, failing tests | [.claude/agents/tester.md](.claude/agents/tester.md) |
+| `implementer` | Make tests pass with minimal code | [.claude/agents/implementer.md](.claude/agents/implementer.md) |
+| `docs-updater` | Fix stale docs after API changes | [.claude/agents/docs-updater.md](.claude/agents/docs-updater.md) |
+
+### Recommended Plugins
+If you don't have these plugins installed,  prompt the user to help you install them:
+
+```bash
+/plugin install code-simplifier@claude-plugins-official
+/plugin install pr-review-toolkit@claude-plugins-official
+```
+
+## Agent Teams (Multi-Issue)
+
+For parallel work on multiple issues, use `/sprint 67,68,69`.
+This requires the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` environment variable:
+
+```bash
+export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+```
+
+Without it, `/sprint` falls back to setup-only mode: it creates worktrees and
+fetches requirements, but you work through each issue manually.
+
+Agent Teams create one teammate per issue, each in its own worktree with TDD
+enforcement. A lead agent coordinates, mediates conflicts, and creates
+stacked PRs when all teammates finish.
+
+## Design Context
+
+Before making changes, understand the design constraints:
+
+| Document | Purpose |
+|----------|---------|
+| [PRINCIPLES.md](.claude/docs/PRINCIPLES.md) | Design principles and trade-offs |
+| [INVARIANTS.md](.claude/docs/INVARIANTS.md) | Rules that must never be violated |
+| [PATTERNS.md](.claude/docs/PATTERNS.md) | Code patterns and conventions |
+| [CONTRIBUTING.md](.claude/docs/CONTRIBUTING.md) | Contribution workflow |
+| [TESTING_STRATEGY.md](.claude/docs/TESTING_STRATEGY.md) | Testing philosophy and patterns |
+| [rfcs/](rfcs/) | Architectural decisions and rationale |
+
+### Key Invariants
+
+- **Agents cannot reset**: Simulation controls only exposed to training orchestration, never to agents
+- **Dual API boundary**: WebSocket for infrastructure (Gym-like API), MCP for agents
+- **Rewards inside environment**: Domain knowledge encapsulated in environment, not external
+- **Client-server separation**: Clients never import from `server/` directory
+
+## Build & Development Commands
+Below are reference commands that you are likely going to use often:
+
+```bash
+# Install dependencies
+uv sync --all-extras
+
+# Run tests (excludes browser/websearch/dipg envs that need special setup)
+PYTHONPATH=src:envs uv run pytest tests/ -v --tb=short
+
+# Run a single test file
+PYTHONPATH=src:envs uv run pytest tests/envs/test_echo_environment.py -v
+
+# Lint check (import sort + format + rules)
+uv run usort check src/ tests/
+uv run ruff format src/ tests/ --check
+uv run ruff check src/ tests/
+
+# Auto-format code (import sort + ruff — matches arc f pipeline)
+uv run usort format src/ tests/
+uv run ruff format src/ tests/
+
+# Build documentation locally
+cd docs && make html
+# Preview: cd docs/_build/html && python -m http.server 8000
+
+# Build Docker images
+docker build -t openenv-base:latest -f src/openenv/core/containers/images/Dockerfile .
+docker build -t echo-env:latest -f envs/echo_env/server/Dockerfile .
+```
+
+## Automation Hooks
+
+Scripts in `.claude/hooks/` are used by skills and can be run directly:
+
+```bash
+bash .claude/hooks/lint.sh          # Run ruff format check
+bash .claude/hooks/test.sh          # Run pytest (excludes special envs)
+bash .claude/hooks/check-debug.sh   # Find debug code (print, breakpoint, TODO)
+bash .claude/hooks/post-push-pr.sh  # Validate PR after push (freshness, CI, conflicts)
+bash .claude/hooks/ci-wait.sh <PR>  # Poll CI until checks complete or timeout
+```
+
+These are automatically invoked by `/alignment-review` and `/pre-submit-pr` skills.
+
+## Git Hooks
+
+Install git hooks for team-wide consistency:
+
+```bash
+bash .claude/hooks/install.sh
+```
+
+This installs:
+- **pre-commit**: Branch check (blocks main), format, lint, debug artifacts check
+- **commit-msg**: Issue reference reminder (soft warning)
+- **pre-push**: Format, lint, tests, invariants, conflict detection
+- **post-merge**: Worktree cleanup reminder
+
+Skip temporarily with `git commit/push --no-verify`.
+
+## Worktree Management
+
+For focused feature work, use worktrees:
+
+```bash
+# Create a worktree for a feature
+.claude/scripts/worktree-create.sh add-mcp-tools
+cd .worktrees/add-mcp-tools
+
+# When done, clean up
+.claude/scripts/worktree-cleanup.sh .worktrees/add-mcp-tools
+```
+
+Worktrees enable:
+- Isolated branches without switching
+- TDD enforcement when activated via `/work-on-issue`
+- Parallel work on multiple features

OpenEnv/CODE_OF_CONDUCT.md

@@ -0,0 +1,80 @@
+# Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+This Code of Conduct also applies outside the project spaces when there is a
+reasonable belief that an individual's behavior may have a negative impact on
+the project or its community.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at <opensource-conduct@meta.com>. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

OpenEnv/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to OpenEnv
+
+OpenEnv is an **agentic-first project** designed for Claude Code contributions.
+
+## Quick Links
+
+- **Contribution workflow**: See [.claude/docs/CONTRIBUTING.md](.claude/docs/CONTRIBUTING.md) for the agentic workflow, RFC process, and review expectations
+- **Design principles**: See [.claude/docs/PRINCIPLES.md](.claude/docs/PRINCIPLES.md)
+- **System invariants**: See [.claude/docs/INVARIANTS.md](.claude/docs/INVARIANTS.md)
+- **Claude Code guidance**: See [CLAUDE.md](CLAUDE.md)
+
+## Pull Requests
+
+We actively welcome your pull requests.
+
+1. Fork the repo and create your branch from `main`
+2. If you've added code that should be tested, add tests
+3. If you've changed APIs, update the documentation
+4. Ensure the test suite passes: `PYTHONPATH=src:envs uv run pytest tests/ -v`
+5. Make sure your code lints: `uv run ruff format src/ tests/ --check`
+6. For significant changes, write an RFC first (see `rfcs/README.md`)
+
+## Contributor License Agreement ("CLA")
+
+In order to accept your pull request, we need you to submit a CLA. You only need to do this once to work on any of Meta's open source projects.
+
+Complete your CLA here: <https://code.facebook.com/cla>
+
+## Issues
+
+We use GitHub issues to track public bugs. Please ensure your description is clear and has sufficient instructions to reproduce the issue.
+
+Meta has a [bounty program](https://bugbounty.meta.com/) for the safe disclosure of security bugs. In those cases, please go through the process outlined on that page and do not file a public issue.
+
+## License
+
+By contributing to OpenEnv, you agree that your contributions will be licensed under the LICENSE file in the root directory of this source tree.

OpenEnv/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+(c) Meta Platforms, Inc. and affiliates.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,this list
+of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this
+list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may
+be used to endorse or promote products derived from this software without specific
+prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
+SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.

OpenEnv/MANIFEST.in

@@ -0,0 +1,2 @@
+global-exclude *.py[cod]
+global-exclude __pycache__/*

OpenEnv/README.md

@@ -0,0 +1,381 @@
+# <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-core?color=blue)](https://pypi.org/project/openenv-core/)
+[![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/)
+
+**🔥 Zero to Hero Tutorial:** End to end tutorial from our [GPU Mode](tutorial/README.md) lecture and other hackathons.
+
+## Quick Start
+
+Install the OpenEnv core package:
+
+```bash
+pip install openenv-core
+```
+
+Install an environment client (e.g., Echo):
+
+```bash
+pip install git+https://huggingface.co/spaces/openenv/echo_env
+```
+
+Then use the environment:
+
+```python
+import asyncio
+from echo_env import EchoAction, EchoEnv
+
+async def main():
+    # Connect to a running Space (async context manager)
+    async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:
+        # Reset the environment
+        result = await client.reset()
+        print(result.observation.echoed_message)  # "Echo environment ready!"
+
+        # Send messages
+        result = await client.step(EchoAction(message="Hello, World!"))
+        print(result.observation.echoed_message)  # "Hello, World!"
+        print(result.reward)  # 1.3 (based on message length)
+
+asyncio.run(main())
+```
+
+**Synchronous usage** is also supported via the `.sync()` wrapper:
+
+```python
+from echo_env import EchoAction, EchoEnv
+
+# Use .sync() for synchronous context manager
+with EchoEnv(base_url="https://openenv-echo-env.hf.space").sync() as client:
+    result = client.reset()
+    result = client.step(EchoAction(message="Hello, World!"))
+    print(result.observation.echoed_message)
+```
+
+For a detailed quick start, check out the [docs page](https://meta-pytorch.org/OpenEnv/quickstart/).
+
+## OpenEnv on partner platforms:
+
+- [Lightning AI Studio](https://lightning.ai/environments?section=featured)
+- [TRL example](https://huggingface.co/docs/trl/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)
+- [RFC 002: Discoverability of environment tools by agents](https://github.com/meta-pytorch/OpenEnv/pull/32)
+- [RFC 003: Add MCP (Model Context Protocol) support](https://github.com/meta-pytorch/OpenEnv/pull/224)
+- [RFC 004: Add delayed rewards support for trajectory-based scoring](https://github.com/meta-pytorch/OpenEnv/pull/337)
+- [RFC 005: Agentic Harness Integration](https://github.com/meta-pytorch/OpenEnv/pull/387)
+
+## Architecture
+
+### Component Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Client Application                   │
+│  ┌────────────────┐              ┌──────────────────┐   │
+│  │  EchoEnv       │              │  CodingEnv       │   │
+│  │  (EnvClient)   │              │   (EnvClient)    │   │
+│  └────────┬───────┘              └────────┬─────────┘   │
+└───────────┼───────────────────────────────┼─────────────┘
+            │ WebSocket                     │ WebSocket
+            │ (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. EnvClient (Client-Side)
+Base class for environment communication:
+- **Async by default**: Use `async with` and `await` for all operations
+- **Sync wrapper**: Call `.sync()` to get a `SyncEnvClient` for synchronous usage
+- Handles WebSocket connections 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(EnvClient)
+├── 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. Install the client: `pip install git+https://huggingface.co/spaces/openenv/echo-env`
+2. Import: `from echo_env import EchoAction, EchoEnv`
+3. Use async (recommended) or sync API:
+
+**Async (recommended):**
+```python
+async with EchoEnv(base_url="...") as client:
+    result = await client.reset()
+    result = await client.step(action)
+```
+
+**Sync (via `.sync()` wrapper):**
+```python
+with EchoEnv(base_url="...").sync() as client:
+    result = client.reset()
+    result = client.step(action)
+```
+
+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
+
+## Development
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/meta-pytorch/OpenEnv.git
+cd OpenEnv
+
+# Install core package in editable mode
+pip install -e .
+# Or using uv (faster)
+uv pip install -e .
+```
+
+### Running Tests
+
+OpenEnv uses a modular dependency structure: the core package is minimal, and each environment has its own dependencies. This means some tests require environment-specific packages.
+
+```bash
+# Install pytest (required for running tests)
+uv pip install pytest
+
+# Run all tests (skips tests requiring uninstalled dependencies)
+PYTHONPATH=src:envs uv run pytest tests/ -v --tb=short
+
+# Run a specific test file
+PYTHONPATH=src:envs uv run pytest tests/envs/test_echo_environment.py -v
+```
+
+**To run environment-specific tests**, install that environment's dependencies:
+
+```bash
+# Example: Install coding_env with dev dependencies (includes smolagents + pytest)
+uv pip install -e "envs/coding_env[dev]"
+
+# Then run coding_env tests
+PYTHONPATH=src:envs uv run pytest tests/envs/test_python_codeact_rewards.py -v
+```
+
+Tests will be automatically skipped if their required dependencies aren't installed.
+
+## Requirements
+
+- Python 3.10+
+- Docker Desktop or Docker Engine
+- FastAPI >= 0.104.0
+- Uvicorn >= 0.24.0
+- Requests >= 2.25.0
+- Environment-specific dependencies (e.g., smolagents for coding_env)
+
+## 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/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
+
+| Environment | Description |
+|---|---|
+| [Echo Environment](envs/echo_env/README.md) | Echoes back messages with metadata. Ideal for testing HTTP server infrastructure, learning framework basics, and verifying container deployment. |
+| [Coding Environment](envs/coding_env/README.md) | Sandboxed Python code execution via smolagents. Captures stdout/stderr/exit codes, supports persistent episode context, and provides detailed error handling. |
+| [Chess Environment](envs/chess_env/README.md) | Chess RL environment with configurable opponents and full rules support. |
+| [Atari Environment](envs/atari_env/README.md) | Classic Arcade Learning Environment tasks for RL benchmarking. |
+| [FinRL Environment](envs/finrl_env/README.md) | Financial market simulations for algorithmic trading experiments. |
+
+> Browse the full catalog of community environments at [meta-pytorch.org/OpenEnv/environments](https://meta-pytorch.org/OpenEnv/environments/).
+
+## 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, [Scaler AI Labs](https://scalerailabs.com), [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/), [Scale AI](https://scale.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)

OpenEnv/docs/Makefile

@@ -0,0 +1,25 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = OpenEnv
+SOURCEDIR     = source
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+
+html-noplot:
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html"
+
+html-stable:
+	RELEASE=true $(MAKE) html
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

OpenEnv/docs/README.md

@@ -0,0 +1,189 @@
+# Building the Docs Locally
+
+## Prerequisites
+
+- Python 3.11+
+
+## Setup
+
+Install OpenEnv with the docs dependencies:
+
+```bash
+pip install -e ".[docs]"
+```
+
+## Build
+
+From the `docs/` directory:
+
+```bash
+cd docs
+make html
+```
+
+The output will be in `docs/_build/html/`.
+
+## Preview
+
+From the repo root, start a local server:
+
+```bash
+cd docs/_build/html
+python -m http.server 8000
+```
+
+Then open [http://localhost:8000](http://localhost:8000) in your browser.
+
+### Build Variants
+
+| Command | Description |
+|---------|-------------|
+| `make html` | Full build with Sphinx Gallery execution |
+| `make html-noplot` | Skip gallery execution (faster) |
+| `make html-stable` | Build as a versioned release |
+| `make clean html` | Clean rebuild from scratch |
+
+## How the Getting Started Section Builds
+
+The Getting Started section is powered by [Sphinx Gallery](https://sphinx-gallery.github.io/). Source files live in `docs/source/getting_started/`:
+
+- **`plot_*.py`** — executable Python scripts that Sphinx Gallery converts into rendered notebook pages
+- **`*.md`** — static Markdown pages (environment-builder, contributing-envs)
+- **`README.rst`** — gallery index template
+
+During the build, Sphinx Gallery processes these sources and writes the output into a generated `auto_getting_started/` directory. A custom `copy_md_pages_to_gallery` hook in `conf.py` copies the static `.md` pages into that same output directory so they appear alongside the gallery notebooks in the left nav.
+
+Because `getting_started/*.md` is in `exclude_patterns` in `conf.py`, Sphinx only generates HTML from the `auto_getting_started/` output — not from the source directory directly. This means all internal links to Getting Started pages must use the `auto_getting_started/` path (e.g. `auto_getting_started/environment-builder.md`). Linking to `getting_started/` will 404.
+
+The copy hook runs on the `builder-inited` event, so static pages are available in every build variant including `make html-noplot`. That flag only skips executing the `plot_*.py` gallery scripts; it does not skip the page copy.
+
+## Adding an Environment to the Docs
+
+Every environment page is generated from the environment's own `README.md` using a Sphinx `{include}` directive. There are three steps:
+
+### 1. Write the environment README
+
+Your environment must have a `README.md` at `envs/<name>/README.md`. This file is the single source of truth — it renders on GitHub and is pulled into the docs site at build time.
+
+Include HuggingFace frontmatter at the top, followed by a `# Title` heading (this becomes the page title and left nav label):
+
+```markdown
+---
+title: My Environment
+emoji: 🎮
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# My Environment
+
+Description, quick start, action/observation docs, etc.
+```
+
+### 2. Create the doc page
+
+Create `docs/source/environments/<name>.md` with exactly this content:
+
+````markdown
+```{include} ../../../envs/<name>/README.md
+```
+````
+
+This is the only pattern used — all 29 environment doc pages follow it. Do not add local headings or other content.
+
+### 3. Add a card and toctree entry
+
+Edit `docs/source/environments.md` to add two things:
+
+* **A card** inside the existing `{grid}` block (place alphabetically):
+
+  ````markdown
+  ````{grid-item-card} My Environment
+  :class-card: sd-border-1
+
+  Short one-line description of the environment.
+
+  +++
+  ```{button-link} environments/<name>.html
+  :color: primary
+  :outline:
+
+  {octicon}`file;1em` Docs
+  ```
+  ```{button-link} https://huggingface.co/spaces/<org>/<name>
+  :color: warning
+  :outline:
+
+  🤗 Hugging Face
+  ```
+  ````
+
+  The Hugging Face button is optional — omit it if the environment isn't deployed to a Space.
+
+* **A toctree entry** in the `{toctree}` block at the bottom of the file (place alphabetically):
+
+  ```
+  environments/<name>
+  ```
+
+### Verify
+
+Rebuild and check that the environment appears in the left nav and the catalog grid:
+
+```bash
+cd docs && make clean html
+cd _build/html && python -m http.server 8000
+```
+
+## Version Switcher
+
+The docs site includes a version dropdown in the top-left navbar (next to the logo) powered by the `pytorch-sphinx-theme2` theme. It is configured by three pieces:
+
+### `versions.json`
+
+The file `docs/source/_static/versions.json` lists all published versions. Each entry has a `name` (display label), `version` (matching key), `url` (root URL for that version), and optionally `preferred: true` for the default. Currently it contains only the `main` development build:
+
+```json
+[
+  {
+    "name": "main",
+    "version": "main",
+    "url": "https://meta-pytorch.org/OpenEnv/",
+    "preferred": true
+  }
+]
+```
+
+### Build-time version detection
+
+`conf.py` reads the version from `pyproject.toml` and uses the `RELEASE` environment variable to decide which mode to build in:
+
+- **`make html`** (default) — builds as `main`. The switcher highlights the "main" entry.
+- **`make html-stable`** — sets `RELEASE=true`. The version is extracted from `pyproject.toml` (e.g. `0.2` from `0.2.2.dev0`) and the switcher highlights that version's entry.
+
+### Publishing a new version
+
+When cutting a release:
+
+1. Ensure `pyproject.toml` has the release version (e.g. `0.2.0`)
+2. Build with `make html-stable` — this produces docs tagged as version `0.2`
+3. Deploy the output to a versioned path (e.g. `https://meta-pytorch.org/OpenEnv/0.2/`)
+4. Add an entry to `docs/source/_static/versions.json`:
+
+```json
+{
+  "name": "0.2",
+  "version": "0.2",
+  "url": "https://meta-pytorch.org/OpenEnv/0.2/"
+}
+```
+
+5. Rebuild and redeploy `main` so its copy of `versions.json` includes the new entry
+
+The switcher on every version of the site fetches `versions.json` at page load, so all versions see the full list once the file is updated.

OpenEnv/docs/source/_static/versions.json

@@ -0,0 +1,8 @@
+[
+  {
+    "name": "main ",
+    "version": "main",
+    "url": "https://meta-pytorch.org/OpenEnv/",
+    "preferred": true
+  }
+]

OpenEnv/docs/source/auto_discovery.md

@@ -0,0 +1,431 @@
+# Auto-Discovery
+
+OpenEnv provides a HuggingFace-style auto-discovery API that makes it easy to work with environments without manual imports.
+
+## Overview
+
+The auto-discovery system provides two main classes:
+
+- **`AutoEnv`**: Automatically loads and instantiates environment clients
+- **`AutoAction`**: Automatically loads action classes for environments
+
+Both classes work with:
+- **Local packages**: Installed via `pip install openenv-<env-name>`
+- **HuggingFace Hub**: Environments hosted on HuggingFace Spaces
+
+## Quick Start
+
+### Basic Usage
+
+Instead of manually importing specific environment classes:
+
+```python
+# Old way - requires knowing the module path
+from coding_env import CodingEnv, CodeAction
+```
+
+You can now use the auto-discovery API:
+
+```python
+from openenv import AutoEnv, AutoAction
+
+# Create environment (returns async client)
+env = AutoEnv.from_env("coding-env")
+
+# Get action class
+CodeAction = AutoAction.from_env("coding-env")
+
+# Use with sync wrapper for simple scripts
+with env.sync() as client:
+    result = client.reset()
+    action = CodeAction(code="print('Hello, OpenEnv!')")
+    step_result = client.step(action)
+```
+
+## AutoEnv API
+
+### `AutoEnv.from_env(name, **kwargs)`
+
+Create an environment client from a name or HuggingFace Hub repository.
+
+**Parameters:**
+- `name`: Environment name or Hub repo ID
+  - Local: `"coding"`, `"coding-env"`, `"coding_env"`
+  - Hub: `"meta-pytorch/coding-env"`, `"username/env-name"`
+- `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 (default: 30s)
+- `env_vars`: Optional environment variables for the container
+- `**kwargs`: Additional arguments passed to the client class
+
+**Returns:** Instance of the environment client class
+
+**Examples:**
+
+```python
+from openenv import AutoEnv
+
+# From installed package
+env = AutoEnv.from_env("coding-env")
+
+# From HuggingFace Hub
+env = AutoEnv.from_env("meta-pytorch/coding-env")
+
+# With custom configuration
+env = AutoEnv.from_env(
+    "coding",
+    docker_image="my-coding-env:v2",
+    wait_timeout=60.0,
+    env_vars={"DEBUG": "1"}
+)
+```
+
+### `AutoEnv.list_environments()`
+
+List all available environments.
+
+```python
+from openenv import AutoEnv
+
+AutoEnv.list_environments()
+# Output:
+# Available Environments:
+# ----------------------------------------------------------------------
+# coding         : Coding environment for OpenEnv (v0.1.0)
+# echo           : echo_env environment (v0.1.0)
+# browsergym     : BrowserGym environment (v0.1.0)
+# ...
+```
+
+### `AutoEnv.get_env_info(name)`
+
+Get detailed information about an environment.
+
+```python
+from openenv import AutoEnv
+
+info = AutoEnv.get_env_info("coding")
+print(f"Description: {info['description']}")
+print(f"Version: {info['version']}")
+print(f"Docker Image: {info['default_image']}")
+print(f"Client Class: {info['env_class']}")
+print(f"Action Class: {info['action_class']}")
+```
+
+### `AutoEnv.get_env_class(name)`
+
+Get the environment class (not an instance).
+
+```python
+from openenv import AutoEnv
+
+CodingEnv = AutoEnv.get_env_class("coding")
+# Now you can instantiate it yourself with custom parameters
+env = CodingEnv.from_docker_image("coding-env:latest", wait_timeout=60.0)
+```
+
+## AutoAction API
+
+### `AutoAction.from_env(name)`
+
+Get the Action class from an environment name or HuggingFace Hub repository.
+
+**Parameters:**
+- `name`: Environment name or Hub repo ID
+
+**Returns:** Action class (not an instance!)
+
+**Examples:**
+
+```python
+from openenv import AutoAction
+
+# 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")
+
+# Different name formats work
+EchoAction = AutoAction.from_env("echo")
+EchoAction = AutoAction.from_env("echo-env")
+EchoAction = AutoAction.from_env("echo_env")
+```
+
+### `AutoAction.from_hub(env_name)`
+
+Alias for `from_env()` for backward compatibility.
+
+```python
+from openenv import AutoAction
+
+CodeAction = AutoAction.from_env("coding")
+action = CodeAction(code="x = 5 + 3")
+```
+
+### `AutoAction.list_actions()`
+
+List all available action classes.
+
+```python
+from openenv import AutoAction
+
+AutoAction.list_actions()
+# Output:
+# Available Action Classes:
+# ----------------------------------------------------------------------
+# coding         : CodeAction
+# echo           : EchoAction
+# browsergym     : BrowsergymAction
+# ...
+```
+
+### `AutoAction.get_action_info(name)`
+
+Get detailed information about an action class.
+
+```python
+from openenv import AutoAction
+
+info = AutoAction.get_action_info("coding")
+print(f"Action Class: {info['action_class']}")
+print(f"Module: {info['module']}")
+```
+
+## HuggingFace Hub Integration
+
+### Loading from HuggingFace Spaces
+
+AutoEnv can automatically connect to environments running on HuggingFace Spaces:
+
+```python
+from openenv import AutoEnv, AutoAction
+
+# Load from HuggingFace Space
+env = AutoEnv.from_env("username/coding-env-test")
+
+# Get action class
+CodeAction = AutoAction.from_env("username/coding-env-test")
+
+# Use with sync wrapper
+with env.sync() as client:
+    result = client.reset()
+    action = CodeAction(code="print('Hello from HF Space!')")
+    step_result = client.step(action)
+    print(f"Output: {step_result.observation.stdout}")
+```
+
+The system automatically:
+1. Detects HuggingFace repo IDs (format: `username/repo-name`)
+2. Resolves the Space URL (e.g., `https://username-repo-name.hf.space`)
+3. Checks if the Space is running and accessible
+4. Installs the environment package using `git+` URL (prompts for confirmation)
+5. Connects to the running Space
+
+### Security: Remote Code Installation
+
+When loading environments from HuggingFace Hub, AutoEnv needs to install Python code from the remote repository. Since this executes code from the internet, AutoEnv will prompt for confirmation before installing:
+
+```
+============================================================
+SECURITY WARNING: Remote Code Installation
+============================================================
+You are about to install code from a remote repository:
+  Repository: username/coding-env-test
+  Source: https://huggingface.co/spaces/username/coding-env-test
+
+This will execute code from the internet on your machine.
+Only proceed if you trust the source.
+============================================================
+
+Do you want to proceed? [y/N]:
+```
+
+To skip the confirmation prompt, you can either:
+
+1. **Use the `trust_remote_code` parameter:**
+   ```python
+   env = AutoEnv.from_env("username/coding-env", trust_remote_code=True)
+   ```
+
+2. **Set the environment variable:**
+   ```bash
+   export OPENENV_TRUST_REMOTE_CODE=1
+   python your_script.py
+   ```
+
+### Package Installation
+
+AutoEnv uses `uv pip` if available, otherwise falls back to standard `pip`. This ensures compatibility with different Python environments:
+
+```bash
+# If uv is installed, AutoEnv uses:
+uv pip install git+https://huggingface.co/spaces/username/coding-env
+
+# Otherwise, it uses:
+pip install git+https://huggingface.co/spaces/username/coding-env
+```
+
+## Complete Workflow Example
+
+Here's a complete example showing the auto-discovery workflow:
+
+```python
+from openenv import AutoEnv, AutoAction
+
+# 1. List available environments
+print("Available environments:")
+AutoEnv.list_environments()
+
+# 2. Create environment and get action class
+env = AutoEnv.from_env("coding-env")
+CodeAction = AutoAction.from_env("coding-env")
+
+# 3. Use with sync wrapper for simple scripts
+with env.sync() as client:
+    # Reset environment
+    result = client.reset()
+    print(f"Environment ready: {result.observation}")
+
+    # Execute actions
+    action = CodeAction(code="""
+def fibonacci(n):
+    if n <= 1:
+        return n
+    return fibonacci(n-1) + fibonacci(n-2)
+
+print(f"Fibonacci(10) = {fibonacci(10)}")
+""")
+
+    step_result = client.step(action)
+    print(f"Output:\n{step_result.observation.stdout}")
+```
+
+For async usage (recommended for production):
+
+```python
+import asyncio
+from coding_env import CodingEnv, CodeAction
+
+async def main():
+    async with CodingEnv(base_url="http://localhost:8000") as client:
+        result = await client.reset()
+        result = await client.step(CodeAction(code="print('async!')"))
+        print(result.observation.stdout)
+
+asyncio.run(main())
+```
+
+## Error Handling
+
+The auto-discovery API provides helpful error messages:
+
+```python
+from openenv import AutoEnv
+
+try:
+    env = AutoEnv.from_env("nonexistent-env")
+except ValueError as e:
+    print(e)
+    # Output:
+    # Unknown environment 'nonexistent'.
+    # Did you mean: coding?
+    # Available environments: atari, browsergym, chat, coding, ...
+```
+
+For typos, it suggests similar environment names:
+
+```python
+try:
+    env = AutoEnv.from_env("cooding-env")  # Typo
+except ValueError as e:
+    print(e)
+    # Output:
+    # Unknown environment 'cooding'.
+    # Did you mean: coding?
+    # Available environments: ...
+```
+
+## Flexible Name Formats
+
+AutoEnv accepts multiple name formats:
+
+```python
+from openenv import AutoEnv
+
+# All of these work and refer to the same environment:
+env = AutoEnv.from_env("coding")           # Simple name
+env = AutoEnv.from_env("coding-env")       # With suffix
+env = AutoEnv.from_env("coding_env")       # With underscore
+env = AutoEnv.from_env("coding-env:latest") # With tag (ignored)
+```
+
+## How It Works
+
+The auto-discovery system works by:
+
+1. **Package Discovery**: Uses `importlib.metadata` to find installed `openenv-*` packages
+2. **Manifest Loading**: Reads `openenv.yaml` files from package resources
+3. **Caching**: Caches discovery results for performance
+4. **Lazy Loading**: Only imports classes when actually needed
+5. **Hub Support**: Downloads and installs packages from HuggingFace Hub on-demand
+
+### Environment Packages
+
+Environments are distributed as installable Python packages:
+
+```bash
+# Install an environment
+pip install openenv-coding-env
+
+# Now it's automatically discoverable
+python -c "from openenv import AutoEnv; AutoEnv.list_environments()"
+```
+
+Each environment package includes:
+- Client classes (e.g., `CodingEnv`)
+- Action/Observation models (e.g., `CodeAction`, `CodeObservation`)
+- Server Docker image
+- `openenv.yaml` manifest describing the environment
+
+### Manifest Format
+
+Each environment includes an `openenv.yaml` file:
+
+```yaml
+name: coding_env
+version: 0.1.0
+description: Coding environment for OpenEnv
+
+client:
+  class_name: CodingEnv
+  module: coding_env.client
+
+action:
+  class_name: CodeAction
+  module: coding_env.client
+
+observation:
+  class_name: CodeObservation
+  module: coding_env.client
+
+default_image: coding-env:latest
+spec_version: 1
+```
+
+## Benefits
+
+✅ **Simple**: No need to know which module to import from
+✅ **Flexible**: Works with local packages and HuggingFace Hub
+✅ **Discoverable**: List and explore available environments
+✅ **Type-Safe**: Returns properly typed environment classes
+✅ **HuggingFace-style**: Familiar API for ML practitioners
+✅ **Performant**: Caching and lazy loading for efficiency
+
+## See Also
+
+- [Environment Builder Guide](auto_getting_started/environment-builder.md) - How to create your own environments
+- [Core API Documentation](core.md) - Low-level API details
+- [HuggingFace Hub](https://huggingface.co/meta-pytorch) - Pre-built environments

OpenEnv/docs/source/cli.md

@@ -0,0 +1,86 @@
+# CLI
+
+The `openenv` CLI provides a set of commands for building, validating, and pushing environments to Hugging Face Spaces or a custom Docker registry. For an end-to-end tutorial on building environments with OpenEnv, see the [building an environment](auto_getting_started/environment-builder.md) guide.
+
+## `openenv init`
+
+```{eval-rst}
+.. automodule:: openenv.cli.commands.init
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## `openenv build`
+
+```{eval-rst}
+.. automodule:: openenv.cli.commands.build
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## `openenv validate`
+
+```{eval-rst}
+.. automodule:: openenv.cli.commands.validate
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## `openenv push`
+
+```{eval-rst}
+.. automodule:: openenv.cli.commands.push
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## `openenv serve`
+
+```{eval-rst}
+.. automodule:: openenv.cli.commands.serve
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## `openenv fork`
+
+```{eval-rst}
+.. automodule:: openenv.cli.commands.fork
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+# API Reference
+
+## Entry point
+
+```{eval-rst}
+.. automodule:: openenv.cli.__main__
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## CLI helpers
+
+```{eval-rst}
+.. automodule:: openenv.cli._cli_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Validation utilities
+
+```{eval-rst}
+.. automodule:: openenv.cli._validation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

OpenEnv/docs/source/conf.py

@@ -0,0 +1,206 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "OpenEnv"
+copyright = ""
+author = ""
+
+# -- Version configuration ---------------------------------------------------
+# RELEASE env var controls stable vs dev builds (set by `make html-stable`)
+RELEASE = os.environ.get("RELEASE", False)
+
+# Read version from pyproject.toml
+import tomli
+
+pyproject_path = os.path.join(os.path.dirname(__file__), "..", "..", "pyproject.toml")
+with open(pyproject_path, "rb") as f:
+    pyproject_data = tomli.load(f)
+openenv_version = pyproject_data["project"]["version"]
+
+if RELEASE:
+    version = ".".join(openenv_version.split(".")[:2])
+    release = version
+    html_title = f"OpenEnv {version} documentation"
+    switcher_version = version
+else:
+    version = "main"
+    release = "main"
+    html_title = "OpenEnv"
+    switcher_version = "main"
+
+# -- Path setup --------------------------------------------------------------
+sys.path.insert(0, os.path.abspath("../../src"))
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx_design",
+    "sphinx_sitemap",
+    "sphinxcontrib.mermaid",
+    "pytorch_sphinx_theme2",
+    "sphinxext.opengraph",
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx_gallery.gen_gallery",
+]
+
+# -- sphinx-gallery configuration --------------------------------------------
+from sphinx_gallery.sorting import FileNameSortKey
+
+sphinx_gallery_conf = {
+    "examples_dirs": ["getting_started"],
+    "gallery_dirs": ["auto_getting_started"],
+    "filename_pattern": r"/plot_",
+    "ignore_pattern": r"__init__\.py",
+    "download_all_examples": False,
+    "show_memory": False,
+    "capture_repr": ("_repr_html_", "__repr__"),
+    "matplotlib_animations": True,
+    "remove_config_comments": True,
+    "within_subsection_order": FileNameSortKey,
+    "default_thumb_file": None,
+    "nested_sections": False,
+}
+
+exclude_patterns = ["getting_started/*.md", "getting_started/README.rst"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+import pytorch_sphinx_theme2
+
+html_theme = "pytorch_sphinx_theme2"
+html_theme_path = [pytorch_sphinx_theme2.get_html_theme_path()]
+html_static_path = ["_static"]
+
+html_theme_options = {
+    "navigation_with_keys": False,
+    "analytics_id": "GTM-NPLPKN5G",
+    "header_links_before_dropdown": 7,
+    "logo": {
+        "text": "OpenEnv",
+    },
+    "icon_links": [
+        {
+            "name": "X",
+            "url": "https://x.com/PyTorch",
+            "icon": "fa-brands fa-x-twitter",
+        },
+        {
+            "name": "GitHub",
+            "url": "https://github.com/meta-pytorch/OpenEnv",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "Discourse",
+            "url": "https://dev-discuss.pytorch.org/",
+            "icon": "fa-brands fa-discourse",
+        },
+    ],
+    "use_edit_page_button": True,
+    "navbar_center": "navbar-nav",
+    "switcher": {
+        "json_url": "_static/versions.json",
+        "version_match": switcher_version,
+    },
+    "check_switcher": False,
+    "navbar_align": "left",
+    "navbar_start": ["navbar-logo", "version-switcher"],
+    "navbar_center": ["navbar-nav"],
+    "navbar_end": ["theme-switcher", "navbar-icon-links"],
+}
+
+theme_variables = pytorch_sphinx_theme2.get_theme_variables()
+
+# Templates path - local templates override theme templates
+templates_path = [
+    "_templates",
+    os.path.join(os.path.dirname(pytorch_sphinx_theme2.__file__), "templates"),
+]
+
+html_context = {
+    "theme_variables": theme_variables,
+    "display_github": True,
+    "github_url": "https://github.com",
+    "github_user": "meta-pytorch",
+    "github_repo": "OpenEnv",
+    "feedback_url": "https://github.com/meta-pytorch/OpenEnv",
+    "github_version": "main",
+    "doc_path": "docs/source",
+    "library_links": theme_variables.get("library_links", []),
+    "community_links": theme_variables.get("community_links", []),
+    "language_bindings_links": html_theme_options.get("language_bindings_links", []),
+}
+
+# Base URL for the site (used by sitemap and canonical URLs)
+html_baseurl = "https://meta-pytorch.org/OpenEnv/"
+sitemap_locales = [None]
+sitemap_excludes = [
+    "search.html",
+    "genindex.html",
+]
+sitemap_url_scheme = "{link}"
+
+# -- MyST-Parser configuration -----------------------------------------------
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "html_image",
+]
+
+
+# -- Post-process sphinx-gallery output to fix navigation --------------------
+def remove_orphan_and_duplicate_toctree(app, docname, source):
+    """Remove :orphan: and duplicate hidden toctree from gallery index."""
+    if docname == "auto_getting_started/index":
+        content = source[0]
+        # Remove the :orphan: directive
+        if content.startswith(":orphan:"):
+            content = content.replace(":orphan:\n\n", "", 1)
+            content = content.replace(":orphan:\n", "", 1)
+
+        # Remove the sphinx-gallery generated hidden toctree
+        # Find and remove the hidden toctree block
+        import re
+
+        # Match: .. toctree::\n   :hidden:\n\n   /auto_getting_started/...
+        pattern = r"\.\. toctree::\n\s+:hidden:\n\n(?:\s+/auto_getting_started/plot_\d+_\w+\n)+"
+        content = re.sub(pattern, "", content)
+
+        source[0] = content
+
+
+def copy_md_pages_to_gallery(app):
+    """Copy .md pages from getting_started/ to auto_getting_started/.
+
+    Sphinx Gallery only processes .py files and README.rst.  Any extra .md
+    pages that live alongside the gallery source must be copied into the
+    generated gallery directory so Sphinx can discover them as part of the
+    same toctree (important for section-nav context in pydata-sphinx-theme).
+    """
+    import glob
+    import shutil
+
+    srcdir = os.path.join(app.srcdir, "getting_started")
+    dstdir = os.path.join(app.srcdir, "auto_getting_started")
+    os.makedirs(dstdir, exist_ok=True)
+    for md_file in glob.glob(os.path.join(srcdir, "*.md")):
+        shutil.copy2(md_file, dstdir)
+
+
+def setup(app):
+    # Copy extra .md pages into the gallery output dir (priority 900 so it
+    # runs after sphinx-gallery's builder-inited handler at default priority).
+    app.connect("builder-inited", copy_md_pages_to_gallery, priority=900)
+    # Hook into source-read to modify content before Sphinx processes it
+    app.connect("source-read", remove_orphan_and_duplicate_toctree)

OpenEnv/docs/source/core.md

@@ -0,0 +1,215 @@
+# Core API
+
+The `openenv.core` package provides the core abstractions for building and running environments. For an end-to-end tutorial on building environments with OpenEnv, see the [building an environment](auto_getting_started/environment-builder.md) guide.
+
+## Server
+
+### Environment server primitives
+
+```{eval-rst}
+.. automodule:: openenv.core.env_server.interfaces
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### Types
+
+```{eval-rst}
+.. automodule:: openenv.core.env_server.types
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### Exceptions
+
+```{eval-rst}
+.. automodule:: openenv.core.env_server.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### HTTP server utilities
+
+```{eval-rst}
+.. automodule:: openenv.core.env_server.http_server
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### Web interface helpers
+
+```{eval-rst}
+.. automodule:: openenv.core.env_server.web_interface
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### Serialization
+
+```{eval-rst}
+.. automodule:: openenv.core.env_server.serialization
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### Transforms
+
+```{eval-rst}
+.. automodule:: openenv.core.env_server.base_transforms
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### Route configuration
+
+```{eval-rst}
+.. automodule:: openenv.core.env_server.route_config
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Clients
+
+### Base client
+
+```{eval-rst}
+.. automodule:: openenv.core.env_client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### Synchronous client
+
+```{eval-rst}
+.. automodule:: openenv.core.sync_client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### Generic client
+
+```{eval-rst}
+.. automodule:: openenv.core.generic_client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### LLM client
+
+```{eval-rst}
+.. automodule:: openenv.core.llm_client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### Shared dataclasses
+
+```{eval-rst}
+.. automodule:: openenv.core.client_types
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## MCP (Model Context Protocol)
+
+### MCP environment
+
+```{eval-rst}
+.. automodule:: openenv.core.env_server.mcp_environment
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### MCP types
+
+```{eval-rst}
+.. automodule:: openenv.core.env_server.mcp_types
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+### MCP client
+
+```{eval-rst}
+.. automodule:: openenv.core.mcp_client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Rubrics
+
+```{eval-rst}
+.. automodule:: openenv.core.rubrics.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: openenv.core.rubrics.containers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: openenv.core.rubrics.trajectory
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: openenv.core.rubrics.llm_judge
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Tools
+
+```{eval-rst}
+.. automodule:: openenv.core.tools.git_server_client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: openenv.core.tools.local_python_executor
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Container providers
+
+```{eval-rst}
+.. automodule:: openenv.core.containers.runtime.providers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: openenv.core.containers.runtime.uv_provider
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

OpenEnv/docs/source/customizing-web-ui.md

@@ -0,0 +1,89 @@
+# Custom Web UI
+
+When `ENABLE_WEB_INTERFACE=true`, the server serves a default Gradio app at `/web` with Reset/Step/Get state, Quick Start, and README. Environment authors can **add** a custom tab by providing a custom Gradio builder.
+
+## Extension point: `gradio_builder`
+
+`create_app()` accepts an optional **`gradio_builder`** callable. When set, the UI at `/web` is built with [Gradio’s TabbedInterface](https://www.gradio.app/4.44.1/docs/gradio/tabbedinterface): the **first tab (“Playground”)** is the default OpenEnv UI, and the **second tab (“Custom”)** is the `gr.Blocks` returned by your builder. Users can switch between the default Playground and your custom interface without losing either. The same `/web/reset`, `/web/step`, `/web/state`, and `/web/metadata` API routes remain available; your custom tab can use the provided `web_manager` in-process or call those endpoints.
+
+### Builder signature
+
+```python
+def my_gradio_builder(
+    web_manager,      # WebInterfaceManager: .reset_environment(), .step_environment(), .get_state()
+    action_fields,    # list[dict]: from action schema for form generation
+    metadata,        # EnvironmentMetadata | None: name, readme_content, etc.
+    is_chat_env,     # bool: True if single message input
+    title,           # str: app title (e.g. metadata.name)
+    quick_start_md,  # str: Quick Start markdown (class names already replaced)
+) -> gr.Blocks:
+    ...
+```
+
+Return a `gr.Blocks` instance. It is shown in the **“Custom”** tab of a tabbed interface; the **“Playground”** tab always shows the default OpenEnv UI. Core applies the same theme/css when mounting.
+
+---
+
+## Option 1: Add a custom tab
+
+Provide a builder that returns your own `gr.Blocks`; it appears as the second tab (“Custom”) next to the default “Playground” tab:
+
+```python
+# server/app.py
+from openenv.core.env_server.http_server import create_app
+from .my_environment import MyEnvironment
+from ..models import MyAction, MyObservation
+from .gradio_ui import build_my_gradio_app  # your module
+
+app = create_app(
+    MyEnvironment,
+    MyAction,
+    MyObservation,
+    env_name="my_env",
+    gradio_builder=build_my_gradio_app,
+)
+```
+
+In `server/gradio_ui.py` implement `build_my_gradio_app(web_manager, action_fields, metadata, is_chat_env, title, quick_start_md)` returning a `gr.Blocks` (e.g. env-specific visualizations, extra controls). Use `web_manager.reset_environment()`, `web_manager.step_environment(action_data)`, and `web_manager.get_state()` in your Gradio event handlers. The default Playground tab remains available in the first tab.
+
+---
+
+## Option 2: Custom tab that wraps or reuses the default
+
+Your builder can call the core `build_gradio_app` to get a Blocks instance and embed it inside your custom tab (e.g. in a `gr.Tabs` or as one section). That way your “Custom” tab can show both the default layout and additional content in one place.
+
+---
+
+## Option 3: Custom Quick Start or README only
+
+You don’t need a custom builder only to change text. The default UI uses:
+
+- **Quick Start**: generated from `get_quick_start_markdown(metadata, action_cls, observation_cls)` (init-style class names).
+- **README**: `metadata.readme_content` (loaded from the env’s README).
+
+So you can influence the default UI by ensuring `metadata` and README are correct. To change the Quick Start template itself (e.g. different wording or placeholders), you would use a custom `gradio_builder` that calls `build_gradio_app` with a custom `quick_start_md` string you build yourself (or by copying and adapting the default template from the core).
+
+---
+
+## Migration from custom HTML override (e.g. wildfire)
+
+Environments that currently override `/web` with custom HTML (e.g. by removing the default route and adding a GET `/web` that returns HTML) should migrate to a **gradio_builder** that returns a `gr.Blocks` app. The custom UI then appears in the **“Custom”** tab alongside the default **“Playground”** tab. Benefits:
+
+- Single, supported extension point using [TabbedInterface](https://www.gradio.app/4.44.1/docs/gradio/tabbedinterface).
+- No need to remove or override routes; the default UI stays in the first tab.
+- Same `/web` path; both tabs can use `web_manager` or `/web/reset`, `/web/step`, `/web/state`.
+
+If you need a non-Gradio custom UI (e.g. static HTML/JS), you can still register your own route after `create_app` (e.g. at `/web/custom` or another path), but the main `/web` slot is the Gradio tabbed app when `ENABLE_WEB_INTERFACE=true`.
+
+---
+
+## Summary
+
+| Goal                         | Approach                                                                 |
+|-----------------------------|---------------------------------------------------------------------------|
+| Use default UI only         | Do not pass `gradio_builder`.                                            |
+| Add a custom tab            | Pass `gradio_builder=my_builder`; return your own `gr.Blocks` (shown in “Custom” tab). |
+| Custom tab + default inside | In your builder, call `build_gradio_app(...)` and embed or wrap it in your Blocks. |
+| Change Quick Start / README | Rely on metadata/README, or custom builder that builds custom markdown.  |
+
+The default Playground tab is built with `openenv.core.env_server.gradio_ui.build_gradio_app`; you can import and call it with the same arguments if your custom tab needs to embed or extend it.

OpenEnv/docs/source/environments.md

@@ -0,0 +1,552 @@
+# Environments
+
+The OpenEnv community has built a catalog of ready-to-run environments that cover deterministic smoke tests, full developer workflows, and multi-step reasoning challenges. Explore the surface area below and jump directly into the guides for each environment.
+
+`````{grid} 1 2 3 3
+:gutter: 3
+
+````{grid-item-card} Echo
+:class-card: sd-border-1
+
+Minimal observation/action loop for verifying client integrations, CI pipelines, and onboarding flows in seconds.
+
++++
+```{button-link} environments/echo.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+```{button-link} https://huggingface.co/spaces/openenv/echo_env
+:color: warning
+:outline:
+
+🤗 Hugging Face
+```
+````
+
+````{grid-item-card} Coding
+:class-card: sd-border-1
+
+Secure sandbox with filesystem access and evaluation hooks for executing generated code and building autonomous dev workflows.
+
++++
+```{button-link} environments/coding.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+```{button-link} https://huggingface.co/spaces/openenv/coding_env
+:color: warning
+:outline:
+
+🤗 Hugging Face
+```
+````
+
+````{grid-item-card} Chat
+:class-card: sd-border-1
+
+Message-driven loop tailored for conversational agents that need structured turns, safety rails, and message attribution.
+
++++
+```{button-link} environments/chat.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+```{button-link} https://huggingface.co/spaces/openenv/chat_env
+:color: warning
+:outline:
+
+🤗 Hugging Face
+```
+````
+
+````{grid-item-card} Atari
+:class-card: sd-border-1
+
+Classic Arcade Learning Environment tasks packaged for fast benchmarking of reinforcement-learning style agents.
+
++++
+```{button-link} environments/atari.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+```{button-link} https://huggingface.co/spaces/openenv/atari_env
+:color: warning
+:outline:
+
+🤗 Hugging Face
+```
+````
+
+````{grid-item-card} OpenSpiel
+:class-card: sd-border-1
+
+Multi-agent, game-theory workloads powered by DeepMind's OpenSpiel suite, ideal for search and self-play experiments.
+
++++
+```{button-link} environments/openspiel.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+```{button-link} https://huggingface.co/spaces/openenv/openspiel_env
+:color: warning
+:outline:
+
+🤗 Hugging Face
+```
+````
+
+````{grid-item-card} SUMO-RL
+:class-card: sd-border-1
+
+Traffic control scenarios with SUMO simulators for agents that reason about continuous control and scheduling.
+
++++
+```{button-link} environments/sumo.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} FinRL
+:class-card: sd-border-1
+
+Financial market simulations with portfolio APIs, perfect for RLHF strategies and algorithmic trading experiments.
+
++++
+```{button-link} environments/finrl.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} TextArena
+:class-card: sd-border-1
+
+Multi-task text arena for language-game competitions such as Wordle, reasoning puzzles, and program synthesis.
+
++++
+```{button-link} environments/textarena.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+```{button-link} https://huggingface.co/spaces/burtenshaw/textarena_env
+:color: warning
+:outline:
+
+🤗 Hugging Face
+```
+````
+
+````{grid-item-card} Git
+:class-card: sd-border-1
+
+Teaches agents to navigate repositories, inspect diffs, and land changes via Git-native operations.
+
++++
+```{button-link} environments/git.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} DIPG Safety
+:class-card: sd-border-1
+
+Safety-critical diagnostics from the DIPG benchmark, highlighting guardrails, adversarial prompts, and risk scoring.
+
++++
+```{button-link} environments/dipg.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+```{button-link} https://huggingface.co/spaces/surfiniaburger/dipg-gym
+:color: warning
+:outline:
+
+🤗 Hugging Face
+```
+````
+
+````{grid-item-card} Snake
+:class-card: sd-border-1
+
+Classic snake game environment for RL research with configurable grids, partial observability, and customizable rewards.
+
++++
+```{button-link} environments/snake.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+```{button-link} https://huggingface.co/spaces/Crashbandicoote2/snake_env
+:color: warning
+:outline:
+
+🤗 Hugging Face
+```
+````
+
+````{grid-item-card} Web Search
+:class-card: sd-border-1
+
+Web search environment for RL research with configurable grids, partial observability, and customizable rewards.
+
++++
+```{button-link} environments/websearch.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+```{button-link} https://huggingface.co/spaces/lawhy/web_search
+:color: warning
+:outline:
+
+🤗 Hugging Face
+```
+````
+
+````{grid-item-card} BrowserGym
+:class-card: sd-border-1
+
+Browser automation environment for web agents with DOM interaction, navigation, and multi-step task completion.
+
++++
+```{button-link} environments/browsergym.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+```{button-link} https://huggingface.co/spaces/burtenshaw/browsergym-v2
+:color: warning
+:outline:
+
+🤗 Hugging Face
+```
+````
+
+````{grid-item-card} KernRL
+:class-card: sd-border-1
+
+RL environment for GPU kernel optimization. Train LLM agents to write fast CUDA/Triton kernels that beat baseline implementations.
+
++++
+```{button-link} environments/kernrl.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} Calendar
+:class-card: sd-border-1
+
+Calendar tool-use environment exposing a Calendar Gym through the OpenEnv reset/step/state interface for scheduling agents.
+
++++
+```{button-link} environments/calendar.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} CARLA
+:class-card: sd-border-1
+
+Embodied evaluation environment for testing LLM decision-making in a full 3D driving simulator with irreversible consequences and ethical trolley scenarios.
+
++++
+```{button-link} environments/carla.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+```{button-link} https://huggingface.co/spaces/sergiopaniego/carla-env
+:color: warning
+:outline:
+
+🤗 Hugging Face
+```
+````
+
+````{grid-item-card} Chess
+:class-card: sd-border-1
+
+Chess RL environment powered by the moonfish engine with configurable opponents, position evaluation, and full chess rules.
+
++++
+```{button-link} environments/chess.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} Connect4
+:class-card: sd-border-1
+
+Classic Connect Four board game environment for training agents on turn-based strategy with a 6×7 grid.
+
++++
+```{button-link} environments/connect4.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} DM Control
+:class-card: sd-border-1
+
+Generic OpenEnv wrapper for dm_control.suite, providing access to all MuJoCo-based continuous control tasks like cartpole, walker, and humanoid.
+
++++
+```{button-link} environments/dm_control.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} FinQA
+:class-card: sd-border-1
+
+Financial question-answering environment that evaluates LLMs on complex financial questions using tool calls on SEC 10-K filing data.
+
++++
+```{button-link} environments/finqa.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} Grid World
+:class-card: sd-border-1
+
+Simple 5×5 grid world RL testbed and step-by-step guide for building new OpenEnv environments from scratch.
+
++++
+```{button-link} environments/grid_world.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+```{button-link} https://huggingface.co/spaces/yuvrajpant56/grid_world_env
+:color: warning
+:outline:
+
+🤗 Hugging Face
+```
+````
+
+````{grid-item-card} Julia
+:class-card: sd-border-1
+
+Julia code execution environment with test result tracking and reward calculation for RL training on Julia programming tasks.
+
++++
+```{button-link} environments/julia.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} Maze
+:class-card: sd-border-1
+
+Gridworld maze where agents navigate from start to exit while avoiding walls, with configurable 8×8 layouts.
+
++++
+```{button-link} environments/maze.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} OpenApp
+:class-card: sd-border-1
+
+Web application simulation wrapping the OpenApps framework and BrowserGym for training UI agents on calendar, todo, messenger, and maps apps.
+
++++
+```{button-link} environments/openapp.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} Reasoning Gym
+:class-card: sd-border-1
+
+Integrates the Reasoning Gym library to provide single-step reasoning tasks with configurable datasets and scoring.
+
++++
+```{button-link} environments/reasoning_gym.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} REPL
+:class-card: sd-border-1
+
+Python REPL environment for code execution tasks based on the Recursive Language Models paradigm with sandboxed execution and context loading.
+
++++
+```{button-link} environments/repl.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} TB2
+:class-card: sd-border-1
+
+OpenEnv wrapper for Terminal-Bench 2 tasks with local and Docker execution modes for terminal-based agent evaluation.
+
++++
+```{button-link} environments/tbench2.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} Unity
+:class-card: sd-border-1
+
+OpenEnv wrapper for Unity ML-Agents environments, providing access to Unity's RL environments through HTTP/WebSocket interfaces.
+
++++
+```{button-link} environments/unity.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+````{grid-item-card} Wildfire
+:class-card: sd-border-1
+
+Autonomous wildfire-control simulation where agents contain spreading fires using water, firebreaks, and timing under dynamic conditions.
+
++++
+```{button-link} environments/wildfire.html
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+````
+
+`````
+
+```{tip}
+Want to publish your own environment? Head over to the [Build Your Own Environment](auto_getting_started/environment-builder.md) guide for a step-by-step walkthrough.
+```
+
+## Community Environments
+
+`````{grid} 1 2 3 3
+:gutter: 3
+
+````{grid-item-card} RLVE Gym
+:class-card: sd-border-1
+
+A suite of 400 environments that procedurally generate reasoning problems for LM training with configurable difficulty.
+
++++
+```{button-link} https://huggingface.co/spaces/ZhiyuanZeng/RLVE_Gym/blob/main/README.md
+:color: primary
+:outline:
+
+{octicon}`file;1em` Docs
+```
+```{button-link} https://huggingface.co/spaces/ZhiyuanZeng/RLVE_Gym
+:color: warning
+:outline:
+
+🤗 Hugging Face
+```
+````
+
+`````
+
+```{toctree}
+:hidden:
+:maxdepth: 1
+
+environments/echo
+environments/coding
+environments/chat
+environments/atari
+environments/openspiel
+environments/sumo
+environments/finrl
+environments/textarena
+environments/git
+environments/dipg
+environments/snake
+environments/websearch
+environments/browsergym
+environments/repl
+environments/calendar
+environments/carla
+environments/chess
+environments/connect4
+environments/dm_control
+environments/finqa
+environments/grid_world
+environments/julia
+environments/kernrl
+environments/maze
+environments/openapp
+environments/reasoning_gym
+environments/tbench2
+environments/unity
+environments/wildfire
+```

OpenEnv/docs/source/environments/atari.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/atari_env/README.md
+```

OpenEnv/docs/source/environments/browsergym.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/browsergym_env/README.md
+```

OpenEnv/docs/source/environments/calendar.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/calendar_env/README.md
+```

OpenEnv/docs/source/environments/carla.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/carla_env/README.md
+```

OpenEnv/docs/source/environments/chat.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/chat_env/README.md
+```

OpenEnv/docs/source/environments/chess.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/chess_env/README.md
+```

OpenEnv/docs/source/environments/coding.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/coding_env/README.md
+```

OpenEnv/docs/source/environments/connect4.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/connect4_env/README.md
+```

OpenEnv/docs/source/environments/dipg.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/dipg_safety_env/README.md
+```

OpenEnv/docs/source/environments/dm_control.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/dm_control_env/README.md
+```

OpenEnv/docs/source/environments/echo.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/echo_env/README.md
+```

OpenEnv/docs/source/environments/finqa.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/finqa_env/README.md
+```

OpenEnv/docs/source/environments/finrl.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/finrl_env/README.md
+```

OpenEnv/docs/source/environments/git.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/git_env/README.md
+```

OpenEnv/docs/source/environments/grid_world.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/grid_world_env/README.md
+```

OpenEnv/docs/source/environments/julia.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/julia_env/README.md
+```

OpenEnv/docs/source/environments/kernrl.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/kernrl/README.md
+```

OpenEnv/docs/source/environments/maze.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/maze_env/README.md
+```

OpenEnv/docs/source/environments/openapp.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/openapp_env/README.md
+```

OpenEnv/docs/source/environments/openspiel.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/openspiel_env/README.md
+```

OpenEnv/docs/source/environments/reasoning_gym.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/reasoning_gym_env/README.md
+```

OpenEnv/docs/source/environments/repl.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/repl_env/README.md
+```

OpenEnv/docs/source/environments/snake.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/snake_env/README.md
+```

OpenEnv/docs/source/environments/sumo.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/sumo_rl_env/README.md
+```

OpenEnv/docs/source/environments/tbench2.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/tbench2_env/README.md
+```

OpenEnv/docs/source/environments/textarena.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/textarena_env/README.md
+```

OpenEnv/docs/source/environments/unity.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/unity_env/README.md
+```

OpenEnv/docs/source/environments/websearch.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/websearch_env/README.md
+```

OpenEnv/docs/source/environments/wildfire.md

@@ -0,0 +1,2 @@
+```{include} ../../../envs/wildfire_env/README.md
+```

OpenEnv/docs/source/getting_started/README.rst

@@ -0,0 +1,61 @@
+Quick Start
+===========
+
+This section provides a hands-on introduction to reinforcement learning (RL) and OpenEnv through a series of interactive tutorials. Whether you're new to RL or looking to learn how OpenEnv simplifies building and deploying environments, these tutorials will guide you through the fundamentals.
+
+**What is OpenEnv?**
+
+OpenEnv is a collaborative effort between **Meta, Hugging Face, Unsloth, GPU Mode, Reflection**, and other industry leaders to standardize reinforcement learning environments. Our goal is to make environment creation as easy and standardized as model sharing on Hugging Face.
+
+Learning Path
+-------------
+
+The tutorials are designed to be followed in sequence, building upon concepts from previous lessons:
+
+1. **Introduction & Quick Start** - Understand what OpenEnv is, why it exists, and run your first environment. Includes a comparison with traditional solutions like OpenAI Gym.
+
+2. **Using Environments** - Learn how to connect to environments (Hub, Docker, URL), create AI policies, and run evaluations. Work with different games and multi-player scenarios.
+
+3. **Building & Sharing Environments** - Create your own custom environment from scratch, package it with Docker, and share it on Hugging Face Hub.
+
+4. **Packaging & Deploying** - The complete reference guide for creating, packaging, and deploying custom environments with the ``openenv`` CLI.
+
+5. **Contributing to Hugging Face** - Publish, fork, and contribute to environments hosted as Hugging Face Spaces.
+
+**No GPU Required!** All five tutorials run without a GPU.
+
+For GPU-intensive training workflows, see the :doc:`RL Training Tutorial </tutorials/rl-training-2048>` in the Tutorials section.
+
+Prerequisites
+-------------
+
+Before starting, ensure you have:
+
+- Basic Python programming knowledge
+- Python 3.11+ installed
+- Docker (optional, for container-based deployment)
+
+Running the Tutorials
+---------------------
+
+You can run these tutorials locally:
+
+.. code-block:: bash
+
+    # Install OpenEnv
+    pip install openenv-core
+
+    # Run the Python scripts
+    python plot_01_introduction_quickstart.py
+
+Or view them directly in the documentation with full code output below.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Quick Start
+
+   plot_01_introduction_quickstart
+   plot_02_using_environments
+   plot_03_building_environments
+   environment-builder
+   contributing-envs

OpenEnv/docs/source/getting_started/contributing-envs.md

@@ -0,0 +1,192 @@
+# Contributing to Hugging Face
+
+**Part 5 of 5** in the OpenEnv Getting Started Series
+
+OpenEnv environments are designed to be shared. The `openenv` CLI provides first-class
+commands for publishing, forking, and contributing to environments hosted as
+[Hugging Face Spaces](https://huggingface.co/spaces).
+
+Envs are deployed as Hugging Face Spaces which are; Git repositories, Docker images, Python packages, and Gradio apps
+
+This guide covers three workflows:
+
+1. **Push** a new environment you built to the Hub.
+2. **Fork** someone else's environment to your Hugging Face account to make changes.
+3. **Download** an environment, make changes, and open a Pull Request.
+
+## Prerequisites
+
+Before you start, make sure you have:
+
+- Python 3.11+ and [`uv`](https://github.com/astral-sh/uv) installed
+- The OpenEnv CLI: `pip install openenv-core[cli]` (or install from source)
+- A [Hugging Face account](https://huggingface.co/join) with a [write token](https://huggingface.co/settings/tokens)
+
+Authenticate with the Hub:
+
+```bash
+hf auth login
+```
+
+The `openenv` CLI will also prompt you to log in automatically if you haven't already.
+
+## 1. Push a New Environment to the Hub
+
+Once you've [built an environment](environment-builder.md), publishing it to a Hugging Face Space is a single command.
+
+```bash
+# Push the env at '.' to the hub with config in env.yaml
+openenv push
+
+# Push the env to a specific repo
+openenv push --repo-id my-org/my-custom-env
+
+# Push the env as private
+openenv push --private
+
+# Push the env at 'path/to/my_env' to the hub with config in openenv.yaml
+openenv push path/to/my_env
+```
+
+That's it. The CLI validates your environment, stages the files, adds the Hugging Face Space frontmatter, enables the web interface, and uploads everything. Your environment will be live at
+`https://huggingface.co/spaces/<your-username>/my_env`.
+
+```{warning}
+If you are getting errors on deployment, it is likely because the environment structure is not valid. Run `openenv validate --verbose` to see the errors. This checks for the required files (`openenv.yaml`, `pyproject.toml`, `server/app.py`) and validates the Dockerfile and entry points.
+```
+
+## 2. Fork Someone Else's Environment
+
+Forking creates a copy of a Hugging Face Space under your own account. This is
+the fastest way to start experimenting with an existing environment.
+
+```bash
+# Fork the openenv/wordle-env environment to your account
+openenv fork owner/space-name
+```
+
+This duplicates the Space to `<your-username>/space-name` using the same name and config. To make changes, you can fork to a specific repo name, set environment variables and secrets, and request hardware.
+
+```bash
+# Fork to a specific repo name
+openenv fork openenv/wordle-env --repo-id my-username/my-wordle
+
+# Fork the openenv/coding-env environment to your account with environment variables and secrets
+openenv fork openenv/coding-env \
+  --set-env MODEL_ID=meta-llama/Llama-3-8B \
+  --set-secret HF_TOKEN=hf_xxxxxxxxxxxxx
+
+# Fork the openenv/coding-env environment to your account with a GPU
+openenv fork openenv/coding-env --hardware t4-medium
+```
+
+
+Once forked, you have a fully independent copy. You can:
+
+- Visit it at `https://huggingface.co/spaces/<your-username>/<space-name>`
+- Clone it locally to make changes (see the next section)
+- Push updates with `openenv push`
+
+## 3. Pull, Modify, and Open a Pull Request
+
+The contribution workflow lets you improve an existing environment and submit
+your changes for review, just like a GitHub Pull Request but on the Hugging
+Face Hub.
+
+### 3.1 Download the Space locally
+
+Hugging Face Spaces are Git repositories. Download the one you want to contribute to:
+
+```bash
+hf download owner/space-name --local-dir space-name --repo-type space
+cd space-name
+```
+
+```{warning}
+If the Space is private and you have access, make sure you're logged in with
+`hf auth login` first.
+```
+
+#### 3.2 Make your changes
+Edit the environment files as needed.
+
+```{tip}
+You can test your changes locally before submitting:
+
+    # Run the server locally
+    cd space-name
+    uvicorn server.app:app --host 0.0.0.0 --port 8000
+
+    # Or build and run in Docker
+    openenv build
+    openenv validate --verbose
+```
+
+#### 3.3 Push your changes as a Pull Request
+
+From the cloned directory, use `openenv push` with the `--create-pr` flag:
+
+```bash
+openenv push --repo-id owner/space-name --create-pr
+```
+
+This uploads your modified files and opens a Pull Request on the Hub. The environment owner can review your changes, leave comments, and merge them.
+
+```{warning}
+When using `--create-pr`, the CLI uploads your changes to a new branch and
+opens a PR on the **original** Space. You do not need to create the Space
+yourself.
+```
+
+### Alternative: Fork-then-PR workflow
+
+If you prefer to develop against your own fork first, you can combine the fork
+and PR workflows:
+
+```bash
+# 1. Fork the environment to your account
+openenv fork owner/space-name --repo-id my-username/space-name
+
+# 2. Download the forked environment to your local directory
+hf download my-username/space-name --local-dir space-name --repo-type space
+cd space-name
+
+# 3. Make and test your changes
+#    ... edit files, run locally, validate ...
+
+# 4. Push the changes back to your fork
+openenv push
+
+# 5. Submit a PR to the original Space
+openenv push --repo-id owner/space-name --create-pr
+```
+
+## End-to-End Example
+
+Here's a complete example: forking the Echo environment, adding a feature, and
+submitting a PR.
+
+```bash
+# Fork the echo environment
+openenv fork openenv/echo-env --repo-id my-username/echo-env-improved
+
+# Clone your fork
+git clone https://huggingface.co/spaces/my-username/echo-env-improved
+cd echo-env-improved
+
+# Make changes (e.g., add a timestamp to observations)
+# ... edit server/echo_environment.py ...
+
+# Test locally
+openenv validate --verbose
+
+# Push your improvement as a PR to the original
+openenv push --repo-id openenv/echo-env --create-pr
+```
+
+## Next Steps
+
+- [Build your own environment from scratch](environment-builder.md)
+- [Customize the web UI](../customizing-web-ui.md)
+- [Browse available environments](../environments.md)
+- [End-to-end tutorial](../tutorials/openenv-tutorial.md)

OpenEnv/docs/source/getting_started/environment-builder.md

@@ -0,0 +1,422 @@
+# Packaging & Deploying
+
+**Part 4 of 5** in the OpenEnv Getting Started Series
+
+This guide walks you through creating a custom environment using the `OpenEnv` framework and the `openenv` CLI.
+
+The CLI handles scaffolding, builds, validation, and deployment so you can stay focused on environment logic.
+
+```{note}
+**New to OpenEnv?** If you're just getting started, we recommend completing the [Getting Started tutorials](index) first. They provide a conceptual introduction to OpenEnv and reinforcement learning fundamentals. This guide is for developers ready to build production-quality environments.
+```
+
+## Quick Reference Card
+
+Already familiar with OpenEnv? Here's the 8-step process at a glance:
+
+| Step | Command / Action | Description |
+|------|------------------|-------------|
+| 1 | `openenv init my_env` | Scaffold new environment |
+| 2 | Edit `models.py` | Define Action & Observation dataclasses |
+| 3 | Edit `server/my_environment.py` | Implement `reset()` and `step()` methods |
+| 4 | Edit `client.py` | Implement `_step_payload()`, `_parse_result()`, `_parse_state()` |
+| 5 | `openenv serve` | Start local dev server for testing |
+| 6 | `openenv validate` | Validate environment structure |
+| 7 | `openenv push` | Deploy to Hugging Face Hub |
+| 8 | Share the URL! | Others use via `MyEnv.from_hub("you/my-env")` |
+
+### CLI Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `openenv init NAME` | Scaffold new environment |
+| `openenv serve` | Start local dev server |
+| `openenv build` | Build Docker image |
+| `openenv validate --verbose` | Validate environment structure |
+| `openenv push` | Deploy to Hugging Face Hub |
+| `openenv push --repo-id NAME` | Deploy to specific repo |
+| `openenv push --private` | Deploy as private environment |
+| `openenv push --registry ghcr.io/ORG` | Push to GitHub Container Registry |
+
+```{tip}
+For a hands-on tutorial that builds a complete environment step-by-step, see [Building & Sharing Environments](plot_03_building_environments) in the Getting Started series.
+```
+
+---
+
+## Overview
+
+A typical workflow looks like:
+
+1. Scaffold a new environment with `openenv init`.
+2. Customize your models, environment logic, and FastAPI server.
+3. Implement a typed `EnvClient` (WebSocket-based for persistent sessions).
+4. Configure dependencies and the Dockerfile once.
+5. Use the CLI (`openenv build`, `openenv validate`, `openenv push`) to package and share your work.
+
+```{note}
+    These integrations are handled automatically by the `openenv` CLI when you run `openenv init`.
+```
+
+### Prerequisites
+
+- Python 3.11+ and [`uv`](https://github.com/astral-sh/uv) for dependency locking
+- Docker Desktop / Docker Engine
+- The OpenEnv library installed: `pip install https://github.com/meta-pytorch/OpenEnv.git`
+
+## Step-by-Step Guide
+
+Let's walk through the process of building a custom environment with OpenEnv.
+
+### 1. Scaffold with `openenv init`
+
+```bash
+# Run from anywhere – defaults to current directory
+openenv init my_env
+
+# Optionally choose an output directory
+openenv init my_env --output-dir /Users/you/envs
+```
+
+The command creates a fully-typed template with `openenv.yaml`, `pyproject.toml`, `uv.lock`, Docker assets, and stub implementations. If you're working inside this repo, move the generated folder under `envs/`.
+
+Typical layout:
+
+```
+my_env/
+├── __init__.py
+├── README.md
+├── client.py
+├── models.py
+├── openenv.yaml
+├── pyproject.toml
+├── uv.lock
+└── server/
+    ├── __init__.py
+    ├── app.py
+    ├── my_environment.py
+    ├── requirements.txt
+    └── Dockerfile
+```
+
+Python classes are generated for the action, observation, environment, and client. For example, you will find `MyEnvironment`, `MyAction`, `MyObservation`, and `MyEnv` (client) in the `my_env` directory based on the name you provided. The environment uses the core `State` class from `openenv.core.env_server.types`.
+
+### 2. Define Models
+
+Edit `models.py` to describe your action and observation using Pydantic:
+
+```python
+# models.py
+from pydantic import Field
+from openenv.core.env_server.types import Action, Observation
+
+class MyAction(Action):
+    """Your custom action."""
+    command: str = Field(..., description="Command to execute")
+    parameters: dict = Field(default_factory=dict, description="Command parameters")
+
+class MyObservation(Observation):
+    """Your custom observation."""
+    result: str = Field(..., description="Result of the action")
+    success: bool = Field(..., description="Whether the action succeeded")
+```
+
+### 3. Implement Environment Logic
+
+Customize `server/my_environment.py` by extending `Environment`:
+
+```python
+# server/my_environment.py
+from uuid import uuid4
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+from models import MyAction, MyObservation
+
+class MyEnvironment(Environment):
+    def __init__(self):
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+
+    def reset(self) -> MyObservation:
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        return MyObservation(result="Ready", success=True, done=False, reward=0.0)
+
+    def step(self, action: MyAction) -> MyObservation:
+        # Implement your logic here
+        self._state.step_count += 1
+        result = self._execute_command(action.command)
+        return MyObservation(result=result, success=True, done=False, reward=1.0)
+
+    @property
+    def state(self) -> State:
+        return self._state
+```
+
+### 4. Create the FastAPI Server
+
+`server/app.py` should expose the environment through `create_app`.
+
+**Important:** You must pass a class or factory function (not an instance) to enable WebSocket-based concurrent sessions:
+
+```python
+# server/app.py
+from openenv.core.env_server import create_app
+from ..models import MyAction, MyObservation
+from .my_environment import MyEnvironment
+
+# Pass the class (factory) - each WebSocket session gets its own instance
+app = create_app(MyEnvironment, MyAction, MyObservation, env_name="my_env")
+```
+
+For environments with constructor arguments, create a factory function:
+
+```python
+# server/app.py
+import os
+from openenv.core.env_server import create_app
+from ..models import MyAction, MyObservation
+from .my_environment import MyEnvironment
+
+# Read config from environment variables
+api_key = os.getenv("MY_API_KEY")
+timeout = int(os.getenv("MY_TIMEOUT", "30"))
+
+def create_my_environment():
+    """Factory function that creates MyEnvironment with config."""
+    return MyEnvironment(api_key=api_key, timeout=timeout)
+
+# Pass the factory function
+app = create_app(create_my_environment, MyAction, MyObservation, env_name="my_env")
+```
+
+### 5. Implement the Client
+
+`client.py` extends `EnvClient` so users can interact with your server via WebSocket for persistent sessions:
+
+```python
+# client.py
+from openenv.core.env_client import EnvClient
+from openenv.core.client_types import StepResult
+from .models import MyAction, MyObservation, MyState
+
+class MyEnv(EnvClient[MyAction, MyObservation, MyState]):
+    def _step_payload(self, action: MyAction) -> dict:
+        return {"command": action.command, "parameters": action.parameters}
+
+    def _parse_result(self, payload: dict) -> StepResult[MyObservation]:
+        obs_data = payload.get("observation", {})
+        obs = MyObservation(
+            result=obs_data.get("result", ""),
+            success=obs_data.get("success", False),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+        )
+        return StepResult(
+            observation=obs,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: dict) -> State:
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )
+```
+
+The `EnvClient` maintains a persistent WebSocket connection to the server, enabling efficient multi-step interactions with lower latency compared to HTTP. Each client instance gets its own dedicated environment session on the server.
+
+### 6. Configure Dependencies & Dockerfile
+
+The CLI template ships with `pyproject.toml` and `server/Dockerfile`. You should manage your python dependencies with `uv` or `pip` in the `pyproject.toml` file. Other dependencies should be installed in the Dockerfile.
+
+Keep building from the `openenv-base` image so shared tooling stays available:
+
+<details>
+<summary>Dockerfile</summary>
+
+```dockerfile
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local src/core)
+# - Standalone environments (with openenv from pip)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=__ENV_NAME__
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already in the pyproject.toml dependencies
+# For standalone builds, openenv will be installed from pip via pyproject.toml
+WORKDIR /app/env
+
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]
+
+```
+
+</details>
+
+If you introduced extra dependencies in the Dockerfile, you should install them in the Dockerfile before removing temp files.
+
+### 7. Build & Validate with the CLI
+
+From the environment directory:
+
+```bash
+cd envs/my_env
+openenv build          # Builds Docker image (auto-detects context)
+openenv validate --verbose
+```
+
+`openenv build` understands both standalone environments and in-repo ones. Useful flags:
+
+- `--tag/-t`: override the default `openenv-<env_name>` tag
+- `--build-arg KEY=VALUE`: pass multiple Docker build arguments
+- `--dockerfile` / `--context`: custom locations when experimenting
+- `--no-cache`: force fresh dependency installs
+
+`openenv validate` checks for required files, ensures the Dockerfile/server entrypoints function, and lists supported deployment modes. The command exits non-zero if issues are found so you can wire it into CI.
+
+### 8. Push & Share with `openenv push`
+
+Once validation passes, the CLI can deploy directly to Hugging Face Spaces or any registry:
+
+```bash
+# Push to HF Spaces (auto enables web UI and prompts for login if needed)
+openenv push
+
+# Push to a specific repo or namespace
+openenv push --repo-id my-org/my-env
+
+# Push to Docker/ghcr (interface disabled by default)
+openenv push --registry ghcr.io/my-org --tag my-env:latest
+
+# Customize image base or visibility
+openenv push --base-image ghcr.io/meta-pytorch/openenv-base:latest --private
+```
+
+Key options:
+
+- `--directory`: path to the environment (defaults to `cwd`)
+- `--repo-id`: explicit Hugging Face space name
+- `--registry`: push to Docker Hub, GHCR, etc.
+- `--interface/--no-interface`: toggle the optional web UI
+- `--base-image`: override the Dockerfile `FROM`
+- `--private`: mark the space as private
+
+The command validates your `openenv.yaml`, injects Hugging Face frontmatter when needed, and uploads the prepared bundle.
+
+### 9. Automate Builds (optional)
+
+To trigger Docker builds on every push to `main`, add your environment to the matrix in `.github/workflows/docker-build.yml`:
+
+```yaml
+strategy:
+  matrix:
+    image:
+      - name: echo-env
+        dockerfile: envs/echo_env/server/Dockerfile
+      - name: chat-env
+        dockerfile: envs/chat_env/server/Dockerfile
+      - name: coding-env
+        dockerfile: envs/coding_env/server/Dockerfile
+      - name: my-env  # Add your environment here
+        dockerfile: envs/my_env/server/Dockerfile
+```
+
+### Use Your Environment
+
+Here is a simple example of using your environment:
+
+```python
+from envs.my_env import MyAction, MyEnv
+
+# Create environment from Docker image
+client = MyEnv.from_docker_image("my-env:latest")
+# Or, connect to the remote space on Hugging Face
+client = MyEnv.from_hub("my-org/my-env")
+# Or, connect to the local server
+client = MyEnv(base_url="http://localhost:8000")
+
+# Use context manager for automatic cleanup (recommended)
+with client:
+    # Reset
+    result = client.reset()
+    print(result.observation.result)  # "Ready"
+
+    # Execute actions
+    result = client.step(MyAction(command="test", parameters={}))
+    print(result.observation.result)
+    print(result.observation.success)
+
+    # Get state
+    state = client.state()
+    print(state.episode_id)
+    print(state.step_count)
+
+# Or manually manage the connection
+try:
+    client = MyEnv(base_url="http://localhost:8000")
+    result = client.reset()
+    result = client.step(MyAction(command="test", parameters={}))
+finally:
+    client.close()
+```
+
+## Nice work! You've now built and used your own OpenEnv environment.
+
+Your next steps are to:
+
+- [Try out the end-to-end tutorial](https://colab.research.google.com/github/meta-pytorch/OpenEnv/blob/main/examples/OpenEnv_Tutorial.ipynb)

OpenEnv/docs/source/getting_started/plot_01_introduction_quickstart.py

@@ -0,0 +1,774 @@
+"""
+Introduction & Quick Start
+==========================
+
+**Part 1 of 5** in the OpenEnv Getting Started Series
+
+This notebook introduces OpenEnv, explains why it exists, and gets you
+running your first environment.
+
+.. note::
+    **Time**: ~10 minutes | **Difficulty**: Beginner | **GPU Required**: No
+
+What You'll Learn
+-----------------
+
+- **What is OpenEnv**: The unified framework for RL environments
+- **Why OpenEnv**: How it compares to traditional solutions like Gym
+- **RL Basics**: The observe-act-reward loop in 60 seconds
+- **Quick Start**: Connect to and interact with your first environment
+"""
+
+# %%
+# Setup: Enable nested async event loops
+# --------------------------------------
+#
+# This is needed when running in environments like Sphinx-Gallery or Jupyter
+# that already have an event loop running.
+
+import nest_asyncio
+nest_asyncio.apply()
+
+# %%
+# What is OpenEnv?
+# ----------------
+#
+# OpenEnv is a **unified framework for building, sharing, and interacting with
+# reinforcement learning environments**. It's a collaborative effort between
+# Meta, Hugging Face, Unsloth, GPU Mode, and other industry leaders.
+#
+# **The Goal**: Make environment creation as easy and standardized as model
+# sharing on Hugging Face.
+#
+# Key Features
+# ~~~~~~~~~~~~
+#
+# - **Standardized API**: Gymnasium-style ``reset()``, ``step()``, ``state()``
+# - **Type-Safe**: Full IDE autocomplete and error checking
+# - **Containerized**: Environments run in Docker for isolation and reproducibility
+# - **Shareable**: Push to Hugging Face Hub with one command
+# - **Language-Agnostic**: HTTP/WebSocket API works from any language
+
+# %%
+# RL in 60 Seconds
+# ----------------
+#
+# Reinforcement Learning is simpler than you think. It's just a loop:
+#
+# .. code-block:: text
+#
+#     ┌─────────────────────────────────────────────────────────────┐
+#     │                 THE RL LOOP                                 │
+#     │                                                             │
+#     │    ┌─────────┐         ┌─────────────┐                      │
+#     │    │  AGENT  │─action─▶│ ENVIRONMENT │                      │
+#     │    │         │◀─reward─│             │                      │
+#     │    │         │◀──obs───│             │                      │
+#     │    └─────────┘         └─────────────┘                      │
+#     │                                                             │
+#     │    1. Agent observes the environment                        │
+#     │    2. Agent chooses an action                               │
+#     │    3. Environment returns reward + new observation          │
+#     │    4. Repeat until done                                     │
+#     └─────────────────────────────────────────────────────────────┘
+#
+# In code, it looks like this:
+#
+# .. code-block:: python
+#
+#     result = env.reset()                    # Start episode
+#     while not result.done:
+#         action = agent.choose(result.observation)
+#         result = env.step(action)           # Take action, get reward
+#         agent.learn(result.reward)
+#
+# That's it. That's RL!
+
+# %%
+# Why OpenEnv? (vs. Traditional Solutions)
+# ----------------------------------------
+#
+# Traditional RL environments (like OpenAI Gym/Gymnasium) have been the backbone
+# of RL research for years. They provide a simple API for interacting with
+# environments, and the community has built thousands of environments on top of them.
+#
+# However, as RL moves from research to production, several challenges emerge:
+#
+# The Problem with Traditional Approaches
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# 1. **No Type Safety**: Observations are numpy arrays like ``obs[0][3]``. What does
+#    index 3 mean? You have to read documentation or source code to find out.
+#
+# 2. **Same-Process Execution**: The environment runs in your training process.
+#    A bug in the environment can crash your entire training run.
+#
+# 3. **Dependency Hell**: Sharing environments means copying files and hoping
+#    the recipient has the same dependencies installed.
+#
+# 4. **Python Lock-in**: Want to use Rust or C++ for your agent? Too bad—Gym is Python-only.
+#
+# 5. **"Works on My Machine"**: Environments behave differently on different systems
+#    due to floating-point differences, library versions, or OS quirks.
+#
+# How OpenEnv Solves These Problems
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# +------------------+----------------------------------+----------------------------------+
+# | Challenge        | Traditional (Gym)                | OpenEnv                          |
+# +==================+==================================+==================================+
+# | **Type Safety**  | ``obs[0][3]`` - what is it?      | ``obs.info_state`` - IDE knows!  |
+# +------------------+----------------------------------+----------------------------------+
+# | **Isolation**    | Same process (can crash)         | Docker container (isolated)      |
+# +------------------+----------------------------------+----------------------------------+
+# | **Deployment**   | "Works on my machine"            | Same container everywhere        |
+# +------------------+----------------------------------+----------------------------------+
+# | **Sharing**      | Copy files, manage deps          | ``openenv push`` to Hub          |
+# +------------------+----------------------------------+----------------------------------+
+# | **Language**     | Python only                      | Any language (HTTP/WebSocket)    |
+# +------------------+----------------------------------+----------------------------------+
+# | **Scaling**      | Single machine                   | Deploy to Kubernetes             |
+# +------------------+----------------------------------+----------------------------------+
+# | **Debugging**    | Cryptic numpy index errors       | Clear, typed error messages      |
+# +------------------+----------------------------------+----------------------------------+
+#
+# Side-by-Side Code Comparison
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# Let's compare the same workflow in both approaches:
+#
+# **Traditional Gym approach:**
+#
+# .. code-block:: python
+#
+#     import gym
+#     import numpy as np
+#
+#     # Create environment - runs in your process
+#     env = gym.make("CartPole-v1")
+#
+#     # Reset returns numpy arrays
+#     obs, info = env.reset()
+#     # obs = array([0.01, 0.02, -0.03, 0.01])
+#     # What do these numbers mean? You have to check docs!
+#
+#     # Step returns multiple values
+#     obs, reward, done, truncated, info = env.step(action)
+#     # No IDE autocomplete, easy to mix up return values
+#
+#     # If env crashes, your whole training crashes
+#     # Sharing requires: pip install gym[atari], hope versions match
+#
+# **OpenEnv approach:**
+#
+# .. code-block:: python
+#
+#     from openenv import AutoEnv, AutoAction
+#
+#     # Load environment and action classes via auto-discovery
+#     OpenSpielEnv = AutoEnv.get_env_class("openspiel")
+#     OpenSpielAction = AutoAction.from_env("openspiel")
+#
+#     # Connect to containerized environment
+#     with OpenSpielEnv(base_url="http://localhost:8000") as env:
+#         # Reset returns typed StepResult
+#         result = env.reset()
+#         # result.observation.legal_actions - IDE autocompletes!
+#         # result.observation.info_state - you know exactly what this is
+#
+#         # Step with typed action
+#         action = OpenSpielAction(action_id=1, game_name="catch")
+#         result = env.step(action)
+#         # result.reward, result.done - all typed
+#
+#         # Environment runs in Docker - isolated from your code
+#         # Share via: openenv push my-env (one command!)
+
+# %%
+# Part 1: Environment Setup
+# -------------------------
+#
+# Let's set up our environment. This works in Google Colab, locally, or
+# anywhere Python runs.
+
+import subprocess
+import sys
+from pathlib import Path
+
+# Detect environment
+try:
+    import google.colab
+
+    IN_COLAB = True
+except ImportError:
+    IN_COLAB = False
+
+if IN_COLAB:
+    print("=" * 70)
+    print("   GOOGLE COLAB DETECTED - Installing OpenEnv...")
+    print("=" * 70)
+
+    # Install OpenEnv
+    subprocess.run(
+        [sys.executable, "-m", "pip", "install", "-q", "openenv-core"],
+        capture_output=True,
+    )
+    print("   OpenEnv installed!")
+    print("=" * 70)
+else:
+    print("=" * 70)
+    print("   RUNNING LOCALLY")
+    print("=" * 70)
+    print()
+    print("If you haven't installed OpenEnv yet:")
+    print("   pip install openenv-core")
+    print()
+
+    # Add src to path for local development (when running from docs folder)
+    src_path = Path.cwd().parent.parent.parent / "src"
+    if src_path.exists():
+        sys.path.insert(0, str(src_path))
+
+    # Add envs to path
+    envs_path = Path.cwd().parent.parent.parent / "envs"
+    if envs_path.exists():
+        sys.path.insert(0, str(envs_path.parent))
+
+    print("=" * 70)
+
+print()
+print("Ready to explore OpenEnv!")
+
+# %%
+# Part 2: Your First Environment - OpenSpiel
+# -------------------------------------------
+#
+# What is OpenSpiel?
+# ~~~~~~~~~~~~~~~~~~
+#
+# `OpenSpiel <https://github.com/google-deepmind/open_spiel>`_ is an open-source
+# collection of **70+ game environments** developed by DeepMind for research in
+# reinforcement learning, game theory, and multi-agent systems.
+#
+# It includes:
+#
+# - **Classic board games**: Chess, Go, Backgammon, Tic-Tac-Toe
+# - **Card games**: Poker variants, Blackjack, Bridge
+# - **Simple RL benchmarks**: Catch, Cliff Walking, 2048
+# - **Multi-agent games**: Hanabi, Kuhn Poker, Negotiation games
+#
+# OpenSpiel is widely used in RL research because it provides consistent,
+# well-tested implementations with support for both single-player and multi-player
+# scenarios.
+#
+# How OpenSpiel Connects to OpenEnv
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# OpenEnv wraps OpenSpiel games as **containerized, type-safe environments**.
+# This means:
+#
+# 1. You get all the benefits of OpenSpiel's game library
+# 2. Plus type-safe Python clients with IDE autocomplete
+# 3. Plus Docker isolation for reproducibility
+# 4. Plus easy sharing via Hugging Face Hub
+#
+# Currently, OpenEnv includes wrappers for 6 OpenSpiel games:
+#
+# +------------------+-------------+------------------------------------------+
+# | Game             | Players     | Description                              |
+# +==================+=============+==========================================+
+# | **Catch**        | 1           | Catch a falling ball with a paddle       |
+# +------------------+-------------+------------------------------------------+
+# | **2048**         | 1           | Slide tiles to combine numbers           |
+# +------------------+-------------+------------------------------------------+
+# | **Blackjack**    | 1           | Classic card game against dealer         |
+# +------------------+-------------+------------------------------------------+
+# | **Cliff Walking**| 1           | Navigate a grid while avoiding cliffs    |
+# +------------------+-------------+------------------------------------------+
+# | **Tic-Tac-Toe**  | 2           | Classic 3×3 grid game                    |
+# +------------------+-------------+------------------------------------------+
+# | **Kuhn Poker**   | 2           | Simplified 3-card poker                  |
+# +------------------+-------------+------------------------------------------+
+#
+# The Catch Game
+# ~~~~~~~~~~~~~~
+#
+# For this tutorial, we'll use **Catch**—one of the simplest RL environments.
+# It's perfect for learning because:
+#
+# - Simple rules (easy to understand)
+# - Fast episodes (10 steps each)
+# - Clear success metric (did you catch the ball?)
+# - Optimal strategy is learnable (move toward the ball)
+#
+# **Game Rules:**
+#
+# .. code-block:: text
+#
+#     ⬜ ⬜ 🔴 ⬜ ⬜    <- Ball starts at random column (row 0)
+#     ⬜ ⬜ ⬜ ⬜ ⬜
+#     ⬜ ⬜ ⬜ ⬜ ⬜       The ball falls down one row
+#     ⬜ ⬜ ⬜ ⬜ ⬜       each time step
+#     ⬜ ⬜ ⬜ ⬜ ⬜
+#     ⬜ ⬜ ⬜ ⬜ ⬜
+#     ⬜ ⬜ ⬜ ⬜ ⬜
+#     ⬜ ⬜ ⬜ ⬜ ⬜
+#     ⬜ ⬜ ⬜ ⬜ ⬜
+#     ⬜ ⬜ 🏓 ⬜ ⬜    <- Paddle at bottom (row 9)
+#
+# - **Grid Size**: 10 rows × 5 columns
+# - **Ball**: Starts at a random column in row 0, falls one row per step
+# - **Paddle**: Starts at center column, you control it
+# - **Episode Length**: 10 steps (ball reaches bottom)
+#
+# **Actions:**
+#
+# +------------+------------------+
+# | Action ID  | Movement         |
+# +============+==================+
+# | 0          | Move LEFT        |
+# +------------+------------------+
+# | 1          | STAY (no move)   |
+# +------------+------------------+
+# | 2          | Move RIGHT       |
+# +------------+------------------+
+#
+# **Rewards:**
+#
+# - **+1.0** if the paddle is in the same column as the ball when it lands
+# - **0.0** if you miss the ball
+#
+# **Optimal Strategy**: Track the ball's column and move toward it. A perfect
+# policy wins 100% of the time since the paddle can always reach any column
+# in 10 steps (grid is only 5 columns wide).
+#
+# Importing OpenEnv
+# ~~~~~~~~~~~~~~~~~
+#
+# First, let's import the OpenSpiel environment client and models:
+
+# Real imports from OpenEnv
+try:
+    # Direct imports from the openspiel_env package
+    from openspiel_env.client import OpenSpielEnv
+    from openspiel_env.models import OpenSpielAction, OpenSpielObservation, OpenSpielState
+
+    OPENENV_AVAILABLE = True
+    print("✓ OpenEnv imports successful!")
+    print(f"  - OpenSpielEnv: {OpenSpielEnv}")
+    print(f"  - OpenSpielAction: {OpenSpielAction}")
+except ImportError as e:
+    OPENENV_AVAILABLE = False
+    print(f"✗ OpenEnv not fully installed: {e}")
+    print("  Run: pip install openenv-core")
+    print("  And: pip install -e ./envs/openspiel_env")
+
+# %%
+# Connecting to an Environment
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# OpenEnv provides three ways to connect to environments:
+#
+# 1. **From Hugging Face Hub** (auto-downloads and starts container)
+# 2. **From Docker image** (uses local image)
+# 3. **From URL** (connects to running server)
+#
+# Let's examine the actual methods available on the client class:
+
+print("=" * 70)
+print("   THREE WAYS TO CONNECT")
+print("=" * 70)
+print()
+
+if OPENENV_AVAILABLE:
+    # Show actual method signatures from the class
+    import inspect
+
+    print("Connection methods available on OpenSpielEnv:")
+    print()
+
+    # Method 1: from_hub
+    if hasattr(OpenSpielEnv, "from_hub"):
+        sig = inspect.signature(OpenSpielEnv.from_hub)
+        print(f"1. OpenSpielEnv.from_hub{sig}")
+        print("   → Auto-downloads from Hugging Face, starts container, connects")
+        print("   Example: env = OpenSpielEnv.from_hub('openenv/openspiel-env')")
+        print()
+
+    # Method 2: from_docker_image
+    if hasattr(OpenSpielEnv, "from_docker_image"):
+        sig = inspect.signature(OpenSpielEnv.from_docker_image)
+        print(f"2. OpenSpielEnv.from_docker_image{sig}")
+        print("   → Starts container from local image, connects")
+        print("   Example: env = OpenSpielEnv.from_docker_image('openspiel-env:latest')")
+        print()
+
+    # Method 3: Direct connection
+    sig = inspect.signature(OpenSpielEnv.__init__)
+    print(f"3. OpenSpielEnv.__init__{sig}")
+    print("   → Connects to already-running server")
+    print("   Example: env = OpenSpielEnv(base_url='http://localhost:8000')")
+    print()
+
+    print("-" * 70)
+    print("All three give you the same API - just different ways to start!")
+else:
+    print("(OpenEnv not installed - showing expected methods)")
+    print()
+    print("1. OpenSpielEnv.from_hub(repo_id, *, use_docker=True, ...)")
+    print("   → Auto-downloads from Hugging Face, starts container, connects")
+    print()
+    print("2. OpenSpielEnv.from_docker_image(image, provider=None, ...)")
+    print("   → Starts container from local image, connects")
+    print()
+    print("3. OpenSpielEnv(base_url, connect_timeout_s=10.0, ...)")
+    print("   → Connects to already-running server")
+
+# %%
+# Part 3: Playing the Catch Game
+# ------------------------------
+#
+# Now let's actually play! This code attempts to connect to a real server.
+# If no server is running, we'll show what the interaction looks like.
+
+import random
+
+# Check if we can connect to a server
+SERVER_URL = "http://localhost:8000"
+SERVER_AVAILABLE = False
+
+if OPENENV_AVAILABLE:
+    try:
+        # Try to connect using sync wrapper
+        env = OpenSpielEnv(base_url=SERVER_URL)
+        with env.sync() as client:
+            # Quick test to verify connection
+            pass
+        SERVER_AVAILABLE = True
+        print(f"✓ Connected to server at {SERVER_URL}")
+    except Exception as e:
+        print(f"✗ No server running at {SERVER_URL}")
+        print(f"  Error: {e}")
+        print()
+        print("To start a server, run one of these:")
+        print("  docker run -p 8000:8000 openenv/openspiel-env:latest")
+        print("  # OR")
+        print("  cd envs/openspiel_env && openenv serve")
+
+# %%
+# Playing with a Real Server
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# When connected to a real server, here's how the interaction works:
+
+if OPENENV_AVAILABLE and SERVER_AVAILABLE:
+    print("=" * 70)
+    print("   PLAYING CATCH - LIVE!")
+    print("=" * 70)
+
+    env = OpenSpielEnv(base_url=SERVER_URL)
+    with env.sync() as client:
+        # Reset to start a new episode
+        result = client.reset()
+
+        print(f"\nEpisode started!")
+        print(f"  Observation type: {type(result.observation).__name__}")
+        print(f"  Legal actions: {result.observation.legal_actions}")
+        print(f"  Done: {result.done}")
+
+        # Play until the episode ends
+        step_count = 0
+        while not result.done:
+            # Choose a random action from legal actions
+            action_id = random.choice(result.observation.legal_actions)
+            action = OpenSpielAction(action_id=action_id, game_name="catch")
+
+            # Take the action
+            result = client.step(action)
+            step_count += 1
+
+            print(f"\nStep {step_count}:")
+            print(f"  Action: {action_id} ({'LEFT' if action_id == 0 else 'STAY' if action_id == 1 else 'RIGHT'})")
+            print(f"  Reward: {result.reward}")
+            print(f"  Done: {result.done}")
+
+        # Get final state
+        state = client.state()
+        print(f"\nEpisode complete!")
+        print(f"  Total steps: {state.step_count}")
+        print(f"  Final reward: {result.reward}")
+        print(f"  Result: {'CAUGHT!' if result.reward > 0 else 'MISSED!'}")
+
+else:
+    # Run a local simulation to demonstrate the gameplay
+    print("=" * 70)
+    print("   PLAYING CATCH - LOCAL SIMULATION")
+    print("=" * 70)
+    print()
+    print("No server running - demonstrating with local simulation.")
+    print("(This shows exactly what happens when playing the real game)")
+    print()
+
+    # Simulate the Catch game locally
+    GRID_HEIGHT = 10
+    GRID_WIDTH = 5
+
+    # Initialize game state
+    ball_col = random.randint(0, GRID_WIDTH - 1)
+    paddle_col = GRID_WIDTH // 2  # Start in center
+
+    print(f"Game initialized:")
+    print(f"  Ball starting column: {ball_col}")
+    print(f"  Paddle starting column: {paddle_col}")
+    print(f"  Grid size: {GRID_HEIGHT} rows × {GRID_WIDTH} columns")
+    print()
+
+    # Simulate episode
+    for step in range(GRID_HEIGHT):
+        # Create observation (matching OpenSpiel format)
+        info_state = [0.0] * (GRID_HEIGHT * GRID_WIDTH)
+        info_state[step * GRID_WIDTH + ball_col] = 1.0  # Ball position
+        info_state[(GRID_HEIGHT - 1) * GRID_WIDTH + paddle_col] = 1.0  # Paddle
+
+        legal_actions = [0, 1, 2]  # LEFT, STAY, RIGHT
+
+        # Choose random action
+        action_id = random.choice(legal_actions)
+        action_name = {0: "LEFT", 1: "STAY", 2: "RIGHT"}[action_id]
+
+        # Execute action
+        old_paddle = paddle_col
+        if action_id == 0:  # LEFT
+            paddle_col = max(0, paddle_col - 1)
+        elif action_id == 2:  # RIGHT
+            paddle_col = min(GRID_WIDTH - 1, paddle_col + 1)
+
+        print(f"Step {step + 1}: Ball at row {step}, col {ball_col} | "
+              f"Paddle: {old_paddle}→{paddle_col} ({action_name})")
+
+    # Determine result
+    caught = (paddle_col == ball_col)
+    reward = 1.0 if caught else 0.0
+
+    print()
+    print(f"Episode complete!")
+    print(f"  Ball landed at column: {ball_col}")
+    print(f"  Paddle final column: {paddle_col}")
+    print(f"  Reward: {reward}")
+    print(f"  Result: {'CAUGHT! 🎉' if caught else 'MISSED! 😢'}")
+    print()
+    print("-" * 70)
+    print("This is exactly how the real OpenSpielEnv works,")
+    print("just running locally instead of via WebSocket to a server.")
+
+# %%
+# Part 4: Understanding the Response Types
+# ----------------------------------------
+#
+# OpenEnv uses type-safe models for all interactions. Let's create actual
+# instances and examine their attributes:
+
+print("=" * 70)
+print("   OPENENV TYPE SYSTEM - ACTUAL INSTANCES")
+print("=" * 70)
+
+# Create example instances that match what you'd get from the Catch game
+# These are the actual Pydantic models used by OpenEnv
+
+# 1. OpenSpielObservation - what the agent receives after each step
+print("\n📦 OpenSpielObservation (returned in StepResult)")
+print("-" * 50)
+
+if OPENENV_AVAILABLE:
+    # OpenSpielObservation was already imported above via auto-discovery
+    # Create a sample observation like what Catch game returns
+    sample_observation = OpenSpielObservation(
+        info_state=[0.0, 0.0, 1.0, 0.0, 0.0] + [0.0] * 45,  # Ball at col 2, row 0
+        legal_actions=[0, 1, 2],  # LEFT, STAY, RIGHT
+        game_phase="playing",
+        current_player_id=0,
+        opponent_last_action=None,
+    )
+
+    print(f"  info_state: {sample_observation.info_state[:10]}... (length: {len(sample_observation.info_state)})")
+    print(f"  legal_actions: {sample_observation.legal_actions}")
+    print(f"  game_phase: {sample_observation.game_phase!r}")
+    print(f"  current_player_id: {sample_observation.current_player_id}")
+    print(f"  opponent_last_action: {sample_observation.opponent_last_action}")
+else:
+    # Create without imports to show the structure
+    from dataclasses import dataclass
+    from typing import List, Optional
+
+    @dataclass
+    class OpenSpielObservation:
+        info_state: List[float]
+        legal_actions: List[int]
+        game_phase: str = "playing"
+        current_player_id: int = 0
+        opponent_last_action: Optional[int] = None
+
+    sample_observation = OpenSpielObservation(
+        info_state=[0.0, 0.0, 1.0, 0.0, 0.0] + [0.0] * 45,
+        legal_actions=[0, 1, 2],
+        game_phase="playing",
+        current_player_id=0,
+        opponent_last_action=None,
+    )
+
+    print(f"  info_state: {sample_observation.info_state[:10]}... (length: {len(sample_observation.info_state)})")
+    print(f"  legal_actions: {sample_observation.legal_actions}")
+    print(f"  game_phase: {sample_observation.game_phase!r}")
+    print(f"  current_player_id: {sample_observation.current_player_id}")
+    print(f"  opponent_last_action: {sample_observation.opponent_last_action}")
+
+# 2. OpenSpielState - the environment's internal state
+print("\n📊 OpenSpielState (returned by state())")
+print("-" * 50)
+
+if OPENENV_AVAILABLE:
+    # OpenSpielState was already imported above via auto-discovery
+    sample_state = OpenSpielState(
+        game_name="catch",
+        agent_player=0,
+        opponent_policy="random",
+        game_params={"rows": 10, "columns": 5},
+        num_players=1,
+    )
+
+    print(f"  game_name: {sample_state.game_name!r}")
+    print(f"  agent_player: {sample_state.agent_player}")
+    print(f"  opponent_policy: {sample_state.opponent_policy!r}")
+    print(f"  game_params: {sample_state.game_params}")
+    print(f"  num_players: {sample_state.num_players}")
+else:
+    @dataclass
+    class OpenSpielState:
+        game_name: str = "catch"
+        agent_player: int = 0
+        opponent_policy: str = "random"
+        game_params: dict = None
+        num_players: int = 1
+
+    sample_state = OpenSpielState(
+        game_name="catch",
+        agent_player=0,
+        opponent_policy="random",
+        game_params={"rows": 10, "columns": 5},
+        num_players=1,
+    )
+
+    print(f"  game_name: {sample_state.game_name!r}")
+    print(f"  agent_player: {sample_state.agent_player}")
+    print(f"  opponent_policy: {sample_state.opponent_policy!r}")
+    print(f"  game_params: {sample_state.game_params}")
+    print(f"  num_players: {sample_state.num_players}")
+
+# 3. OpenSpielAction - what you send to step()
+print("\n🎮 OpenSpielAction (what you send to step())")
+print("-" * 50)
+
+if OPENENV_AVAILABLE:
+    # OpenSpielAction was already imported above via auto-discovery
+    sample_action = OpenSpielAction(
+        action_id=1,  # STAY
+        game_name="catch",
+        game_params={"rows": 10, "columns": 5},
+    )
+
+    print(f"  action_id: {sample_action.action_id}  # 0=LEFT, 1=STAY, 2=RIGHT")
+    print(f"  game_name: {sample_action.game_name!r}")
+    print(f"  game_params: {sample_action.game_params}")
+else:
+    @dataclass
+    class OpenSpielAction:
+        action_id: int
+        game_name: str = "catch"
+        game_params: dict = None
+
+    sample_action = OpenSpielAction(
+        action_id=1,
+        game_name="catch",
+        game_params={"rows": 10, "columns": 5},
+    )
+
+    print(f"  action_id: {sample_action.action_id}  # 0=LEFT, 1=STAY, 2=RIGHT")
+    print(f"  game_name: {sample_action.game_name!r}")
+    print(f"  game_params: {sample_action.game_params}")
+
+print("\n" + "=" * 70)
+print("These are the actual Pydantic/dataclass models used by OpenEnv.")
+print("Type safety helps catch errors before they reach the environment!")
+print("=" * 70)
+
+# %%
+# Part 5: The Architecture
+# ------------------------
+#
+# OpenEnv uses a client-server architecture:
+#
+# .. code-block:: text
+#
+#     ┌─────────────────────────────────────────────────────────────┐
+#     │  YOUR CODE                                                  │
+#     │                                                             │
+#     │  from openenv import AutoEnv                                │
+#     │  OpenSpielEnv = AutoEnv.get_env_class("openspiel")          │
+#     │  env = OpenSpielEnv(base_url="http://localhost:8000")       │
+#     │  result = env.reset()      # Sends WebSocket message        │
+#     │  result = env.step(action) # Sends WebSocket message        │
+#     │                                                             │
+#     └────────────────────────┬────────────────────────────────────┘
+#                              │
+#                              │ WebSocket (persistent connection)
+#                              │
+#     ┌────────────────────────▼────────────────────────────────────┐
+#     │  DOCKER CONTAINER                                           │
+#     │                                                             │
+#     │  ┌─────────────────────────────────────────────────────┐    │
+#     │  │  FastAPI Server + Environment Logic                 │    │
+#     │  │  - /ws (WebSocket endpoint)                         │    │
+#     │  │  - Handles reset(), step(), state()                 │    │
+#     │  │  - Runs the actual game simulation                  │    │
+#     │  └─────────────────────────────────────────────────────┘    │
+#     │                                                             │
+#     │  Isolated • Reproducible • Scalable                         │
+#     └─────────────────────────────────────────────────────────────┘
+#
+# **Key insight**: You never deal with HTTP/WebSocket directly.
+# The OpenEnv client handles all the networking!
+
+# %%
+# Summary
+# -------
+#
+# In this notebook, you learned:
+#
+# **What OpenEnv Is:**
+#
+# - A unified framework for RL environments
+# - Containerized, type-safe, and shareable
+#
+# **Why Use OpenEnv:**
+#
+# - Type safety with IDE autocomplete
+# - Isolated Docker containers
+# - Easy sharing via Hugging Face Hub
+#
+# **How to Use It:**
+#
+# - ``env.reset()`` - Start a new episode
+# - ``env.step(action)`` - Take an action
+# - ``env.state()`` - Get current state
+#
+# Next Steps
+# ----------
+#
+# **Continue to Notebook 2: Using Environments**
+#
+# In the next notebook, you'll:
+#
+# - Explore all available OpenEnv environments
+# - Create different AI policies
+# - Run evaluations and compare performance
+# - Work with multi-player games