Skip to main content

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.

Rammerhead is a self-hostable web proxy built on top of testcafe-hammerhead. It lets you deploy a fully configurable proxy server that works across a wide range of websites, with support for persistent sessions that preserve cookies and localStorage — even across devices.

Quickstart

Clone the repo, install dependencies, and have a proxy running in minutes

Configuration

Customize ports, SSL, sessions, caching, password protection, and more

Core Concepts

Understand sessions, URL shuffling, and the JS caching system

API Reference

Explore the full public API — classes, utilities, and HTTP endpoints

​
What Rammerhead does

Rammerhead proxies web traffic through your server, rewriting all URLs and JavaScript on the fly so that the original site’s scripts run in the context of your proxy domain. Each user gets an isolated session that tracks cookies, localStorage, and optionally a custom upstream proxy.

Session management

Persistent sessions with cookie and localStorage sync across devices

URL shuffling

Per-session character-map encoding to obfuscate proxied URLs

JS caching

Disk and memory caches for rewritten JavaScript to reduce CPU load

Multi-threading

Sticky-session cluster support for multi-core production deployments

​
Getting started

1

Clone and install

Clone the repository and install dependencies with Node.js v16 or later.
git clone https://github.com/binary-person/rammerhead.git
cd rammerhead
npm install
2

Build client scripts

Build the minified client-side hammerhead scripts that get injected into proxied pages.
npm run build
3

Configure

Edit src/config.js to set your binding address, port, password, and other options. For persistent customizations that survive upstream updates, create a config.js in the project root to override defaults.
4

Start the proxy

Launch the proxy server. By default it listens on http://127.0.0.1:8080.
node src/server.js
The default password for creating new sessions is sharkie4life. Change the password field in src/config.js before deploying publicly, or set it to null to disable password protection.

​
Use as an npm package

Rammerhead is also available as an npm package for embedding the proxy into your own Node.js application: 
npm install rammerhead

const { RammerheadProxy, RammerheadSessionFileCache } = require('rammerhead');

const proxy = new RammerheadProxy({ port: 8080, crossDomainPort: 8081 });
const sessionStore = new RammerheadSessionFileCache({ saveDirectory: './sessions' });
sessionStore.attachToProxy(proxy);
See the npm integration guide for a complete walkthrough.

Build docs developers (and LLMs) love

Get started for freeTalk to us