Getting Started

Installation

Run directly without installing:

npx @rvanbaalen/roxyproxy

Or install globally:

npm install -g @rvanbaalen/roxyproxy
roxyproxy

Quick Start

The fastest way to capture traffic:

# One command: starts proxy, enables system proxy, opens interactive TUI
roxyproxy requests --tail

# Filter for a specific host
roxyproxy requests --host api.example.com --tail

This auto-starts the proxy, routes macOS system traffic through it, and opens a live terminal UI. Press Ctrl+C to quit. The system proxy is automatically disabled.

Manual Setup

# Start the proxy (default: proxy on :8080, web UI on :8081)
roxyproxy start

# Route traffic through it
curl -x http://127.0.0.1:8080 http://httpbin.org/get

# View captured traffic
roxyproxy requests

# Open the web UI
open http://127.0.0.1:8081

# Stop
roxyproxy stop

HTTPS Interception

To capture HTTPS traffic, trust the CA certificate first:

roxyproxy start
roxyproxy trust-ca
curl -x http://127.0.0.1:8080 https://api.example.com/endpoint

AI-Assisted Debugging

Install the AI agent plugin to let your AI agent query captured traffic:

/plugin marketplace add rvanbaalen/roxyproxy

Once installed, just tell your AI agent what you need: "The Stripe webhook is failing. Debug it." Your agent will query RoxyProxy, find the failing request, and fix your code.

Platform Support

RoxyProxy works on macOS and Linux. Some features are macOS-only:

  • System proxy (proxy-on / proxy-off) uses macOS networksetup
  • CA trust (trust-ca) uses macOS Keychain. Linux support exists but is less tested

Next Steps

← Overview CLI Reference →