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.

Every user of a Rammerhead proxy interacts through a session. A session stores cookies, localStorage, the URL-shuffling dictionary, and optional upstream proxy settings. Sessions can be managed through the built-in HTTP endpoints exposed by setupRoutes, or programmatically through the session store object in your server code.

​
The session store API

Both RammerheadSessionFileCache and RammerheadSessionMemoryStore implement the same interface, defined by RammerheadSessionAbstractStore. You can also implement this interface yourself for a custom backend (Redis, a database, etc.).
MethodSignatureDescription
keys() => string[]Returns all session IDs currently in the store.
has(id: string) => booleanReturns true if the session exists.
get(id: string, updateActiveTimestamp?: boolean) => RammerheadSession | undefinedRetrieves a session. Updating the timestamp (default true) prevents the session from being pruned as stale.
add(id: string) => RammerheadSessionCreates a new session with the given ID. Throws if the ID already exists.
delete(id: string) => booleanDeletes a session. Returns true if a deletion occurred.
addSerializedSession(id: string, serialized: string) => voidImports a session from a JSON string produced by session.serializeSession().
attachToProxy(proxy: RammerheadProxy) => voidAssigns the store to proxy.openSessions so the proxy can look up sessions by ID.
close() => voidFlushes any in-memory sessions to disk (file cache only). Call this before your process exits.

​
HTTP endpoints

The setupRoutes function registers these endpoints on the proxy. All of them are plain GET requests for simplicity, even the ones that modify state.

​
Create a session

GET /newsession?pwd=<password>
Returns the new session ID as plain text. If password is set in your config, the pwd parameter must match or the request is rejected with 403. 
curl "http://localhost:8080/newsession?pwd=sharkie4life"
# Response: a1b2c3d4e5f6...
The session is created with restrictIP set to the requesting IP, so subsequent proxy requests from a different IP will be blocked if restrictSessionToIP is enabled in config.

​
Edit a session

GET /editsession?id=<sessionId>&httpProxy=<proxyUrl>&enableShuffling=1|0
ParameterDescription
idThe session ID to modify. Required.
httpProxySet an upstream HTTP proxy for this session (e.g., http://user:pass@host:port). Omit the parameter to clear.
enableShuffling1 to enable URL shuffling (generates a new dictionary if none exists), 0 to disable.
# Set an upstream proxy
curl "http://localhost:8080/editsession?id=SESSION_ID&httpProxy=http://proxy.example.com:3128"

# Disable URL shuffling
curl "http://localhost:8080/editsession?id=SESSION_ID&enableShuffling=0"

​
Delete a session

GET /deletesession?id=<sessionId>
Removes the session from the store. Returns Success or not found. 
curl "http://localhost:8080/deletesession?id=SESSION_ID"

​
Check session existence

GET /sessionexists?id=<sessionId>
Returns exists or not found. Does not require a password. 
curl "http://localhost:8080/sessionexists?id=SESSION_ID"
# Response: exists

​
Programmatic session management

​
Creating a session

Use sessionStore.add(id) to create a session with a specific ID, or generate one first with generateId(). 
const { generateId, RammerheadSessionFileCache } = require('rammerhead');

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

// Generate a random ID and create the session
const id = generateId();
const session = sessionStore.add(id);

console.log('Created session:', id);

​
Restricting a session to an IP

After creating a session, set session.data.restrictIP to an IP address string. When restrictSessionToIP is enabled in the pipeline (setupPipeline or your own handler), proxy requests from any other IP will be rejected with 403. 
const session = sessionStore.add(generateId());
session.data.restrictIP = '203.0.113.42';

​
Setting an upstream proxy

Assign an externalProxySettings object to route the session’s traffic through an additional HTTP proxy. The host field must include host and port. 
const session = sessionStore.get(id);
session.externalProxySettings = {
  host: 'proxy.example.com:3128',
  hostname: 'proxy.example.com',
  port: '3128',
  proxyAuth: 'user:password' // optional
};
To clear the upstream proxy, set session.externalProxySettings = null.

​
Session serialization and deserialization

RammerheadSession.serializeSession() returns a JSON string containing the session’s data object and cookie jar. You can store this string anywhere and restore it later with RammerheadSession.DeserializeSession(id, serialized). 
const session = sessionStore.get(id);
const serialized = session.serializeSession();

// Store in a database, Redis, etc.
await db.set(`session:${id}`, serialized);
Rammerhead writes session files as JSON. If Node.js exits abruptly while serializing a session (for example, due to a SIGKILL), the file can be truncated and will produce a parse error the next time it is read. Set deleteCorruptedSessions: true (the default) to have the file cache automatically remove these files.

​
File cache configuration

RammerheadSessionFileCache accepts the following options to control how sessions are stored and cleaned up. 
const { RammerheadSessionFileCache } = require('rammerhead');

const sessionStore = new RammerheadSessionFileCache({
  // Directory where .rhfsession files are written
  saveDirectory: './sessions',

  // How long an active session stays in memory before being flushed to disk
  cacheTimeout: 1000 * 60 * 20,        // 20 minutes

  // How often the flush check runs
  cacheCheckInterval: 1000 * 60 * 10,  // 10 minutes

  // Delete sessions from memory (not disk) if they were never used after creation
  deleteUnused: true,

  // Auto-delete .rhfsession files that contain invalid JSON
  deleteCorruptedSessions: true,

  // Stale session cleanup — set to null to disable entirely
  staleCleanupOptions: {
    // Delete sessions not accessed within this window
    staleTimeout: 1000 * 60 * 60 * 24 * 3,  // 3 days

    // Delete sessions older than this regardless of activity (null to disable)
    maxToLive: null,

    // How often stale cleanup runs
    staleCheckInterval: 1000 * 60 * 60 * 6  // 6 hours
  }
});
In a multi-worker deployment, disable stale cleanup on worker processes and let only the master handle it, to avoid multiple processes racing to delete the same files. The built-in server does this automatically by setting staleCleanupOptions: null on workers.

​
Memory store configuration

RammerheadSessionMemoryStore keeps all sessions in memory and is simpler to configure. It is best suited for development or single-instance deployments where persistence is not required. 
const { RammerheadSessionMemoryStore } = require('rammerhead');

const sessionStore = new RammerheadSessionMemoryStore({
  // Delete sessions not accessed within this window (null to disable)
  staleTimeout: 1000 * 60 * 30,   // 30 minutes

  // Delete sessions older than this regardless of activity (null to disable)
  maxToLive: 1000 * 60 * 60 * 4, // 4 hours

  // How often the cleanup check runs
  cleanupInterval: 1000 * 60      // 1 minute
});

Build docs developers (and LLMs) love

Get started for freeTalk to us