proxyctl
proxyctl is a keyboard-driven Linux TUI that applies one Active Profile to independently switchable proxy Targets. It configures existing system components; it does not run a proxy server.
Supported systems
Linux amd64 and arm64 are supported.
| Target | Scope |
|---|---|
| Shell | Bash and Zsh sessions |
| APT | Debian-family apt configuration |
| Docker daemon | systemd-managed Docker service |
| Docker containers/builds | Per-user Docker client defaults |
| GNOME | org.gnome.system.proxy settings |
Unavailable Targets are hidden by default. Press u to show them and ? for contextual help.
Install
Release binary
Download the binary for your architecture together with SHA256SUMS, then verify and install it:
grep 'proxyctl-linux-amd64$' SHA256SUMS | sha256sum -c - # use arm64 when needed
chmod +x proxyctl-linux-amd64
install -m 0755 proxyctl-linux-amd64 "$HOME/.local/bin/proxyctl"
proxyctl version
From source
Go 1.24 or newer is required:
go install ./cmd/proxyctl
Quick start
proxyctl
- Press
m, thenn, to create a Proxy Profile. - Enter a name and proxy URL; press Ctrl+S to save.
- Press
pon the dashboard to select the Active Profile. - Select a Target with
↑/↓orj/k. - Press Space to enable, disable, apply, or resolve that Target.
Common keys:
| Key | Action |
|---|---|
p |
Switch Active Profile |
m |
Manage Profiles |
| Space | Run the selected Target action |
r |
Refresh Target detection |
u |
Show unavailable Targets |
? |
Contextual help |
q / Esc |
Back or exit |
For Profile modes, Protocol Probe, Target states, complete keyboard behavior, and accessibility details, see docs/user-guide.md.
Shell integration
A child TUI cannot modify its parent Shell. Install the Bash/Zsh startup hook once:
proxyctl shell install
Restart or source the startup file. Remove the hook with:
proxyctl shell uninstall
System Targets and permissions
APT and Docker daemon changes normally require root authority. proxyctl never invokes sudo, pkexec, or another elevation mechanism itself. Start it explicitly with sudo proxyctl when system Targets are required.
Docker daemon changes reload systemd and restart Docker. Review the confirmation before proceeding.
See docs/security.md for privilege boundaries, credential handling, restoration guarantees, and project scope.
Diagnose, reset, and remove
proxyctl doctor # read-only diagnostics
proxyctl reset # restore managed Targets
proxyctl shell uninstall # remove Shell startup integration
Complete a successful reset before deleting recovery state or uninstalling the executable.
Privacy
proxyctl has no telemetry, automatic update checks, or automatic proxy-connectivity tests. Network traffic is generated only by the user-initiated Protocol Probe. Diagnostic output and logs redact credentials; stored Profile and Target configuration can still contain credentials and is protected with restrictive file permissions.