Use your own proxy

Route a command or an interactive shell through a proxy you already have. No Shellroute account is needed: nothing is logged in, metered or billed. The hosted routes stay the zero-setup option; your own proxy is the free one.

Save a proxy and use it

your-proxy-name in every example is a placeholder for the alias you choose when saving the proxy. Pick any name of 3 to 32 characters: lowercase letters, digits, _ or -. USER, PASSWORD, HOST and PORT are the values your provider gives you.

Save the proxy once, then use the alias in any mode.

# Save it once. The URL carries the credentials.
shellroute upstream add your-proxy-name http://USER:PASSWORD@HOST:PORT

# Check it: opens one tunnel, reports exit IP and location.
shellroute upstream test your-proxy-name
#   ✓ via your-proxy-name · exit IP 91.198.0.12 · DE (observed) · 212 ms

Interactive shell

Open Shellroute and connect to your proxy from inside the shell.

shellroute
/connect your-proxy-name
curl https://ipinfo.io/json
# run any commands — all traffic goes through your proxy
/disconnect

Direct mode

Route a single command and exit.

shellroute run your-proxy-name -- curl https://ipinfo.io/json

Proxy mode

Start a persistent local proxy on 127.0.0.1:41900 that forwards through your proxy.

shellroute proxy --upstream your-proxy-name

Manage saved proxies

shellroute upstream list                      # passwords shown as ***
shellroute upstream remove your-proxy-name

Without saving

Pass a proxy URL directly when you don't want to save it — useful for one-off checks and CI.

# Pass a proxy URL with --proxy (not saved)
shellroute run --proxy socks5://127.0.0.1:1080 -- curl https://ipinfo.io/json

# Or set it in the environment — good for CI
SHELLROUTE_PROXY=http://USER:PASSWORD@HOST:PORT shellroute run -- curl https://ipinfo.io/json

# Test a URL before saving it
shellroute upstream test https://USER:PASSWORD@HOST:443

Proxy URLs

• The port is required.
• Credentials go in the URL: scheme://user:password@host:port. Username and password are taken exactly as written, any character. Put the URL in single quotes if it contains spaces or shell characters.
• IPv6 hosts go in brackets: http://[2001:db8::1]:8080.
• Your provider's documentation gives the hostname, port and username format. Many providers select the country or a sticky session through the username; paste it into the URL as given.

How Shellroute picks the route

When you run a command, Shellroute decides which proxy to use by checking these sources in order. The first match wins:

1. --proxy <url>: your own proxy, this run only.
2. --country CC: a hosted route.
3. A two-letter word before --: a hosted country, as before.
4. Any other word before --: one of your saved upstreams.
5. Nothing given: SHELLROUTE_PROXY from the environment if set, else default_country from the config.

There is no country setting for an own proxy. Shellroute cannot know where a third-party proxy exits, so it looks instead: when a route starts, the exit IP service that returns the IP also reports a country for it, and that is shown as DE (observed) in upstream test, run, status and the shell prompt. It is a measurement from a public geo-IP database, usually right and occasionally wrong, and it is empty when the service does not report one.

What stays the same

The child command only ever sees the local proxy on 127.0.0.1, the same as with a hosted route. HTTP_PROXY, HTTPS_PROXY, their lowercase twins, NO_PROXY and NODE_USE_ENV_PROXY are set the same way, so the compatibility matrix and the Playwright and Puppeteer guidance apply unchanged.

Your proxy's password never reaches the child process, its environment, your shell history or your CI logs. It is stored in ~/.shellroute/config.toml (mode 600) and shown as user:*** everywhere else: upstream list, status, the session file and error messages.

What is different

• No login, no balance, no cost line. The end-of-run summary shows duration and data only.
• The exit IP and its observed country come from a probe through your proxy (ipinfo.io, then api.ipify.org). --no-check skips it; the route then starts without an exit IP line. On a rotating provider later requests may leave from other exits; the probe shows the first one only.
• Rotation is your provider's job. In the shell, /rotate says so and does nothing; /iptype, /sticky, /cities, /countries and /balance answer "not applicable to your own upstream".
• An https:// proxy must present a certificate your system trusts. A self-signed certificate is refused; on Linux you can point SSL_CERT_FILE at the CA file for the run, on macOS the system keychain decides.

Failure behavior

Starting a route makes one connection attempt with a 10 second timeout and one retry, then fails with the cause:

A wrong password is final and not retried. If the tunnel opens but the exit IP service does not answer, the route starts with a warning.

Route death

While a route runs, each client request opens its own tunnel through your proxy. One failed connection answers that client with 502 and nothing else changes. A credentials error, or three consecutive connection failures with no success in between, marks the route dead:

• shellroute run: active connections are closed and the command is killed, with "Connection lost during execution. Command killed.", exactly as with a hosted route. There is no retry that could make a half-run script look successful.
• shellroute proxy --upstream: clients get 503 until you restart it.
• Interactive shell: the prompt shows "Connection lost through your-proxy-name. Run /connect." and blocks commands until you reconnect.

A 4xx from the proxy for one target is forwarded to the client and does not count towards route death.

Troubleshooting

• unknown upstream "your-proxy-name": nothing is saved under that alias. shellroute upstream list shows what is; shellroute upstream add your-proxy-name <url> saves it.
• proxy URL needs a port: add :8080, :1080 or whatever your provider gives.
• proxy URL is not valid: the host part is wrong. The format is scheme://user:password@host:port. If the shell split the URL at a space or a symbol, put it in single quotes.
• upstream test passes but a program is not routed: the program does not read the proxy environment variables. See the compatibility matrix.
• upstream test reports an unexpected country: the exit is the provider's choice. Check the username or port format in the provider's documentation. Geo-IP databases also misplace some addresses.

Tested providers

Results of running the bring-your-own-proxy commands against real proxy providers. A provider missing from this table has not been tested, which says nothing about whether it works. The living source is in the CLI repository.

How to read the rotation note: with a rotating pool every connection may leave from a different exit, and often a different country. upstream test and the via … line at the start of run show the first exit only. If you need one country, select it the way the provider documents, usually through the username or a dedicated port, and check the result with curl https://ipinfo.io/json through the route.