sing-box-config-converter

Generate a sing-box client config from a server config, with optional QR code output.

Supported protocols: hysteria2, shadowsocks, trojan

Requirements

• Python 3.10+
• uv

Quick Start with uvx

No installation required — run directly with:

uvx sing-box-config-converter server.json

With QR code support:

uvx --with "sing-box-config-converter[qr]" sing-box-config-converter server.json

Installation

uv sync --extra qr

The --extra qr flag installs qrcode[pil] for QR code support. Omit it if you don't need QR output.

Usage

uv run sing-box-config-converter <server_config> [server_address] [options]

Arguments

Options

Examples

Generate a client config (server address auto-detected):

uv run sing-box-config-converter /etc/sing-box/config.json

Specify the server address explicitly:

uv run sing-box-config-converter /etc/sing-box/config.json 203.0.113.42

Use TUN mode and save a QR code image:

uv run sing-box-config-converter config.json 203.0.113.42 --use-tun --qr-dir ./qr

Print a QR code in the terminal:

uv run sing-box-config-converter config.json --show-terminal-qr

If --show-terminal-qr QR code is too large to fit in the terminal, try --qr-dir to save QR code as a PNG, and use imgcat to display it:

uvx imgcat qr_client_config.png

Output

The generated client config includes:

• Outbounds — one per supported inbound in the server config; wrapped in a urltest selector when there are multiple
• DNS — fakeip for remote, 223.5.5.5 for local/direct
• Route — DNS hijack, private IP bypass, sniff
• Inbound — mixed (SOCKS5+HTTP) on a local port, or tun with auto_route

Notes

• QR codes encode the full client config JSON. Large configs may exceed QR capacity; consider sharing the config file directly if the QR is unreadable.