How to Get Started with OpenEnv Examples: A Complete Guide

To get started with OpenEnv examples, install the core library with pip install openenv, install a specific environment client (such as echo_env), and run the ready-made scripts in the examples/ directory that demonstrate async and sync API usage.

OpenEnv by Hugging Face provides a collection of ready-to-run example scripts that demonstrate how to install environment clients and interact with remote or local environments. This guide walks through the exact steps to run your first OpenEnv example using the official huggingface/OpenEnv repository. Whether you prefer asynchronous programming or synchronous wrappers, the examples in the examples/ folder provide complete working implementations.

Install the OpenEnv Core Library

Begin by installing the base package from PyPI. The core library provides the EnvClient class and CLI tools required to communicate with any OpenEnv environment.

pip install openenv

This installation is documented in the repository's README.md and provides the foundation for all subsequent environment interactions.

Install an Environment Client

Each environment in OpenEnv is distributed as a separate Python package hosted on Hugging Face Spaces. The Echo environment serves as the simplest starting point for understanding the API.

Install the Echo client directly from its Hugging Face Space:

pip install git+https://huggingface.co/spaces/openenv/echo_env

For text-based challenges, install the TextArena client using the same pattern. Each client package contains environment-specific action definitions and observation schemas documented in their respective envs/ subdirectories.

Run the Example Scripts

The examples/ directory contains a dozen small programs demonstrating various interaction patterns. The examples/textarena_simple.py script provides a complete "Hello World" demonstration for text-based environments, creating a TextArenaEnv client, calling reset(), stepping through Wordle guesses, and printing episode rewards.

Async API Implementation

OpenEnv clients support native asynchronous programming. The following example from the repository's Quick-Start demonstrates the Echo environment using async/await syntax:

import asyncio
from echo_env import CallToolAction, EchoEnv

async def main() -> None:
    async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:
        await client.reset()
        result = await client.step(
            CallToolAction(
                tool_name="echo_message",
                arguments={"message": "Hello, OpenEnv!"},
            )
        )
        print(result.observation.result)   # → Hello, OpenEnv!

        print(result.reward)               # reward for the step

asyncio.run(main())

This script initializes the client, resets the environment state, executes a tool call action, and inspects the observation result.

Sync API Implementation

For synchronous workflows, wrap the client with the .sync() method. This approach blocks on I/O operations and behaves like standard imperative Python:

from echo_env import CallToolAction, EchoEnv

with EchoEnv(base_url="https://openenv-echo-env.hf.space").sync() as client:
    client.reset()
    result = client.step(
        CallToolAction(
            tool_name="echo_message",
            arguments={"message": "Hello, OpenEnv!"},
        )
    )
    print(result.observation.result)

Both implementations connect to the same WebSocket endpoint and produce identical results, allowing you to choose based on your application's concurrency requirements.

Understand the Three-Layer Architecture

OpenEnv examples rely on a consistent architecture consisting of three distinct layers. Understanding these components helps when debugging or extending the provided examples:

• Client Layer (src/openenv/core/client.py): The EnvClient class manages WebSocket connections to the server, marshals actions and observations, and exposes both async (await client.reset()) and sync (client.sync()) interfaces.

• Server Layer (src/openenv/core/env_server.py): A FastAPI application implementing environment logic (reset, step, state) over WebSocket. Each concrete environment ships its own server module under envs/*/server/.

• Container Layer (src/openenv/core/containers/): Docker images built from environment-specific Dockerfile definitions. The CLI uses LocalDockerProvider to spin containers up locally or openenv push to deploy to Hugging Face Spaces.

When you execute an example script, the client automatically launches the appropriate Docker container (if not running), establishes the WebSocket connection, and drives the environment. This design ensures the same script works against both remote Spaces and local containers without code modifications.

Explore Additional Environments

Beyond the Echo sandbox, the repository ships multiple ready-made environments under envs/. Each environment includes dedicated documentation:

• envs/echo_env/README.md: Documents the Echo sandbox API and available tools.
• envs/textarena_env/README.md: Details the TextArena environment's action space and observation formats.

Review these README files to understand environment-specific capabilities before running the associated example scripts.

Local Development Without Docker

If you prefer not to use remote Hugging Face Spaces or local Docker containers, you can start the server directly. The README.md contains a "Running server locally" snippet that launches the FastAPI application on your machine. Point your client to localhost instead of the Space URL to connect to the local instance.

Summary

• Install the core library with pip install openenv before attempting any examples.
• Environment clients install separately via git+https URLs from Hugging Face Spaces.
• The examples/textarena_simple.py script demonstrates a complete episode loop with reset, step, and reward inspection.
• src/openenv/core/client.py provides the EnvClient class powering all interactions.
• Use .sync() for synchronous code or async with for asynchronous workflows.
• The architecture supports both remote Spaces and local Docker containers transparently.

Frequently Asked Questions

What is the simplest OpenEnv example to start with?

The Echo environment provides the gentlest introduction. Install the echo_env client and run a basic script calling reset() and step() with a CallToolAction. This environment simply echoes your input, allowing you to verify connectivity and API usage without complex game logic.

How do I switch between async and sync APIs in OpenEnv?

Append .sync() to any client instantiation to create a synchronous wrapper. For example, EchoEnv(base_url=url).sync() returns a blocking client where reset() and step() return values directly rather than coroutines. The underlying implementation in src/openenv/core/client.py handles the event loop management automatically.

Can I run OpenEnv examples without Docker?

Yes. While the examples automatically manage Docker containers by default, you can run the server locally using the FastAPI implementation in src/openenv/core/env_server.py. Start the server manually and point your client to the local URL instead of the Hugging Face Space endpoint.

Where are the environment-specific client implementations located?

Each environment's client code resides in its respective envs/ subdirectory (e.g., envs/echo_env/). The core EnvClient class in src/openenv/core/client.py provides the base WebSocket functionality, while environment packages extend this with specific action types like CallToolAction and observation schemas.

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