Quick start

The main goal of HARP is to be a nearline proxy to remote HTTP APIs, to enhance observability and reliability while lowering development, operations and maintenance costs.

By default, HARP respects HTTP caching headers and will speed up your API calls without further configuration. Of course, a lot of APIs are non-standard or behave strangely, and HARP provides a toolkit for handling those edge cases. Read more about Features Guide and /features/http-proxy.

Installation

The fastest way to run HARP is using UV:

uvx harp-proxy server --example sqlite --example proxy:httpbin

Note

HARP 0.9+ requires Python 3.13. If your system’s default Python version is older, use:

uvx -p 3.13 harp-proxy server --example sqlite --example proxy:httpbin

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

Alternatively, use our Docker image:

docker run -it --rm \
           -p 4000-4100:4000-4100 \
           makersquad/harp-proxy:latest \
           server --endpoint httpbin=4000:http://httpbin.org/

For more installation options:

• installing with UV (recommended)

• installing with docker and docker compose

• installing from a python package

• installing from sources

See Configuration for configuration options.

First glance

Once the container runs, it will serve two different ports from your local host:

• localhost:4000 serves a proxy to httpbin.org (an example external api that we’ll use as our first proxy target)

• localhost:4080 serves a dashboard allowing to observe the network traffic going through the proxy. It is activated and unsecure by default but for production environments you can disable it or add authentication.

Open the dashboard and go to the «Transactions» tab. It should be empty.

Now make a few requests through the proxy:

curl -X GET "http://localhost:4000/get" -H "accept: application/json"
curl -X POST "http://localhost:4000/post" -H "accept: application/json"
curl -X PUT "http://localhost:4000/put" -H "accept: application/json"

If you go back to the dashboard, you’ll now see the transactions.

Congratulations, you just ran your first harp proxy!

Next Steps

Now that you have HARP running:

• Configure your proxy: Configuration - Learn about endpoint configuration, caching, and advanced settings

• Explore features: Features Guide - Discover HARP’s capabilities for API reliability and observability

• Monitor your APIs: /operate/dashboard - Use the dashboard to observe traffic patterns and debug issues