How to Install OpenEnv from Hugging Face: Complete Setup Guide

Install OpenEnv by first running pip install openenv for the core library, then installing a specific environment client such as pip install git+https://huggingface.co/spaces/openenv/echo_env to interact with remote or local execution environments.

OpenEnv is an end-to-end framework for creating, deploying, and interacting with isolated execution environments for agentic reinforcement-learning training. This guide walks you through how to install OpenEnv from Hugging Face, covering both the core package and individual environment clients that implement the Gymnasium-style API.

Understanding the OpenEnv Architecture

OpenEnv uses a client-server architecture that separates the lightweight client library from containerized environment implementations. The core openenv package provides base classes and CLI tooling, while specific environments like EchoEnv or CodingEnv run inside Docker containers exposing FastAPI servers.

This design requires a two-step installation process. The core package in src/openenv/core/__init__.py defines the EnvClient interface and communication protocols, while individual environments in the envs/ directory implement the actual logic in src/openenv/core/env_server.py. Understanding this separation clarifies why you must install both components to run experiments.

Step-by-Step Installation Guide

Install the Core Package

Start by installing the base OpenEnv library from PyPI. This provides the client abstractions, Docker helpers, and command-line interface defined in src/openenv/cli/main.py.

pip install openenv

This installs the framework's foundation, including the EnvClient class and WebSocket communication utilities, but does not include any runnable environments.

Install an Environment Client

Next, install a specific environment implementation. The simplest starting point is the Echo Environment, which echoes back messages for testing connectivity:

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

This command pulls the client code from the Hugging Face Space and installs the EchoEnv class exported in envs/echo_env/__init__.py. For development work on the coding environment, install in editable mode with development dependencies:

uv pip install -e "envs/coding_env[dev]"

Verify Your Installation

Confirm that both packages installed correctly by checking imports and version information:

python -c "import openenv; print(openenv.__version__)"
python -c "from echo_env import EchoEnv; print('EchoEnv imported successfully')"

If both commands execute without errors, your OpenEnv installation from Hugging Face is ready for use.

Working with OpenEnv Clients

Once installed, you can interact with environments either asynchronously (recommended for production) or synchronously (convenient for scripting).

Async Usage (Recommended)

The primary interface uses async/await patterns for non-blocking communication with remote environments. This example connects to a hosted EchoEnv instance:

import asyncio
from echo_env import CallToolAction, EchoEnv

async def main():
    async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:
        # Initialize episode

        result = await client.reset()
        print(result.observation.echoed_message)
        
        # Execute action

        result = await client.step(
            CallToolAction(
                tool_name="echo_message", 
                arguments={"message": "Hello, OpenEnv!"}
            )
        )
        print(result.observation.result)
        print("Reward:", result.reward)

asyncio.run(main())

This pattern leverages the async implementation in src/openenv/core/client.py (referenced by environment clients) to handle WebSocket communication efficiently.

Synchronous Usage

For synchronous scripts or Jupyter notebooks, wrap the client using the .sync() method:

from echo_env import CallToolAction, EchoEnv

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

The .sync() wrapper converts all async methods to blocking calls while maintaining the same API surface.

Local Development Setup

To run environments locally without connecting to Hugging Face Spaces, clone the repository and install components in editable mode:

git clone https://github.com/huggingface/OpenEnv.git
cd OpenEnv
pip install -e .

cd envs/echo_env
pip install -e .

# Run the FastAPI server directly

uv run python -m echo_env.server.app --host 0.0.0.0 --port 8000

This workflow references the server implementation in envs/echo_env/server/app.py, which extends the base server utilities in src/openenv/core/env_server.py.

Key Files and Components

Understanding these source files helps troubleshoot installation issues and extend the framework:

• README.md – Contains the architecture diagram, quick-start instructions, and CLI documentation at the repository root.

• envs/echo_env/README.md – Specific setup instructions for the Echo environment, including available actions and observations.

• src/openenv/core/__init__.py – Exports core abstractions including EnvClient, StepResult, and CallToolAction used by all environment implementations.

• src/openenv/core/env_server.py – Provides FastAPI server utilities and the base environment server class that handles WebSocket connections and container lifecycle management.

• src/openenv/cli/main.py – Entry point for the openenv command-line tool, supporting commands like init, push, and serve for environment development.

• envs/echo_env/__init__.py – Re-exports the EchoEnv client class and its associated Pydantic models for user convenience.

• envs/echo_env/server/app.py – Concrete FastAPI application implementing the Echo environment logic, demonstrating how to extend the base server for custom environments.

Summary

• Install the core framework with pip install openenv to get client libraries and CLI tools.
• Install specific environments separately using pip install git+https://huggingface.co/spaces/openenv/[env_name] to interact with remote execution environments.
• Use async patterns for production workloads, or call .sync() for blocking, script-friendly interfaces.
• Develop locally by installing packages in editable mode and running FastAPI servers directly from envs/[name]/server/app.py.

Frequently Asked Questions

What is the difference between the core package and environment clients?

The core package (openenv) provides the infrastructure for WebSocket communication, Docker management, and base classes defined in src/openenv/core/__init__.py. Environment clients (like echo_env) are specific implementations that inherit from these base classes and connect to particular Docker containers or Hugging Face Spaces. You need both because the core contains no runnable environments, and environment clients depend on the core's communication protocols.

Can I run OpenEnv environments without Docker?

Yes, though Docker provides the intended isolation. For local development, you can run the FastAPI server directly using uv run python -m [env_module].server.app as shown in the EchoEnv example. This executes the environment logic in envs/echo_env/server/app.py without containerization, though you must manually manage dependencies.

How do I install a custom environment from a private Hugging Face Space?

Use the same pip install git+https://huggingface.co/spaces/[username]/[space_name] pattern, but ensure you have authenticated Hugging Face CLI access or include an access token in the URL: git+https://[token]@huggingface.co/spaces/[username]/[space_name]. The OpenEnv client in src/openenv/core/client.py will handle the WebSocket connection regardless of whether the Space is public or private.

Which Python versions are supported by OpenEnv?

OpenEnv requires Python 3.9 or higher. The core package uses modern async/await syntax and Pydantic v2 features, while environment implementations may have additional requirements specified in their individual pyproject.toml files within the envs/ directory.

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