Skip to content

Contributing Environments to the Hugging Face Hub

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.

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:

Authenticate with the Hub:

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, publishing it to a Hugging Face Space is a single command.

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

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

# 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:

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:

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:

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

# 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