Running LPI

Once you've downloaded and prepared your LPI binary, follow these steps to start inspecting webhooks and HTTP traffic.

Quick Start

Windows

lpi-windows-x64.exe --license YOUR-LICENSE-KEY --email [email protected]

macOS/Linux

./lpi-darwin-x64 --license YOUR-LICENSE-KEY --email [email protected]    # macOS Intel
./lpi-darwin-arm64 --license YOUR-LICENSE-KEY --email [email protected]  # macOS Apple Silicon
./lpi-linux-x64 --license YOUR-LICENSE-KEY --email [email protected]     # Linux x64
./lpi-linux-arm64 --license YOUR-LICENSE-KEY --email [email protected]   # Linux ARM64

Version Information

Check your LPI version:

./lpi --version
# Output: Local Proxy Inspector (LPI) v1.1.0

Default Configuration

By default, LPI will:

  • Start the proxy server on port 3000
  • Open the web UI on port 3001
  • Forward requests to http://localhost:8080
  • Store requests in ~/.lpi/requests.db
  • Keep requests for 7 days

Command Line Options

Essential Options

# License (required)
./lpi --license YOUR-LICENSE-KEY --email [email protected]

# Or use environment variables
export LPI_LICENSE=YOUR-LICENSE-KEY
export [email protected]
./lpi

Port Configuration

# Change proxy port (default: 3000)
./lpi --proxy 8888 --license KEY --email EMAIL

# Change UI port (default: 3001)
./lpi --ui 8080 --license KEY --email EMAIL

# Change target backend (default: http://localhost:8080)
./lpi --target http://localhost:3000 --license KEY --email EMAIL

Mock Mode (NEW!)

Test webhooks without a running backend:

# Always return 200 OK for any request
./lpi --always-reply 200 --license KEY --email EMAIL

# Return custom JSON response
./lpi --always-reply 200 --mock-body '{"status":"ok","received":true}' --license KEY --email EMAIL

# Simulate slow server (2 second delay)
./lpi --always-reply 200 --mock-delay 2000 --license KEY --email EMAIL

# Full mock setup for webhook testing
./lpi --always-reply 201 \
      --mock-body '{"id":"webhook_123","status":"processed"}' \
      --mock-delay 500 \
      --license KEY --email EMAIL

Storage Options

# Custom database location
./lpi --db /path/to/my/requests.db --license KEY --email EMAIL

# Keep requests for 30 days (default: 7)
./lpi --retention 30 --license KEY --email EMAIL

# Limit to 5000 stored requests (default: 10000)
./lpi --max-entries 5000 --license KEY --email EMAIL

View All Options

./lpi --help

Common Usage Patterns

Testing Webhooks Without a Backend

Perfect for when you're just starting development:

# Start LPI in mock mode
./lpi --always-reply 200 --mock-body '{"ok":true}' --license KEY --email EMAIL

# Configure webhook provider to use http://localhost:3000
# All webhooks will receive your mock response

Testing Webhooks with Local Backend

When you have a local service running:

# Your app runs on port 3000, LPI proxies on 8888
./lpi --proxy 8888 --target http://localhost:3000 --license KEY --email EMAIL

# Configure webhooks to use http://localhost:8888

Multiple Webhook Sources

Run separate instances for different services:

# Terminal 1: Stripe webhooks
./lpi --proxy 8881 --ui 3001 --db ~/.lpi/stripe.db --license KEY --email EMAIL

# Terminal 2: GitHub webhooks
./lpi --proxy 8882 --ui 3002 --db ~/.lpi/github.db --license KEY --email EMAIL

# Terminal 3: Custom webhooks (mock mode)
./lpi --proxy 8883 --ui 3003 --always-reply 200 --license KEY --email EMAIL

With Tunnel Services

When using with tunneling services:

# Start LPI in mock mode (no backend needed!)
./lpi --proxy 8888 --always-reply 200 --license KEY --email EMAIL

# Start your tunnel
cloudflared tunnel --url http://localhost:8888

# Use the tunnel URL for your webhooks

Mock Mode Use Cases

1. Initial Integration Setup

Start receiving webhooks immediately without building a backend:

./lpi --always-reply 200 --license KEY --email EMAIL

2. Documentation & Testing

Capture webhook formats for documentation:

./lpi --always-reply 200 --mock-body '{"documented":true}' --license KEY --email EMAIL

3. Error Simulation

Test how providers handle errors:

# Simulate server errors
./lpi --always-reply 500 --license KEY --email EMAIL

# Simulate timeouts
./lpi --always-reply 200 --mock-delay 30000 --license KEY --email EMAIL

4. Offline Development

Work without internet or backend services:

./lpi --always-reply 201 --mock-body '{"id":"test_123"}' --license KEY --email EMAIL

Troubleshooting

Port Already in Use

# Check what's using the port
lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

# Use different ports
./lpi --proxy 9000 --ui 9001 --license KEY --email EMAIL

License Issues

# Verify your license
./lpi --license YOUR-KEY --email [email protected] --version

# Use environment variables
export LPI_LICENSE=YOUR-KEY
export [email protected]
./lpi

Permission Denied (Linux/macOS)

# Make the binary executable
chmod +x lpi-linux-x64

Can't Access Web UI

  • Check firewall settings for both proxy and UI ports
  • Try accessing directly: http://localhost:3001
  • Ensure no other service is using the ports

Security Notes

  • LPI is designed for local development only
  • All captured data is stored locally on your machine
  • No data is sent to external servers
  • License validation is done offline
  • Be cautious when using mock mode with sensitive data

Pro Tips

  1. Use Mock Mode First: Start with --always-reply 200 to quickly test webhook integrations
  2. Separate Databases: Use different DB files for different projects
  3. Environment Variables: Store license in LPI_LICENSE and LPI_EMAIL to avoid typing
  4. Visual Indicators: Mock responses show a "MOCK" badge in the UI
  5. Response Delays: Use --mock-delay to test timeout handling

Next Steps

  • Learn about setting up free tunnels for testing webhooks
  • Check the FAQ for common questions
  • See example configurations for popular webhook providers