prxy is a command-line reverse proxy written in Go for forwarding HTTP requests through an outbound proxy, while automatically rewriting the Host header for you.
Why? • Installation • Usage • Contributing • Acknowledgements • License
The idea for prxy was born out of a common, yet specific, personal need: accessing self-hosted services in my homelab from the other side of the world.
Like many homelab enthusiasts, my services are not exposed to the public internet; they are only accessible through a WireGuard VPN. While connecting to the VPN is easy, I didn't want to route my entire computer's traffic through my home network. This would change my public IP and slow down my local internet access.
The goal was to achieve split-tunneling on an application-by-application basis. A fantastic tool, wireproxy, got me 90% of the way there. It creates an HTTP proxy from a WireGuard peer, allowing applications with proxy settings (like Firefox Containers, Thunderbird, or Joplin) to have their traffic transparently routed through the VPN.
But what about applications that don't support proxy configurations?
This was the missing piece. Many tools, especially browser extensions or simple clients, expect a direct URL and have no field to enter a proxy. This is precisely the gap prxy is designed to fill.
prxy acts as the perfect companion to wireproxy. It creates a local HTTP reverse proxy that can forward traffic to your target service through another outbound proxy (like the one wireproxy creates). Crucially, it automatically rewrites the Host header, ensuring the request reaches your service correctly, even if it's behind a reverse proxy in your homelab.
I selfhost Karakeep. The Browser extensions need a URL to connect to, but don't have a proxy setting. With prxy, the solution is simple:
prxy --target https://karakeep.my-homelab.tld \
--proxy http://127.0.0.1:25345 \
--port 12345Now, I can configure the Karakeep extension to point to http://localhost:12345. prxy accepts the connection locally and transparently forwards it through wireproxy to my homelab, making the extension work seamlessly as if I were on my local network.
Via Homebrew:
brew install madh93/tap/prxyUse the docker run command to start prxy:
docker run --name prxy ghcr.io/madh93/prxy:latest --target https://myservice.domain.tld \
--proxy http://my-http-proxy \
--port 12345Create a docker-compose.yml file with the following content:
services:
prxy:
image: ghcr.io/madh93/prxy:latest
restart: unless-stopped
environment:
- PRXY_TARGET=https://myservice.domain.tld
- PRXY_PROXY=http://my-http-proxy
- PRXY_PORT=12345Use the docker compose up command to start prxy:
docker compose upDownload the latest binary from the releases page:
curl -L https://github.com/Madh93/prxy/releases/latest/download/prxy_$(uname -s)_$(uname -m).tar.gz | tar -xz -O prxy > /usr/local/bin/prxy
chmod +x /usr/local/bin/prxyIf you have Go installed:
go install github.com/Madh93/prxy@latestTo start prxy, you need to specify at least the target and outbound proxy URLs.
prxy --target https://myservice.domain.tld --proxy http://127.0.0.1:25345 --port 12345Now, requests to http://127.0.0.1:12345/some/path will be forwarded to https://myservice.domain.tld/some/path with the Host: myservice.domain.tld header, through your outbound proxy.
The application can be configured using command-line flags or environment variables.
For a complete and up-to-date list of all available flags, you can always run:
prxy --helpThe main configuration options are summarized in the table below:
| Flag | Environment Variable | Description | Required | Default Value |
|---|---|---|---|---|
--target, -t |
PRXY_TARGET |
Target service URL. | Yes | N/A |
--proxy, -x |
PRXY_PROXY |
Outbound HTTP Proxy URL. | Yes | N/A |
--host, -H |
PRXY_HOST |
Host to listen on. | No | localhost |
--port, -P |
PRXY_PORT |
Port to listen on. | No | random |
--log-level, -l |
PRXY_LOG_LEVEL |
Set log level: debug, info, warn, error, fatal. |
No | info |
--log-format, -f |
PRXY_LOG_FORMAT |
Set log format: text, json. |
No | text |
--log-output, -o |
PRXY_LOG_OUTPUT |
Set log output: stdout, stderr, file. |
No | stdout |
As an alternative to flags, all configuration options can be set using environment variables prefixed with PRXY_.
It is important to understand the configuration precedence order:
- Command-line flags (Highest priority)
- Environment variables
- Default values (Lowest priority)
This means a flag will always override the value of an environment variable if both are defined. Environment variables are ideal for establishing a base configuration, especially in containerized environments or CI/CD pipelines, while flags are useful for overriding that configuration for a specific execution.
Contributions are welcome! Please open an issue or submit a pull request for any bug fixes or enhancements.
- Fork the repository.
- Create a new branch (
git checkout -b feature-branch). - Commit your changes (
git commit -am 'Add new feature'). - Push to the branch (
git push origin feature-branch). - Open a Pull Request.
- The
prxylogo was adapted from the amazing free-gophers-pack created by Maria Letta.
This project is licensed under the MIT license.