Important: Please Read This First

This is a work in progress and may include bugs or other issues. If you encounter any problems, please report them.

This tool is NOT intended for production use.

This tool is designed for testing and debugging purposes only.

How It Works

MITM = Man-in-the-Middle Proxy

The proxy operates as a simple HTTP server that listens on a specified port. It is configured to intercept all traffic destined for and reroutes it—with the correct headers and configurations to This enables you to swiftly integrate Helicone and all of its features without having to alter a single line of code.

Potential Use Cases for the MITM Proxy

  • Github Actions
    • Continuous Integration/Continuous Deployment (CI/CD)
    • Testing
    • Debugging
    • Cost savings (utilizing Bucket Cache)
  • Local Development
    • Debugging
    • Testing
    • Cost savings (utilizing Bucket Cache)

Installation (Ubuntu/Debian)

Use this tool only in controlled/testing environments.

We provide a script that will automatically install and configure the proxy for you.

Starting the Proxy

# Configure Cache
export HELICONE_CACHE_ENABLED="true" # Enable caching

# Configure Custom Properties
# Note: There is a lock file that allows you to configure properties dynamically

bash -c "$(curl -fsSL" -s start
echo "sk-<HELICONE_KEY>" > ~/.helicone/api_key # Alternatively, you can export HELICONE_API_KEY to your path before starting the proxy to bypass this step.

export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt # This is required for HTTPS requests to work properly.
# Your python script here...

Stopping the Proxy

bash -c "$(curl -fsSL" -s stop

Viewing Logs

bash -c "$(curl -fsSL" -s tail

Installation (Mac)

We do not recommend installing this on your local machine. Instead, please use a virtual environment or a container. Man-in-the-Middle (MITM) Proxies can pose serious security risks.

To install on a Mac, follow the same instructions as for Ubuntu/Debian, but use the script instead. You can find this script here:

Configuring the Dynamic Helicone Headers

You can configure custom properties using a lock file located at ~/.helicone/custom_properties.json. These properties will be applied to all requests.


To dynamically configure the proxy, you can install our python package.

pip install helicone

Then, use the following code:

from helicone.lock import HeliconeLockManager
HeliconeLockManager.write_custom_property("job_id", "1")
Other Methods:
 - write_custom_property(property_name: str, value: str) // Write a custom property
 - remove_custom_property(property_name: str) // Remove a custom property
 - clear_all_properties() // Clear all properties

This enables you to manipulate properties dynamically, making your workflow more flexible and efficient.