slimproxy 0.1.0

Slim forward proxy with IP, auth, and destination filtering

🛡️ 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):

uv tool install slimproxy

Or via pip:

pip install slimproxy

Or run directly without installing:

uvx slimproxy

Or from source (clone + run):

git clone https://github.com/hugobatista/slimproxy.git
cd slimproxy
uv sync
uv run slimproxy run

Or via Docker:

docker build -t slimproxy .

Usage

run — Start the proxy server

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:

slimproxy run --wizard

Configure your client to use it:

# 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

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:

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

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

docker run -it --rm \
  -p 3128:3128 \
  ghcr.io/hugobatista/slimproxy:latest run --basic-auth myuser:password123