Meta

• Requires: Python >=3.10
• Provides-Extra: core , cli , docs , all , daytona , inspect

👁 image
OpenEnv: Agentic Execution Environments

An e2e framework for creating, deploying and using isolated execution environments for agentic RL training, built using Gymnasium style simple APIs.

👁 PyPI
👁 Discord
👁 Open In Colab
👁 Docs

---

🚀 Featured Example: Train LLMs to play BlackJack using torchforge (PyTorch's agentic RL framework): examples/grpo_blackjack/

🔥 Zero to Hero Tutorial: End to end tutorial from our GPU Mode lecture and other hackathons.

Quick Start

Install the OpenEnv package:

pipinstallopenenv

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

pipinstallgit+https://huggingface.co/spaces/openenv/echo_env

Then use the environment:

importasyncio
fromecho_envimport CallToolAction, EchoEnv

async defmain():
 # 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.echoed_message) # "Echo environment ready!"

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

asyncio.run(main())

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

fromecho_envimport 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)

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

OpenEnv on partner platforms:

• Lightning AI Studio
• TRL example
• Unsloth Google Colab
• ART example
• Oumi example

Overview

OpenEnv provides a standard for interacting with agentic execution environments via simple Gymnasium style APIs - step(), reset(), state(). Users of agentic execution environments can interact with the environment during RL training loops using these simple APIs.

In addition to making it easier for researchers and RL framework writers, we also provide tools for environment creators making it easier for them to create richer environments and make them available over familiar protocols like HTTP and packaged using canonical technologies like docker. Environment creators can use the OpenEnv framework to create environments that are isolated, secure, and easy to deploy and use.

The OpenEnv CLI (openenv) provides commands to initialize new environments and deploy them to Hugging Face Spaces.

OpenEnv is openly governed by a technical committee that includes Hugging Face, Unsloth, Reflection, and Meta PyTorch. The committee coordinates project direction, major technical decisions, RFCs, and release planning through the public issue tracker, pull requests, and RFC process.

⚠️ Early Development Warning OpenEnv is currently in an experimental stage. You should expect bugs, incomplete features, and APIs that may change in future versions. The project welcomes bugfixes, but significant changes should be discussed before implementation so the technical committee and community can coordinate scope, compatibility, and release timing. It's recommended that you signal your intention to contribute in the issue tracker, either by filing a new issue or by claiming an existing one.

RFCs

Below is a list of active and historical RFCs for OpenEnv. RFCs are proposals for major changes or features. Please review and contribute!

• RFC 001: Baseline API and Interface Specifications
• RFC 002: Discoverability of environment tools by agents
• RFC 003: Add MCP (Model Context Protocol) support
• RFC 004: Add delayed rewards support for trajectory-based scoring
• RFC 005: Agentic Harness Integration

Architecture

Component Overview

┌─────────────────────────────────────────────────────────┐
│ Client Application │
│ ┌────────────────┐ ┌──────────────────┐ │
│ │ EchoEnv │ │ CodingEnv │ │
│ │ (EnvClient) │ │ (EnvClient) │ │
│ └────────┬───────┘ └────────┬─────────┘ │
└───────────┼───────────────────────────────┼─────────────┘
 │ WebSocket │ WebSocket
 │ (reset, step, state) │
┌───────────▼───────────────────────────────▼─────────────┐
│ Docker Containers (Isolated) │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ FastAPI Server │ │ FastAPI Server │ │
│ │ EchoEnvironment │ │ PythonCodeActEnv │ │
│ │ (Environment base) │ │ (Environment base) │ │
│ └──────────────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Core Components

1. Web Interface

OpenEnv includes a built-in web interface for interactive environment exploration and debugging. The web interface provides:

• Two-Pane Layout: HumanAgent interaction on the left, state observation on the right
• Real-time Updates: WebSocket-based live updates without page refresh
• Dynamic Forms: Automatically generated action forms based on environment Action types
• Action History: Complete log of all actions taken and their results

The web interface is conditionally enabled based on environment variables:

• Local Development: Disabled by default for lightweight development
• Manual Override: Enable with ENABLE_WEB_INTERFACE=true

To use the web interface:

fromopenenv.core.env_serverimport create_web_interface_app
fromyour_env.modelsimport YourAction, YourObservation
fromyour_env.server.your_environmentimport YourEnvironment

env = YourEnvironment()
app = create_web_interface_app(env, YourAction, YourObservation)

When enabled, open http://localhost:8000/web in your browser to interact with the environment.

2. Environment (Server-Side)

Base class for implementing environment logic:

• reset(): Initialize a new episode, returns initial Observation
• step(action): Execute an Action, returns resulting Observation
• state(): Access episode metadata (State with episode_id, step_count, etc.)

3. EnvClient (Client-Side)

Base class for environment communication:

• Async by default: Use async with and await for all operations
• Sync wrapper: Call .sync() to get a SyncEnvClient for synchronous usage
• Handles WebSocket connections to environment server
• Contains a utility to spin up a docker container locally for the corresponding environment
• Type-safe action/observation parsing

4. Container Providers

Manage container deployment:

• LocalDockerProvider: Run containers on local Docker daemon
• KubernetesProvider: Deploy to K8s clusters (future)

5. Models

Type-safe data structures:

• Action: Base class for environment actions
• Observation: Base class for environment observations
• State: Episode state tracking
• StepResult: Combines observation, reward, done flag

Project Structure

For Environment Creators

Use the CLI to quickly scaffold a new environment:

openenvinitmy_env

This creates the following structure:

my_env/
├── .dockerignore # Docker build exclusions
├── __init__.py # Export YourAction, YourObservation, YourEnv
├── models.py # Define Action, Observation, State dataclasses
├── client.py # Implement YourEnv(EnvClient)
├── README.md # Document your environment
├── openenv.yaml # Environment manifest
├── pyproject.toml # Dependencies and package configuration
├── outputs/ # Runtime outputs (logs, evals) - gitignored
│ ├── logs/
│ └── evals/
└── server/
 ├── your_environment.py # Implement YourEnvironment(Environment)
 ├── app.py # Create FastAPI app
 ├── requirements.txt # Dependencies for Docker (can be generated)
 └── Dockerfile # Define container image

Dependency Management

OpenEnv uses pyproject.toml as the primary dependency specification:

• Environment-level pyproject.toml: Each environment defines its own dependencies
• Root-level pyproject.toml: Contains shared core dependencies (fastapi, pydantic, uvicorn)
• Server requirements.txt: Can be auto-generated from pyproject.toml for Docker builds

Development Workflow:

# Install environment in editable mode
cdmy_env
pipinstall-e.

# Or using uv (faster)
uvpipinstall-e.

# Run server locally without Docker
uvrunserver--host0.0.0.0--port8000

Benefits:

• ✅ Client-side extensions: Modify client classes locally without repo changes
• ✅ Better dependency management: Clear separation between environments
• ✅ Flexible workflows: Use pip, uv, or Docker for different scenarios
• ✅ CI/CD ready: Automated dependency generation and validation

See envs/README.md for a complete guide on building environments.

For Environment Users

To use an environment:

1. Install the client: pip install git+https://huggingface.co/spaces/openenv/echo-env
2. Import: from echo_env import CallToolAction, EchoEnv
3. Use async (recommended) or sync API:

Async (recommended):

async with EchoEnv(base_url="...") as client:
 result = await client.reset()
 result = await client.step(action)

Sync (via .sync() wrapper):

with EchoEnv(base_url="...").sync() as client:
 result = client.reset()
 result = client.step(action)

See example scripts in examples/ directory.

CLI Commands

The OpenEnv CLI provides commands to manage environments:

• openenv init <env_name> - Initialize a new environment from template
• openenv push [--repo-id <repo>] [--private] - Deploy environment to Hugging Face Spaces

Quick Start

# Create a new environment
openenvinitmy_game_env

# Deploy to Hugging Face (will prompt for login if needed)
cdmy_game_env
openenvpush

For detailed options: openenv init --help and openenv push --help.

Design Principles

1. Separation of Concerns: Clear client-server boundaries
2. Type Safety: Strongly-typed actions, observations, and state
3. Container Isolation: Each environment runs in its own container
4. Simple APIs: Minimal, intuitive interfaces

Development

Installation

# Clone the repository
gitclonehttps://github.com/meta-pytorch/OpenEnv.git
cdOpenEnv

# Install core package in editable mode
pipinstall-e.
# Or using uv (faster)
uvpipinstall-e.

Running Tests

OpenEnv uses a modular dependency structure: the core package is minimal, and each environment has its own dependencies. This means some tests require environment-specific packages.

# Install pytest (required for running tests)
uvpipinstallpytest

# Run all tests (skips tests requiring uninstalled dependencies)
PYTHONPATH=src:envsuvrunpytesttests/-v--tb=short

# Run a specific test file
PYTHONPATH=src:envsuvrunpytesttests/envs/test_echo_environment.py-v

To run environment-specific tests, install that environment's dependencies:

# Example: Install coding_env with dev dependencies (includes smolagents + pytest)
uvpipinstall-e"envs/coding_env[dev]"

# Then run coding_env tests
PYTHONPATH=src:envsuvrunpytesttests/envs/test_python_codeact_rewards.py-v

Tests will be automatically skipped if their required dependencies aren't installed.

Requirements

• Python 3.10+
• Docker Desktop or Docker Engine
• FastAPI >= 0.104.0
• Uvicorn >= 0.24.0
• Requests >= 2.25.0
• Environment-specific dependencies (e.g., smolagents for coding_env)

Supported RL Tools

The goal of this project is to support a broad set of open and closed tools to help standardize the agentic RL community. If you have a project that supports OpenEnv environments, please put up a PR to add your tool name along with a link to your documentation.

torchforge

See GRPO BlackJack training example: examples/grpo_blackjack/

TRL

See the TRL example on how to integrate OpenEnv environments with GRPO training.

Unsloth

See the 2048 game example based on gpt-oss: Colab notebook

SkyRL

See the SkyRL example on how to train on OpenEnv environments with SkyRL.

ART

See the ART example on how OpenEnv environments can be used to train models with ART.

Oumi

See the Oumi example on how OpenEnv environments can be used to train models with Oumi.

Example Environments

Environment	Description
Echo Environment	Echoes back messages with metadata. Ideal for testing HTTP server infrastructure, learning framework basics, and verifying container deployment.
Coding Environment	Sandboxed Python code execution via smolagents. Captures stdout/stderr/exit codes, supports persistent episode context, and provides detailed error handling.
Chess Environment	Chess RL environment with configurable opponents and full rules support.
Atari Environment	Classic Arcade Learning Environment tasks for RL benchmarking.
FinRL Environment	Financial market simulations for algorithmic trading experiments.

Browse the full catalog of community environments at meta-pytorch.org/OpenEnv/environments.

Community Support & Acknowledgments

This is an open and community-centric project, governed in public by a technical committee that includes Hugging Face, Unsloth, Reflection, and Meta PyTorch. If you would like to add your project or organization here, please open a pull request for maintainer review.

Supporters include: Meta-PyTorch, Hugging Face, Scaler AI Labs, Patronus AI, Surge AI, LastMile AI, Unsloth, Reflection, vLLM, SkyRL (UC-Berkeley), LightningAI, Axolotl AI, Stanford Scaling Intelligence Lab, Mithril, OpenMined, Fleet AI, Halluminate, Turing, Scale AI, Scorecard ..

And we'd also like to acknowledge the team at Farama Foundation as the OpenEnv API was heavily inspired by the work you all have done on Gymnasium. Cheers!

License

BSD 3-Clause License (see LICENSE file)

Verified details

These details have been verified by PyPI

Maintainers

👁 Avatar for burtenshaw from gravatar.com
burtenshaw

Unverified details

These details have not been verified by PyPI

• Download URL: openenv-0.3.1.tar.gz
• Upload date: Jun 2, 2026
• Size: 165.3 kB
• Tags: Source
• Uploaded using Trusted Publishing? Yes
• Uploaded via: twine/6.1.0 CPython/3.13.12

Hashes for openenv-0.3.1.tar.gz

Algorithm	Hash digest
SHA256	9e99a08872c781c7c16d5ba214e532caf5cf29f2278eb9cc478544dc538f3918
MD5	e279ba5d07a3d7c630e8e11c544186dc
BLAKE2b-256	7a1612825046f4180173d8f845ad95ff7b7aac32486391d822df38d4e52b82df

See more details on using hashes here.

• Download URL: openenv-0.3.1-py3-none-any.whl
• Upload date: Jun 2, 2026
• Size: 194.9 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? Yes
• Uploaded via: twine/6.1.0 CPython/3.13.12

Hashes for openenv-0.3.1-py3-none-any.whl

Algorithm	Hash digest
SHA256	9cad4b66c08a04fd9d9fe48d7b13cd31f8322b348ff24891646e4440e0b7468c
MD5	b73f58e493dfc047412a8e68b2eab872
BLAKE2b-256	cc2820af86f825054561c10eb31236e19835f79036fd4a9f600f529adef42b7b

See more details on using hashes here.