Anesthesia

Anesthesia is a small Linux-first CLI/TUI wrapper around sing-box for connecting to a VLESS endpoint from the terminal.

What it does

• Saves one VLESS URL locally.
• Imports http:// and https:// subscription URLs.
• Validates and parses the URL.
• Generates a sing-box client config.
• Starts sing-box as a subprocess.
• Exposes a local SOCKS5 proxy on 127.0.0.1:10808.
• Optionally routes all system traffic through a TUN interface (--tun).
• Provides both CLI commands and an interactive arrow-key menu.

What it does not do

• It does not implement the VLESS protocol itself.
• It does not package sing-box inside the binary.
• It does not target Windows in the MVP.

Installation

Prebuilt binary

Each tagged release ships a standalone Linux x86_64 binary on the Releases page.

curl -fsSL -o anesthesia \
  https://github.com/jesuspeterson342-dot/anesthesia/releases/latest/download/anesthesia-linux-x86_64
chmod +x anesthesia
./anesthesia --version

A matching anesthesia-linux-x86_64.sha256 checksum is published alongside it. The binary still needs a system sing-box (see below).

PyPI

pip install anesthesia

Arch Linux (AUR)

A prebuilt-binary package is provided in packaging/aur/:

# once published to the AUR
paru -S anesthesia-bin   # or: yay -S anesthesia-bin

Python development install

make install-dev

sing-box backend

Anesthesia requires a system sing-box binary.

• Arch Linux: sudo pacman -S --needed sing-box
• Debian/Ubuntu: sudo apt install sing-box
• Fedora: sudo dnf install -y sing-box

If sing-box is missing, anesthesia connect and the interactive UI offer auto-installation through the detected package manager.

Usage

Run the interactive menu:

anesthesia

CLI commands:

anesthesia connect
anesthesia connect --tun
anesthesia disconnect
anesthesia import "https://..."
anesthesia servers
anesthesia use 2
anesthesia update
anesthesia current
anesthesia status
anesthesia url set "vless://..."
anesthesia url delete
anesthesia logs
anesthesia doctor
anesthesia help

First launch

On first start, if no connection source is saved:

1. The program asks for a VLESS URL.
2. It accepts either a direct vless://... URL or a subscription https://... URL.
3. It saves it to ~/.config/anesthesia/config.json.
4. For subscriptions, it downloads the list and lets you choose a server.
5. It generates ~/.local/state/anesthesia/singbox.json.
6. It starts sing-box.

On later starts, the saved URL is reused automatically.

TUN mode (system-wide traffic)

By default anesthesia connect only opens a local SOCKS5 proxy — nothing uses it unless an app is explicitly configured to. anesthesia connect --tun instead creates a TUN network interface and routes all system traffic (not just one app) through the tunnel, including DNS.

TUN mode needs sing-box to hold CAP_NET_ADMIN/CAP_NET_RAW (so it can create the interface and manage routes without running fully as root). Anesthesia checks for this and offers to grant it once via:

sudo setcap cap_net_admin,cap_net_raw=eip "$(command -v sing-box)"

This persists on the binary until it's reinstalled/upgraded, so it's only needed once.

Notes:

• The VLESS outbound here is TCP-only (Reality + XTLS Vision carries no UDP). System DNS is hijacked and resolved over DNS-over-TCP through the tunnel, but anything else that prefers UDP first (e.g. HTTP/3 / QUIC) will fail once and transparently fall back to TCP — expected, not a bug.
• anesthesia status shows Mode: System-wide (tun: anesthesia0) when connected this way.
• anesthesia disconnect tears down the interface and routes along with the sing-box process.

Storage paths

• Config: ~/.config/anesthesia/config.json
• State: ~/.local/state/anesthesia/state.json
• Logs: ~/.local/state/anesthesia/anesthesia.log
• Generated sing-box config: ~/.local/state/anesthesia/singbox.json
• Imported subscription cache: ~/.local/state/anesthesia/subscription.json

Build a single binary

make build

This creates:

dist/anesthesia

Build command used by the project:

python -m PyInstaller --onefile --name anesthesia anesthesia/__main__.py

E2E subscription test

The project includes a real end-to-end subscription test that uses:

• a real subscription URL
• the built binary dist/anesthesia
• a system sing-box
• curl

Required environment variables:

export ANESTHESIA_E2E_SUBSCRIPTION_URL="https://example.com/sub/xxxx"
export ANESTHESIA_E2E_SERVER_ID=1

Optional:

export ANESTHESIA_E2E_BINARY=dist/anesthesia

Run it with:

make build
make test-e2e

Remove the program

Delete the binary and local data:

rm -f dist/anesthesia
rm -rf ~/.config/anesthesia ~/.local/state/anesthesia

Security notes

• The VLESS URL is stored locally on the machine.
• config.json is written with mode 600.
• sing-box is used as the backend; Anesthesia does not implement VLESS itself.
• Logs never intentionally store the full VLESS URL.
• Logged URLs are masked to hide the UUID and query parameters.
• Log files are kept at mode 600 and rotated (1 MB × 3) to avoid unbounded growth.

Contributing

Issues and pull requests are welcome. Before opening a PR:

make install-dev
make test

CI runs the test suite on Python 3.11–3.13 for every push and pull request.

License

Anesthesia is free software licensed under the GNU General Public License v3.0 or later.

You can redistribute it and/or modify it under the terms of the GPL as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.