dockprox

Inverse HTTP(S) proxy with SOCKS5 support — direct by default, route only what you choose.

Overview

dockprox is a local HTTP(S) proxy that dials destinations directly by default. Only hosts matched by a rule in your config are forwarded through a named upstream — SOCKS5, HTTP CONNECT, or explicit direct. It bridges HTTPS_PROXY-style clients (which speak HTTP CONNECT) to SOCKS5 upstreams, so tools like docker pull and az acr login transparently get a SOCKS5 path without needing native support.

Why

The standard HTTPS_PROXY + NO_PROXY contract is "proxy everything; exclude via NO_PROXY" — opt-out, brittle for long allow-lists. dockprox inverts it: opt-in routing per host pattern. Public internet stays direct; only the registries you list (e.g. *.azurecr.io, internal Harbor, ghcr.io) go through your SOCKS5 jumphost.

See docs/guide/why.md for the full rationale.

Quick start

Create dockprox.yaml:

listen: 127.0.0.1:3128
logLevel: info
upstreams:
  jumphost:
    type: socks5
    addr: 127.0.0.1:1080
rules:
  - match: "*.azurecr.io"
    upstream: jumphost

Run:

dockprox serve --config dockprox.yaml

Point your client at it:

export HTTPS_PROXY=http://127.0.0.1:3128
docker pull myregistry.azurecr.io/image:tag

Flags can also override or supply config inline:

dockprox serve \
  --listen 127.0.0.1:3128 \
  --upstream jumphost=socks5://127.0.0.1:1080 \
  --rule '*.azurecr.io=jumphost'

Configuration

Top-level keys (dockprox.schema.json):

Key	Description
listen	Local proxy bind address (host:port).
logLevel	debug | info | warn | error.
upstreams	Map of named upstream proxies.
rules	Ordered list of match → upstream mappings.

Upstream type values:

• socks5 — addr: host:port, optional auth, tls, dns: local|remote.
• http — HTTP CONNECT proxy, url: http(s)://....
• direct — explicit passthrough.

Rule match: exact host (ghcr.io) or *.suffix wildcard (*.azurecr.io).

Full reference: docs/guide/configuration.md · JSON Schema: dockprox.schema.json.

Use cases

• Azure Container Registry — route *.azurecr.io through a corporate SOCKS5 jumphost; everything else direct.
• GitHub Container Registry — send ghcr.io through SOCKS5 only when on a restricted network.
• Private Harbor / internal registries — proxy internal hosts while keeping Docker Hub and public mirrors direct.

Documentation

• Installation
• Usage
• Configuration
• Why dockprox

Installation

Homebrew (macOS / Linux)

brew install foomo/tap/dockprox

See the foomo/homebrew-tap repository.

Docker

docker run --rm foomo/dockprox:latest scan

Multi-arch images (amd64, arm64) are published to Docker Hub.

mise

mise use github:foomo/dockprox

or run directly:

mise x github:foomo/dockprox -- scan

See mise.jdx.dev.

Binary release

Download the archive for your OS/arch from the releases page and extract dockprox into your $PATH.

go install

go install github.com/foomo/dockprox/cmd/dockprox@latest

Requires Go 1.26+.

macOS menu bar app

A native menu bar (tray) app ships as the menubar subcommand of the dockprox binary. It runs a dockprox proxy in-process and exposes Start / Stop / Restart / Reveal-config-in-Finder / Quit from the system tray.

Build:

make build

Run:

bin/dockprox menubar

Run from source:

go run -tags=safe ./cmd/dockprox menubar

Config is resolved from $XDG_CONFIG_HOME/dockprox/config.yaml (or ~/.config/dockprox/config.yaml if XDG_CONFIG_HOME is unset), falling back to ~/.dockprox.yaml. If neither exists at launch, a default config is written to one of those locations (XDG when $XDG_CONFIG_HOME is set; otherwise the dotfile).

How to Contribute

Contributions are welcome! Please read the contributing guide.

License

Distributed under MIT License, please see license file within the code for more details.

Made with ♥ foomo by bestbytes