Proxy Mode

shellroute proxy starts a local proxy server and keeps it running until you press Ctrl+C. Other terminals, scripts, and tools can use the proxy by setting HTTP_PROXY.

When to use proxy mode

Use shellroute proxy when you need a proxy running in one terminal while you work in others. Unlike shellroute run (which wraps a single command) or interactive mode (which gives you a proxied shell), proxy mode just starts the server — you decide which processes use it.

Basic usage

terminal 1

# Start the proxy (blocks until Ctrl+C)
shellroute proxy --country US

terminal 2

# Set the proxy and use it
export HTTP_PROXY=http://127.0.0.1:41900
export HTTPS_PROXY=http://127.0.0.1:41900

curl https://httpbin.org/ip     # → proxied through US
python3 check.py                # → proxied

# Stop using the proxy
unset HTTP_PROXY HTTPS_PROXY
curl https://httpbin.org/ip     # → direct

Output formats

Use --format to get connection info in a machine-readable format.

JSON output

$ shellroute proxy --country US --format json
{
  "proxy_url": "http://127.0.0.1:41900",
  "exit_ip": "45.12.67.89",
  "country": "US",
  "city": "Ashburn",
  "type": "residential"
}

env output

$ shellroute proxy --country US --format env
export HTTP_PROXY=http://127.0.0.1:41900
export HTTPS_PROXY=http://127.0.0.1:41900

Flags

Flag	Description	Default
--country <code>	2-letter country code	required
--city <name>	Target a specific city. Fails if not found.	any
--iptype <type>	`residential`, `datacenter`, or `mix`	residential
--sticky	Attempts to keep the same IP on reconnect.	off
--format <fmt>	`json` or `env`	json

What gets proxied

Proxied automatically

Any tool that reads HTTP_PROXY / HTTPS_PROXY: curl, wget, Python (requests, urllib), Node.js (fetch, axios), Go http.Client, Ruby, Java.

Needs explicit config

Browser tools (Playwright, Puppeteer, Selenium) need the proxy passed in their launch config. See the agents page for examples.

Not proxied

SSH, ping, DNS lookups, raw TCP sockets, UDP traffic — these don't read proxy env vars.

Selective proxying

Unlike interactive mode (which proxies everything in the shell), proxy mode lets you choose which commands use the proxy:

terminal

# Proxy only this one command
HTTP_PROXY=http://127.0.0.1:41900 curl https://httpbin.org/ip

# Or set it for the whole terminal
export HTTP_PROXY=http://127.0.0.1:41900
curl https://httpbin.org/ip     # proxied
python3 check.py                # proxied

# Direct access (no proxy)
unset HTTP_PROXY HTTPS_PROXY
curl https://my-internal-api.com # direct

Stopping the proxy

Press Ctrl+C in the terminal where shellroute proxy is running, or stop it from another terminal:

terminal

shellroute proxy stop

This stops running proxy sessions. It does not affect interactive or shellroute run sessions.

Direct Mode Use Cases