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

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 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 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 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 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 – Exposes the public API, including EnvClient, MCP server classes, and utility functions.
• README.md – Provides the project overview, quick-start guide, and high-level architecture summary.
• 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 – The primary onboarding document for new developers.
• 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:

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:

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.

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

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