Implementation:Helicone Helicone Mitmproxy Linux
| Knowledge Sources | |
|---|---|
| Domains | Proxy, Developer Tools, Networking |
| Last Updated | 2026-02-14 06:32 GMT |
Overview
A Linux shell script that sets up a mitmproxy-based reverse proxy for transparently intercepting OpenAI API calls and routing them through Helicone's proxy.
Description
The mitmproxy.sh script automates the full lifecycle of a local reverse proxy on Linux systems. When started, it installs mitmproxy and related packages via apt, modifies /etc/hosts to redirect api.openai.com to localhost, generates a Python mitmproxy addon script that injects Helicone-Auth headers and custom properties from a JSON file (~/.helicone/custom_properties.json), starts mitmweb as a reverse proxy targeting oai.helicone.ai:443, installs the mitmproxy CA certificate system-wide, and runs endpoint validation tests.
The Python addon supports reading the API key from either the HELICONE_API_KEY environment variable or ~/.helicone/api_key file, respects HELICONE_CACHE_ENABLED, and reads custom properties from both environment variables prefixed with HELICONE_PROPERTY_ and the JSON properties file using a file-based locking mechanism.
The script provides three commands: start (installs, configures, starts proxy, and runs tests), stop (kills proxy and cleans up hosts file), and tail (follows proxy logs).
Usage
Use this script on Linux systems to intercept OpenAI API calls and route them through Helicone without modifying application code. Useful for local development and testing of Helicone integration.
Code Reference
Source Location
- Repository: Helicone
- File: mitmproxy.sh
Signature
# Shell functions
test_endpoint() # Validates the proxy setup with test requests
create_files() # Creates ~/.helicone directory structure
start_proxy() # Installs packages, configures hosts, starts mitmweb
stop_proxy() # Kills proxy process, cleans up /etc/hosts
tail_logs() # Tails ~/.helicone/mitmproxy.log
# Commands: start | stop | tail
Import
# Run directly from GitHub
bash -c "$(curl -fsSL https://raw.githubusercontent.com/Helicone/helicone/main/mitmproxy.sh)" -s start
# Or clone and run locally
bash mitmproxy.sh start
bash mitmproxy.sh stop
bash mitmproxy.sh tail
I/O Contract
| Command | Action | Side Effects |
|---|---|---|
start
|
Install packages, start reverse proxy, run tests | Modifies /etc/hosts, installs CA cert, starts background process
|
stop
|
Kill proxy process and clean up | Removes /etc/hosts entry, kills mitmweb process
|
tail
|
Follow proxy logs | None (read-only) |
| File Path | Purpose |
|---|---|
~/.helicone/proxy_pid
|
Stores the PID of the running mitmweb process |
~/.helicone/mitmproxy.log
|
Proxy output and debug logs |
~/.helicone/api_key
|
Helicone API key (plain text) |
~/.helicone/custom_properties.json
|
JSON file of custom Helicone properties to inject as headers |
~/.helicone/proxy_dir/add_headers.py
|
Generated Python addon for mitmproxy header injection |
| Environment Variable | Purpose |
|---|---|
HELICONE_API_KEY
|
Helicone authentication API key |
HELICONE_CACHE_ENABLED
|
Set to "true" to enable Helicone caching header |
HELICONE_PROPERTY_*
|
Custom properties injected as Helicone-Property-* headers
|
Usage Examples
# Start the proxy (installs dependencies, configures, and tests)
export HELICONE_API_KEY="sk-helicone-..."
bash mitmproxy.sh start
# In another terminal, tail the logs
bash mitmproxy.sh tail
# Stop and clean up
bash mitmproxy.sh stop
# After starting, any OpenAI SDK call is transparently intercepted:
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
python3 -c "
import openai
client = openai.OpenAI()
response = client.chat.completions.create(model='gpt-4', messages=[{'role': 'user', 'content': 'Hello'}])
print(response)
"