README

OpenEnv: Agentic Execution Environments

An end-to-end framework for creating, deploying and using isolated execution environments for agentic RL, with a simple Gymnasium-style API.


    
    
    
    
    
    


 What you get

- One API for every environment. reset(), step() and state(), sync or async, over a WebSocket.
- Isolated, deployable environments. Each environment is a Docker image that runs locally, on a cloud sandbox, or as a Hugging Face Space.
- 40+ ready-to-use environments, from games and coding sandboxes to browsers, finance and simulators, in the environment catalog.
- Train with your framework. TRL, Unsloth, SkyRL, ART, Oumi, torchforge, Miles and more (see Integrations).
- Train real coding agents. The Harbor integration runs Claude Code, Codex, OpenCode, mini-swe-agent and other harnesses on Harbor tasks, and captures the exact tokens for RL.
- Serve tools to agents. MCP environments expose their tools to agents over /mcp in production mode, while training keeps using step() and rewards.
- Rewards and evals built in. Compose rewards with rubrics and evaluate with Inspect AI.

 Quick Start

Install the OpenEnv package:

bash
pip install openenv


Install an environment client (e.g., Echo):

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


Then use the environment:

python
import asyncio
from echo_env import CallToolAction, EchoEnv

async def main():
     Connect to a running Space (async context manager)
    async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:
         Reset the environment
        result = await client.reset()
        print(result.observation.metadata["message"])   "Echo environment ready!"

         Send messages
        result = await client.step(
            CallToolAction(
                tool_name="echo_message",
                arguments={"message": "Hello, World!"},
            )
        )
        print(result.observation.result["data"])   "Hello, World!"
        print(result.reward)

asyncio.run(main())


Synchronous usage is also supported via the .sync() wrapper:

python
from echo_env import CallToolAction, EchoEnv

 Use .sync() for synchronous context manager
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, World!"},
        )
    )
    print(result.observation.result["data"])


For a detailed quick start, check out the docs page.

 Train an agent

Any training framework that can call an environment can train on it. Training with OpenEnv maps the ways to train and the frameworks that support each one.

- Environments as tools (white-box). The trainer runs the multi-turn tool loop and the environment supplies the tools and the reward. Each framework under Integrations has its own example. With TRL, GRPOTrainer takes an environment_factory: start with the Wordle GRPO tuto