ProxyLens CLI

Instant HTTP tunnels and local proxy with a live traffic inspector — no config, no signup required to get started.

Installation

npm install -g node-proxylens

Quick Start

# Expose localhost:3000 to the internet instantly (no login needed)
proxylens 3000

A public URL like https://happy-tiger.proxylens.dev is printed. Requests hitting that URL are forwarded to your local server and shown in real time at proxylens.dev/interceptor.

Modes

Tunnel Mode (default)

Forwards public HTTPS traffic to your local server through ProxyLens's tunnel.

Guest mode — no login required. A random adjective-animal.proxylens.dev domain is assigned for the session.

Authenticated mode — log in to use a persistent domain from your account:

proxylens login <token>
proxylens 3000 -d my-app          # → https://my-app.proxylens.dev
proxylens 3000 -d api.mysite.com  # → https://api.mysite.com

Local Proxy Mode (--local)

Runs a local HTTP proxy on a port instead of creating a tunnel. Point your HTTP client at http://localhost:<port> and ProxyLens intercepts everything.

proxylens 3000 --local           # Proxy on default port 4150
proxylens 3000 --local -i 5050   # Proxy on port 5050

Usage

proxylens <target> [flags]
proxylens <command>

Target

| Format | Example | Description | |---|---|---| | Port number | 3000 | Shorthand for http://localhost:3000 | | Host:port | localhost:3000 | Port is required when using localhost | | Full URL | http://192.168.1.5:8080 | Any reachable HTTP server | | Domain | myservice.internal | Internal hostnames or other machines |

Flags

| Flag | Short | Default | Description | |---|---|---|---| | --domain <name> | -d | auto-assigned | Subdomain or full custom domain to use for the tunnel. Pass just a name (my-app) for a .proxylens.dev subdomain, or a full domain (api.mysite.com). Requires login. | | --local | -l | off | Run as a local proxy instead of a tunnel. Starts an HTTP proxy server on --interceptor-port. | | --interceptor-port <port> | -i | 4150 | Port for the local inspector/proxy server. In tunnel mode this is opt-in; in --local mode it is the proxy port. | | --server <url> | -s | wss://tunnel.proxylens.dev | Override the tunnel server WebSocket URL. Useful for self-hosted setups. | | --no-ui | | off | Disable the local inspector UI server. Cannot be combined with --local. | | --help | -h | | Print help and exit. |

Commands

proxylens login <token>

Save an API token to ~/.proxylens/config.json. Get your token from proxylens.dev/dashboard/tokens.

proxylens login plk_abc123...

Running proxylens login with no token shows your current session if you are already logged in.

proxylens logout

Remove the stored credentials.

proxylens logout

proxylens whoami

Show the currently authenticated user and plan.

proxylens whoami
# Logged in as: [email protected] (pro)

proxylens domains

List all domains registered in your account with their type and status.

proxylens domains

# Domain                                        Type       Status
# ──────────────────────────────────────────────────────────────────────
# my-app.proxylens.dev                          Free       active
# api.mysite.com                                Custom     active

Examples

# Instant public URL, no login required
proxylens 3000

# Use a persistent subdomain from your account
proxylens 3000 -d my-app

# Use a custom domain (must be registered in the dashboard first)
proxylens 3000 -d api.mycompany.com

# Local proxy on default port 4150 — point your client at http://localhost:4150
proxylens http://staging.internal --local

# Local proxy on a custom port
proxylens 3000 --local -i 8888

# Tunnel + open local inspector UI on port 5050
proxylens 3000 -i 5050

# Tunnel without any local UI server
proxylens 3000 --no-ui

# Use a custom tunnel server
proxylens 3000 -s wss://tunnel.mycompany.com

Domain Conflict

If you connect with a domain that is already active in another session, ProxyLens will ask:

⚠ The domain 'my-app.proxylens.dev' is already in use.
Do you want to close the remote connection and take over? (y/N)

Answering y disconnects the previous session and takes over the domain.

Reconnection

In tunnel mode, if the connection drops unexpectedly (network error / code 1006), the CLI automatically retries every 3 seconds. It will not retry if the session was intentionally closed or replaced by another client.

Programmatic Usage

Embed the ProxyLens inspector into your own Node.js HTTP server to stream traffic to the live UI.

const http = require('http');
const { ProxyLens } = require('node-proxylens');

const server = http.createServer((req, res) => {
  res.end('Hello');
});

const lens = new ProxyLens(server, {
  historyLimit: 100,              // requests kept in memory (default: 50)
  proxyTarget: 'http://localhost:3000', // used when replaying from UI
});

// Manually log a transaction
lens.logTransaction({
  id: 'req-1',
  timestamp: Date.now(),
  duration: 42,
  clientIp: '127.0.0.1',
  request:  { method: 'GET', path: '/api/users', headers: {}, body: null, queryParams: {} },
  response: { status: 200, statusText: 'OK', headers: {}, body: '[]' },
  pending: false,
});

server.listen(3000);

The inspector UI connects to /_proxylens on your server via WebSocket and streams all logged transactions in real time.

ProxyLens options

| Option | Type | Default | Description | |---|---|---|---| | historyLimit | number | 50 | Max requests kept in memory and sent to new UI connections on connect | | proxyTarget | string | — | Target URL used when replaying requests from the inspector UI | | domain | string | — | Public domain associated with this instance |

Configuration

Credentials are stored in ~/.proxylens/config.json.

Set PROXY_PORT as an environment variable to change the default local proxy/inspector port (default: 4150):

PROXY_PORT=8080 proxylens 3000 --local

Links

• Dashboard: proxylens.dev/dashboard
• Live interceptor: proxylens.dev/interceptor
• Docs: proxylens.dev/docs

License

Copyright © 2025 ProxyLens. All rights reserved.

This software is licensed, not sold. You may not copy, modify, distribute, sublicense, or reverse engineer this software except as explicitly permitted by ProxyLens.

See LICENSE for the full terms.