Use Cases

Shellroute works wherever developers need controlled, session-scoped proxy access from the terminal.

Geo-testing

Test how websites, APIs, and services behave from specific countries.

terminal

# Interactive — open a US shell
shellroute
❯ /connect US
❯ curl https://example.com  # see US version

# Or direct — one command
shellroute run --country US -- curl https://example.com

QA automation

Run Playwright or Puppeteer tests through country-specific exits.

terminal

shellroute run --country DE -- npx playwright test
shellroute run --country JP -- npx playwright test

Public web data

Route collection scripts through residential exits for price monitoring, search tracking, and marketplace research.

terminal

shellroute run --country US -- python price_monitor.py
shellroute run --country GB -- node collect.js

AI agents

Give AI agents, browser agents, and automation scripts per-task proxy access. Each shellroute run gets its own session and exit IP. No code changes in the agent — proxy env vars are inherited automatically.

terminal

# Agent checks what US users see
shellroute run --country US -- curl -s https://httpbin.org/ip
# → {"origin": "203.0.113.42"}

# Browser agent through Germany
shellroute run --country DE -- python browser_agent.py

# Parallel agents, different countries
shellroute run --country US -- python task.py --market us &
shellroute run --country JP -- python task.py --market jp &
wait

Ad verification

Verify ad placements and landing pages from different geographies.

terminal

shellroute run --country BR -- curl https://ads.example.com/verify
shellroute run --country US -- curl https://ads.example.com/verify

CI/CD pipelines

Add geo-specific steps to your build pipeline. Set SHELLROUTE_API_KEY as a CI secret — get the key with shellroute reveal-key from a logged-in machine.

github-actions.yml

env:
  SHELLROUTE_API_KEY: ${{ secrets.SHELLROUTE_API_KEY }}

steps:
  - run: npm install -g shellroute

  - name: Test from US
    run: shellroute run US -- npm run test:geo

  - name: Test from DE (datacenter)
    run: shellroute run --iptype datacenter DE -- npm run test:geo

any CI

# Or pass key inline (no env var needed)
shellroute --api-key $MY_KEY run US -- npm run test:geo

Quickstart Direct Mode