How to Fork OpenEnv Environments from Hugging Face Spaces: Complete CLI Guide

Use the openenv fork CLI command to duplicate any OpenEnv Space to your own Hugging Face account with optional custom hardware, environment variables, and privacy settings.

The OpenEnv project provides a streamlined workflow for copying existing environments directly from Hugging Face Spaces to your personal account. This functionality enables developers to customize pre-built OpenEnv configurations without starting from scratch. The forking capability is implemented in the Hugging Face OpenEnv repository and integrates seamlessly with the Hugging Face Hub API.

Understanding the openenv fork Command Architecture

The fork implementation resides in [src/openenv/cli/commands/fork.py](https://github.com/huggingface/OpenEnv/blob/main/src/openenv/cli/commands/fork.py). This module defines a typer-based CLI command that orchestrates authentication, parameter validation, and Hub API communication.

CLI Registration and Entry Point

The command registers with Typer's application registry in the app = typer.Typer(...) block. When users execute openenv fork, Typer invokes the fork() function with the provided arguments.

Authentication Flow

Before issuing any Hub requests, the helper _ensure_hf_authenticated() validates the user's session by calling huggingface_hub.whoami(). This function handles two response formats (dictionary and object) to extract the authenticated username. If no valid token exists, the CLI prompts the user to run login() from huggingface_hub. Successful authentication displays a status message through the Rich-styled console: [bold green]✓[/bold green] Authenticated as: ….

Parameter Handling and Validation

The command accepts several arguments to customize the fork:

• source_space (required): The owner/space-name identifier of the Space to copy
• --repo-id (optional): Target username/repo-name; defaults to the original name under the authenticated user
• --private: Boolean flag to create a private Space
• --set-env: Repeatable KEY=VALUE pairs for public environment variables
• --set-secret: Repeatable KEY=VALUE pairs for secret variables
• --hardware: Hardware tier specification (defaults to cpu-basic)

The helper _parse_key_value() validates the KEY=VALUE format for environment variables and secrets, returning cleaned tuples for API consumption.

Step-by-Step Forking Process

Building the API Request

The command constructs a dup_kwargs dictionary containing only user-provided arguments. Environment variables and secrets undergo transformation via list comprehensions that call _parse_key_value(), converting them to the Hub API's expected format: [{"key": ..., "value": ...}]. The hardware parameter is always included because the Hub's duplicate_space endpoint requires explicit hardware specification.

Server-Side Duplication

An instance of huggingface_hub.HfApi initializes and calls api.duplicate_space(**dup_kwargs). This method executes the server-side copy operation, applying all specified configurations including variables, secrets, and hardware settings to the new Space.

Result Normalization

The API response varies between a URL string, a RepoUrl object, or any object with a repo_id attribute. The command normalizes these formats to extract a consistent new_repo_id string. Upon success, the CLI prints a banner displaying the public URL of the newly created Space.

Practical Usage Examples

Execute these commands to fork OpenEnv environments with different configurations:

# Basic fork – keeps the original Space name under your account

openenv fork huggingface/openenv-demo

# Fork as a private Space

openenv fork huggingface/openenv-demo --private

# Fork with a custom repository name

openenv fork huggingface/openenv-demo --repo-id myuser/my-fork

# Fork while setting a public environment variable and a secret

openenv fork huggingface/openenv-demo \
    --set-env MODEL_ID=facebook/opt-125m \
    --set-secret HF_TOKEN=hf_xxx

# Request specific hardware for the new Space (e.g. a GPU)

openenv fork huggingface/openenv-demo --hardware t4-medium

Each execution produces output similar to:

[bold green]✓[/bold green] Authenticated as: myuser
[bold cyan]Forking Space huggingface/openenv-demo...[/bold cyan]
[bold green]✓[/bold green] Space forked successfully
Space URL: https://huggingface.co/spaces/myuser/openenv-demo

Working with Your Forked Environment

Once forked, the Space contains a complete OpenEnv repository including openenv.yaml, Dockerfile, and source code. Navigate to your local clone and use standard OpenEnv commands:

cd path/to/your/forked-repo
openenv serve   # starts the HTTP server inside the container

openenv push    # pushes the environment back to the Space (if you made changes)

For additional context on how OpenEnv structures Spaces for deployment, reference [tutorial/02-deployment.md](https://github.com/huggingface/OpenEnv/blob/main/tutorial/02-deployment.md). This documentation explains the three required artifacts: pyproject.toml, a Docker-based server, and the openenv.yaml manifest.

Summary

• openenv fork duplicates existing OpenEnv Spaces from Hugging Face to your account via a single CLI command
• The implementation in src/openenv/cli/commands/fork.py handles authentication through huggingface_hub.whoami() and parameter validation via _parse_key_value()
• Support for --set-env and --set-secret enables immediate configuration of environment variables during the fork process
• Hardware specification (defaulting to cpu-basic) is mandatory for the underlying duplicate_space() API call
• Forked environments maintain full OpenEnv compatibility, supporting openenv serve and openenv push operations immediately after creation

Frequently Asked Questions

How do I fork an OpenEnv environment to a different repository name?

Use the --repo-id parameter with your desired username/repo-name format. If omitted, the fork retains the original Space name under your authenticated Hugging Face account.

Can I change the hardware configuration when forking an OpenEnv Space?

Yes. Specify the --hardware flag with your desired tier (e.g., t4-medium, cpu-basic). The command defaults to cpu-basic if no hardware option is provided, as the Hub API requires explicit hardware specification for all duplicated Spaces.

What authentication is required to fork OpenEnv environments?

You must have an active Hugging Face Hub authentication token. The CLI automatically checks your status using huggingface_hub.whoami() and prompts you to run login() if no valid credentials exist. The fork operation requires write permissions to create new Spaces under your account.

Are environment variables preserved when forking OpenEnv Spaces?

No, original environment variables are not automatically copied. You must explicitly set them using --set-env for public variables or --set-secret for sensitive values during the fork command. These parameters accept KEY=VALUE pairs that _parse_key_value() validates before API submission.

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