GeezerVison

singbox2proxy

Supported Protocols

Installation

Quick Install (no Python required)

curl -fsSL https://raw.githubusercontent.com/nichind/singbox2proxy/main/scripts/install.sh | sh

irm https://raw.githubusercontent.com/nichind/singbox2proxy/main/scripts/install.ps1 | iex

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/nichind/singbox2proxy/main/scripts/install.sh | sh -s -- --python

# Windows
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/nichind/singbox2proxy/main/scripts/install.ps1))) -Mode python

Standalone Binary (no Python, no pip)

sb2p "vless://..."

With pip

pip install singbox2proxy 

uv pip install singbox2proxy 

git clone https://github.com/nichind/singbox2proxy.git
cd singbox2proxy
pip install -e .

pip install git+https://github.com/nichind/singbox2proxy.git

Python Usage

from singbox2proxy import SingBoxProxy

proxy = SingBoxProxy("vless://...")
response = proxy.request("GET", "https://api.ipify.org?format=json")  # IF curl-cffi is installed, it will be used; otherwise, requests will be used.
print(response.status_code, response.text)  # 200, {"ip":"..."}

import requests
from singbox2proxy import SingBoxProxy

proxy = SingBoxProxy("hy2://...")
session = requests.Session()
session.proxies = proxy.proxy_for_requests  # {"http": "http://127.0.0.1:<port>", "https": "http://127.0.0.1:<port>"}
response = session.get("https://api.ipify.org?format=json")
print(response.status_code, response.text)  # 200, {"ip":"..."}

from singbox2proxy import SingBoxProxy
import aiohttp

async def main():
    proxy = SingBoxProxy("vmess://...")
    async with aiohttp.ClientSession(proxy=proxy.socks5_proxy_url or proxy.http_proxy_url) as session:
        async with session.get("https://api.ipify.org?format=json") as response:
            print(response.status, await response.text())  # 200, {"ip":"..."}

Chaining

Note

See what protocols can be used as middleman proxies at supported protocols

from singbox2proxy import SingBoxProxy

proxy1 = SingBoxProxy("vmess://...")
proxy2 = SingBoxProxy("vless://...", chain_proxy=proxy1)

response = proxy2.request("GET", "https://api.ipify.org?format=json")
print(response.status_code, response.text)  # 200, {"ip": "<proxy2's IP>"}
# Here, requests made through `proxy2` will first go through `proxy1`, then proxy1 will forward the request to proxy2, and finally proxy2 will send the request to the target server.

Batch Engine

from singbox2proxy import SingBoxBatch

# From a list
batch = SingBoxBatch(["vless://...", "trojan://...", "ss://..."])

# From a file (one URL per line, # comments)
batch = SingBoxBatch.from_file("proxies.txt")

# With options
batch = SingBoxBatch(urls, batch_size=30, log_level="error")

# By index
resp = batch[0].get("https://api.ipify.org?format=json")
print(resp.json())  # {"ip": "..."}

# SOCKS URL for external clients
print(batch[0].socks_url)   # socks5://127.0.0.1:40000

# With requests library
import requests
requests.get("https://example.com", proxies=batch[0].proxies)

# Iterate
for proxy in batch:
    print(proxy.protocol, proxy.socks_url)

for result in batch.check(timeout=5, workers=10):
    if result.working:
        print(f"{result.protocol} OK {result.ip} {result.latency_ms:.0f}ms")

# Or check + filter in one go
for proxy in list(batch):
    if not proxy.check().working:
        batch.remove(proxy)
# batch now contains only working proxies

# Via URL string
batch = SingBoxBatch.from_file("proxies.txt", chain_proxy="trojan://upstream")

# Via existing SingBoxProxy (same API as SingBoxProxy's chain_proxy)
from singbox2proxy import SingBoxProxy
upstream = SingBoxProxy("trojan://upstream")
batch = SingBoxBatch.from_file("proxies.txt", chain_proxy=upstream)

# Add more proxies (starts a new sing-box process, returns new handles)
new = batch.add(["trojan://new-one", "vmess://another"])
print(new[0].socks_url)

# Remove a proxy
batch.remove(batch[0])
print(len(batch))  # updated count

batch.stop()

# Or use as context manager
with SingBoxBatch.from_file("proxies.txt") as batch:
    for proxy in batch:
        proxy.get("https://example.com")

TUN Mode (System-Wide VPN)

Important

Very experimental, use at your own risk.

# Requires root/admin privileges
proxy = SingBoxProxy("vless://...", tun_enabled=True)

# All system traffic is now routed through the proxy
# Use like a normal VPN connection

Relay - Share Your Proxy Connection

from singbox2proxy import SingBoxProxy

# Relay through an existing proxy
proxy = SingBoxProxy(
    "vless://original-proxy-url",
    relay_protocol="ss",  # Protocol for the relay server
    relay_host="192.168.1.100",  # Your server's IP (auto-detected if not specified)
    relay_port=8443  # Port for the relay server (auto-assigned if not specified)
)

# Or create a direct connection relay (no proxy URL needed)
direct_relay = SingBoxProxy(
    None,  # No proxy - direct connection
    relay_protocol="ss",
    relay_host="my-server.com",
    relay_port=8443
)

# Get the shareable URL
print(f"Share this URL: {proxy.relay_url}")
# Output: ss://[email protected]:8443?type=tcp&security=none#singbox2proxy-relay

# Keep the proxy running
input("Press Enter to stop...")
proxy.stop()

System Proxy Configuration

Note

The system proxy settings will be restored to their original state when the SingBoxProxy instance is closed or goes out of scope, but multiple instances may interfere with each other, may be better to backup your initial settings before using this feature.

# Automatically sets system proxy and restores on exit
with SingBoxProxy("vless://...", set_system_proxy=True) as proxy:
    # Your web browser and other apps will now use the proxy
    print(f"System proxy configured to use {proxy.http_proxy_url}")

CLI

Note

If the singbox2proxy or sb2p command isn't working in your terminal, use python -m singbox2proxy <command>, uv run -m singbox2proxy <command>, etc. instead.

Basic Commands

sb2p "vmess://eyJ2IjoiMiIsInBzIj..."

sb2p "ss://..." --http-port 8080 --socks-port False  # Socks disabled

sb2p "trojan://..." --test
# sing-box 1.12.4
#   http   http://127.0.0.1:57539
#   socks  socks5://127.0.0.1:57540
# test:
#   latency  46/129/296 ms (min/avg/max)
#   exit-ip  203.0.113.42
#   result   PASS

sb2p --cmd version
sb2p -C "check -c config.json"

Batch Proxy Checking

# Basic check
sb2p --check proxies.txt

# Save working proxies, sorted by latency
sb2p --check proxies.txt -o working.txt

# Tune concurrency
sb2p --check proxies.txt --workers 20 --batch-size 100 --timeout 8

# Check through an upstream proxy (chain)
sb2p "trojan://upstream" --check proxies.txt

# Quiet mode — summary only
sb2p --check proxies.txt -q
# 78/200 working (39%) in 8.1s

# Verbose mode — see dead proxies too
sb2p --check proxies.txt -v

Proxy Chaining

sb2p "vmess://..." "vless://..." "hy2://..." --chain

Note

See what protocols can be used as middleman proxies at supported protocols

Relay - Share Your Proxy Connection

# Relay through an existing proxy
sb2p "ss://original-proxy" --relay ss

# Direct connection relay (no proxy, just share your server's internet)
sb2p --relay ss

# Output includes a shareable URL + QR code:
#   relay  vless://uuid@your-ip:port?type=tcp&security=none#singbox2proxy-relay

Note

Consider also setting a custom --relay-port to avoid port change, since the default is to auto-assign an available port.

sb2p --relay vmess --uuid-seed "my-persistent-seed" --relay-port 12345
#   relay  vmess://[email protected]:12345

sb2p --relay vmess --uuid-seed "my-persistent-seed" --relay-port 54321
#   relay  vmess://[email protected]:54321

sb2p "ss://..." --relay ss --relay-host "myserver.com" --relay-port 8443

Note

QR rendering requires the qrcode package: pip install qrcode

Configuration Management

sb2p "vless://..." --config-only

sb2p "vmess://..." --output-config config.json

Logging Options

sb2p "ss://..." --verbose

sb2p "hy2://..." --quiet

TUN Mode (System-Wide VPN)

# Linux/macOS (requires sudo)
sudo sb2p "vless://..." --tun

# Windows (run as Administrator)
sb2p "vless://..." --tun

Important

Very experimental, use at your own risk.

System Proxy

# Set system proxy on start, restore on stop
sb2p "vless://..." --set-system-proxy

Note

The system proxy settings will be restored to their original state when the SingBoxProxy instance is closed or goes out of scope, but multiple instances may interfere with each other, may be better to backup your initial settings before using this feature.

Discaimer

Consider leaving a star ⭐