Local Installation

This guide walks you through setting up the OpenModels registry and documentation site on your local machine for development and contributions.

Prerequisites

Make sure you have the following installed:

Verify your setup:

python3 --version # 3.11 or higher
node --version    # v22.x or higher
git --version     # 2.30 or higher

Clone the Repository

git clone https://github.com/openmodelsrun/openmodels.git
cd openmodels

Set Up the Registry

Install Python dependencies and run the validation script to verify everything works:

pip install -r requirements.txt
python validate_registry.py

If validation passes with no errors, the registry is set up correctly. You can now add or edit models, providers, and mappings.

Run the Docs Site

To run this documentation site locally:

cd docs
 
# Install dependencies
npm install
 
# Start the dev server
npm run dev

The docs site will be available at http://localhost:3040.

Registry Directory Structure

openmodels/
├── models/              # One YAML file per canonical model
├── providers/           # One YAML file per inference provider
├── mappings/            # Provider-model mappings, organized by provider
│   ├── anthropic/
│   ├── openai/
│   └── ...
├── schemas/             # JSON Schema definitions for validation
├── validate_registry.py # Validation script
├── requirements.txt     # Python dependencies
└── VERSION              # Current registry version

Common Tasks

Validate after making changes

After editing or adding YAML files, always run validation:

python validate_registry.py

Build the docs site

To generate a static export of the documentation:

cd docs
npm run build

The output will be in the docs/out/ directory.

Troubleshooting

Python validation fails

If the validation script errors out:

# Ensure you have the right Python version
python3 --version
 
# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

npm install fails

If you encounter dependency resolution issues with the docs site:

cd docs
rm -rf node_modules package-lock.json
npm install

Docs dev server port conflict

If port 3040 is already in use:

npm run dev -- -p 3041

Next Steps

• Quickstart — Query the API to search and compare models
• Adding a Model — Contribute a new model to the registry
• Adding a Provider — Add a new inference provider
• Architecture — Understand how the full system works