# How to Get Started with OpenEnv Examples: A Complete Guide

> Learn to get started with OpenEnv examples by installing the library, a client, and running ready-made scripts from the examples directory. Explore async and sync API usage.

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

---

**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.

```bash
pip install openenv

```

This installation is documented in the repository's [`README.md`](https://github.com/huggingface/OpenEnv/blob/main/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:

```bash
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`](https://github.com/huggingface/OpenEnv/blob/main/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:

```python
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:

```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`](https://github.com/huggingface/OpenEnv/blob/main/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`](https://github.com/huggingface/OpenEnv/blob/main/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`](https://github.com/huggingface/OpenEnv/blob/main/envs/echo_env/README.md)**: Documents the Echo sandbox API and available tools.
- **[`envs/textarena_env/README.md`](https://github.com/huggingface/OpenEnv/blob/main/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`](https://github.com/huggingface/OpenEnv/blob/main/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`](https://github.com/huggingface/OpenEnv/blob/main/examples/textarena_simple.py) script demonstrates a complete episode loop with reset, step, and reward inspection.
- [`src/openenv/core/client.py`](https://github.com/huggingface/OpenEnv/blob/main/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`](https://github.com/huggingface/OpenEnv/blob/main/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`](https://github.com/huggingface/OpenEnv/blob/main/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`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/client.py) provides the base WebSocket functionality, while environment packages extend this with specific action types like `CallToolAction` and observation schemas.