https://github.com/hugobatista/slimproxy
Slim forward proxy CLI with IP allowlisting, Basic auth, and destination host filtering — built on proxy.py
https://github.com/hugobatista/slimproxy
cli forward-proxy http-proxy proxy proxy-py python
Last synced: 12 days ago
JSON representation
Slim forward proxy CLI with IP allowlisting, Basic auth, and destination host filtering — built on proxy.py
- Host: GitHub
- URL: https://github.com/hugobatista/slimproxy
- Owner: hugobatista
- License: mit
- Created: 2026-05-25T13:39:45.000Z (13 days ago)
- Default Branch: main
- Last Pushed: 2026-05-25T16:57:39.000Z (12 days ago)
- Last Synced: 2026-05-25T17:31:06.507Z (12 days ago)
- Topics: cli, forward-proxy, http-proxy, proxy, proxy-py, python
- Language: Python
- Size: 65.4 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
[](https://go.hugobatista.com/gh/slimproxy/releases)
[](https://go.hugobatista.com/gh/slimproxy/actions/workflows/lint.yml)
[](https://go.hugobatista.com/gh/slimproxy/actions/workflows/test.yml)
[](https://pypi.org/project/slimproxy)
[](https://pypi.org/project/slimproxy)
[](https://pypi.org/project/slimproxy)
🛡️ **slimproxy** — A lightweight forward proxy CLI built on `proxy.py` — deploy anywhere Python runs.
**The problem**: Your enterprise-managed desktop sits behind a corporate forward proxy that intercepts and inspects TLS traffic to certain endpoints (AI APIs, for example). You can't control the proxy settings or install software — the machine is locked down.
**The workaround**: Deploy slimproxy on a **second machine** on the same network — an unmanaged one you control (a Raspberry Pi, an old laptop, a cloud VM). That machine connects directly to the internet. Point your tools on the locked-down desktop at slimproxy, and traffic flows through the unmanaged machine, bypassing the corporate inspection entirely.
```
Locked-down desktop → slimproxy on unmanaged host → internet (direct)
HTTPS_PROXY=http://unmanaged:3128 no inspection
```
**Why not Squid?** Squid doesn't run on Windows without Cygwin, needs a config file, and is overkill for a raw TCP forwarder. slimproxy is `pip install` + one command on any OS.
## Installation
Install globally via `uv` (recommended):
```bash
uv tool install slimproxy
```
Or via `pip`:
```bash
pip install slimproxy
```
Or run directly without installing:
```bash
uvx slimproxy
```
Or from source (clone + run):
```bash
git clone https://github.com/hugobatista/slimproxy.git
cd slimproxy
uv sync
uv run slimproxy run
```
Or via Docker:
```bash
docker build -t slimproxy .
```
## Usage
### `run` — Start the proxy server
```bash
slimproxy run \
--port 3128 \
--basic-auth myuser:password123 \
--allow-ips "192.168.1.0/24,10.0.0.0/8" \
--allow-dests "api.opencode.ai,api.github.com,models.dev"
```
All options are optional. With no flags, the proxy listens on `0.0.0.0:3128` and forwards everything without auth or filtering.
Use `--wizard` for an interactive guided setup that prompts for each option:
```bash
slimproxy run --wizard
```
Configure your client to use it:
```bash
# Linux / macOS
export HTTPS_PROXY=http://myuser:password123@host:3128
# Windows CMD
set HTTPS_PROXY=http://myuser:password123@host:3128
# Windows PowerShell
$env:HTTPS_PROXY="http://myuser:password123@host:3128"
```
### `check` — Detect SSL inspection
```bash
slimproxy check api.opencode.ai api.github.com
```
Connects to each target over TLS and prints the certificate issuer. If the issuer is your company, SSL inspection is active.
## Options
| Flag | Default | Description |
|------|---------|-------------|
| `--hostname` | `0.0.0.0` | Address to bind to |
| `--port` | `3128` | Listen port |
| `--basic-auth` | *(none)* | Enable Basic auth (`user:password` format) |
| `--allow-ips` | *(none)* | Comma-separated client CIDRs (e.g. `192.168.1.0/24`). When omitted, all IPs are allowed. |
| `--allow-dests` | *(none)* | Comma-separated upstream hosts (e.g. `api.opencode.ai`). When omitted, all destinations are allowed. |
| `--log-level` | `INFO` | Log level |
| `--timeout` | `10` | Connection timeout in seconds |
| `--wizard` | *(off)* | Guided interactive setup — prompts for hostname, port, auth, IP/dest allowlists, log level, and timeout. On Windows, also handles firewall elevation. Requires an interactive terminal. |
| `--firewall-rule` | *(off)* | Add Windows Firewall inbound rule for the proxy port (Windows only, requires admin) |
## Security
All three filters are optional, independent, and disabled by default — when a filter is
omitted, the corresponding access is unrestricted:
- **IP allowlist**: Clients outside the specified CIDR ranges are rejected with `418`
- **Basic auth**: Password checked against `--basic-auth` value on every CONNECT request
- **Dest allowlist**: Upstream hosts not in the list are rejected with `403`
The proxy speaks vanilla HTTP CONNECT — no TLS interception, no decryption. The end-to-end TLS handshake happens between the client and the target server.
Note: When `--basic-auth` is used on a non-localhost interface, credentials
are transmitted in cleartext HTTP and can be intercepted by anyone on the
network.
### Windows Firewall
On Windows, pass `--firewall-rule` to auto-add an inbound firewall rule for the proxy port:
```bash
slimproxy run --port 3128 --firewall-rule
```
If not running as Administrator, a UAC prompt will appear to elevate. The rule is removed when the proxy stops. On other platforms the flag is accepted but ignored.
## Docker
```bash
# Build
docker build -t slimproxy .
# Run
docker run -it --rm \
-p 3128:3128 \
slimproxy run --basic-auth myuser:password123
```
Published via GHCR on tagged releases:
```bash
docker run -it --rm \
-p 3128:3128 \
ghcr.io/hugobatista/slimproxy:latest run --basic-auth myuser:password123
```