User guide

Profiles

A Proxy Profile contains proxy URLs and bypass rules. The Active Profile is the source applied to every Enabled Target.

Open Profile management with m:

n: create a Profile
e or Enter: edit the selected Profile
d: safely delete the selected Profile
Ctrl+S: save the editor
Ctrl+T: switch between Single and Advanced modes

Single mode applies one URL to HTTP, HTTPS, and ALL/SOCKS. Advanced mode accepts separate values. A bare host:port is normalized to http://.

Bypass entries may be comma- or newline-delimited hostnames, domain suffixes, IPv4/IPv6 addresses, or CIDR ranges. The editor normalizes and deduplicates valid entries.

Protocol Probe

Press Ctrl+D while editing the Single proxy URL to run an explicit handshake probe. It reports HTTP and SOCKS5 support without forwarding traffic or contacting another endpoint.

If both protocols are detected, the editor changes to Advanced mode and fills HTTP/HTTPS with http:// and ALL/SOCKS with socks5://. GNOME cannot represent socks5h remote-DNS semantics; use Advanced mode with socks5 when GNOME must use that endpoint.

Dashboard

Press p to search and select the Active Profile. Select Targets with arrows or j/k; Space runs the contextual action:

Enable a Disabled Target
Disable an Enabled Target
Apply Profile to an External Target
Resolve a Drifted Target by reapplying the Active Profile or restoring the original configuration

Restoration refuses to overwrite configuration that changed after proxyctl applied it.

Other controls:

r: refresh detection
u: show unavailable Targets
Tab: switch between Target list and details
Page Up/Page Down: scroll details
e: expand or collapse the current error
x: acknowledge the current error
?: contextual Help
q or Esc: close the current page/dialog; q exits from the unobscured dashboard
Ctrl+C: request exit

Conflicting actions are disabled while a mutation runs. Exit requests cancel cancellable work and wait for the operation to settle safely.

Target states

Enabled: managed configuration matches the Active Profile.
Disabled: no managed or positively recognized external proxy configuration was detected.
External: recognized proxy configuration exists outside proxyctl ownership.
Drifted: managed configuration no longer matches the Active Profile, including partial failures.

External detection is best-effort. Disabled does not claim that every possible configuration source was exhaustively searched.

What each Target affects

Shell — future commands in integrated Bash/Zsh sessions. It does not change existing processes or services.
APT — persistent Debian-family package operations through a tool-owned apt.conf.d overlay.
Docker daemon — registry and daemon traffic. Every change reloads systemd and restarts Docker.
Docker containers/builds — proxy defaults for future containers and builds in the owning user's Docker client configuration. It does not configure the daemon.
GNOME — compatible desktop applications using GNOME system proxy settings. It does not rewrite browser-specific profiles.

Responsive and accessible TUI

At 100×28 and larger, Targets and details are side by side. At 60–99 columns they use one column. Below 60×16, proxyctl displays a minimum-size warning and restores interaction state after resize.

Focus and state never rely on color alone. States include symbols and words such as ● Enabled, ○ Disabled, ◇ External, ! Drifted, and … Checking. No Nerd Font is required. Set NO_COLOR to disable color.

Confirmation dialogs start on Cancel. The TUI uses the terminal alternate screen and restores the previous screen after exit.

Profiles are normally stored at ~/.config/proxyctl/profiles.json with owner-only permissions.

3.8 KiB Raw Blame History Unescape Escape