Skip to main content
Glama

@profullstack/proxy

Call the web through the residential proxies we pay for, with each provider's own authentication and targeting. One package, every surface:

surface

how

library

proxyFetch(url, init, { country, session }), proxyUrl(), exitIp(), status()

CLI

proxy <url>, proxy ip, proxy url, proxy status

API

proxy serve: a local forward proxy that holds the credentials, plus a JSON API

MCP

proxy mcp: tools proxy_fetch, proxy_ip, proxy_url, proxy_status

TUI

proxy tui: accounts, renewals, and a live exit test

Providers:

  • Proxiware Unlimited Residential (unlimited.proxiware.com:1337). Targeting rides in the username: -country-us, -state-…, -city-…, sticky -sid-<n>-ttl-<min>. Defaults to a US exit.

  • Webshare (p.webshare.io:80). -rotate, -US-rotate, or -<n> to pin proxy n. With only WEBSHARE_API_KEY, the proxy login is read from the API.

  • HProxy Residential, pay per GB (premium.hproxy.com:10000). Username grammar -type-residential-country-us-state-…-city-…-session-<id>-lifetime-<min> (lifetime 3 to 1440, default 30 with a session). Defaults to a US exit. With only HPROXY_API_KEY, lines come from HProxy's generate API instead and are used as-is. See HProxy: what is verified.

Install

curl -fsSL https://raw.githubusercontent.com/profullstack/proxy/main/install.sh | sh

No root needed: it installs under ~/.local (fetching a private Node if yours is too old). Run it again to update; remove with sh ~/.local/share/proxy/uninstall.sh.

Or with npm:

npm install -g @profullstack/proxy     # the `proxy` command
npm install @profullstack/proxy        # the library

Node 22.19+ (or Bun). In the Profullstack fleet, cli-tools ships proxy with the shared vault keys already wired in.

Related MCP server: roamproxy-mcp

Credentials

Environment only; the package never reads or writes a file.

variable

PROXIWARE_PROXY_USER, PROXIWARE_PROXY_PASSWORD

proxy login (Proxiware dashboard, or GET /v1/unlimited/subscriptions)

PROXIWARE_API_KEY

account status (proxy status)

PROXIWARE_PROXY_HOST, PROXIWARE_PROXY_PORT

override unlimited.proxiware.com:1337

WEBSHARE_API_KEY

account status, and the proxy login when no user/password is set

WEBSHARE_PROXY_USER, WEBSHARE_PROXY_PASSWORD

proxy login, skips the API lookup

WEBSHARE_PROXY_HOST, WEBSHARE_PROXY_PORT

override p.webshare.io:80

HPROXY_PROXY_USER, HPROXY_PROXY_PASSWORD

proxy login (HProxy dashboard, the plan's credential pair)

HPROXY_API_KEY

hpx_… key: account status, and generated lines when no user/password is set

HPROXY_PLAN_ID

plan to generate lines from (default: the first residential plan)

HPROXY_PROXY_HOST, HPROXY_PROXY_PORT

override premium.hproxy.com:10000

PROXY_PROVIDER

default provider when several are configured (else proxiware, then webshare, then hproxy)

PROXY_SERVE_TOKEN

default --token for proxy serve

CLI

proxy https://example.com                    # body to stdout, US residential exit
proxy -i -c gb https://example.com           # status + headers, UK exit
proxy -s job42 --ttl 10 https://example.com  # sticky: same IP for 10 minutes
proxy -X POST -H 'content-type: application/json' -d @body.json https://api.example.com
proxy -o page.html https://example.com
proxy ip                                     # 75.179.96.136  US Ohio …  AS10796 Charter  (proxiware)
proxy url                                    # http://user-country-us:***@unlimited.proxiware.com:1337
export HTTPS_PROXY="$(proxy url --reveal)"   # hand the real URL to another tool
proxy status                                 # credit, plans, renewal, expiry
proxy -p webshare ip                         # a specific provider
proxy -p hproxy -c de --city berlin -s w1 --ttl 30 ip   # HProxy, sticky Berlin exit

The default User-Agent is curl/8.5.0 (+@profullstack/proxy): some APIs (ESPN) allowlist curl-like agents and refuse browser and runtime defaults whatever the exit IP. -A overrides it. Exit codes: 0 ok, 22 non-2xx response (curl's --fail), 3 no credentials, 2 bad arguments, 1 anything else.

HProxy: what is verified

Built 2026-10-07 from HProxy's own docs (hproxy.com/llms-full.txt and hproxy.com/api/v1/openapi.json), without an account, so nothing here has carried live traffic yet.

  • Verified in their docs: the two example Residential Premium lines, premium.hproxy.com:10000:USERNAME-type-residential-country-de-city-berlin-os-windows-session-…-lifetime-30:PASSWORD (HTTP) and premium.hproxy.com:12000:…-asn-7922-requireUdp-true-session-…-lifetime-1440:PASSWORD (SOCKS5); lifetime in minutes, 3 to 1440; the API (https://hproxy.com/api/v1, X-API-Key: hpx_…, GET /me, GET /wallet, GET /plans, POST /plans/{id}/generate).

  • Unverified: the -state-<name> token (a documented API field, but no example line shows it); whether a username without -session- rotates per request on port 10000 (the docs call 10000 a sticky port, and the rotating port range is only in the authenticated plan object); Residential Lite, whose host and grammar are not published. HProxy also says the grammar "varies by pool" and to use generated lines verbatim, which is what HPROXY_API_KEY without a user/password does. If a hand-built username 407s or will not rotate, use that path, or set HPROXY_PROXY_PORT from a generated line.

  • With the API path a session id maps to one generated sticky line per process: the same id in another process gets a different IP.

proxy serve

proxy serve --port 8888                      # binds 127.0.0.1
HTTPS_PROXY=http://127.0.0.1:8888 curl https://ipinfo.io/json
curl http://127.0.0.1:8888/status            # JSON API: /status /ip /url /fetch?url=

Clients send no credentials; the server adds them on the hop upstream, so a tool with no proxy-auth support (or one you would rather not hand a password) still gets the paid exit. Per-connection overrides: X-Proxy-Country, X-Proxy-Session. Bind beyond localhost only with --token T, which clients then send as Proxy-Authorization: Bearer T (proxy traffic) or Authorization: Bearer T (API).

MCP

{ "mcpServers": { "proxy": { "command": "proxy", "args": ["mcp"] } } }

proxy_fetch (url, method, headers, body, max_bytes, provider, country, session), proxy_ip, proxy_url (masked unless reveal), proxy_status.

Library

import { proxyFetch, proxyUrl, exitIp, status } from '@profullstack/proxy';

const res = await proxyFetch('https://example.com', { headers: { accept: 'text/html' } }, { country: 'us' });
const url = await proxyUrl({ provider: 'proxiware', session: 'worker-3', ttl: 30 });
const { ip, org } = await exitIp({ country: 'gb' });

Under Node this is undici's fetch with a ProxyAgent (credentials sent as a Basic token, not URL userinfo, which some undici versions drop). Under Bun it is the built-in fetch with its per-request proxy option. createDispatcher() returns the undici agent for code that wants to keep one around.

Development

npm test                 # offline: fake upstream proxy, no credentials needed
scripts/smoke.sh --vault # live, against the real accounts (shared vault keys)

Releases publish to npm from GitHub when a release is published (.github/workflows/publish.yml).

MIT © Profullstack, Inc.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables fetching public HTTP(S) pages through DataImpulse residential proxies with country, city, and session targeting, plus an exit IP check tool. Includes best-effort SSRF safeguards and response size limits for safe bounded access.
      2
      24
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables agents to manage account balance, usage, credentials, invoices, and ISP proxies, and to fetch URLs through residential, datacenter, or mobile proxies with location and sticky-session targeting. It also supports exporting reports and proxy lists as files.
      29
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to query pack pricing, account balance and remaining bandwidth, and daily usage, and to generate geo-targeted HTTP or SOCKS5 proxy lines with rotating or sticky sessions. Also lets users fetch web pages and run connection checks through their own residential, datacenter or mobile proxies to see the exit IP, detected country and latency.
      1
      MIT