Skip to main content
httpmon lets you write JavaScript scripts that intercept and modify HTTP traffic in real time. You can add headers, block requests, mock responses, set breakpoints, and more. Scripts live in ~/.httpmon/scripts/. Each script is a .js file with YAML frontmatter in comments followed by JavaScript hook functions.

​
Script format

A script has two parts: a YAML frontmatter block (wrapped in // --- comment delimiters) and one or both hook functions. 
// ---
// name: My Script
// match:
//   - "*://example.com/*"
// enabled: true
// ---

function onRequest(ctx) {
  // Runs before the request is sent upstream
}

function onResponse(ctx) {
  // Runs before the response reaches the client
}

​
Frontmatter fields

FieldRequiredDescription
nameYesDisplay name shown in the script manager
matchYesURL patterns to match. Supports * wildcards.
enabledNotrue or false. Defaults to true if omitted.

​
Hooks

onRequest(ctx) runs before the request is sent to the server.
FieldTypeDescription
ctx.methodstringHTTP method (read/write)
ctx.urlstringFull URL (read/write)
ctx.headersobjectRequest headers (read/write)
ctx.bodystringRequest body (read)
ctx.blockedboolSet to true to block the request
ctx.respondWith()functionReturn a synthetic response without hitting the server
ctx.breakpoint()functionPause the request and open an interactive editor
onResponse(ctx) runs before the response reaches the client.
FieldTypeDescription
ctx.statusintStatus code (read/write)
ctx.headersobjectResponse headers (read/write)
ctx.bodystringResponse body (read)

​
Script manager

Press S in the TUI to open the script manager. From there you can toggle, create, and delete scripts.
KeyAction
SpaceToggle a script on or off
nCreate a new script from a template
dDelete a script (with confirmation)
Scripts are reloaded each time the manager opens. Edit scripts in your favorite text editor and reopen the manager to pick up changes.
httpmon script manager

​
Examples

All examples below use httpbin.org so you can test them immediately.
Add custom headers to outgoing requests. The httpbin /headers endpoint echoes back all received headers, so you can verify the script works.
// ---
// name: Add Custom Header
// match:
//   - "*://httpbin.org/headers"
// enabled: true
// ---

function onRequest(ctx) {
  ctx.headers["X-Custom-Header"] = "httpmon-test";
  ctx.headers["X-Request-ID"] = "12345";
}
Override the status code or headers on a response before it reaches the client.
// ---
// name: Override Response
// match:
//   - "*://httpbin.org/json"
// enabled: true
// ---

function onResponse(ctx) {
  ctx.status = 200;
  ctx.headers["X-Modified"] = "true";
}
Block all requests to slow endpoints. Blocked requests never leave the proxy.
// ---
// name: Block Slow Endpoints
// match:
//   - "*://httpbin.org/delay/*"
// enabled: true
// ---

function onRequest(ctx) {
  ctx.blocked = true;
}
Return a synthetic JSON response without hitting the server. Use ctx.respondWith() to define the status, body, and headers.
// ---
// name: Mock GET Response
// match:
//   - "*://httpbin.org/get"
// enabled: true
// ---

function onRequest(ctx) {
  ctx.respondWith({
    status: 200,
    body: JSON.stringify({ mocked: true, tool: "httpmon" }),
    headers: { "Content-Type": "application/json" }
  });
}
Serve a file from disk instead of forwarding the request. The file path is relative to the script directory (~/.httpmon/scripts/).
// ---
// name: Serve Local Config
// match:
//   - "*://httpbin.org/get"
// enabled: true
// ---

function onRequest(ctx) {
  ctx.respondWith({
    status: 200,
    file: "mock-response.json"
  });
}
Pause the request flow and open an interactive editor. You can inspect and modify the request before it is sent to the server.
// ---
// name: Inspect POST Requests
// match:
//   - "*://httpbin.org/post"
// enabled: true
// ---

function onRequest(ctx) {
  ctx.breakpoint();
}
Inject a bearer token into requests. The httpbin /bearer endpoint validates the Authorization header and returns 200 on success or 401 without it.
// ---
// name: Inject Bearer Token
// match:
//   - "*://httpbin.org/bearer"
// enabled: true
// ---

function onRequest(ctx) {
  ctx.headers["Authorization"] = "Bearer my-secret-token";
}
Rewrite the URL to redirect a request to a different endpoint. The client sees the response from the new URL.
// ---
// name: Redirect to IP Endpoint
// match:
//   - "*://httpbin.org/get"
// enabled: true
// ---

function onRequest(ctx) {
  ctx.url = "https://httpbin.org/ip";
}

​
URL matching

The match field accepts an array of glob patterns. Use * as a wildcard for any sequence of characters.
PatternMatches
*://httpbin.org/*Any scheme, any path on httpbin.org
*://httpbin.org/getOnly the /get endpoint
*://httpbin.org/delay/*Any delay duration
*://*.example.com/*Any subdomain of example.com
You can specify multiple patterns to match different endpoints with a single script: 
match:
  - "*://api.example.com/v1/*"
  - "*://api.example.com/v2/*"

​
Error handling

If a script throws an error, httpmon catches it and continues processing the request normally. The error is tracked and displayed in the script manager next to the script name, so you can spot and fix issues without disrupting traffic.
See the Script API reference for the full list of context fields and methods.