2.7 KiB
Security and operational boundaries
Privileges
User Targets normally require only access to user-owned files. APT and Docker daemon configuration generally require root authority.
proxyctl never starts sudo, pkexec, or another elevation mechanism. Run sudo proxyctl explicitly when system Targets are needed. Under sudo, the invoking user remains the owner of Profiles, Shell integration, Docker client configuration, and GNOME settings; root authority is used for system Targets. A direct root login uses root as the owner.
Docker daemon changes reload systemd and restart Docker immediately after confirmation.
Configuration recovery
proxyctl prefers isolated, tool-owned overlays. Where shared configuration must be edited, it records the original value and a fingerprint of the last applied state.
Restore and reset operations refuse to overwrite configuration that changed after proxyctl applied it. Recovery metadata must not be deleted before a successful reset.
Use:
proxyctl doctor
proxyctl reset
proxyctl shell uninstall
Inspect and resolve all failures before removing the executable or state directory.
Credentials and privacy
Proxy URLs may contain credentials. Profile, recovery, and managed credential-bearing files use restrictive permissions. Docker daemon configuration is owner-only while proxyctl manages credential-bearing proxy values.
The TUI, diagnostics, errors, command output, and bounded local operation logs defensively redact credentials. Profile editor frames obscure URL user information. Credentials remain present in underlying configuration where a selected Target requires them, so host file security still matters.
proxyctl has:
- no telemetry
- no automatic update checks
- no automatic proxy-connectivity tests
The user-initiated Protocol Probe contacts only the entered endpoint, performs protocol handshakes, and never forwards traffic through the proxy.
Scope
proxyctl configures proxy settings; it 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 plugins.
It currently excludes DNF, Git-specific settings, npm/pip settings, arbitrary systemd services, browser policies, KDE, Fish, Windows, macOS, distribution packages, mouse interaction, and cross-Target rollback.
Support is limited to the Linux architectures and Targets documented in the README. When reporting an issue, include:
proxyctl version- redacted
proxyctl doctoroutput - distribution and desktop/Shell details
- affected Target and state
Never include unredacted proxy credentials.