UV & UVX (Recommended)

The fastest way to install and run HARP is using UV, a fast Python package manager.

Install UV

Install UV on your system:

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

For other installation methods, see the UV installation guide.

Quick Start with UVX

The fastest way to try HARP:

# Run HARP directly (UV will automatically install Python 3.13 if needed)
uvx harp-proxy --help

# Start a server with example configuration
uvx harp-proxy server --example sqlite --example proxy:httpbin

This will start the proxy with SQLite storage and a httpbin endpoint. The dashboard will be available at http://localhost:4080.

Note

Python 3.13 Required

HARP 0.9+ requires Python 3.13. If your system’s default Python version is older, you can explicitly specify the Python version:

# Explicitly use Python 3.13 (UV will manage the installation)
uvx -p 3.13 harp-proxy --help
uvx -p 3.13 harp-proxy server --example sqlite --example proxy:httpbin

UV will automatically download and manage the correct Python version for you.

Test Your Proxy

Send some requests through your proxy:

# Send requests through the proxy
curl "http://localhost:4000/get"
curl "http://localhost:4000/json"

# View results in the dashboard
open http://localhost:4080

Local Development

For development work, clone the repository and use UV:

# Clone the repository
git clone https://github.com/msqd/harp.git
cd harp

# Install dependencies
uv sync

# Run HARP
uv run harp-proxy server --example sqlite --example proxy:httpbin

Common Commands

# One-time execution (no install needed)
uvx harp-proxy server --help

# Run from local project
uv run harp-proxy server
uv run harp-proxy server

# Install dependencies
uv sync

Next Steps

Now that you have HARP running:

1. Learn the basics: Quick start

2. Configure your proxy: Configuration

3. Explore features: Features Guide