# Roentgen

Roentgen is a Linux CLI/TUI for importing 3x-ui subscription link lists and controlling the local machine's proxy intent through a root-owned controller. The implementation follows [.scratch/linux-first-release/spec.md](.scratch/linux-first-release/spec.md).

This is an implementation candidate. Full native-TUN forwarding and managed-probe lifecycle acceptance on the required current ALT Xray package is incomplete. The supplied VM passed diagnostics transport, terminal authentication, enabled/blocked reboot protection, and recovery checks. The available ALT test VM and its refreshed Sisyphus repository currently supply Xray 26.3.27. Activation rejects that release before changing enabled intent. This build currently gates activation on the researched Xray 26.10.29 configuration contract. That gate is not a claim that the full release acceptance matrix has passed.

## Build

Use Rust with Cargo. The Linux runtime additionally needs ALT's `libnftnl-devel` and `libmnl-devel` packages. SQLite is bundled into the executable; Xray remains the distribution-owned `/usr/bin/xray` executable.

```sh
cargo build --release --features linux-runtime
```

The default build contains the CLI/TUI and controller library. Installation and daemon execution require the `linux-runtime` feature. Roentgen never downloads or replaces Xray.

## Install and use

Run the privileged installation step after validating the runtime on a disposable ALT VM:

```sh
sudo target/release/roentgen install
roentgen subscription add --name Personal
roentgen configuration list
roentgen configuration select ID
roentgen enable
roentgen status --json
roentgen disable
```

Subscription add/edit reads its secret URL from a prompt or one stdin line. Do not put it in a command argument. Import never chooses a configuration or enables proxying. Invalid and unsupported entries remain visible. An accepted refresh can clear selection while leaving enabled intent and protection in place.

Run `roentgen` to open the TUI. Use h/l to switch screens, j/k to move, Enter to select/open, Space to enable/disable, s to choose a viewed subscription, J/K to cycle subscriptions, / to filter, d for details, t for Ping, b for Speed, x to unset, c for the console, e for the editor and ? for help. Text fields preserve literal typing. Closing the TUI leaves the background service running.

Mutations use server-side polkit authorization. Noninteractive commands never request interactive authentication. Interactive commands register a terminal polkit agent. Public status and lists omit URLs, passwords and raw imported links.

Settings and subscription definitions live in `/etc/roentgen/config.toml`; retained entries, explicit selection and enabled intent live in `/var/lib/roentgen/state.sqlite3`. Runtime files belong under `/run/roentgen`. Refresh changes and selection reconciliation commit in one SQLite transaction. The early guard reads its separate durable input from `/etc/roentgen/guard.toml`.

## Recovery and removal

```sh
sudo roentgen recover --disable
sudo roentgen uninstall
sudo roentgen uninstall --purge
```

Explicit recovery persists disabled intent before releasing owned capture and protection. Default uninstall retains saved configuration/data. Purge also removes them. Neither operation removes the system Xray package. The dedicated service account remains to avoid reassigning its UID to an unrelated process.

## Validation

Run tests only on the supplied disposable ALT VM. Compile acceptance executables with `cargo test --features linux-runtime --no-run`; copy the executable and test artifacts to the VM or run Cargo there. CLI tests support `ROENTGEN_TEST_BINARY` when the executable is installed at another path.

`tests/controller_acceptance.rs` exercises the public controller with real TOML/SQLite persistence and HTTP/runtime boundary fixtures. `tests/cli_acceptance.rs` exercises the executable interface. `tests/diagnostics_acceptance.rs` uses the public controller and CLI with verified TLS, the production probe configuration, and a real non-TUN Xray Trojan path. Its VM wrapper is `tests/vm_diagnostics_acceptance.py`. `tests/vm_guard_acceptance.py` checks real kernel traffic through the guard CLI. `tests/vm_boot_acceptance.py` checks enabled/blocked reboot ordering, controller crashes, and recovery from a stopped controller. `tests/vm_controller_acceptance.py` checks the CLI/system-bus/polkit boundary, using temporary integration fixtures when the packaged Xray is too old for product installation. The Python checks refuse to run outside the authorized `altctlrs` VM and require its explicit VM-only marker.

The VM guard checks use a temporary network namespace and veth pair, never the workstation's network. Preserve a powered-off checkpoint before running them, and restore it after validation. Credentials and VM reset settings belong outside this repository.

The latest VM run passed 20 Rust acceptance tests and 29 VM workflow checks. See the [review and qualification limits](docs/implementation-review.md) and [captured output](docs/validation/linux-vm-continued.txt). The VM checkpoint was restored after validation.