docs/source/getting_started/contributing-envs.md

# Contributing to Hugging Face

**Part 5 of 5** in the OpenEnv Getting Started Series

OpenEnv environments are designed to be shared. The `openenv` CLI provides first-class
commands for publishing, forking, and contributing to environments hosted as
[Hugging Face Spaces](https://huggingface.co/spaces).

Envs are deployed as Hugging Face Spaces which are; Git repositories, Docker images, Python packages, and Gradio apps

This guide covers three workflows:

1. **Push** a new environment you built to the Hub.
2. **Fork** someone else's environment to your Hugging Face account to make changes.
3. **Download** an environment, make changes, and open a Pull Request.

## Prerequisites

Before you start, make sure you have:

- Python 3.11+ and [`uv`](https://github.com/astral-sh/uv) installed
- The OpenEnv CLI: `pip install openenv-core[cli]` (or install from source)
- A [Hugging Face account](https://huggingface.co/join) with a [write token](https://huggingface.co/settings/tokens)

Authenticate with the Hub:

```bash

hf auth login

```

The `openenv` CLI will also prompt you to log in automatically if you haven't already.

## 1. Push a New Environment to the Hub

Once you've [built an environment](environment-builder.md), publishing it to a Hugging Face Space is a single command.

```bash

# Push the env at '.' to the hub with config in env.yaml

openenv push



# Push the env to a specific repo

openenv push --repo-id my-org/my-custom-env



# Push the env as private

openenv push --private



# Push the env at 'path/to/my_env' to the hub with config in openenv.yaml

openenv push path/to/my_env

```

That's it. The CLI validates your environment, stages the files, adds the Hugging Face Space frontmatter, enables the web interface, and uploads everything. Your environment will be live at
`https://huggingface.co/spaces/<your-username>/my_env`.

```{warning}

If you are getting errors on deployment, it is likely because the environment structure is not valid. Run `openenv validate --verbose` to see the errors. This checks for the required files (`openenv.yaml`, `pyproject.toml`, `server/app.py`) and validates the Dockerfile and entry points.

```

## 2. Fork Someone Else's Environment

Forking creates a copy of a Hugging Face Space under your own account. This is
the fastest way to start experimenting with an existing environment.

```bash

# Fork the openenv/wordle-env environment to your account

openenv fork owner/space-name

```

This duplicates the Space to `<your-username>/space-name` using the same name and config. To make changes, you can fork to a specific repo name, set environment variables and secrets, and request hardware.

```bash

# Fork to a specific repo name

openenv fork openenv/wordle-env --repo-id my-username/my-wordle



# Fork the openenv/coding-env environment to your account with environment variables and secrets

openenv fork openenv/coding-env \

  --set-env MODEL_ID=meta-llama/Llama-3-8B \

  --set-secret HF_TOKEN=hf_xxxxxxxxxxxxx



# Fork the openenv/coding-env environment to your account with a GPU

openenv fork openenv/coding-env --hardware t4-medium

```


Once forked, you have a fully independent copy. You can:

- Visit it at `https://huggingface.co/spaces/<your-username>/<space-name>`
- Clone it locally to make changes (see the next section)
- Push updates with `openenv push`

## 3. Pull, Modify, and Open a Pull Request

The contribution workflow lets you improve an existing environment and submit
your changes for review, just like a GitHub Pull Request but on the Hugging
Face Hub.

### 3.1 Download the Space locally

Hugging Face Spaces are Git repositories. Download the one you want to contribute to:

```bash

hf download owner/space-name --local-dir space-name --repo-type space

cd space-name

```

```{warning}

If the Space is private and you have access, make sure you're logged in with

`hf auth login` first.

```

#### 3.2 Make your changes
Edit the environment files as needed.

```{tip}

You can test your changes locally before submitting:



    # Run the server locally

    cd space-name

    uvicorn server.app:app --host 0.0.0.0 --port 8000



    # Or build and run in Docker

    openenv build

    openenv validate --verbose

```

#### 3.3 Push your changes as a Pull Request

From the cloned directory, use `openenv push` with the `--create-pr` flag:

```bash

openenv push --repo-id owner/space-name --create-pr

```

This uploads your modified files and opens a Pull Request on the Hub. The environment owner can review your changes, leave comments, and merge them.

```{warning}

When using `--create-pr`, the CLI uploads your changes to a new branch and

opens a PR on the **original** Space. You do not need to create the Space

yourself.

```

### Alternative: Fork-then-PR workflow

If you prefer to develop against your own fork first, you can combine the fork
and PR workflows:

```bash

# 1. Fork the environment to your account

openenv fork owner/space-name --repo-id my-username/space-name



# 2. Download the forked environment to your local directory

hf download my-username/space-name --local-dir space-name --repo-type space

cd space-name



# 3. Make and test your changes

#    ... edit files, run locally, validate ...



# 4. Push the changes back to your fork

openenv push



# 5. Submit a PR to the original Space

openenv push --repo-id owner/space-name --create-pr

```

## End-to-End Example

Here's a complete example: forking the Echo environment, adding a feature, and
submitting a PR.

```bash

# Fork the echo environment

openenv fork openenv/echo-env --repo-id my-username/echo-env-improved



# Clone your fork

git clone https://huggingface.co/spaces/my-username/echo-env-improved

cd echo-env-improved



# Make changes (e.g., add a timestamp to observations)

# ... edit server/echo_environment.py ...



# Test locally

openenv validate --verbose



# Push your improvement as a PR to the original

openenv push --repo-id openenv/echo-env --create-pr

```

## Next Steps

- [Build your own environment from scratch](environment-builder.md)
- [Customize the web UI](../customizing-web-ui.md)
- [Browse available environments](../environments.md)
- [End-to-end tutorial](../tutorials/openenv-tutorial.md)