Rammerhead is an open-source web proxy server that rewrites web traffic in real time, letting users browse through your server as if it were their own browser. It is built on top of testcafe-hammerhead, a battle-tested URL and JavaScript rewriting engine originally developed for end-to-end browser testing. Rammerhead extends that engine into a production-ready, self-hostable proxy with sessions, caching, and multi-threading.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/binary-person/rammerhead/llms.txt
Use this file to discover all available pages before exploring further.
Who it’s for
Rammerhead is for developers and system administrators who want a fully configurable proxy they can deploy and control. Unlike hosted proxy services, you run Rammerhead on your own server and have complete control over every aspect of how it operates — from which headers get stripped to how sessions are stored and how JavaScript is cached.How it works
When a user connects to a Rammerhead session, the proxy intercepts all outgoing requests and rewrites URLs and JavaScript on the fly so that the proxied site’s scripts run in the context of your proxy domain. Cookies and localStorage are synchronized within the session, so users stay logged in and their settings persist. Each session is isolated from others and can optionally be restricted to a single IP address.Key features
Persistent sessions
Each user gets a session that stores cookies and localStorage, preserving logins and settings across requests and across devices.
URL shuffling
Per-session character-map encoding obfuscates proxied URLs so the destination site is not immediately visible in the address bar.
JS caching
Rewritten JavaScript is cached to disk or memory using an LRU cache, dramatically reducing CPU usage for repeat visitors.
Multi-threading
Sticky-session cluster support distributes connections across all available CPU cores for production deployments.
HTTP/2 support
Proxy-to-destination connections use HTTP/2 by default, with a configuration option to disable it for compatibility.
Custom upstream proxy
Each session can be configured with its own HTTP proxy server, letting users route their traffic through an additional hop.
Password protection
Session creation can be gated behind a password, preventing unauthorized use of your proxy server.
Flexible header rewriting
Strip reverse-proxy headers from client requests and rewrite or remove response headers like
x-frame-options.Powered by testcafe-hammerhead
Rammerhead uses testcafe-hammerhead as its core rewriting engine. Hammerhead was built to make arbitrary websites run inside a sandboxed iframe for automated testing, which means it handles edge cases — cross-origin iframes, WebSockets, Service Workers, and more — that simpler proxies miss. Rammerhead wraps hammerhead with a session layer, a file-based session store, a JS cache, and a configurable HTTP server.Next steps
Quickstart
Clone the repo, install dependencies, and have a proxy running in minutes.
Configuration
Explore every option in
src/config.js and learn how to override defaults without touching upstream files.