sc-vpn

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:[email protected]:8080" https://ifconfig.me

# Route ONE request through Brazil
curl -x "http://br:[email protected]: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}:[email protected]:8080",
        "http":  f"http://{region}:[email protected]: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:[email protected]:8080"
export HTTPS_PROXY="http://jp:[email protected]: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:[email protected]: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:[email protected]: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