prime env push

​

Overview

​

Usage

prime env push <env> [OPTIONS]

​

Arguments

​

Options

​

Prerequisites

​

Authentication

prime login

​

Environment Structure

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

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

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

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

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

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

​

Version Management

[project]
version = "0.1.0"

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

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

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

​

Metadata and Tags

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

• 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

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"
   }
   

​

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

prime login

​

Missing pyproject.toml

Error: No pyproject.toml found in environment directory

​

Build Failed (OpenEnv)

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

• 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

​

Missing .build.json (OpenEnv)

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

uv run vf-build my-env

​

Updating Published Environments

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
   

prime env install owner/[email protected]

​

Next Steps

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]