# 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)