109 lines
3.4 KiB
Markdown
109 lines
3.4 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
go install ./cmd/proxyctl
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```sh
|
|
proxyctl
|
|
```
|
|
|
|
1. Press `m`, then `n`, to create a Proxy Profile.
|
|
2. Enter a name and proxy URL; press Ctrl+S to save.
|
|
3. Press `p` on the dashboard to select the Active Profile.
|
|
4. Select a Target with `↑`/`↓` or `j`/`k`.
|
|
5. 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](docs/user-guide.md).
|
|
|
|
## Shell integration
|
|
|
|
A child TUI cannot modify its parent Shell. Install the Bash/Zsh startup hook once:
|
|
|
|
```sh
|
|
proxyctl shell install
|
|
```
|
|
|
|
Restart or source the startup file. Remove the hook with:
|
|
|
|
```sh
|
|
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](docs/security.md) for privilege boundaries, credential handling, restoration guarantees, and project scope.
|
|
|
|
## Diagnose, reset, and remove
|
|
|
|
```sh
|
|
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.
|
|
|
|
## Documentation
|
|
|
|
- [User guide](docs/user-guide.md)
|
|
- [Security and operational boundaries](docs/security.md)
|
|
- [Development and release verification](docs/development.md)
|
|
- [Product specifications](docs/specs/)
|
|
- [Linux Target research](docs/research/linux-proxy-targets.md)
|