byo-proxy — bring-your-own proxy
Users supply their own proxy account (currently IPRoyal); this skill stores
the credentials, maintains a skill → provider binding table, and exposes a tiny
Python API that other skills can opt into.
This skill does not run a proxy server and does not intercept any traffic.
It is a configuration center plus a URL builder. Other skills only behave differently
if they explicitly import from exports.py.
Boundaries vs. existing proxy skills
| Skill |
What it does |
When |
sc-vpn |
Internal VPN gateway, 18 fixed countries, no auth |
Last resort for geo-blocked requests inside Starchild |
transparent-proxy-maintenance |
Maintain the platform's billing proxy plugins |
Ops work on sc-proxy |
byo-proxy (this) |
Manage user's own provider keys + per-skill bindings |
User wants residential IPs, paid accounts, country granularity beyond sc-vpn's 18, or a dedicated fixed IP |
Supported providers
| Provider |
Kind |
Endpoint |
IP behaviour |
Auth |
iproyal |
gateway |
geo.iproyal.com:12321 |
rotates; sticky ≤ 7 days per session |
account username + password |
iproyal-isp |
isp |
per-IP host:port (e.g. 191.116.125.248:12323) |
dedicated, never changes |
per-proxy username + password |
Two shapes of "fixed IP":
- Sticky session (
iproyal + --session + --sticky) → same exit IP for up to
7 days, then pool rotation can move it. Cheap (per GB).
- Dedicated static IP (
iproyal-isp) → an IP reserved for you that never
changes. Priced per IP, unlimited traffic. This is the "permanent fixed IP".
Adding more providers later: add an entry to PROVIDERS + a URL builder in
exports.py. See references/iproyal.md (residential) and
references/iproyal-isp.md (dedicated).
Storage
- Account credentials (gateway providers) →
/data/workspace/.env (same convention
as polymarket, birdeye, coingecko). Keys: IPROYAL_USERNAME, IPROYAL_PASSWORD.
- Bindings + ISP proxy inventory →
/data/workspace/.byo-proxy.json:{
"bindings": { "web-crawler": { "provider": "iproyal", "country": "jp",
"session": "crawler-jp", "sticky_minutes": 360 } },
"isp_proxies": { "jp-1": { "host": "191.116.125.248", "port": 12323,
"socks_port": 12324, "username": "…", "password": "…",
"label": "Tokyo ISP" } }
}
ISP credentials are per-IP, so they live here (keyed by local proxy_id) rather
than in .env. Both files are edited only through scripts; agents should not
hand-edit. Legacy bindings-only files are migrated automatically on next save.
User workflow
SKILL=/data/workspace/skills/byo-proxy
# ── Residential gateway (rotating / sticky) ──────────────────────────────────
# 0. One-shot onboarding — prompts for creds only if missing, binds, live-tests:
python3 $SKILL/scripts/onboard.py web-crawler --provider iproyal --country jp
# 1. Register credentials (interactive — prompts for username/password)
python3 $SKILL/scripts/setup_provider.py iproyal
# 2. Bind a skill (long-term preference)
python3 $SKILL/scripts/bind_skill.py web-crawler --provider iproyal --country jp
# Pin one exit IP for up to 7 days (sticky needs a session id):
python3 $SKILL/scripts/bind_skill.py web-crawler --provider iproyal --country jp \
--session crawler-jp --sticky 360 # 6 hours
# ── Dedicated static IP (permanent) ─────────────────────────────────────────
# 3. Register a purchased ISP proxy (interactive if flags omitted), then bind:
python3 $SKILL/scripts/add_isp_proxy.py jp-1 \
--host 191.116.125.248 --port 12323 --socks-port 12324 \
--username <user> --password <pass> --label "Tokyo ISP"
python3 $SKILL/scripts/bind_skill.py web-crawler --provider iproyal-isp --proxy-id jp-1
# Or one-shot: python3 $SKILL/scripts/onboard.py web-crawler --provider iproyal-isp
# ── Inspect / verify / clean up ────────────────────────────────────────────
python3 $SKILL/scripts/list_providers.py # providers, ISP proxies, bindings
python3 $SKILL/scripts/test_proxy.py iproyal --country jp
python3 $SKILL/scripts/test_proxy.py iproyal-isp --proxy-id jp-1
python3 $SKILL/scripts/bind_skill.py web-crawler --unset
python3 $SKILL/scripts/add_isp_proxy.py --list
python3 $SKILL/scripts/add_isp_proxy.py --remove jp-1 [--force]
How other skills consume it
Two patterns. Both raise ProxyNotConfiguredError on misconfiguration — never
silent fallback (a proxy user is debugging a geo/identity problem; silently falling
through to a direct connection makes that debugging much harder).
Pattern A — explicit, one-off
import sys, requests
sys.path.insert(0, "/data/workspace/skills/byo-proxy")
from exports import get_proxy_url
p = get_proxy_url(provider="iproyal", country="jp") # rotating
p = get_proxy_url(provider="iproyal", country="jp",
session="crawler-jp", sticky_minutes=360) # sticky 6h
p = get_proxy_url(provider="iproyal-isp", proxy_id="jp-1") # dedicated IP
r = requests.get("https://example.com", proxies={"http": p, "https": p}, timeout=30)
Pattern B — bound, long-term
Use when a skill always wants to route through whatever the user configured for it:
import sys, requests
sys.path.insert(0, "/data/workspace/skills/byo-proxy")
from exports import get_proxy_for_skill, ProxyNotConfiguredError
try:
p = get_proxy_for_skill("web-crawler") # caller declares its own name
except ProxyNotConfiguredError as e:
# The exception message IS a multi-line onboarding guide for the user —
# surface it verbatim. It includes the signup URL, pricing note, and the
# one-shot `onboard.py` command to fix the situation.
raise SystemExit(str(e))
r = requests.get(url, proxies={"http": p, "https": p}, timeout=30)
get_proxy_for_skill is provider-agnostic: it returns the right URL whether the
user bound a rotating country, a sticky session, or a dedicated ISP IP. A skill that
does not import it is unaffected, even if the user has bindings configured.
Opt-in only.
Onboarding for unconfigured skills
When get_proxy_for_skill("X") raises because nothing is configured for X, the
exception message is already a complete onboarding script: signup URL, pricing,
credential location, and the exact onboard.py command to run. Agents that surface
this error to a user will naturally walk them through registration and binding — no
extra logic needed in the calling skill.
If a calling skill wants to render its own onboarding UI (instead of relying on the
error message), it can import the same text directly:
from exports import onboarding_guide
print(onboarding_guide("web-crawler", provider="iproyal", country="jp"))
print(onboarding_guide("web-crawler", provider="iproyal-isp"))
Public API (exports.py)
| Function |
Returns |
Raises |
get_proxy_url(provider, country=None, sticky_minutes=None, session=None, proxy_id=None) |
str proxy URL |
ProxyNotConfiguredError if creds/proxy missing; ValueError on bad provider/country/param |
get_proxy_for_skill(skill_name) |
str proxy URL |
ProxyNotConfiguredError (multi-line onboarding guide) if unbound, provider gone, creds or ISP proxy missing |
onboarding_guide(skill_name, provider="iproyal", country="<cc>", proxy_id=None) |
str onboarding text |
ValueError on bad provider |
list_providers() |
list[dict] — {provider, kind, configured, …} + bound_skills |
never |
set_binding(skill_name, provider, country=None, sticky_minutes=None, session=None, proxy_id=None) |
None |
ValueError on bad provider/country/param or unregistered ISP proxy |
unset_binding(skill_name) |
None |
never |
add_isp_proxy(proxy_id, host, port, username, password, socks_port=None, label=None) |
None |
ValueError on bad id/host/port |
remove_isp_proxy(proxy_id, force=False) |
list of still-bound skills |
ValueError if bound and not force |
list_isp_proxies() |
list[dict] — {proxy_id, endpoint, socks_endpoint, label, bound_skills} (creds redacted) |
never |
test_proxy(provider, country=None, proxy_id=None, timeout=15) |
dict — {ok, exit_ip, geo_country, latency_ms} |
ProxyNotConfiguredError / ValueError |
Sticky bounds: sticky_minutes ∈ 1..10080 (7 days). sticky_minutes requires
session (IPRoyal's lifetime- only applies to a session-).
Per-request only — no global proxy
Same rule as sc-vpn: never export HTTP_PROXY=... from this skill's URLs.
Pass proxies= to the specific request only. Setting global env vars will
break unrelated skills (notably sc-proxy traffic for paid APIs).
Troubleshooting
| Error |
Cause |
Fix |
Skill 'X' has no proxy binding |
bindings has no entry for X |
python3 scripts/onboard.py X --provider iproyal --country <cc> (or --provider iproyal-isp) |
... USERNAME / ... PASSWORD not found |
gateway creds never saved (or removed from .env) |
python3 scripts/setup_provider.py iproyal (or re-run onboard.py) |
ISP proxy 'X' is not registered |
binding references an id absent from .byo-proxy.json |
python3 scripts/add_isp_proxy.py X --host … --port … --username … --password … |
... bound to unknown provider |
bindings references a provider that no longer exists |
rebind, or bind_skill.py X --unset |
sticky_minutes requires a session id |
--sticky without --session |
add --session <id> (IPRoyal's lifetime- needs session-) |
sticky_minutes must be between 1 and 10080 |
out of range |
max is 7 days |
ValueError: Unknown country code 'XX' |
not in IPRoyal's supported list |
see references/iproyal.md |
test_proxy returns ok=false |
wrong creds/host, expired account, network |
check the dashboard; for ISP re-register the proxy string |
Files
byo-proxy/
├── SKILL.md
├── exports.py # public API for other skills
├── scripts/
│ ├── onboard.py # one-shot: register (if needed) + bind + test
│ ├── setup_provider.py # interactive gateway credential setup
│ ├── add_isp_proxy.py # register/list/remove dedicated ISP proxies
│ ├── list_providers.py # show providers + ISP proxies + bindings
│ ├── bind_skill.py # set/unset skill→provider binding
│ └── test_proxy.py # verify exit IP via ifconfig.co
└── references/
├── iproyal.md # residential gateway: params, sticky sessions
└── iproyal-isp.md # dedicated static IPs: per-IP endpoint + auth
1---2name: byo-proxy3version: 0.2.04description: |5 Bring-your-own proxy: per-skill country bindings (rotating + sticky sessions) and dedicated static IPs, opt-in routing.67 Use when the user wants paid residential/static IPs or per-skill geo routing (e.g. bind web-crawler to JP, add IPRoyal account, pin one fixed IP to a skill, route this scrape via DE).8delivery: script9metadata:10 source: https://skillmd.com/skills/starchild-ai-agent/byo-proxy11 starchild:12 emoji: "🌐"13 skillKey: byo-proxy14 requires:15 bins: [python3]16user-invocable: true17author: starchild18tags: [proxy, residential, static-ip, geo, byo, iproyal]1920---2122# byo-proxy — bring-your-own proxy2324Users supply their own proxy account (currently **IPRoyal**); this skill stores25the credentials, maintains a `skill → provider` binding table, and exposes a tiny26Python API that other skills can opt into.2728This skill **does not run a proxy server** and **does not intercept any traffic**.29It is a configuration center plus a URL builder. Other skills only behave differently30if they explicitly `import` from `exports.py`.3132## Boundaries vs. existing proxy skills3334| Skill | What it does | When |35|---|---|---|36| `sc-vpn` | Internal VPN gateway, 18 fixed countries, no auth | Last resort for geo-blocked requests inside Starchild |37| `transparent-proxy-maintenance` | Maintain the platform's billing proxy plugins | Ops work on `sc-proxy` |38| **`byo-proxy`** (this) | Manage user's own provider keys + per-skill bindings | User wants residential IPs, paid accounts, country granularity beyond sc-vpn's 18, or a dedicated fixed IP |3940## Supported providers4142| Provider | Kind | Endpoint | IP behaviour | Auth |43|---|---|---|---|---|44| `iproyal` | gateway | `geo.iproyal.com:12321` | rotates; sticky ≤ 7 days per session | account username + password |45| `iproyal-isp` | isp | **per-IP** `host:port` (e.g. `191.116.125.248:12323`) | **dedicated, never changes** | per-proxy username + password |4647Two shapes of "fixed IP":4849- **Sticky session** (`iproyal` + `--session` + `--sticky`) → same exit IP for up to50 **7 days**, then pool rotation can move it. Cheap (per GB).51- **Dedicated static IP** (`iproyal-isp`) → an IP reserved for you that **never52 changes**. Priced per IP, unlimited traffic. This is the "permanent fixed IP".5354Adding more providers later: add an entry to `PROVIDERS` + a URL builder in55`exports.py`. See `references/iproyal.md` (residential) and56`references/iproyal-isp.md` (dedicated).5758## Storage5960- **Account credentials** (gateway providers) → `/data/workspace/.env` (same convention61 as `polymarket`, `birdeye`, `coingecko`). Keys: `IPROYAL_USERNAME`, `IPROYAL_PASSWORD`.62- **Bindings + ISP proxy inventory** → `/data/workspace/.byo-proxy.json`:63 ```json64 {65 "bindings": { "web-crawler": { "provider": "iproyal", "country": "jp",66 "session": "crawler-jp", "sticky_minutes": 360 } },67 "isp_proxies": { "jp-1": { "host": "191.116.125.248", "port": 12323,68 "socks_port": 12324, "username": "…", "password": "…",69 "label": "Tokyo ISP" } }70 }71 ```72 ISP credentials are per-IP, so they live here (keyed by local `proxy_id`) rather73 than in `.env`. Both files are edited only through scripts; agents should not74 hand-edit. Legacy bindings-only files are migrated automatically on next save.7576## User workflow7778```bash79SKILL=/data/workspace/skills/byo-proxy8081# ── Residential gateway (rotating / sticky) ──────────────────────────────────82# 0. One-shot onboarding — prompts for creds only if missing, binds, live-tests:83python3 $SKILL/scripts/onboard.py web-crawler --provider iproyal --country jp8485# 1. Register credentials (interactive — prompts for username/password)86python3 $SKILL/scripts/setup_provider.py iproyal8788# 2. Bind a skill (long-term preference)89python3 $SKILL/scripts/bind_skill.py web-crawler --provider iproyal --country jp90# Pin one exit IP for up to 7 days (sticky needs a session id):91python3 $SKILL/scripts/bind_skill.py web-crawler --provider iproyal --country jp \92 --session crawler-jp --sticky 360 # 6 hours9394# ── Dedicated static IP (permanent) ─────────────────────────────────────────95# 3. Register a purchased ISP proxy (interactive if flags omitted), then bind:96python3 $SKILL/scripts/add_isp_proxy.py jp-1 \97 --host 191.116.125.248 --port 12323 --socks-port 12324 \98 --username <user> --password <pass> --label "Tokyo ISP"99python3 $SKILL/scripts/bind_skill.py web-crawler --provider iproyal-isp --proxy-id jp-1100# Or one-shot: python3 $SKILL/scripts/onboard.py web-crawler --provider iproyal-isp101102# ── Inspect / verify / clean up ────────────────────────────────────────────103python3 $SKILL/scripts/list_providers.py # providers, ISP proxies, bindings104python3 $SKILL/scripts/test_proxy.py iproyal --country jp105python3 $SKILL/scripts/test_proxy.py iproyal-isp --proxy-id jp-1106python3 $SKILL/scripts/bind_skill.py web-crawler --unset107python3 $SKILL/scripts/add_isp_proxy.py --list108python3 $SKILL/scripts/add_isp_proxy.py --remove jp-1 [--force]109```110111## How other skills consume it112113Two patterns. Both raise `ProxyNotConfiguredError` on misconfiguration — never114silent fallback (a proxy user is debugging a geo/identity problem; silently falling115through to a direct connection makes that debugging much harder).116117### Pattern A — explicit, one-off118119```python120import sys, requests121sys.path.insert(0, "/data/workspace/skills/byo-proxy")122from exports import get_proxy_url123124p = get_proxy_url(provider="iproyal", country="jp") # rotating125p = get_proxy_url(provider="iproyal", country="jp",126 session="crawler-jp", sticky_minutes=360) # sticky 6h127p = get_proxy_url(provider="iproyal-isp", proxy_id="jp-1") # dedicated IP128r = requests.get("https://example.com", proxies={"http": p, "https": p}, timeout=30)129```130131### Pattern B — bound, long-term132133Use when a skill always wants to route through whatever the user configured for it:134135```python136import sys, requests137sys.path.insert(0, "/data/workspace/skills/byo-proxy")138from exports import get_proxy_for_skill, ProxyNotConfiguredError139140try:141 p = get_proxy_for_skill("web-crawler") # caller declares its own name142except ProxyNotConfiguredError as e:143 # The exception message IS a multi-line onboarding guide for the user —144 # surface it verbatim. It includes the signup URL, pricing note, and the145 # one-shot `onboard.py` command to fix the situation.146 raise SystemExit(str(e))147148r = requests.get(url, proxies={"http": p, "https": p}, timeout=30)149```150151`get_proxy_for_skill` is **provider-agnostic**: it returns the right URL whether the152user bound a rotating country, a sticky session, or a dedicated ISP IP. A skill that153does **not** import it is unaffected, even if the user has bindings configured.154Opt-in only.155156### Onboarding for unconfigured skills157158When `get_proxy_for_skill("X")` raises because nothing is configured for `X`, the159exception message is **already a complete onboarding script**: signup URL, pricing,160credential location, and the exact `onboard.py` command to run. Agents that surface161this error to a user will naturally walk them through registration and binding — no162extra logic needed in the calling skill.163164If a calling skill wants to render its own onboarding UI (instead of relying on the165error message), it can import the same text directly:166167```python168from exports import onboarding_guide169print(onboarding_guide("web-crawler", provider="iproyal", country="jp"))170print(onboarding_guide("web-crawler", provider="iproyal-isp"))171```172173## Public API (`exports.py`)174175| Function | Returns | Raises |176|---|---|---|177| `get_proxy_url(provider, country=None, sticky_minutes=None, session=None, proxy_id=None)` | `str` proxy URL | `ProxyNotConfiguredError` if creds/proxy missing; `ValueError` on bad provider/country/param |178| `get_proxy_for_skill(skill_name)` | `str` proxy URL | `ProxyNotConfiguredError` (multi-line onboarding guide) if unbound, provider gone, creds or ISP proxy missing |179| `onboarding_guide(skill_name, provider="iproyal", country="<cc>", proxy_id=None)` | `str` onboarding text | `ValueError` on bad provider |180| `list_providers()` | `list[dict]` — `{provider, kind, configured, …}` + `bound_skills` | never |181| `set_binding(skill_name, provider, country=None, sticky_minutes=None, session=None, proxy_id=None)` | `None` | `ValueError` on bad provider/country/param or unregistered ISP proxy |182| `unset_binding(skill_name)` | `None` | never |183| `add_isp_proxy(proxy_id, host, port, username, password, socks_port=None, label=None)` | `None` | `ValueError` on bad id/host/port |184| `remove_isp_proxy(proxy_id, force=False)` | `list` of still-bound skills | `ValueError` if bound and not `force` |185| `list_isp_proxies()` | `list[dict]` — `{proxy_id, endpoint, socks_endpoint, label, bound_skills}` (creds redacted) | never |186| `test_proxy(provider, country=None, proxy_id=None, timeout=15)` | `dict` — `{ok, exit_ip, geo_country, latency_ms}` | `ProxyNotConfiguredError` / `ValueError` |187188Sticky bounds: `sticky_minutes` ∈ 1..10080 (7 days). `sticky_minutes` **requires**189`session` (IPRoyal's `lifetime-` only applies to a `session-`).190191## Per-request only — no global proxy192193Same rule as `sc-vpn`: never `export HTTP_PROXY=...` from this skill's URLs.194Pass `proxies=` to the specific request only. Setting global env vars will195break unrelated skills (notably `sc-proxy` traffic for paid APIs).196197## Troubleshooting198199| Error | Cause | Fix |200|---|---|---|201| `Skill 'X' has no proxy binding` | bindings has no entry for X | `python3 scripts/onboard.py X --provider iproyal --country <cc>` (or `--provider iproyal-isp`) |202| `... USERNAME / ... PASSWORD not found` | gateway creds never saved (or removed from `.env`) | `python3 scripts/setup_provider.py iproyal` (or re-run `onboard.py`) |203| `ISP proxy 'X' is not registered` | binding references an id absent from `.byo-proxy.json` | `python3 scripts/add_isp_proxy.py X --host … --port … --username … --password …` |204| `... bound to unknown provider` | bindings references a provider that no longer exists | rebind, or `bind_skill.py X --unset` |205| `sticky_minutes requires a session id` | `--sticky` without `--session` | add `--session <id>` (IPRoyal's `lifetime-` needs `session-`) |206| `sticky_minutes must be between 1 and 10080` | out of range | max is 7 days |207| `ValueError: Unknown country code 'XX'` | not in IPRoyal's supported list | see `references/iproyal.md` |208| `test_proxy` returns `ok=false` | wrong creds/host, expired account, network | check the dashboard; for ISP re-register the proxy string |209210## Files211212```213byo-proxy/214├── SKILL.md215├── exports.py # public API for other skills216├── scripts/217│ ├── onboard.py # one-shot: register (if needed) + bind + test218│ ├── setup_provider.py # interactive gateway credential setup219│ ├── add_isp_proxy.py # register/list/remove dedicated ISP proxies220│ ├── list_providers.py # show providers + ISP proxies + bindings221│ ├── bind_skill.py # set/unset skill→provider binding222│ └── test_proxy.py # verify exit IP via ifconfig.co223└── references/224 ├── iproyal.md # residential gateway: params, sticky sessions225 └── iproyal-isp.md # dedicated static IPs: per-IP endpoint + auth226```