> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/primeintellect-ai/verifiers/llms.txt
> Use this file to discover all available pages before exploring further.

# prime env push

> Publish an environment to the Environments Hub

## Overview

The `prime env push` command publishes an environment to the [Environments Hub](https://app.primeintellect.ai/dashboard/environments), making it available for others to discover, install, and use.

For OpenEnv-based environments, this command also builds and registers the Docker image using `prime images push`.

## Usage

```bash theme={null}
prime env push <env> [OPTIONS]
```

## Arguments

<ParamField path="env" type="string" required>
  Environment ID to publish. This should match the environment directory name.

  Example: `my-env` pushes from `./environments/my_env/`
</ParamField>

## Options

<ParamField path="--path" type="string" default="./environments">
  Base path for environments directory.

  Aliases: `-p`
</ParamField>

## Prerequisites

### Authentication

Log in to the Prime Intellect platform:

```bash theme={null}
prime login
```

### Environment Structure

Your environment must have:

1. **Valid `pyproject.toml`** with metadata:
   ```toml theme={null}
   [project]
   name = "my-env"
   description = "Environment description"
   version = "0.1.0"
   tags = ["category", "train", "eval"]
   ```

2. **Implementation file** with `load_environment()` function

3. **README.md** with documentation

### OpenEnv Environments

For OpenEnv environments (with `proj/` directory), you must also:

1. **Build the Docker image first:**
   ```bash theme={null}
   uv run vf-build my-env
   ```

2. **Verify `.build.json` exists:**
   ```bash theme={null}
   cat environments/my_env/proj/.build.json
   ```

## Examples

### Publish a Standard Environment

```bash theme={null}
prime env push my-env
```

**Output:**

```
Pushing environment my-env to Environments Hub...
Uploading package...
Successfully published my-env v0.1.0
View at: https://app.primeintellect.ai/dashboard/environments/your-username/my-env
```

### Publish an OpenEnv Environment

```bash theme={null}
# First, build the Docker image
uv run vf-build my-env

# Then push the environment
prime env push my-env
```

**Output:**

```
Building image for 'my-env' with context='./environments/my_env/proj' dockerfile='server/Dockerfile' image='my-env:latest'
Image build completed with status=ready
Wrote ./environments/my_env/proj/.build.json
Pushing environment my-env to Environments Hub...
Successfully published my-env v0.1.0
```

### Custom Path

```bash theme={null}
prime env push my-env --path ~/my-projects/environments
```

## What Gets Published

The command packages and uploads:

* **Environment code** (Python files)
* **pyproject.toml** (metadata and dependencies)
* **README.md** (documentation)
* **Additional files** specified in `tool.hatch.build.include`

For OpenEnv environments, it also includes:

* **proj/** directory with OpenEnv project files
* **proj/.build.json** with Docker image reference

## Version Management

The version is read from `pyproject.toml`:

```toml theme={null}
[project]
version = "0.1.0"
```

To publish a new version:

1. Update the version number in `pyproject.toml`
2. Run `prime env push` again

```bash theme={null}
# Update version
sed -i 's/version = "0.1.0"/version = "0.1.1"/' environments/my_env/pyproject.toml

# Push new version
prime env push my-env
```

## Visibility and Access

By default, environments are:

* **Public** - anyone can view and install
* **Listed** - appears in Hub search results

To make an environment private:

1. Navigate to the environment page on the Hub
2. Click "Settings"
3. Change visibility to "Private"

Private environments can only be installed by authorized users using `prime env pull`.

## Metadata and Tags

Configure environment metadata in `pyproject.toml`:

```toml theme={null}
[project]
name = "my-env"
description = "Clear, concise description"
tags = ["math", "reasoning", "train", "eval"]
version = "0.1.0"

[project.urls]
Homepage = "https://github.com/username/my-env"
Repository = "https://github.com/username/my-env"
```

**Recommended tags:**

* **Domain**: `math`, `coding`, `reasoning`, `tool-use`, `web`, `games`
* **Use case**: `train`, `eval`, `benchmark`
* **Difficulty**: `easy`, `medium`, `hard`
* **Format**: `single-turn`, `multi-turn`, `tool-env`

## OpenEnv Image Building

For OpenEnv environments, the `vf-build` command:

1. **Detects the contract** (gym vs. mcp) from `server/app.py`
2. **Builds the Docker image** using `prime images push`
3. **Waits for build completion** (up to 20 minutes)
4. **Writes `.build.json`** with image reference and metadata:
   ```json theme={null}
   {
     "schema_version": 1,
     "environment_id": "my-env",
     "image": "registry.primeintellect.ai/username/my-env:latest",
     "port": 8000,
     "app": "server.app:app",
     "contract": "gym",
     "start_command": "sh -lc \"cd /app/env && /app/.venv/bin/uvicorn server.app:app --host 0.0.0.0 --port 8000\"",
     "image_status": "ready"
   }
   ```

This metadata is included when pushing to the Hub.

## Testing Before Publishing

Always test your environment locally before publishing:

```bash theme={null}
# Install locally
prime env install my-env

# Run evaluation
prime eval run my-env -m gpt-4.1-mini -n 10

# Check results
prime eval tui

# For OpenEnv: test the image
uv run vf-build my-env
prime eval run my-env -m gpt-4.1-mini -n 1
```

## Troubleshooting

### Not Logged In

```
Error: Not authenticated. Run 'prime login' first.
```

**Solution:**

```bash theme={null}
prime login
```

### Missing pyproject.toml

```
Error: No pyproject.toml found in environment directory
```

**Solution:** Ensure your environment has a valid `pyproject.toml`.

### Build Failed (OpenEnv)

```
Image build did not complete successfully (status=failed).
```

**Solution:**

* Check Docker image build logs: `prime images list`
* Verify Dockerfile is valid
* Test Docker build locally:
  ```bash theme={null}
  cd environments/my_env/proj
  docker build -f server/Dockerfile -t my-env:test .
  ```

### Invalid Version

```
Error: Version 0.1.0 already exists
```

**Solution:** Increment the version number in `pyproject.toml`.

### Missing .build.json (OpenEnv)

```
Error: OpenEnv environment requires .build.json. Run 'vf-build' first.
```

**Solution:**

```bash theme={null}
uv run vf-build my-env
```

## Updating Published Environments

To update an environment on the Hub:

1. **Make changes** to your local environment code
2. **Update version** in `pyproject.toml`
3. **Test changes** locally
4. **Rebuild image** (if OpenEnv):
   ```bash theme={null}
   uv run vf-build my-env
   ```
5. **Push update:**
   ```bash theme={null}
   prime env push my-env
   ```

Users can then install the new version:

```bash theme={null}
prime env install owner/my-env@0.1.1
```

## Next Steps

After publishing:

1. **Share your environment** - post the Hub URL
2. **Test installation** from Hub:
   ```bash theme={null}
   prime env install your-username/my-env
   ```
3. **Monitor usage** on the Hub dashboard
4. **Iterate and improve** based on feedback

## Best Practices

* **Write clear documentation** in README.md
* **Use semantic versioning** (MAJOR.MINOR.PATCH)
* **Add comprehensive tags** for discoverability
* **Test thoroughly** before publishing
* **Include examples** in the README
* **Document environment arguments** and their defaults
* **Specify evaluation defaults** in `[tool.verifiers.eval]`