136 lines
8.2 KiB
Markdown
136 lines
8.2 KiB
Markdown
# proxyctl
|
|
|
|
`proxyctl` is a keyboard-driven Linux TUI for coordinating one **Active Profile** across independently switchable proxy **Targets**. It manages proxy configuration surfaces; it does not run a proxy server.
|
|
|
|
## Supported systems
|
|
|
|
The v1 binaries target Linux on amd64 and arm64. General TUI behavior and the Shell Target are distribution-independent. The supported Target boundaries are:
|
|
|
|
- **Shell:** Bash and Zsh only.
|
|
- **APT:** Debian-family systems with `apt-config` and `apt.conf.d`.
|
|
- **Docker daemon:** Docker installations managed by systemd.
|
|
- **Docker containers/builds:** the standard per-user Docker client `config.json` model.
|
|
- **GNOME:** sessions exposing the expected `org.gnome.system.proxy` settings schemas.
|
|
|
|
Unavailable Targets are hidden from the main panel; `?` shows every built-in Target and its detection evidence.
|
|
|
|
## Install
|
|
|
|
### Verified release binary
|
|
|
|
Download the binary for your architecture together with `SHA256SUMS`, then verify it before installing:
|
|
|
|
```sh
|
|
grep 'proxyctl-linux-amd64$' SHA256SUMS | sha256sum -c - # substitute arm64 when needed
|
|
chmod +x proxyctl-linux-amd64 # use proxyctl-linux-arm64 on arm64
|
|
install -m 0755 proxyctl-linux-amd64 "$HOME/.local/bin/proxyctl"
|
|
proxyctl version
|
|
proxyctl version --short # exact value only, for scripts
|
|
```
|
|
|
|
Release output is two single binaries, not packages or archives. The project does not publish deb, rpm, AUR, Snap, Flatpak, or similar packages.
|
|
|
|
### Install from source with Go
|
|
|
|
Go 1.24 or newer is required. From a source checkout:
|
|
|
|
```sh
|
|
go install ./cmd/proxyctl
|
|
```
|
|
|
|
The executable is placed in `GOBIN`, or in `$(go env GOPATH)/bin` when `GOBIN` is unset. Ensure that directory is on `PATH`. Source builds report `dev` unless a release version is injected by release automation.
|
|
|
|
## First use and Profiles
|
|
|
|
Start the Target panel with no arguments:
|
|
|
|
```sh
|
|
proxyctl
|
|
```
|
|
|
|
Press `p` for Proxy Profile management, `n` to create a Profile, enter a name and proxy URL, and press Ctrl+S to save. Single mode applies one URL to HTTP, HTTPS, and ALL/SOCKS. Ctrl+T selects advanced mode for separate values. Bypass accepts hostnames, domain suffixes, IPv4, IPv6, and CIDR entries. Select the Profile and press `a` or Enter to make it the Active Profile.
|
|
|
|
The main panel shows the Active Profile. Use arrows or `j`/`k` to select an Available Target, Space to toggle it, `r` to refresh detection, `?` for details, and `q` or Escape to leave. A Target cannot be enabled without an Active Profile, but previously managed configuration can still be disabled.
|
|
|
|
Profiles are human-readable under the user's XDG configuration directory (normally `~/.config/proxyctl/profiles.json`) and are stored owner-only because proxy URLs may contain credentials.
|
|
|
|
## Shell integration
|
|
|
|
A child TUI cannot change its parent Shell. Install the one-time Bash/Zsh startup hook:
|
|
|
|
```sh
|
|
proxyctl shell install
|
|
```
|
|
|
|
Restart or source the startup file once. Thereafter the wrapper reloads proxy exports and unsets after `proxyctl` exits. The Shell Target emits conventional upper- and lower-case `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY` forms. Remove the hook with:
|
|
|
|
```sh
|
|
proxyctl shell uninstall
|
|
```
|
|
|
|
Fish and other Shells are intentionally unsupported in v1.
|
|
|
|
## What each Target affects
|
|
|
|
1. **Shell** — commands started by integrated Bash/Zsh sessions. It does not change existing processes, system services, Docker, or desktop settings.
|
|
2. **APT** — persistent APT package operations across Shell and privilege boundaries through a tool-owned `apt.conf.d` overlay. It does not configure other package managers and requires no service restart.
|
|
3. **Docker daemon** — daemon operations such as registry access. It does not set container networking or container/build defaults. Every change reloads systemd and immediately restarts Docker; confirm only when disruption to running work is acceptable.
|
|
4. **Docker containers/builds** — proxy variables and build arguments for future containers and builds via the owning user's Docker client configuration. It does not affect existing containers, the Docker CLI connection, or the daemon.
|
|
5. **GNOME** — GNOME system proxy settings used by compatible desktop applications. It does not rewrite browser-specific profiles or configure non-GNOME desktops.
|
|
|
|
proxyctl prefers isolated, tool-owned overlays. Where that is impossible it records original values and a last-applied fingerprint so disable/reset can restore prior state safely.
|
|
|
|
## Target states
|
|
|
|
- **Enabled:** actual managed configuration matches the Active Profile.
|
|
- **Disabled:** no managed or positively recognized external proxy configuration was detected.
|
|
- **External:** a recognized proxy configuration exists but is not owned by proxyctl.
|
|
- **Drifted:** managed configuration exists but no longer matches the Active Profile, including partial failures or configuration left when the final Profile is deleted.
|
|
|
|
External detection is best-effort; Disabled does not claim that every possible configuration source was exhaustively searched.
|
|
|
|
## Permissions, sudo, and restarts
|
|
|
|
User Targets normally need only user-file permissions. APT and Docker daemon files generally require authority to write system locations, and Docker daemon operations require authority to reload/restart its systemd service.
|
|
|
|
proxyctl **never** runs `sudo`, `pkexec`, or another elevation mechanism. Permission failures are reported normally. If system Targets are wanted, the user must explicitly start `sudo proxyctl`; under sudo, the invoking user remains the owner of Profiles, Shell, Docker client, and GNOME configuration while current root authority is available to system Targets. In a direct root login, root is the owner. Review the Docker restart warning before confirming any daemon change.
|
|
|
|
## Diagnose, reset, and remove
|
|
|
|
Run read-only diagnostics for Profile validity, storage permissions, required commands, Target availability/state, and Target-specific authority:
|
|
|
|
```sh
|
|
proxyctl doctor
|
|
```
|
|
|
|
Before removal, restore every managed Target. The command asks for confirmation and does nothing when declined:
|
|
|
|
```sh
|
|
proxyctl reset
|
|
proxyctl shell uninstall
|
|
```
|
|
|
|
Inspect failures and rerun until reset reports no failed managed Target. Then remove the installed executable and, after retaining any desired logs, remove empty proxyctl configuration/state directories. Do not delete recovery state before a successful reset because it may be needed to restore original settings.
|
|
|
|
## Privacy and safety boundaries
|
|
|
|
proxyctl has no telemetry, automatic update checks, or automatic proxy-connectivity tests. It does not contact the network on its own. Local diagnostic logs are credential-redacted and bounded in size. Proxy credentials remain present where a selected Target requires them, so normal local file security still matters.
|
|
|
|
proxyctl does **not** manage or supervise proxy processes such as Clash, sing-box, or Xray. It does not manage subscriptions, nodes, latency, routing rules, transparent proxying, TUN/iptables/nftables, arbitrary services or commands, plugins, or a complete headless Profile/Target CLI.
|
|
|
|
Deferred integrations include DNF, Git-specific settings, npm/pip, arbitrary systemd services, Firefox policies, Chromium launch flags, KDE and other desktops, Snap/Ubuntu Core, Fish, Windows, macOS, distribution packages, mouse interaction, and cross-Target rollback. Conventional Shell variables may already cover some deferred command-line tools.
|
|
|
|
Support is limited to the Linux architectures and Target boundaries above. When reporting an issue, include `proxyctl version`, redacted `proxyctl doctor` output, distribution/desktop/Shell details, and the affected Target/state. Never include unredacted proxy credentials.
|
|
|
|
## Build and verification
|
|
|
|
Create reproducible Linux binaries and checksums without packages or archives:
|
|
|
|
```sh
|
|
VERSION=v1.0.0 ./scripts/build-release.sh
|
|
sha256sum -c dist/SHA256SUMS
|
|
file dist/proxyctl-linux-amd64 dist/proxyctl-linux-arm64
|
|
```
|
|
|
|
`./scripts/test-release.sh` builds twice, compares binaries and checksum manifests, verifies both checksums, and checks ELF architectures. `./scripts/verify-clean-machine.sh` uses an isolated identity and XDG roots to exercise `go install`, Profile and hermetic Target workflows, doctor, reset cancellation, Shell install/uninstall, removal, and unchanged host-state snapshots.
|