A transparent HTTP proxy for monitoring traffic between client and server.
httpSandwich is a lightweight HTTP monitor-in-the-middle tool that sits between your client and server, capturing and displaying all HTTP traffic in real-time. Perfect for debugging API integrations, understanding service communication, or troubleshooting network issues.
Unlike heavyweight solutions, httpSandwich is:
- Zero-config — Just specify source and target ports
- Terminal-native — Beautiful TUI with adjustable detail levels
- Non-intrusive — Transparent proxying, no code changes required
- Inspectable — Open any request in your browser for detailed analysis
- 🔄 Transparent Proxying — Forward requests without modification
- 📊 6 Detail Levels — From minimal dots to full headers and bodies
- ⌨️ Interactive TUI — Navigate, select, and inspect requests in real-time
- 🌐 Browser Inspect — View any request as a beautifully formatted HTML page
- 💾 Auto-persistence — All exchanges saved as JSON for later analysis
- 🎨 Status Coloring — Instant visual feedback (green=success, red=error, etc.)
- 📱 Responsive — Adapts to terminal size with smart truncation
- Node.js 20 or higher
It is recommended to simply run httpSandwich directly via npx, as shown below.
Position httpSandwich between your client and server:
# Natural language syntax (recommended)
npx httpsandwich between 8000 and localhost:3000
# Traditional flag syntax
npx httpsandwich --from 8000 --to localhost:3000Now point your client to localhost:8000 instead of localhost:3000. All traffic flows through httpSandwich and is displayed in real-time.
# Monitor traffic to a local API server
npx httpsandwich between 8080 and localhost:3000
# Proxy to a remote service
npx httpsandwich between 9000 and api.example.com:443
# Start with minimal output (dots only)
npx httpsandwich between 8000 and 5009 --level 1
# Keep more history in memory
npx httpsandwich between 8000 and 5009 --history 500While httpSandwich is running, use these keyboard shortcuts:
| Key | Action |
|---|---|
+ / = |
Increase detail level |
- / _ |
Decrease detail level |
↑ / ↓ |
Select request (enter selection mode) |
i |
Inspect selected request in browser |
ESC |
Exit selection mode |
q |
Quit |
| Level | Output |
|---|---|
| 1 | Dots only (minimal) |
| 2 | Timestamp + status code |
| 3 | Timestamp + status + method + path (default) |
| 4 | Level 3 + headers (truncated) |
| 5 | Level 4 + full headers + body preview |
| 6 | Full headers + complete body |
Select any request with arrow keys, then press i to open a detailed HTML view in your default browser. The inspect view includes:
- Complete request and response headers
- Formatted JSON bodies with syntax highlighting
- Status code with semantic coloring
- Request duration and timing information
- Collapsible sections for easy navigation
All HTML files are saved alongside the JSON data in your system's temp directory.
httpSandwich automatically saves all captured exchanges to:
{temp-directory}/httpSandwich/{session-id}/
├── {exchange-id}.json # Raw exchange data
└── {exchange-id}.html # Browser-viewable format (when inspected)
Session IDs are timestamp-based (e.g., 20251207-143052), making it easy to find and analyze past sessions.
# Clone and install
git clone https://github.com/dx-tooling/httpSandwich.git
cd httpSandwich
npm install
# Run in development mode (with hot reload)
npm run dev -- between 8000 and 3000
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
# Full quality check (lint + format + typecheck + test)
npm run quality
# Auto-fix linting and formatting issues
npm run quality:fixsrc/
├── cli/ # CLI entry point and argument parsing
├── domain/ # Core business logic and interfaces
├── application/ # Use cases and services
├── infrastructure/ # External concerns (HTTP, terminal, files)
└── shared/ # Cross-cutting utilities
Contributions are welcome! Please ensure:
- All tests pass:
npm run quality - Code follows the existing style
- New features include appropriate tests
MIT © 2025 Manuel Kießling for the DX·Tooling initiative.