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 ships as an npm package so you can embed the proxy directly into an existing Node.js application instead of running it as a standalone server. This approach is useful when you want to mount the proxy on a custom port, share a listener with an Express app, add your own middleware before requests reach the proxy, or bundle a custom front-end alongside the proxy routes.

​
Install

npm install rammerhead
The package requires Node.js 16 or later. All runtime dependencies — including testcafe-hammerhead, ws, and mime — are bundled.

​
All exports

Everything exported by require('rammerhead') is documented below. You will use RammerheadProxy, RammerheadSessionFileCache, and addStaticFilesToProxy for most embedding scenarios.
ExportDescription
RammerheadProxyThe core proxy class. Wraps testcafe-hammerhead’s Proxy with session routing, pipeline hooks, and WebSocket support.
RammerheadLoggingStructured logger with levels disabled, debug, traffic, info, warn, and error.
RammerheadSessionA single proxy session. Extends hammerhead’s Session with serialization and URL-shuffling.
RammerheadSessionAbstractStoreAbstract base class for custom session stores.
RammerheadSessionMemoryStoreIn-process session store backed by a Map. Suitable for development and low-traffic deployments.
RammerheadSessionFileCacheProduction session store that keeps active sessions in memory and serializes inactive ones to disk.
RammerheadJSAbstractCacheAbstract base for JS rewrite caches.
RammerheadJSFileCacheDisk-backed LRU cache for rewritten JavaScript. Recommended for production.
RammerheadJSMemCacheIn-memory LRU cache for rewritten JavaScript.
StrShufflerURL-shuffling utility used by sessions.
generateIdGenerates a random session ID string.
addStaticFilesToProxyRegisters an entire directory as static GET routes on the proxy.
URLPathURL parsing helper used internally by route handlers.

​
Minimal working example

The four steps below are all you need to get a working proxy server: create the proxy, create a session store, attach the store, and register the default routes.
1

Import and create the proxy

server.js
const {
  RammerheadProxy,
  RammerheadSessionFileCache,
  RammerheadLogging,
  addStaticFilesToProxy
} = require('rammerhead');
const setupRoutes = require('rammerhead/src/server/setupRoutes');
const setupPipeline = require('rammerhead/src/server/setupPipeline');

const logger = new RammerheadLogging({ logLevel: 'info' });

const proxy = new RammerheadProxy({
  logger,
  port: 8080,
  crossDomainPort: 8081,
  bindingAddress: '0.0.0.0'
});
2

Create and attach the session store

server.js
const sessionStore = new RammerheadSessionFileCache({
  saveDirectory: './sessions',
  logger
});

sessionStore.attachToProxy(proxy);
attachToProxy assigns the store to proxy.openSessions so that hammerhead can look up sessions by ID on every request.
3

Register routes and pipeline

server.js
setupPipeline(proxy, sessionStore);
setupRoutes(proxy, sessionStore, logger);
setupRoutes registers the /newsession, /editsession, /deletesession, and /sessionexists HTTP endpoints. setupPipeline adds the IP-restriction and header-stripping middleware.
4

Run the server

node server.js
The proxy is now listening on http://localhost:8080 (main) and http://localhost:8081 (cross-domain).

​
Share a port with an existing Express server

Pass dontListen: true to prevent RammerheadProxy from calling server.listen() itself. Then forward incoming requests from your existing HTTP server to the proxy’s internal handlers.
express-integration.js
const http = require('http');
const express = require('express');
const { RammerheadProxy, RammerheadSessionFileCache } = require('rammerhead');

const app = express();

// Your own routes
app.get('/health', (_req, res) => res.send('ok'));

const proxy = new RammerheadProxy({
  port: 8080,
  crossDomainPort: 8081,
  dontListen: true // do not auto-bind
});

const sessionStore = new RammerheadSessionFileCache({ saveDirectory: './sessions' });
sessionStore.attachToProxy(proxy);

// Create a single HTTP server driven by Express
const server = http.createServer((req, res) => {
  // Delegate proxy traffic to rammerhead's internal handler
  proxy._onRequest(req, res);
});

server.on('upgrade', (req, socket, head) => {
  proxy._onUpgradeRequest(req, socket, head);
});

server.listen(8080, () => {
  console.log('Server listening on http://localhost:8080');
});
The _onRequest and _onUpgradeRequest methods are internal. Routing all traffic through them bypasses Express middleware for proxied requests. Only your own routes handled by app will see Express middleware.

​
Serve a custom UI with addStaticFilesToProxy

addStaticFilesToProxy reads a directory recursively and registers every file as a static GET route. If the directory contains an index.html, it is also served at the root path /. 
const path = require('path');
const { addStaticFilesToProxy } = require('rammerhead');

// Serve everything in ./public at the root of the proxy
addStaticFilesToProxy(proxy, path.join(__dirname, 'public'));

// Or serve files under a sub-path, e.g. /ui/
addStaticFilesToProxy(proxy, path.join(__dirname, 'public'), '/ui/');
The following routes are reserved by hammerhead and will throw if your static directory contains files that would conflict with them: /hammerhead.js, /rammerhead.js, /task.js, /iframe-task.js, /messaging, /transport-worker.js, /worker-hammerhead.js.

​
Configure RammerheadLogging

RammerheadLogging accepts six log levels in ascending order of severity: disabled, debug, traffic, info, warn, error. Passing logLevel: 'debug' enables all output including per-request traffic logs. 
const { RammerheadLogging } = require('rammerhead');

const logger = new RammerheadLogging({
  logLevel: 'debug',
  generatePrefix: (level) => `[${new Date().toISOString()}] [${level.toUpperCase()}] `
});

logger.info('Proxy starting');
logger.debug('Verbose detail');
logger.warn('Something looks off');
logger.error('An error occurred');
You can also change the level after construction by setting logger.logLevel = 'warn'.

​
Version history

The package is published as rammerhead on npm. Recent changes of note:
  • v1.2.64 — WebSocket errors are caught; HTTP/2 is re-enabled by default.
  • v1.2.63 — Added overrideExternalProxySettings for server-level proxy override; updated testcafe-hammerhead from 24.5.18 to 31.6.2.
  • v1.2.5 — Replaced keyv-lru-files with a built-in JS cache implementation (RammerheadJSFileCache, RammerheadJSMemCache, RammerheadJSAbstractCache).
  • v1.2.2 — Introduced disk-cache option for processed JS files, fixing high server memory usage in multi-worker setups.
  • v1.2.0 — Added multi-threading support via sticky-session-custom.
  • v1.0.4 — Added support for the DEVELOPMENT environment variable and the addStaticFilesToProxy utility.
See the full CHANGELOG on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us