# Top-Level Directories in the OpenEnv Repository: Complete Structure Guide

> Explore the huggingface OpenEnv repository's complete structure. Understand the purpose of each top-level directory: .claude, .github, envs, examples, rfcs, scripts, src, tests, and tutorial.

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

---

**The huggingface/OpenEnv repository organizes its codebase into nine primary directories—`.claude`, `.github`, `envs`, `examples`, `rfcs`, `scripts`, `src`, `tests`, and `tutorial`—that separate configuration, core library code, environment implementations, and learning resources.**

The **OpenEnv** project provides a modular framework for building containerized AI environments. Understanding the **top-level directories in the OpenEnv repository** is essential for navigating the codebase, contributing new features, or extending the library with custom environment implementations.

## Overview of the Repository Layout

The root folder follows a clear hierarchy that enforces **separation of concerns**. **Metadata and CI** configurations live in hidden directories, **framework code** is isolated under `src`, **environment specifications** reside in `envs`, and **learning resources** are split between `tutorial` and `examples`. This structure ensures that users can quickly locate the Docker configurations, API definitions, or test suites they need.

## Detailed Breakdown of Top-Level Directories

### .claude

The `.claude` directory contains supporting files for Claude-Code integration, including agents, documentation, and hooks. This directory supports AI-assisted development workflows specific to the repository.

### .github

The `.github` directory houses CI/CD pipelines, issue templates, and GitHub-specific configuration files. This is where automated testing workflows and repository maintenance bots are defined.

### envs

The `envs` directory stores ready-to-run **environment implementations**, such as the Echo demo and the wildfire environment. Each subdirectory contains a complete, containerized environment specification with Docker configurations and server implementations.

### examples

The `examples` directory provides end-to-end usage scripts and Jupyter notebooks illustrating how to build and run environments. These files serve as practical starting points for developers integrating OpenEnv into their own projects.

### rfcs

The `rfcs` directory contains design-level documentation (Request-for-Comments) that defines core abstractions, agent interfaces, and project phases. These documents establish the architectural decisions governing the codebase.

### scripts

The `scripts` directory holds utility scripts for testing, documentation synchronization, deployment, and general repository maintenance. For example, [`scripts/sync_env_docs.py`](https://github.com/huggingface/OpenEnv/blob/main/scripts/sync_env_docs.py) keeps documentation in sync with environment definitions.

### src

The `src` directory contains the **core library code** (`openenv_core`), including the client API, MCP server implementations, and Docker helper utilities. According to the OpenEnv source code, [`src/openenv_core/__init__.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv_core/__init__.py) exposes the public API containing `EnvClient` and server utilities.

### tests

The `tests` directory contains the unit and integration test suite covering both the core library and specific environment implementations. Files like [`tests/test_core/test_generic_client.py`](https://github.com/huggingface/OpenEnv/blob/main/tests/test_core/test_generic_client.py) validate core client behavior and serve as executable documentation.

### tutorial

The `tutorial` directory contains guided tutorials, markdown guides, and supporting images for onboarding new users. The file [`tutorial/01-environments.md`](https://github.com/huggingface/OpenEnv/blob/main/tutorial/01-environments.md) provides the first tutorial in the series, introducing environment construction concepts.

## Key Files at the Repository Root

Several critical files sit at the repository root and define the project's entry points:

- **[`src/openenv_core/__init__.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv_core/__init__.py)** – Exposes the public API, including `EnvClient`, MCP server classes, and utility functions.
- **[`README.md`](https://github.com/huggingface/OpenEnv/blob/main/README.md)** – Provides the project overview, quick-start guide, and high-level architecture summary.
- **[`tests/test_core/test_generic_client.py`](https://github.com/huggingface/OpenEnv/blob/main/tests/test_core/test_generic_client.py)** – Validates core client behavior and demonstrates usage patterns.
- **`envs/echo_env/server/Dockerfile`** – Demonstrates how environments are containerized for deployment.
- **[`tutorial/01-environments.md`](https://github.com/huggingface/OpenEnv/blob/main/tutorial/01-environments.md)** – The primary onboarding document for new developers.
- **[`scripts/sync_env_docs.py`](https://github.com/huggingface/OpenEnv/blob/main/scripts/sync_env_docs.py)** – Automates synchronization between environment definitions and documentation.

## Navigating the Codebase: Practical Examples

You interact with these directories through the Python API and command-line tools. To spin up an environment from the `envs` folder, instantiate the client using the environment path:

```python
from openenv_core import EnvClient

client = EnvClient.from_env_path("envs/echo_env")
obs = client.reset()
print("Initial observation:", obs)

```

To validate changes across the codebase, run the test suite from the repository root:

```bash
PYTHONPATH=src:envs uv run pytest tests/ -v

```

This command ensures that modifications to `src/openenv_core` do not break existing environment implementations in `envs/`.

## Summary

- The OpenEnv repository uses nine **top-level directories** to organize code, configuration, and documentation.
- **Configuration** lives in `.github` and `.claude`, while **framework code** resides in `src`.
- **Environment implementations** are isolated in `envs`, with **tutorials** in `tutorial` and **example scripts** in `examples`.
- **Utility scripts** in `scripts` automate maintenance tasks like documentation synchronization.
- **Tests** in `tests/` provide coverage for both core library functionality and specific environment behaviors.

## Frequently Asked Questions

### What is the purpose of the `src` directory in OpenEnv?

The `src` directory contains the core library code (`openenv_core`), including the client API, MCP server implementations, and Docker helper utilities. This directory houses the framework code that users import when building applications, as defined in [`src/openenv_core/__init__.py`](https://github.com/huggingface/OpenEnv/blob/main/src/openenv_core/__init__.py).

### Where are the runnable environment implementations located?

Environment implementations are stored in the `envs` directory. This folder contains complete, containerized environments such as the Echo demo and wildfire environment, each with their own server configurations and Dockerfiles (e.g., `envs/echo_env/server/Dockerfile`).

### How does the `tutorial` directory differ from `examples`?

The `tutorial` directory contains guided, step-by-step markdown documentation and supporting images designed for onboarding new users (starting with [`tutorial/01-environments.md`](https://github.com/huggingface/OpenEnv/blob/main/tutorial/01-environments.md)). The `examples` directory provides raw, end-to-end usage scripts and notebooks that demonstrate specific implementation patterns without explanatory narrative.

### What files configure CI/CD pipelines in OpenEnv?

CI/CD configurations are stored in the `.github` directory, which contains GitHub-specific workflows, issue templates, and automation hooks. The `scripts` directory complements this by housing utility scripts for deployment and repository maintenance tasks.