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, then n, to create a Proxy Profile.
Enter a name and proxy URL; press Ctrl+S to save.
Press p on the dashboard to select the Active Profile.
Select a Target with ↑/↓ or j/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.

3.4 KiB Raw Permalink Blame History