{"id":30946376,"url":"https://github.com/nichind/singbox2proxy","last_synced_at":"2026-05-03T19:02:10.310Z","repository":{"id":313868664,"uuid":"1051628736","full_name":"nichind/singbox2proxy","owner":"nichind","description":"🐳 Use sing-box (v2ray, xray) proxies (VLESS + REALITY, VMess, Trojan, Shadowsocks, Hysteria, Hysteria2, TUIC, WireGuard, SSH) directly in your http clients, with chaining support and easy CLI + Relay your traffic to bypass WHITELISTS","archived":false,"fork":false,"pushed_at":"2026-05-03T17:37:58.000Z","size":341,"stargazers_count":37,"open_issues_count":1,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-03T18:40:34.694Z","etag":null,"topics":["hysteria2","proxy","python","python-module","shadowsocks","sing-box","socks5","trojan","tuic","v2ray","vless","vmess","xray"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/singbox2proxy/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nichind.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":"https://boosty.to/nichind"}},"created_at":"2025-09-06T11:55:47.000Z","updated_at":"2026-05-03T17:35:27.000Z","dependencies_parsed_at":"2025-09-29T07:10:41.081Z","dependency_job_id":"80e49614-680a-4e97-a51e-17cc87913929","html_url":"https://github.com/nichind/singbox2proxy","commit_stats":null,"previous_names":["nichind/singbox2proxy","nichind/sing-box2proxy"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/nichind/singbox2proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nichind%2Fsingbox2proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nichind%2Fsingbox2proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nichind%2Fsingbox2proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nichind%2Fsingbox2proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nichind","download_url":"https://codeload.github.com/nichind/singbox2proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nichind%2Fsingbox2proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32581021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hysteria2","proxy","python","python-module","shadowsocks","sing-box","socks5","trojan","tuic","v2ray","vless","vmess","xray"],"created_at":"2025-09-11T00:46:41.846Z","updated_at":"2026-05-03T19:02:10.304Z","avatar_url":"https://github.com/nichind.png","language":"Python","funding_links":["https://boosty.to/nichind"],"categories":[],"sub_categories":[],"readme":"## singbox2proxy \n\n[![Pip module installs total downloads](https://img.shields.io/pypi/dm/singbox2proxy.svg)](https://pypi.org/project/singbox2proxy/)[![Run Tests](https://github.com/nichind/singbox2proxy/actions/workflows/build.yml/badge.svg)](https://github.com/nichind/singbox2proxy/actions/workflows/build.yml) [![Upload Python Package to PyPI when a Release is Created](https://github.com/nichind/singbox2proxy/actions/workflows/publish.yml/badge.svg)](https://github.com/nichind/singbox2proxy/actions/workflows/publish.yml)\n\nIntegrate sing-box proxies into your python applications with ease on any device.\n\n- sing-box auto-install \u0026 easy management\n- zero dependencies for base functionality\n- seamless integration with existing applications\n- batch proxy engine with shared singbox process\n- tuned for best performance and latency in mind\n\n### Supported Protocols\n\nThis module supports these sing-box protocols:\n\n- VMess (`vmess://`)\n- VLESS (`vless://`)\n- Shadowsocks (`ss://`)\n- Trojan (`trojan://`)\n- Hysteria2* (`hy2://`, `hysteria2://`)\n- Hysteria* (`hysteria://`)\n- TUIC* (`tuic://`)\n- WireGuard (`wg://`)\n- SSH (`ssh://`)\n- HTTP/HTTPS (`http://`, `https://`)\n- SOCKS (`socks://`, `socks4://`, `socks5://`)\n- NaiveProxy* (`naive+https://`)\n\n*: Chaining as a middle proxy not supported, according to the [sing-box docs](https://sing-box.sagernet.org/configuration/inbound/)\n\n### Installation\n\n#### Quick Install (no Python required)\n\n**Linux / macOS:**\n```shell\ncurl -fsSL https://raw.githubusercontent.com/nichind/singbox2proxy/main/scripts/install.sh | sh\n```\n\n**Windows (PowerShell):**\n```powershell\nirm https://raw.githubusercontent.com/nichind/singbox2proxy/main/scripts/install.ps1 | iex\n```\n\nBy default this downloads a standalone binary. To install via Python/pip instead:\n```shell\n# Linux/macOS\ncurl -fsSL https://raw.githubusercontent.com/nichind/singbox2proxy/main/scripts/install.sh | sh -s -- --python\n\n# Windows\n\u0026 ([scriptblock]::Create((irm https://raw.githubusercontent.com/nichind/singbox2proxy/main/scripts/install.ps1))) -Mode python\n```\n\n#### Standalone Binary (no Python, no pip)\n\nDownload a pre-built binary from [Releases](https://github.com/nichind/singbox2proxy/releases) — just download, put anywhere in PATH, and use:\n```shell\nsb2p \"vless://...\"\n```\n\n#### With pip\n\n```shell\npip install singbox2proxy \n```\n\nwith [uv](https://pypi.org/project/uv/)\n\n```shell\nuv pip install singbox2proxy \n```\n\nbuild from source\n\n```shell\ngit clone https://github.com/nichind/singbox2proxy.git\ncd singbox2proxy\npip install -e .\n```\n\nor install directly from GitHub\n\n```shell\npip install git+https://github.com/nichind/singbox2proxy.git\n```\n\n### Python Usage\n\nUsing built-in client powered by [curl-cffi](https://pypi.org/project/curl-cffi/) or [requests](https://pypi.org/project/requests/)\n\n```python\nfrom singbox2proxy import SingBoxProxy\n\nproxy = SingBoxProxy(\"vless://...\")\nresponse = proxy.request(\"GET\", \"https://api.ipify.org?format=json\")  # IF curl-cffi is installed, it will be used; otherwise, requests will be used.\nprint(response.status_code, response.text)  # 200, {\"ip\":\"...\"}\n```\n\nIntegrating with your own HTTP client\n\n```python\nimport requests\nfrom singbox2proxy import SingBoxProxy\n\nproxy = SingBoxProxy(\"hy2://...\")\nsession = requests.Session()\nsession.proxies = proxy.proxy_for_requests  # {\"http\": \"http://127.0.0.1:\u003cport\u003e\", \"https\": \"http://127.0.0.1:\u003cport\u003e\"}\nresponse = session.get(\"https://api.ipify.org?format=json\")\nprint(response.status_code, response.text)  # 200, {\"ip\":\"...\"}\n```\n\nExample with aiohttp\n\n```python\nfrom singbox2proxy import SingBoxProxy\nimport aiohttp\n\nasync def main():\n    proxy = SingBoxProxy(\"vmess://...\")\n    async with aiohttp.ClientSession(proxy=proxy.socks5_proxy_url or proxy.http_proxy_url) as session:\n        async with session.get(\"https://api.ipify.org?format=json\") as response:\n            print(response.status, await response.text())  # 200, {\"ip\":\"...\"}\n```\n\n#### Chaining\n\nChained proxies allow you to route your traffic through multiple proxy servers if you'll ever need more privacy or easy restriction bypass. You can chain multiple proxies together by specifying a `chain_proxy` with a gate `SingBoxProxy` instance when creating a new `SingBoxProxy`.\n\n\u003e [!NOTE]\n\u003e See what protocols can be used as middleman proxies at [supported protocols](#supported-protocols)\n\n```python\nfrom singbox2proxy import SingBoxProxy\n\nproxy1 = SingBoxProxy(\"vmess://...\")\nproxy2 = SingBoxProxy(\"vless://...\", chain_proxy=proxy1)\n\nresponse = proxy2.request(\"GET\", \"https://api.ipify.org?format=json\")\nprint(response.status_code, response.text)  # 200, {\"ip\": \"\u003cproxy2's IP\u003e\"}\n# 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.\n```\n\n#### Batch Engine\n\nRun hundreds of proxies through shared sing-box processes (~30 MB per batch instead of per proxy):\n\n```python\nfrom singbox2proxy import SingBoxBatch\n\n# From a list\nbatch = SingBoxBatch([\"vless://...\", \"trojan://...\", \"ss://...\"])\n\n# From a file (one URL per line, # comments)\nbatch = SingBoxBatch.from_file(\"proxies.txt\")\n\n# With options\nbatch = SingBoxBatch(urls, batch_size=30, log_level=\"error\")\n```\n\n**Use proxies** — each one gets its own SOCKS5 port:\n\n```python\n# By index\nresp = batch[0].get(\"https://api.ipify.org?format=json\")\nprint(resp.json())  # {\"ip\": \"...\"}\n\n# SOCKS URL for external clients\nprint(batch[0].socks_url)   # socks5://127.0.0.1:40000\n\n# With requests library\nimport requests\nrequests.get(\"https://example.com\", proxies=batch[0].proxies)\n\n# Iterate\nfor proxy in batch:\n    print(proxy.protocol, proxy.socks_url)\n```\n\n**Check which ones work:**\n\n```python\nfor result in batch.check(timeout=5, workers=10):\n    if result.working:\n        print(f\"{result.protocol} OK {result.ip} {result.latency_ms:.0f}ms\")\n\n# Or check + filter in one go\nfor proxy in list(batch):\n    if not proxy.check().working:\n        batch.remove(proxy)\n# batch now contains only working proxies\n```\n\n**Chain through an upstream proxy:**\n\n```python\n# Via URL string\nbatch = SingBoxBatch.from_file(\"proxies.txt\", chain_proxy=\"trojan://upstream\")\n\n# Via existing SingBoxProxy (same API as SingBoxProxy's chain_proxy)\nfrom singbox2proxy import SingBoxProxy\nupstream = SingBoxProxy(\"trojan://upstream\")\nbatch = SingBoxBatch.from_file(\"proxies.txt\", chain_proxy=upstream)\n```\n\n**Add/remove at runtime:**\n\n```python\n# Add more proxies (starts a new sing-box process, returns new handles)\nnew = batch.add([\"trojan://new-one\", \"vmess://another\"])\nprint(new[0].socks_url)\n\n# Remove a proxy\nbatch.remove(batch[0])\nprint(len(batch))  # updated count\n```\n\n**Cleanup:**\n\n```python\nbatch.stop()\n\n# Or use as context manager\nwith SingBoxBatch.from_file(\"proxies.txt\") as batch:\n    for proxy in batch:\n        proxy.get(\"https://example.com\")\n```\n\n#### TUN Mode (System-Wide VPN)\n\nCreate a virtual network interface to route all system traffic through the proxy. This requires root/administrator privileges.\n\n\u003e [!IMPORTANT]\n\u003e Very experimental, use at your own risk.\n\n```python\n# Requires root/admin privileges\nproxy = SingBoxProxy(\"vless://...\", tun_enabled=True)\n\n# All system traffic is now routed through the proxy\n# Use like a normal VPN connection\n```\n\n#### Relay - Share Your Proxy Connection\n\nCreate a shareable proxy server that relays traffic through your existing proxy connection or provides direct internet access:\n\n```python\nfrom singbox2proxy import SingBoxProxy\n\n# Relay through an existing proxy\nproxy = SingBoxProxy(\n    \"vless://original-proxy-url\",\n    relay_protocol=\"ss\",  # Protocol for the relay server\n    relay_host=\"192.168.1.100\",  # Your server's IP (auto-detected if not specified)\n    relay_port=8443  # Port for the relay server (auto-assigned if not specified)\n)\n\n# Or create a direct connection relay (no proxy URL needed)\ndirect_relay = SingBoxProxy(\n    None,  # No proxy - direct connection\n    relay_protocol=\"ss\",\n    relay_host=\"my-server.com\",\n    relay_port=8443\n)\n\n# Get the shareable URL\nprint(f\"Share this URL: {proxy.relay_url}\")\n# Output: ss://uuid@192.168.1.100:8443?type=tcp\u0026security=none#singbox2proxy-relay\n\n# Keep the proxy running\ninput(\"Press Enter to stop...\")\nproxy.stop()\n```\n\n**Supported protocols:** `vmess`, `vless`, `trojan`, `ss`, `shadowsocks`, `socks`, `http`\n\n#### System Proxy Configuration\n\nAutomatically configure your OS proxy settings. This is a great alternative to TUN mode when you don't have root access.\n\n\u003e [!NOTE]\n\u003e 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.\n\n```python\n# Automatically sets system proxy and restores on exit\nwith SingBoxProxy(\"vless://...\", set_system_proxy=True) as proxy:\n    # Your web browser and other apps will now use the proxy\n    print(f\"System proxy configured to use {proxy.http_proxy_url}\")\n```\n\n### CLI\n\n\u003e [!NOTE]\n\u003e If the `singbox2proxy` or `sb2p` command isn't working in your terminal, use `python -m singbox2proxy \u003ccommand\u003e`, `uv run -m singbox2proxy \u003ccommand\u003e`, etc. instead.\n\n#### Basic Commands\n\nStart a single proxy:\n\n```shell\nsb2p \"vmess://eyJ2IjoiMiIsInBzIj...\"\n```\n\nSpecify custom ports:\n\n```shell\nsb2p \"ss://...\" --http-port 8080 --socks-port False  # Socks disabled\n```\n\nTest the proxy connection:\n\n```shell\nsb2p \"trojan://...\" --test\n# sing-box 1.12.4\n#   http   http://127.0.0.1:57539\n#   socks  socks5://127.0.0.1:57540\n# test:\n#   latency  46/129/296 ms (min/avg/max)\n#   exit-ip  203.0.113.42\n#   result   PASS\n```\n\nRun a sing-box subcommand:\n\n```shell\nsb2p --cmd version\nsb2p -C \"check -c config.json\"\n```\n\n#### Batch Proxy Checking\n\nCheck proxies from a file (one URL per line):\n\n```shell\n# Basic check\nsb2p --check proxies.txt\n\n# Save working proxies, sorted by latency\nsb2p --check proxies.txt -o working.txt\n\n# Tune concurrency\nsb2p --check proxies.txt --workers 20 --batch-size 100 --timeout 8\n\n# Check through an upstream proxy (chain)\nsb2p \"trojan://upstream\" --check proxies.txt\n\n# Quiet mode — summary only\nsb2p --check proxies.txt -q\n# 78/200 working (39%) in 8.1s\n\n# Verbose mode — see dead proxies too\nsb2p --check proxies.txt -v\n```\n\n#### Proxy Chaining\n\nChain multiple proxies (traffic flows: you -\u003e proxy1 -\u003e proxy2 -\u003e target):\n\n```shell\nsb2p \"vmess://...\" \"vless://...\" \"hy2://...\" --chain\n```\n\n\u003e [!NOTE]\n\u003e See what protocols can be used as middleman proxies at [supported protocols](#supported-protocols)\n\nThe first URL becomes the entry point, and the last URL connects to the target server.\n\n#### Relay - Share Your Proxy Connection\n\nCreate a shareable proxy server that relays traffic through your existing proxy connection, or provides direct internet access from your server:\n\n```shell\n# Relay through an existing proxy\nsb2p \"ss://original-proxy\" --relay ss\n\n# Direct connection relay (no proxy, just share your server's internet)\nsb2p --relay ss\n\n# Output includes a shareable URL + QR code:\n#   relay  vless://uuid@your-ip:port?type=tcp\u0026security=none#singbox2proxy-relay\n```\n\nSupported relay protocols: `vmess`, `trojan`, `ss`/`shadowsocks`, `socks`, `http`\n\n**Persistent relay URLs** with `--uuid-seed` (same seed = same URL every restart):\n\n\u003e [!NOTE]\n\u003e Consider also setting a custom `--relay-port` to avoid port change, since the default is to auto-assign an available port.\n\n```shell\nsb2p --relay vmess --uuid-seed \"my-persistent-seed\" --relay-port 12345\n#   relay  vmess://a1b2c3d4-...@203.0.113.42:12345\n\nsb2p --relay vmess --uuid-seed \"my-persistent-seed\" --relay-port 54321\n#   relay  vmess://a1b2c3d4-...@203.0.113.42:54321\n```\n\nCustom host and port:\n\n```shell\nsb2p \"ss://...\" --relay ss --relay-host \"myserver.com\" --relay-port 8443\n```\n\n\u003e [!NOTE]\n\u003e QR rendering requires the `qrcode` package: `pip install qrcode`\n\n#### Configuration Management\n\nGenerate configuration without starting:\n\n```shell\nsb2p \"vless://...\" --config-only\n```\n\nSave configuration to file:\n\n```shell\nsb2p \"vmess://...\" --output-config config.json\n```\n\n#### Logging Options\n\nEnable verbose logging:\n\n```shell\nsb2p \"ss://...\" --verbose\n```\n\nDisable all logging:\n\n```shell\nsb2p \"hy2://...\" --quiet\n```\n\n#### TUN Mode (System-Wide VPN)\n\nEnable TUN mode to route all system traffic through the proxy.\n\n```shell\n# Linux/macOS (requires sudo)\nsudo sb2p \"vless://...\" --tun\n\n# Windows (run as Administrator)\nsb2p \"vless://...\" --tun\n```\n\n\u003e [!IMPORTANT]\n\u003e Very experimental, use at your own risk.\n\n#### System Proxy\n\nAutomatically configure your OS to use the proxy.\n\n```shell\n# Set system proxy on start, restore on stop\nsb2p \"vless://...\" --set-system-proxy\n```\n\n\u003e [!NOTE]\n\u003e 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.\n\n### Discaimer\n\nI'm not responsible for possible misuse of this software. Please use it in accordance with the law and respect the terms of service of the services you access through proxies.\n\n#### Consider leaving a star ⭐\n\n[![Star History Chart](https://api.star-history.com/svg?repos=nichind/singbox2proxy\u0026type=Date)](https://github.com/nichind/singbox2proxy)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnichind%2Fsingbox2proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnichind%2Fsingbox2proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnichind%2Fsingbox2proxy/lists"}