README.md
July 20, 2026 ยท View on GitHub
unbox
Unbox is a CLI tool for sing-box that has commands:
examples: Show usage examplesconf: Works with sing-box config file to- Deduplicate (compares all fields but
tag) - Convert sing-box config outbounds to URLs
- Remove unreachable nodes from sing-box config file
- Deduplicate (compares all fields but
keep: Keep connection alive, auto switch proxyparse: Convert file with URLs to sing-box config
Supported URLs: vless://,hysteria2:// or hy2://,trojan://
Experimental: anytls://, ss://, tuic://
Screenshot
Expand
Install
Expand
Docker
Example keep command with sing-box Clash API:
docker run aceberg/unbox keep -a "http://192.168.0.11:9090"
Or use ghcr.io/aceberg/unbox
Binary
All available binaries are listed in the latest release.
For amd64 there is an apt repo.
Android and Termux
For arm64 there are android and termux.deb files.
Deduplicate
Expand
unbox conf -d -o sing-box.json
| Key | Description | Default |
|---|---|---|
| -d | Deduplicate | |
| -o | Path to sing-box config file |
Convert sing-box config outbounds to URLs
Expand
unbox conf -i sing-box.json > URLs.txt
| Key | Description | Default |
|---|---|---|
| -i | Path to sing-box config file |
Remove unreachable nodes from sing-box config
Expand
unbox conf -a "http://127.0.0.1:9090" -o sing-box.json
| Key | Description | Default |
|---|---|---|
| -a | URL of sing-box Clash API | |
| -as | Clash API secret | |
| -l | Timeout for proxy delay (latency) check (ms) | 3000 |
| -n | Number of best servers to save (0 - save all) | 0 |
| -o | Path to sing-box config file | |
| -u | URL to test proxies. https://www.gstatic.com/generate_204 will be used if empty |
Keep connection alive and switch if not
Expand
unbox keep -a "http://127.0.0.1:9090"
| Key | Description | Default |
|---|---|---|
| -a | URL of sing-box Clash API | |
| -as | Clash API secret | |
| -da | Delay between checks of all proxy servers (seconds). Use 0 to disable | 300 |
| -db | Delay between checks of 4-5 backup servers (seconds). Use 0 to disable | 30 |
| -dm | Delay between checks of the main server (seconds). Use 0 to disable | 5 |
| -ds | Delay between auto switch to a faster proxy attempts (seconds). Use 0 to disable | 300 |
| -l | Timeout for proxy delay (latency) check (ms) | 3000 |
| -n | Number of backup servers | 5 |
| -st | Switch to a faster proxy if it is at least this many ms faster than the current one (ms) | 50 |
| -u | URL to test proxies. https://www.gstatic.com/generate_204 will be used if empty |
Convert file with URLs to sing-box config
Expand
Here VLESS.txt is a file with vless://,hysteria2://,trojan:// links. Unbox will ignore anything else in the file, including other protocols and comments.
unbox parse -f VLESS.txt
In this example tmpl.json is a template sing-box config and sing-box.json is where unbox will put generated config.
unbox parse -f VLESS.txt -t tmpl.json -o sing-box.json -j
| Key | Description | Default |
|---|---|---|
| -f | Path to file with URLs | VLESS.txt |
| -j | Validate and Indent JSON output | |
| -n | Rename tags. If used, will rename tags to tag1, tag2... | |
| -o | Path to output sing-box config file | |
| -t | Path to template sing-box config. Example here. There are only two variables available in template: {{ .Unbox_tags }} and {{ .Unbox_outbounds }} |