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 runs as a Node.js server. You clone the repository, install dependencies, build the client scripts, and start the server. The whole process takes a few minutes on any machine with Node.js v16 or later installed.
1

Check prerequisites

Rammerhead requires Node.js v16 or later. Verify your version before continuing:
node --version
If your version is below v16, update Node.js from nodejs.org before proceeding.
2

Clone the repository and install dependencies

Clone the Rammerhead repository and install its dependencies:
git clone https://github.com/binary-person/rammerhead.git
cd rammerhead
npm install
The preinstall script runs npm-force-resolutions to pin the tmp dependency to a stable version. This is normal and expected.
3

Build the client scripts

Rammerhead injects client-side scripts into proxied pages. You must build these before starting the server:
npm run build
This produces minified versions of the hammerhead client script that get served to browsers.
4

Configure the proxy

Open src/config.js and adjust the settings for your environment. The two most important options to review before your first run are:
// src/config.js (excerpt)
bindingAddress: '127.0.0.1',
port: 8080,

// enforce a password for creating new sessions. set to null to disable
password: 'sharkie4life',
The default password is sharkie4life. Change it to something unique before exposing the proxy on a public network, or set password: null to disable password protection entirely.
To keep your customizations separate from upstream code — so git pull never creates merge conflicts — create a config.js file in the project root (not inside src/). Rammerhead automatically merges it over the defaults at the end of src/config.js:
// config.js (project root)
module.exports = {
    port: 9000,
    password: 'my-secret-password',
};
5

Start the proxy server

Start Rammerhead with:
node src/server.js
You can also use the start npm script:
npm start
When the server is ready, you will see a log line like:
[2024-01-01T00:00:00.000Z] [INFO] Rammerhead proxy is listening on http://127.0.0.1:8080
On multi-core machines with workers enabled, the master process logs its load-balancer status instead:
[2024-01-01T00:00:00.000Z] [INFO] {"port":8080,"crossPort":8081,"master":true}
[2024-01-01T00:00:00.000Z] [INFO] Rammerhead proxy load balancer is listening on http://127.0.0.1:8080

​
Access a URL through the proxy

Rammerhead uses a session-based flow. You first create a session, then route traffic through it. Step 1: Create a session Send a GET request to /newsession, passing your password in the pwd query parameter: 
curl "http://127.0.0.1:8080/newsession?pwd=sharkie4life"
The server responds with a session ID: 
a1b2c3d4-e5f6-7890-abcd-ef1234567890
Step 2: Browse through the session Prepend the session ID to the URL you want to proxy. The format is: 
http://<your-host>:<port>/<session-id>/<destination-url>
For example, to proxy https://example.com through a local server: 
http://127.0.0.1:8080/a1b2c3d4-e5f6-7890-abcd-ef1234567890/https://example.com/
Open that URL in a browser and Rammerhead will fetch, rewrite, and serve the destination site.

​
Check if a password is required

Your client application can discover at runtime whether the server requires a password: 
curl "http://127.0.0.1:8080/needpassword"
# returns "true" or "false"

​
Next steps

Configuration reference

Every option in src/config.js documented with types, defaults, and examples.

Sessions

Learn how sessions store cookies and localStorage, and how to manage them.

Build docs developers (and LLMs) love

Get started for freeTalk to us