SC-VPN Gateway
Internal VPN service for the Starchild platform. Provides exit nodes in 18 fixed countries — accessible only from within the Starchild internal network. No credentials or setup needed.
⚠️ When to Use
SC-VPN is a last resort, not a default. Most agent HTTP traffic already goes through sc-proxy (the platform's transparent billing proxy for paid APIs). Setting a global VPN proxy will break sc-proxy routing.
Use SC-VPN only when:
- A specific request is geo-blocked or returns a region error
- You need to appear from a specific country for a particular API call
- A target website/API refuses connections from the default exit
Always use per-request proxy (pass proxies= to requests.get() or -x to curl). Never set global HTTP_PROXY / HTTPS_PROXY environment variables
Available Countries
| Country |
Code |
Example Cities |
| 🇦🇺 Australia |
au |
Adelaide, Sydney, Melbourne |
| 🇨🇭 Switzerland |
ch |
Zürich |
| 🇩🇪 Germany |
de |
Berlin, Frankfurt |
| 🇯🇵 Japan |
jp |
Tokyo, Osaka |
| 🇲🇾 Malaysia |
my |
Kuala Lumpur |
| 🇲🇽 Mexico |
mx |
Querétaro |
| 🇹🇭 Thailand |
th |
Bangkok |
| 🇿🇦 South Africa |
za |
Johannesburg |
| 🇧🇷 Brazil |
br |
São Paulo, Fortaleza |
| 🇦🇷 Argentina |
ar |
Buenos Aires |
| 🇸🇬 Singapore |
sg |
Singapore |
| 🇭🇰 Hong Kong |
hk |
Hong Kong |
| 🇬🇧 United Kingdom |
gb |
London, Manchester |
| 🇳🇱 Netherlands |
nl |
Amsterdam |
| 🇫🇷 France |
fr |
Paris, Marseille |
| 🇸🇪 Sweden |
se |
Stockholm, Malmö |
| 🇪🇸 Spain |
es |
Madrid |
| 🇮🇹 Italy |
it |
Milan, Rome |
Only these 18 countries. Requests for other regions are rejected (502). The specific server per country is auto-selected daily based on latency.
Quick Start
curl (per-request proxy)
# Route ONE request through Japan
curl -x "http://jp:x@sc-vpn.internal:8080" https://ifconfig.me
# Route ONE request through Brazil
curl -x "http://br:x@sc-vpn.internal:8080" https://example.com/api
Python requests (per-request proxy)
import requests
def vpn_proxy(region: str) -> dict:
"""Return proxy dict for a given region code."""
return {
"https": f"http://{region}:x@sc-vpn.internal:8080",
"http": f"http://{region}:x@sc-vpn.internal:8080",
}
# Only the geo-blocked request goes through VPN
resp = requests.get("https://geo-restricted-api.example.com", proxies=vpn_proxy("jp"))
# All other requests go through normal sc-proxy routing (no proxies= arg)
resp2 = requests.get("https://api.coingecko.com/...")
❌ Do NOT do this
# WRONG — may influence other requests
export HTTP_PROXY="http://jp:x@sc-vpn.internal:8080"
export HTTPS_PROXY="http://jp:x@sc-vpn.internal:8080"
Region Selection
The username in the proxy URL selects the exit country:
| Input |
Resolves To |
jp or japan |
Japan |
au or australia |
Australia |
de or germany |
Germany |
ch or switzerland |
Switzerland |
th or thailand |
Thailand |
br or brazil |
Brazil |
ar or argentina |
Argentina |
mx or mexico |
Mexico |
my or malaysia |
Malaysia |
za or south_africa |
South Africa |
sg or singapore |
Singapore |
hk or hong_kong |
Hong Kong |
gb or uk or united_kingdom |
United Kingdom |
nl or netherlands |
Netherlands |
fr or france |
France |
se or sweden |
Sweden |
es or spain |
Spain |
it or italy |
Italy |
REST API
Base URL: http://sc-vpn.internal:8081
| Endpoint |
Description |
GET /api/tunnels |
Status of all 18 tunnels (region, latency, uptime) |
GET /api/status |
Gateway overview |
GET /api/usage |
Your traffic stats (identified by source IP) |
GET /health |
Health check |
Rate Limits
| Limit |
Default |
| Monthly quota per client |
500 GB |
| Max concurrent connections |
50 |
| Requests per second |
100 |
Clients identified by source IP. No API keys needed — internal network only.
Verify It Works
# Your real exit IP
curl https://ifconfig.me
# VPN exit IP (should be different, from Japan)
curl -x "http://jp:x@sc-vpn.internal:8080" https://ifconfig.me
Troubleshooting
| Problem |
Fix |
502 Bad Gateway: Unknown region |
Use one of: au, ch, de, jp, my, mx, th, za, br, ar, sg, hk, gb, nl, fr, se, es, it |
502 Bad Gateway: Tunnel not active |
Gateway may need restart — check /api/status |
400 Bad Request: No region specified |
Add username to proxy URL: http://jp:x@sc-vpn.internal:8080 |
DNS failure for sc-vpn.internal |
Only accessible from Starchild internal network |
| Other requests broken after using VPN |
You set global HTTP_PROXY — unset it immediately |
1---
2name: sc-vpn
3version: 1.0.2
4description: |
5 Route outbound HTTP through SC-VPN Gateway to bypass region restrictions.
6
7 Use when a script hits a geo block and needs to appear from a specific country (e.g. Binance 451, US-only news site, request as JP, KR exit IP).
8keywords: vpn, proxy, geo, region, ip, country, blocked, restricted, geo-restricted
9triggers:
10 - vpn
11 - proxy through
12 - different country
13 - appear from
14 - geo region
15 - IP address from
16 - access from japan
17 - need a VPN
18 - route through
19 - geo blocked
20 - region restricted
21
22metadata:
23 source: https://skillmd.com/skills/starchild-ai-agent/sc-vpn
24---
25
26# SC-VPN Gateway
27
28Internal VPN service for the Starchild platform. Provides exit nodes in **18 fixed countries** — accessible only from within the Starchild internal network. No credentials or setup needed.
29
30## ⚠️ When to Use
31
32**SC-VPN is a last resort, not a default.** Most agent HTTP traffic already goes through `sc-proxy` (the platform's transparent billing proxy for paid APIs). Setting a global VPN proxy will **break sc-proxy routing**.
33
34Use SC-VPN **only** when:
35- A specific request is **geo-blocked** or returns a region error
36- You need to appear from a **specific country** for a particular API call
37- A target website/API **refuses connections** from the default exit
38
39**Always use per-request proxy** (pass `proxies=` to `requests.get()` or `-x` to `curl`). **Never set global `HTTP_PROXY` / `HTTPS_PROXY` environment variables**
40
41## Available Countries
42
43| Country | Code | Example Cities |
44|---------|------|---------------|
45| 🇦🇺 Australia | `au` | Adelaide, Sydney, Melbourne |
46| 🇨🇭 Switzerland | `ch` | Zürich |
47| 🇩🇪 Germany | `de` | Berlin, Frankfurt |
48| 🇯🇵 Japan | `jp` | Tokyo, Osaka |
49| 🇲🇾 Malaysia | `my` | Kuala Lumpur |
50| 🇲🇽 Mexico | `mx` | Querétaro |
51| 🇹🇭 Thailand | `th` | Bangkok |
52| 🇿🇦 South Africa | `za` | Johannesburg |
53| 🇧🇷 Brazil | `br` | São Paulo, Fortaleza |
54| 🇦🇷 Argentina | `ar` | Buenos Aires |
55| 🇸🇬 Singapore | `sg` | Singapore |
56| 🇭🇰 Hong Kong | `hk` | Hong Kong |
57| 🇬🇧 United Kingdom | `gb` | London, Manchester |
58| 🇳🇱 Netherlands | `nl` | Amsterdam |
59| 🇫🇷 France | `fr` | Paris, Marseille |
60| 🇸🇪 Sweden | `se` | Stockholm, Malmö |
61| 🇪🇸 Spain | `es` | Madrid |
62| 🇮🇹 Italy | `it` | Milan, Rome |
63
64**Only these 18 countries.** Requests for other regions are rejected (502). The specific server per country is auto-selected daily based on latency.
65
66## Quick Start
67
68### curl (per-request proxy)
69
70```bash
71# Route ONE request through Japan
72curl -x "http://jp:x@sc-vpn.internal:8080" https://ifconfig.me
73
74# Route ONE request through Brazil
75curl -x "http://br:x@sc-vpn.internal:8080" https://example.com/api
76```
77
78### Python requests (per-request proxy)
79
80```python
81import requests
82
83def vpn_proxy(region: str) -> dict:
84 """Return proxy dict for a given region code."""
85 return {
86 "https": f"http://{region}:x@sc-vpn.internal:8080",
87 "http": f"http://{region}:x@sc-vpn.internal:8080",
88 }
89
90# Only the geo-blocked request goes through VPN
91resp = requests.get("https://geo-restricted-api.example.com", proxies=vpn_proxy("jp"))
92
93# All other requests go through normal sc-proxy routing (no proxies= arg)
94resp2 = requests.get("https://api.coingecko.com/...")
95```
96
97### ❌ Do NOT do this
98
99```bash
100# WRONG — may influence other requests
101export HTTP_PROXY="http://jp:x@sc-vpn.internal:8080"
102export HTTPS_PROXY="http://jp:x@sc-vpn.internal:8080"
103```
104
105## Region Selection
106
107The **username** in the proxy URL selects the exit country:
108
109| Input | Resolves To |
110|-------|-------------|
111| `jp` or `japan` | Japan |
112| `au` or `australia` | Australia |
113| `de` or `germany` | Germany |
114| `ch` or `switzerland` | Switzerland |
115| `th` or `thailand` | Thailand |
116| `br` or `brazil` | Brazil |
117| `ar` or `argentina` | Argentina |
118| `mx` or `mexico` | Mexico |
119| `my` or `malaysia` | Malaysia |
120| `za` or `south_africa` | South Africa |
121| `sg` or `singapore` | Singapore |
122| `hk` or `hong_kong` | Hong Kong |
123| `gb` or `uk` or `united_kingdom` | United Kingdom |
124| `nl` or `netherlands` | Netherlands |
125| `fr` or `france` | France |
126| `se` or `sweden` | Sweden |
127| `es` or `spain` | Spain |
128| `it` or `italy` | Italy |
129
130## REST API
131
132Base URL: `http://sc-vpn.internal:8081`
133
134| Endpoint | Description |
135|----------|-------------|
136| `GET /api/tunnels` | Status of all 18 tunnels (region, latency, uptime) |
137| `GET /api/status` | Gateway overview |
138| `GET /api/usage` | Your traffic stats (identified by source IP) |
139| `GET /health` | Health check |
140
141## Rate Limits
142
143| Limit | Default |
144|-------|---------|
145| Monthly quota per client | 500 GB |
146| Max concurrent connections | 50 |
147| Requests per second | 100 |
148
149Clients identified by source IP. No API keys needed — internal network only.
150
151## Verify It Works
152
153```bash
154# Your real exit IP
155curl https://ifconfig.me
156
157# VPN exit IP (should be different, from Japan)
158curl -x "http://jp:x@sc-vpn.internal:8080" https://ifconfig.me
159```
160
161## Troubleshooting
162
163| Problem | Fix |
164|---------|-----|
165| `502 Bad Gateway: Unknown region` | Use one of: au, ch, de, jp, my, mx, th, za, br, ar, sg, hk, gb, nl, fr, se, es, it |
166| `502 Bad Gateway: Tunnel not active` | Gateway may need restart — check `/api/status` |
167| `400 Bad Request: No region specified` | Add username to proxy URL: `http://jp:x@sc-vpn.internal:8080` |
168| DNS failure for `sc-vpn.internal` | Only accessible from Starchild internal network |
169| Other requests broken after using VPN | You set global `HTTP_PROXY` — unset it immediately |