{"id":28899410,"url":"https://github.com/madh93/prxy","last_synced_at":"2025-10-25T20:43:10.731Z","repository":{"id":298344426,"uuid":"995545139","full_name":"Madh93/prxy","owner":"Madh93","description":"🔌 Command-line reverse proxy for forwarding HTTP requests through an outbound proxy","archived":false,"fork":false,"pushed_at":"2025-08-21T14:45:30.000Z","size":123,"stargazers_count":106,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-22T06:39:29.634Z","etag":null,"topics":["cli","go","golang","homelab","proxy","reverse-proxy","self-hosted","wireproxy"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Madh93.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-03T16:35:58.000Z","updated_at":"2025-09-03T16:10:10.000Z","dependencies_parsed_at":"2025-06-10T17:36:41.613Z","dependency_job_id":null,"html_url":"https://github.com/Madh93/prxy","commit_stats":null,"previous_names":["madh93/prxy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Madh93/prxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Madh93%2Fprxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Madh93%2Fprxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Madh93%2Fprxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Madh93%2Fprxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Madh93","download_url":"https://codeload.github.com/Madh93/prxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Madh93%2Fprxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280873676,"owners_count":26405937,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-24T02:00:06.418Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","go","golang","homelab","proxy","reverse-proxy","self-hosted","wireproxy"],"created_at":"2025-06-21T08:30:33.851Z","updated_at":"2025-10-25T20:43:10.727Z","avatar_url":"https://github.com/Madh93.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/img/logo.png\" alt=\"prxy logo\" width=\"75%\" height=\"75%\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003c/br\u003e\n  \u003cb\u003eprxy\u003c/b\u003e is a command-line reverse proxy written in \u003ca href=\"https://go.dev/\"\u003eGo\u003c/a\u003e for forwarding HTTP requests through an outbound proxy, while automatically rewriting the \u003cb\u003eHost\u003c/b\u003e header for you.\n\u003c/p\u003e\n\u003chr\u003e\n\n[![Latest release](https://img.shields.io/github/v/tag/Madh93/prxy?label=Release)](https://github.com/Madh93/prxy/releases)\n[![Go Version](https://img.shields.io/badge/Go-1.24-blue)](https://go.dev/doc/install)\n[![Go Report Card](https://goreportcard.com/badge/github.com/Madh93/prxy)](https://goreportcard.com/report/github.com/Madh93/prxy)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/Madh93/prxy/continuous-integration.yml?branch=main)](https://github.com/Madh93/prxy/actions)\n[![Go Reference](https://pkg.go.dev/badge/github.com/Madh93/prxy.svg)](https://pkg.go.dev/github.com/Madh93/prxy)\n[![License](https://img.shields.io/badge/License-MIT-brightgreen)](LICENSE)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#why\"\u003eWhy?\u003c/a\u003e •\n  \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e •\n  \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e •\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e •\n  \u003ca href=\"#acknowledgements\"\u003eAcknowledgements\u003c/a\u003e •\n  \u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\n\u003c/p\u003e\n\n## Why?\n\nThe 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.\n\nLike many [homelab](https://www.reddit.com/r/homelab/) enthusiasts, my services are not exposed to the public internet; they are only accessible through a [WireGuard VPN](https://www.wireguard.com/). 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.\n\nThe goal was to achieve split-tunneling on an application-by-application basis. A fantastic tool, [wireproxy](https://github.com/whyvl/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](https://support.mozilla.org/en-US/kb/containers), [Thunderbird](https://www.thunderbird.net/), or [Joplin](https://joplinapp.org/)) to have their traffic transparently routed through the VPN.\n\n**But what about applications that don't support proxy configurations?**\n\nThis 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.\n\n`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.\n\n### A Real-World Example\n\nI selfhost [Karakeep](https://karakeep.app/). The [Browser extensions](https://docs.karakeep.app/quick-sharing/#browser-extensions) need a URL to connect to, but don't have a proxy setting. With `prxy`, the solution is simple:\n\n```shell\nprxy --target https://karakeep.my-homelab.tld \\\n     --proxy http://127.0.0.1:25345 \\\n     --port 12345\n```\n\nNow, 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.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./docs/img/karakeep.png\" alt=\"Karakeep Browser Extension integration\"\u003e\n\u003c/div\u003e\n\n## Installation\n\n### GNU/Linux or macOS\n\nVia [Homebrew](https://brew.sh/):\n\n```shell\nbrew install madh93/tap/prxy\n```\n\n### Docker\n\n#### Using `docker run`\n\nUse the `docker run` command to start `prxy`:\n\n```sh\ndocker run --name prxy ghcr.io/madh93/prxy:latest --target https://myservice.domain.tld \\\n     --proxy http://my-http-proxy \\\n     --port 12345\n```\n\n#### Using `docker compose`\n\nCreate a `docker-compose.yml` file with the following content:\n\n```yml\nservices:\n  prxy:\n    image: ghcr.io/madh93/prxy:latest\n    restart: unless-stopped\n    environment:\n      - PRXY_TARGET=https://myservice.domain.tld\n      - PRXY_PROXY=http://my-http-proxy\n      - PRXY_PORT=12345\n```\n\nUse the `docker compose up` command to start `prxy`:\n\n```sh\ndocker compose up\n```\n\n### From releases\n\nDownload the latest binary from [the releases page](https://github.com/Madh93/prxy/releases):\n\n```sh\ncurl -L https://github.com/Madh93/prxy/releases/latest/download/prxy_$(uname -s)_$(uname -m).tar.gz | tar -xz -O prxy \u003e /usr/local/bin/prxy\nchmod +x /usr/local/bin/prxy\n```\n\n### From source\n\nIf you have Go installed:\n\n```sh\ngo install github.com/Madh93/prxy@latest\n```\n\n## Usage\n\nTo start `prxy`, you need to specify at least the target and outbound proxy URLs.\n\n```shell\nprxy --target https://myservice.domain.tld --proxy http://127.0.0.1:25345 --port 12345\n```\n\nNow, 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.\n\n### Configuration Options\n\nThe application can be configured using command-line flags or environment variables.\n\nFor a complete and up-to-date list of all available flags, you can always run:\n\n```shell\nprxy --help\n```\n\nThe main configuration options are summarized in the table below:\n\n| Flag | Environment Variable | Description | Required | Default Value |\n| :--- | :--- | :--- | :--- | :--- |\n| `--target`, `-t` | `PRXY_TARGET` | Target service URL. | **Yes** | N/A |\n| `--proxy`, `-x` | `PRXY_PROXY` | Outbound HTTP Proxy URL. | **Yes** | N/A |\n| `--host`, `-H` | `PRXY_HOST` | Host to listen on. | No | `localhost` |\n| `--port`, `-P` | `PRXY_PORT` | Port to listen on. | No | `random` |\n| `--log-level`, `-l` | `PRXY_LOG_LEVEL` | Set log level: `debug`, `info`, `warn`, `error`, `fatal`. | No | `info` |\n| `--log-format`, `-f` | `PRXY_LOG_FORMAT`| Set log format: `text`, `json`. | No | `text` |\n| `--log-output`, `-o`| `PRXY_LOG_OUTPUT`| Set log output: `stdout`, `stderr`, `file`. | No | `stdout` |\n\n### Configuration Precedence\n\nAs an alternative to flags, all configuration options can be set using environment variables prefixed with `PRXY_`.\n\nIt is important to understand the configuration precedence order:\n\n1. **Command-line flags** (Highest priority)\n2. **Environment variables**\n3. **Default values** (Lowest priority)\n\nThis 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.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request for any bug fixes or enhancements.\n\n1. Fork the repository.\n2. Create a new branch (`git checkout -b feature-branch`).\n3. Commit your changes (`git commit -am 'Add new feature'`).\n4. Push to the branch (`git push origin feature-branch`).\n5. Open a Pull Request.\n\n## Acknowledgements\n\n* The `prxy` logo was adapted from the amazing [free-gophers-pack](https://github.com/MariaLetta/free-gophers-pack) created by [Maria Letta](https://github.com/MariaLetta).\n\n## License\n\nThis project is licensed under the [MIT license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadh93%2Fprxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadh93%2Fprxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadh93%2Fprxy/lists"}