# Main Features of OpenEnv: A Framework for Agentic Execution Environments

> Discover OpenEnv, the framework for agentic execution environments. Integrate Gymnasium, container isolation, and WebSocket for secure, scalable RL pipelines.

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

---

**OpenEnv is a framework for building agentic execution environments that combines a Gymnasium-compatible API with container isolation, WebSocket communication, and a comprehensive CLI to create secure, scalable reinforcement learning pipelines.**

OpenEnv, developed by Hugging Face, provides modern infrastructure for creating isolated execution environments used in reinforcement learning (RL) workflows with LLM-based agents. The framework bridges classic RL patterns with contemporary needs for security and distribution, offering both synchronous and asynchronous interfaces. Understanding the main features of OpenEnv reveals how it enables reproducible agent training with minimal boilerplate while maintaining strict isolation guarantees.

## Gym-Style API for Drop-In RL Integration

OpenEnv follows the classic Gymnasium pattern, exposing `reset()`, `step(action)`, and `state()` methods that make environments drop-in replacements for existing RL pipelines. In [`src/openenv/core/env_client.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/env_client.py), the `EnvClient` class implements these methods with both async and sync wrappers, allowing seamless integration with training frameworks like TRL, torchforge, SkyRL, ART, and Lightning AI.

## WebSocket-Based Async Communication

The framework uses a WebSocket client/server architecture for low-latency interaction between agents and environments. The `EnvClient` in [`src/openenv/core/env_client.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/env_client.py) communicates with the server over WebSocket, enabling real-time streaming of actions and observations. On the server side, [`src/openenv/core/env_server/mcp_environment.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/env_server/mcp_environment.py) implements the Model Context Protocol (MCP), exposing `reset`, `step`, and `state` endpoints that handle rich message exchanges including actions, observations, and rewards.

## Container Isolation with Multi-Provider Support

Security and reproducibility come through Docker containerization, with [`src/openenv/core/containers/runtime/providers.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/containers/runtime/providers.py) abstracting multiple runtime providers:

- **LocalDockerProvider** for local development
- **DockerSwarmProvider** for distributed deployments
- **KubernetesProvider** for cloud-native orchestration
- **UVProvider** for fast Python environment management
- **DaytonaProvider** for additional cloud deployment options

Each environment runs in its own isolated container, ensuring that agent actions cannot affect the host system.

## Model Context Protocol (MCP) Support

OpenEnv implements the Model Context Protocol specification, allowing environments to exchange structured messages beyond simple action/observation pairs. The [`mcp_environment.py`](https://github.com/huggingface/OpenEnv/blob/main/mcp_environment.py) file enables richer interaction patterns where agents can query environment capabilities and receive detailed feedback, essential for LLM-based agent workflows.

## Trajectory Rubrics and Delayed Rewards

Unlike traditional step-by-step reward systems, OpenEnv supports scoring entire trajectories through rubrics defined in [`src/openenv/core/rubrics/trajectory.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/rubrics/trajectory.py). This enables LLM-judge evaluations and complex reward shaping that considers the full episode history, crucial for training agents on multi-step reasoning tasks.

## CLI Tooling for Environment Lifecycle

The `openenv` CLI provides commands to scaffold, build, and deploy environments without manual configuration. Key commands include:

1. `openenv init` (from [`src/openenv/cli/commands/init.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/cli/commands/init.py)): Scaffolds a new environment package with [`models.py`](https://github.com/huggingface/OpenEnv/blob/main/models.py), [`client.py`](https://github.com/huggingface/OpenEnv/blob/main/client.py), and FastAPI server templates located in `src/openenv/cli/templates/openenv_env/`
2. `openenv build` (from [`src/openenv/cli/commands/build.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/cli/commands/build.py)): Constructs Docker images with proper dependencies
3. `openenv push` (from [`src/openenv/cli/commands/push.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/cli/commands/push.py)): Deploys environments to Hugging Face Spaces
4. `openenv serve`: Runs local development servers with auto-reload

## Auto-Discovery and Debugging Tools

The framework includes [`src/openenv/auto/_discovery.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/auto/_discovery.py) for automatic tool enumeration, allowing agents to query available actions without prior knowledge. For debugging, [`src/openenv/core/env_server/gradio_ui.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/env_server/gradio_ui.py) provides an optional Gradio-based web interface that displays action history, live observations, and manual action injection capabilities.

## Practical Usage Examples

### Async Environment Interaction

```python
import asyncio
from echo_env import EchoEnv, CallToolAction

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

        result = await client.reset()
        print(result.observation.echoed_message)   # → "Echo environment ready!"

        # send an action

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

        print("Reward:", result.reward)

asyncio.run(main())

```

### Synchronous Usage

```python
from echo_env import EchoEnv, CallToolAction

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

```

### Scaffolding and Deployment

```bash

# Create a fresh environment

openenv init my_game_env
cd my_game_env
pip install -e .

# Local development

openenv serve

# Production deployment

openenv build
openenv push --repo-id your-username/my-game-env

```

## Summary

- **Gym-compatible API**: Drop-in replacement for Gymnasium environments with `reset()`, `step()`, and `state()` methods implemented in [`src/openenv/core/env_client.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/env_client.py)
- **Container isolation**: Secure execution via Docker, Kubernetes, Swarm, UV, or Daytona providers defined in [`src/openenv/core/containers/runtime/providers.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/containers/runtime/providers.py)
- **WebSocket architecture**: Low-latency async communication between clients and servers using the `EnvClient` class
- **MCP support**: Rich message exchange protocol for LLM-agent integration via [`src/openenv/core/env_server/mcp_environment.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/env_server/mcp_environment.py)
- **Trajectory scoring**: Built-in rubrics in [`src/openenv/core/rubrics/trajectory.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/rubrics/trajectory.py) for evaluating complete episode trajectories
- **Complete CLI**: Scaffold, build, and deploy environments with commands from `src/openenv/cli/commands/`
- **Auto-discovery**: Automatic tool enumeration via [`src/openenv/auto/_discovery.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/auto/_discovery.py) for agent flexibility
- **Web UI**: Gradio-based debugging interface in [`src/openenv/core/env_server/gradio_ui.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/env_server/gradio_ui.py) for monitoring and manual interaction

## Frequently Asked Questions

### How does OpenEnv differ from standard Gymnasium environments?

OpenEnv extends the Gymnasium pattern by adding container isolation, WebSocket communication, and support for the Model Context Protocol. While traditional Gymnasium environments run locally in the same process, OpenEnv environments execute in isolated Docker containers accessed via the `EnvClient` in [`src/openenv/core/env_client.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/env_client.py), enabling secure execution of untrusted agent code with reproducible state management.

### Can I use OpenEnv with existing RL training frameworks?

Yes. OpenEnv provides adapters for popular frameworks including TRL, torchforge, SkyRL, ART, and Lightning AI. The `EnvClient` class exposes both async methods and a `.sync()` wrapper, making integration straightforward regardless of whether your training loop uses asyncio or synchronous code, as demonstrated in the `echo_env` example environment.

### What container runtimes does OpenEnv support?

According to [`src/openenv/core/containers/runtime/providers.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/core/containers/runtime/providers.py), OpenEnv supports LocalDockerProvider for local development, DockerSwarmProvider for cluster deployments, KubernetesProvider for cloud-native infrastructure, UVProvider for fast Python environment provisioning, and DaytonaProvider for additional cloud deployment options, all configurable through the container provider abstraction layer.

### How do I deploy an OpenEnv environment to production?

Use the CLI commands defined in [`src/openenv/cli/commands/build.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/cli/commands/build.py) and [`src/openenv/cli/commands/push.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/cli/commands/push.py). Run `openenv build` to create a Docker image, then `openenv push --repo-id your-username/environment-name` to deploy to Hugging Face Spaces. The framework handles WebSocket endpoint exposure and container orchestration automatically, making environments accessible via the `EnvClient` using the deployed Space URL.