Complete Guide to Environments Available in OpenEnv: 2024 Catalog

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 declaring the Action, Observation, and State schemas (e.g., envs/echo_env/models.py).

2. Server implementation – A FastAPI service in server/app.py exposing reset, step, and state endpoints via the OpenEnv HTTP protocol (e.g., 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 that handles HTTP serialization and typed deserialization (e.g., envs/echo_env/client.py).

5. Specification file – openenv.yaml declaring the environment name, Docker image reference, and supported schemas for CI orchestration (e.g., 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.

# 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, envs/echo_env/models.py, envs/echo_env/server/app.py.

Example: Coding Environment

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

# 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, envs/coding_env/models.py, 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.

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 – Declarative specification defining the environment name, Docker image tag, and action/observation schemas. Used by the OpenEnv CLI and CI matrix.
• models.py – Typed dataclasses (e.g., Action, Observation, State) that enforce type safety between client and server.
• client.py – Thin wrapper extending EnvClient that translates Python objects to HTTP payloads for the OpenEnv protocol.
• 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 – 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), FastAPI servers (server/app.py), Docker containers (server/Dockerfile), Python clients (client.py), and declarative specs (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 with your domain-specific Action and Observation types, implement the reset, step, and state methods in server/app.py, and update the 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 (e.g., CodingAction vs. ChessAction). The client wrapper in client.py serializes these Pydantic models to JSON for the HTTP payload, and the FastAPI server in 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 to ensure dependency isolation and reproducibility.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}