Implementation:Helicone Helicone Mitmproxy Mac
| Knowledge Sources | |
|---|---|
| Domains | Proxy, Developer Tools, Networking |
| Last Updated | 2026-02-14 06:32 GMT |
Overview
A macOS 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_mac.sh script provides the macOS-specific variant of the Helicone proxy interception tool. It uses Homebrew to install mitmproxy and curl, modifies /etc/hosts to redirect api.openai.com to localhost, generates a Python mitmproxy addon that injects Helicone-Auth and Helicone-Cache-Enabled headers, starts mitmweb as a reverse proxy targeting oai.helicone.ai:443 on port 443, and adds the mitmproxy CA certificate to the macOS System Keychain via the security command.
The script includes prominent security warnings and requires explicit user confirmation before each action (start, stop, tail). It also verifies that brew, curl, and sudo are available before proceeding. On stop, it removes the mitmproxy certificate from the System Keychain using its SHA-1 fingerprint and cleans the /etc/hosts entry.
The API key is read from either the HELICONE_API_KEY environment variable or ~/.helicone/api_key file. Cache behavior is controlled by the HELICONE_CACHE_ENABLED environment variable.
Usage
Use this script on macOS systems to intercept OpenAI API calls and route them through Helicone without modifying application code. Useful for local development and testing.
Code Reference
Source Location
- Repository: Helicone
- File: mitmproxy_mac.sh
Signature
# Shell functions
setup_proxy_environment() # Creates ~/.helicone directory structure
start_proxy() # Installs via Homebrew, configures hosts, starts mitmweb
stop_proxy() # Kills proxy, cleans /etc/hosts, removes cert from Keychain
tail_logs() # Tails ~/.helicone/mitmproxy.log
# Commands: start | stop | tail
Import
# Clone and run locally
bash mitmproxy_mac.sh start
bash mitmproxy_mac.sh stop
bash mitmproxy_mac.sh tail
I/O Contract
| Command | Action | Side Effects |
|---|---|---|
start
|
Install via Homebrew, start reverse proxy, install CA cert | Modifies /etc/hosts, adds cert to System Keychain, starts background process
|
stop
|
Kill proxy, clean up hosts and certificate | Removes /etc/hosts entry, removes cert from System Keychain, kills mitmweb
|
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/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 |
REQUESTS_CA_BUNDLE
|
Should be set to ~/.mitmproxy/mitmproxy-ca-cert.pem for Python usage
|
Usage Examples
# Start the proxy on macOS (will prompt for confirmation)
export HELICONE_API_KEY="sk-helicone-..."
bash mitmproxy_mac.sh start
# After proxy starts, set the CA bundle for Python
export REQUESTS_CA_BUNDLE=~/.mitmproxy/mitmproxy-ca-cert.pem
# Tail the logs
bash mitmproxy_mac.sh tail
# Stop and clean up (removes cert from Keychain)
bash mitmproxy_mac.sh stop