Metadata-Version: 2.4
Name: anesthesia
Version: 0.1.1
Summary: Terminal VLESS connection manager built on sing-box.
Author-email: Davud <admin@davudlabs.xyz>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/jesuspeterson342-dot/anesthesia
Project-URL: Repository, https://github.com/jesuspeterson342-dot/anesthesia
Project-URL: Issues, https://github.com/jesuspeterson342-dot/anesthesia/issues
Keywords: vless,sing-box,proxy,vpn,cli,tui,socks5
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: System :: Networking
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: platformdirs>=4.2.0
Requires-Dist: questionary>=2.0.1
Requires-Dist: requests>=2.32.0
Requires-Dist: rich>=13.7.1
Requires-Dist: typer>=0.12.3
Provides-Extra: dev
Requires-Dist: pyinstaller>=6.8.0; extra == "dev"
Requires-Dist: pytest>=8.2.0; extra == "dev"
Dynamic: license-file

# 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](https://github.com/jesuspeterson342-dot/anesthesia/releases).

```bash
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

```bash
pip install anesthesia
```

### Arch Linux (AUR)

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

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

### Python development install

```bash
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:

```bash
anesthesia
```

CLI commands:

```bash
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:

```bash
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

```bash
make build
```

This creates:

```bash
dist/anesthesia
```

Build command used by the project:

```bash
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:

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

Optional:

```bash
export ANESTHESIA_E2E_BINARY=dist/anesthesia
```

Run it with:

```bash
make build
make test-e2e
```

## Remove the program

Delete the binary and local data:

```bash
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:

```bash
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](LICENSE).

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.
