# Complete Guide to Environments Available in OpenEnv: 2024 Catalog

> Explore 34 production-ready environments in OpenEnv from Atari to autonomous driving. Discover the catalog of environments for your next simulation project.

- Repository: [Hugging Face/OpenEnv](https://github.com/huggingface/OpenEnv)
- Tags: getting-started
- Published: 2026-06-16

---

**OpenEnv ships 34 production-ready environments ranging from classic Atari games to financial trading simulators and autonomous driving scenarios, all unified under a standardized five-component architecture.**

OpenEnv by Hugging Face is a modular framework for reinforcement learning and agent evaluation that standardizes interaction with diverse simulation backends. Understanding the specific environments available in OpenEnv is essential for selecting the right simulation for your research or production workload. Each environment follows a consistent structure defined in the `envs/` directory, making it trivial to swap implementations without changing your client code.

## Standard Architecture of OpenEnv Environments

Every environment in the catalog implements the same architectural pattern, located in its own subdirectory under `envs/`. This uniformity allows researchers to switch between domains by changing only the import statement and Docker image tag.

### Five Core Components

1. **Model definitions** – Typed dataclasses in [`models.py`](https://github.com/huggingface/OpenEnv/blob/main/models.py) declaring the `Action`, `Observation`, and `State` schemas (e.g., [`envs/echo_env/models.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/models.py)).

2. **Server implementation** – A FastAPI service in [`server/app.py`](https://github.com/huggingface/OpenEnv/blob/main/server/app.py) exposing `reset`, `step`, and `state` endpoints via the OpenEnv HTTP protocol (e.g., [`envs/echo_env/server/app.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/server/app.py)).

3. **Docker image** – A `server/Dockerfile` inheriting from `openenv-base` that bundles dependencies and launches the FastAPI server (e.g., `envs/echo_env/server/Dockerfile`).

4. **Client wrapper** – A thin Python class extending `EnvClient` in [`client.py`](https://github.com/huggingface/OpenEnv/blob/main/client.py) that handles HTTP serialization and typed deserialization (e.g., [`envs/echo_env/client.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/client.py)).

5. **Specification file** – [`openenv.yaml`](https://github.com/huggingface/OpenEnv/blob/main/openenv.yaml) declaring the environment name, Docker image reference, and supported schemas for CI orchestration (e.g., [`envs/echo_env/openenv.yaml`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/openenv.yaml)).

## Complete List of OpenEnv Environments

The repository contains 34 distinct environments. Below is the full catalog organized by domain, with links to their implementation folders:

### Games and Classic Control

- **Atari** – Arcade Learning Environment wrappers (`envs/atari_env`)
- **Chess** – Full chess simulation with legal move validation (`envs/chess_env`)
- **Connect 4** – Two-player connection game (`envs/connect4_env`)
- **OpenSpiel** – Integration with Google's games suite (`envs/openspiel_env`)
- **Snake** – Classic grid-based arcade game (`envs/snake_env`)
- **Grid World** – Simple navigation tasks (`envs/grid_world_env`)
- **Maze** – Solvable maze generation (`envs/maze_env`)

### Robotics, Physics, and Simulation

- **CARLA** – Autonomous driving simulator integration (`envs/carla_env`)
- **DM Control** – DeepMind Control Suite physics tasks (`envs/dm_control_env`)
- **Unity** – 3D simulation via Unity ML-Agents (`envs/unity_env`)
- **Wildfire** – Wildfire suppression simulation (`envs/wildfire_env`)
- **Sumo RL (SFL)** – Traffic control via SUMO simulator (`envs/sumo_rl_env`)

### Coding, Development, and REPL

- **Coding** – Secure Python code execution environment (`envs/coding_env`)
- **Coding Tools** – Extended coding with tool use capabilities (`envs/coding_tools_env`)
- **Git** – Git command execution and repository manipulation (`envs/git_env`)
- **Jupyter** – Jupyter notebook interaction (`envs/jupyter_env`)
- **Julia** – Julia language REPL execution (`envs/julia_env`)
- **Opencode** – General code execution sandbox (`envs/opencode_env`)
- **Repl** – Interactive shell environment (`envs/repl_env`)

### Web and Browser Automation

- **Audio BrowserGym** – Browser automation with audio capabilities (`envs/browsergym_env`)
- **Websearch** – Web search and retrieval tasks (`envs/websearch_env`)

### Financial and Business

- **FinRL** – Financial reinforcement learning for trading (`envs/finrl_env`)
- **FinQA** – Financial question answering and analysis (`envs/finqa_env`)
- **Calendar** – Calendar scheduling and management (`envs/calendar_env`)

### Specialized and Reference

- **Echo** – Reference implementation that echoes actions back (`envs/echo_env`)
- **Agent World Model** – World model for agent simulation (`envs/agent_world_model_env`)
- **Chat** – Conversational agent environment (`envs/chat_env`)
- **Dipg Safety** – Safety-focused RL environment (`envs/dipg_safety_env`)
- **KernRL** – Kernel-based reinforcement learning (`envs/kernrl`)
- **OpenApp** – Application recording and playback (`envs/openapp_env`)
- **Reasoning Gym** – Logical reasoning task suite (`envs/reasoning_gym_env`)
- **T-Bench 2** – Benchmark environment for tool use (`envs/tbench2_env`)
- **Terminus** – Terminal interaction environment (`envs/terminus_env`)
- **TextArena** – Text-based competitive environment (`envs/textarena_env`)

## How to Use OpenEnv Environments

All environments share identical client APIs. You initialize them from Docker images, call `reset()`, and interact via `step()` methods.

### Basic Usage Pattern

Every environment exposes a client class named `<EnvName>Env` (e.g., `EchoEnv`, `CodingEnv`) that inherits from `EnvClient`. The standard workflow imports the action and environment classes, instantiates the client from a Docker image, and runs the reset-step loop.

### Example: Echo Environment

The Echo environment serves as the reference implementation. Located in `envs/echo_env/`, it simply returns the action message in the observation.

```python

# example_echo.py

from envs.echo_env import EchoAction, EchoEnv

# Create client from pre-built Docker image

client = EchoEnv.from_docker_image("echo-env:latest")

# Reset returns a StepResult containing EchoObservation

reset_res = client.reset()
print("Reset observation:", reset_res.observation)

# Send typed action

action = EchoAction(message="hello OpenEnv")
step_res = client.step(action)
print("Step observation:", step_res.observation)

# Query current state

state = client.state()
print("Current state:", state)

client.close()  # Clean up container

```

*Key source files:* [`envs/echo_env/client.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/client.py), [`envs/echo_env/models.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/models.py), [`envs/echo_env/server/app.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/server/app.py).

### Example: Coding Environment

The Coding environment (`envs/coding_env/`) executes arbitrary Python code in a sandboxed container.

```python

# example_coding.py

from envs.coding_env import CodingAction, CodingEnv

client = CodingEnv.from_docker_image("coding-env:latest")

client.reset()
action = CodingAction(code="print('Hello from OpenEnv')")
result = client.step(action)
print("Stdout:", result.observation.stdout)
print("Stderr:", result.observation.stderr)

client.close()

```

*Key source files:* [`envs/coding_env/client.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/coding_env/client.py), [`envs/coding_env/models.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/coding_env/models.py), [`envs/coding_env/server/app.py`](https://github.com/huggingface/OpenEnv/blob/main/envs/coding_env/server/app.py).

### Dynamic Environment Switching

Because all clients implement the same interface, you can switch environments at runtime by changing the import module and Docker tag.

```python
def run_env(env_name: str, docker_tag: str, action):
    # Dynamically import client module

    module = __import__(f"envs.{env_name}", fromlist=["client"])
    client_cls = getattr(module, f"{env_name.split('_')[0].capitalize()}Env")
    client = client_cls.from_docker_image(docker_tag)

    client.reset()
    res = client.step(action)
    print(f"[{env_name}] Observation:", res.observation)

    client.close()

# Run Wildfire environment

run_env(
    env_name="wildfire_env",
    docker_tag="wildfire-env:latest",
    action=__import__("envs.wildfire_env.models", fromlist=["WildfireAction"]).WildfireAction(...)
)

```

## Core Implementation Files

Each environment in the catalog contains these standardized files:

- **[`openenv.yaml`](https://github.com/huggingface/OpenEnv/blob/main/openenv.yaml)** – Declarative specification defining the environment name, Docker image tag, and action/observation schemas. Used by the OpenEnv CLI and CI matrix.
- **[`models.py`](https://github.com/huggingface/OpenEnv/blob/main/models.py)** – Typed dataclasses (e.g., `Action`, `Observation`, `State`) that enforce type safety between client and server.
- **[`client.py`](https://github.com/huggingface/OpenEnv/blob/main/client.py)** – Thin wrapper extending `EnvClient` that translates Python objects to HTTP payloads for the OpenEnv protocol.
- **[`server/app.py`](https://github.com/huggingface/OpenEnv/blob/main/server/app.py)** – FastAPI entry point wiring the core environment logic to HTTP routes (`/reset`, `/step`, `/state`).
- **`server/<environment>.py`** – Core logic implementing the `reset`, `step`, and `state` methods specific to the domain.
- **`server/Dockerfile`** – Build recipe inheriting from `openenv-base`, installing domain-specific dependencies (e.g., CARLA SDK, Julia runtime).
- **[`README.md`](https://github.com/huggingface/OpenEnv/blob/main/README.md)** – Domain-specific documentation and quick-start examples.

## Summary

OpenEnv provides a unified interface to 34 diverse simulation environments through Hugging Face's standardized architecture. Key takeaways include:

- **34 ready-to-use environments** spanning games, robotics, coding, finance, and web automation, all located in the `envs/` directory.
- **Five-component standardization** ensures every environment includes typed models ([`models.py`](https://github.com/huggingface/OpenEnv/blob/main/models.py)), FastAPI servers ([`server/app.py`](https://github.com/huggingface/OpenEnv/blob/main/server/app.py)), Docker containers (`server/Dockerfile`), Python clients ([`client.py`](https://github.com/huggingface/OpenEnv/blob/main/client.py)), and declarative specs ([`openenv.yaml`](https://github.com/huggingface/OpenEnv/blob/main/openenv.yaml)).
- **Interchangeable implementations** allow swapping from Echo to CARLA or Coding by changing the import statement and Docker image tag, with no changes to the control loop logic.
- **Type-safe interactions** via dataclasses ensure that `Action` and `Observation` schemas are enforced at runtime between client and container.

## Frequently Asked Questions

### How do I add a new environment to OpenEnv?

Copy the template structure from `envs/echo_env`, which serves as the reference implementation. Replace the dataclasses in [`models.py`](https://github.com/huggingface/OpenEnv/blob/main/models.py) with your domain-specific `Action` and `Observation` types, implement the `reset`, `step`, and `state` methods in [`server/app.py`](https://github.com/huggingface/OpenEnv/blob/main/server/app.py), and update the [`openenv.yaml`](https://github.com/huggingface/OpenEnv/blob/main/openenv.yaml) specification with your Docker image name. The CI matrix automatically picks up new directories in `envs/`.

### What is the difference between the Echo environment and production environments?

**Echo** (`envs/echo_env`) is a minimal reference implementation that returns the input action as the observation, useful for testing the OpenEnv protocol and client connectivity. Production environments like **CARLA** or **FinRL** implement complex domain logic in their `server/<environment>.py` files, manage external dependencies (Unreal Engine, financial data APIs), and provide specialized observation spaces.

### How does OpenEnv handle different action spaces across environments?

Each environment defines its own typed dataclasses in [`models.py`](https://github.com/huggingface/OpenEnv/blob/main/models.py) (e.g., `CodingAction` vs. `ChessAction`). The client wrapper in [`client.py`](https://github.com/huggingface/OpenEnv/blob/main/client.py) serializes these Pydantic models to JSON for the HTTP payload, and the FastAPI server in [`server/app.py`](https://github.com/huggingface/OpenEnv/blob/main/server/app.py) validates them against the schema before execution. This ensures type safety without requiring changes to the generic `EnvClient` base class.

### Can I run OpenEnv environments without Docker?

No. According to the `huggingface/OpenEnv` source code, every environment requires Docker because the server implementation runs inside a containerized FastAPI service. The `from_docker_image()` method in client classes manages the container lifecycle. While you can run the server binary directly from Python for development, production usage always requires the Docker image specified in [`openenv.yaml`](https://github.com/huggingface/OpenEnv/blob/main/openenv.yaml) to ensure dependency isolation and reproducibility.