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

> Fork OpenEnv environments from Hugging Face Spaces using the CLI. Duplicate any OpenEnv Space to your account with custom hardware, env vars, and privacy settings.

- Repository: [Hugging Face/OpenEnv](https://github.com/huggingface/OpenEnv)
- Tags: how-to-guide
- Published: 2026-06-15

---

**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)](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:

```bash

# 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`](https://github.com/huggingface/OpenEnv/blob/main/openenv.yaml), Dockerfile, and source code. Navigate to your local clone and use standard OpenEnv commands:

```bash
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)](https://github.com/huggingface/OpenEnv/blob/main/tutorial/02-deployment.md). This documentation explains the three required artifacts: [`pyproject.toml`](https://github.com/huggingface/OpenEnv/blob/main/pyproject.toml), a Docker-based server, and the [`openenv.yaml`](https://github.com/huggingface/OpenEnv/blob/main/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`](https://github.com/huggingface/OpenEnv/blob/main/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.