prime env push

Publish an environment to the Environments Hub

Overview

The prime env push command publishes an environment to the Environments Hub, 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

prime env push <env> [OPTIONS]

Arguments

env · string · required

Environment ID to publish. This should match the environment directory name.

Example: my-env pushes from ./environments/my_env/

Options

--path · string · default: "./environments"

Base path for environments directory.

Aliases: -p

Prerequisites

Authentication

Log in to the Prime Intellect platform:

prime login

Environment Structure

Your environment must have:

1. Valid pyproject.toml with metadata:

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

   uv run vf-build my-env
   

2. Verify .build.json exists:

   cat environments/my_env/proj/.build.json
   

Examples

Publish a Standard Environment

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

# 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

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:

[project]
version = "0.1.0"

To publish a new version:

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

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

[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:
   {
     "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:

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

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

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):
   uv run vf-build my-env
   
5. Push update:
   prime env push my-env
   

Users can then install the new version:

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