{"id":15508690,"url":"https://github.com/jay7x/etc-hosts-proxy","last_synced_at":"2025-08-18T12:10:03.140Z","repository":{"id":176114678,"uuid":"651946471","full_name":"jay7x/etc-hosts-proxy","owner":"jay7x","description":"Stop changing /etc/hosts file! Use `etc-hosts-proxy` instead!","archived":false,"fork":false,"pushed_at":"2025-08-12T03:41:56.000Z","size":57,"stargazers_count":8,"open_issues_count":4,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-12T05:35:30.822Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jay7x.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["jay7x"]}},"created_at":"2023-06-10T15:27:26.000Z","updated_at":"2025-08-12T03:41:58.000Z","dependencies_parsed_at":"2024-02-07T12:29:18.726Z","dependency_job_id":"ac663d42-a23b-4c62-885d-9adb1fd00c7d","html_url":"https://github.com/jay7x/etc-hosts-proxy","commit_stats":null,"previous_names":["jay7x/etc-hosts-proxy"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/jay7x/etc-hosts-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jay7x%2Fetc-hosts-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jay7x%2Fetc-hosts-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jay7x%2Fetc-hosts-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jay7x%2Fetc-hosts-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jay7x","download_url":"https://codeload.github.com/jay7x/etc-hosts-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jay7x%2Fetc-hosts-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270989168,"owners_count":24680688,"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-08-18T02:00:08.743Z","response_time":89,"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":[],"created_at":"2024-10-02T09:39:42.990Z","updated_at":"2025-08-18T12:10:03.113Z","avatar_url":"https://github.com/jay7x.png","language":"Go","funding_links":["https://github.com/sponsors/jay7x"],"categories":[],"sub_categories":[],"readme":"# etc-hosts-proxy\n\n\u003e Stop changing `/etc/hosts` file! Use `etc-hosts-proxy` instead!\n\nWhen testing a website there are usually 3 ways to access the test environment while keeping the `Host` HTTP header:\n\n1. Override the hostname in the `/etc/hosts` file. Admin privileges are required for this.\n\n2. Use local DNS server with ability to override the hostname (`dnsmasq` e.g.). You should configure the local DNS server properly. Then you should change your network settings to use it.\n\n3. Use a proxy server which can override the hostname in a request.\n\nThis proxy implements the 3rd way. Nor admin privileges neither any system-wide changes are required for this. Just start the proxy server and direct your browser to use it.\n\nA proxy-switching extension for your browser (FoxyProxy or SwitchyOmega e.g.) is highly recommended.\n\n## WARNING \u0026 DISCLAIMER\n\n⚠️ DO NOT RUN this server on a publicly available network interface! This may compromise your network, privacy, wallet, etc. Never run this proxy on `0.0.0.0` if you do not understand what you're doing!\n\nContributors are not responsible for any damage incurred by using this proxy server.\n\n## What this proxy does and what's not\n\n- ✅ HTTP proxy protocol is supported\n- ✅ HTTPS CONNECT method is supported\n- ✅ SOCKS5 protocol is supported\n- ✅ HTTP proxy-chaining is supported (use `HTTP_PROXY` environment variable)\n- ❌ Config file support is possible but not planned\n- ❌ Daemon mode support is possible but not planned\n- ❌ HTTPS MitM support is not planned (use mitmproxy)\n- ❌ Request/response rewrite support is not planned (use mitmproxy)\n- ❌ ACL support is not planned\n\n## Usage\n\nRun the HTTP proxy on 127.0.0.1:8080 and redirect some hostnames to a local web server:\n\n```bash\netc-hosts-proxy run -H example.com=127.0.0.1 -H www.example.com=127.0.0.1\n```\n\nTest the above with curl:\n\n```bash\ncurl -v -x 127.0.0.1:8080 http://example.com\ncurl -v -x 127.0.0.1:8080 http://www.example.com\n```\n\nNOTE: Proxy listens on `127.0.0.1:8080` by default. Use `-L` (or `--listen-address`) CLI option to change this.\n\nRun the SOCKS5 proxy on 127.0.0.1:1080 and redirect some hostnames to a local web server:\n\n```bash\netc-hosts-proxy run -M socks5 -L 127.0.0.1:1080 -H example.com=127.0.0.1,www.example.com=127.0.0.1\n\ncurl -v -x socks5h://127.0.0.1:1080 http://example.com\ncurl -v -x socks5h://127.0.0.1:1080 http://www.example.com\n```\n\nSee `etc-hosts-proxy --help` for general CLI usage information.\n\n## Docker usage\n\nYou may also use a Docker image if you'd prefer:\n\n```bash\ndocker run -d --name=etc-hosts-proxy -p 127.0.0.1:8080:8080 --rm \\\n  -e ETC_HOSTS_PROXY_HOSTS_LIST=\"akamai.com=2.21.250.7,www.akamai.com=2.21.250.7\" \\\n  -e ETC_HOSTS_PROXY_DEBUG=true \\\n  ghcr.io/jay7x/etc-hosts-proxy:latest\n\ncurl -v -x 127.0.0.1:8080 http://akamai.com\n\ndocker logs etc-hosts-proxy\ndocker stop etc-hosts-proxy\n```\n\nNOTE: You should not use 127.0.0.1 (or ::1) as your redirection destination in the hosts list while running in a container. This will redirect the request to the container's localhost, which is not what you might expect. You can use `host` Docker network if you really need it.\n\nA bit more complex example to redirect some domains to a nginx container:\n\n```bash\n# Create a docker network\ndocker network create somenet\n\n# Run a web server exposed in somenet and on 127.0.0.1:8080 on the host\ndocker run -d --name=nginx --net=somenet -p 127.0.0.1:8080:80 --rm nginx:latest\n\n# Run the proxy connected to somenet and exposed on 127.0.0.1:3128 on the host\ndocker run -d --name=etc-hosts-proxy --net=somenet -p 127.0.0.1:3128:8080 --rm \\\n  -e ETC_HOSTS_PROXY_HOSTS_LIST=\"example.com=nginx,www.example.com=nginx\" \\\n  -e ETC_HOSTS_PROXY_DEBUG=true \\\n  ghcr.io/jay7x/etc-hosts-proxy:latest\n\n# Check nginx\ncurl -v http://127.0.0.1:8080\n\n# Check proxy is proxying (note the port is 3128 here)\ncurl -v -x 127.0.0.1:3128 http://example.com\ncurl -v -x 127.0.0.1:3128 http://www.example.com\n# This should not be redirected\ncurl -v -x 127.0.0.1:3128 http://example.net\n\n# Check logs\ndocker logs etc-hosts-proxy\ndocker logs nginx\n\n# Cleanup\ndocker stop etc-hosts-proxy\ndocker stop nginx\ndocker network rm somenet\n```\n\nDocker images are built by `goreleaser` from the [Dockerfile](https://github.com/jay7x/etc-hosts-proxy/blob/main/.dockerfile)\n\nSee [etc-hosts-proxy Github Container registry](https://github.com/jay7x/etc-hosts-proxy/pkgs/container/etc-hosts-proxy) for more details\n\n## Environment variables\n\n| Variable | Description |\n| - | - |\n| `ETC_HOSTS_PROXY_DEBUG` | Enable debug mode |\n| `ETC_HOSTS_PROXY_LOG_LEVEL` | Set the logging level [`trace`, `debug`, `info`, `warn`, `error`] |\n| `ETC_HOSTS_PROXY_MODE` | Mode to start proxy in (`http` or `socks5`) |\n| `ETC_HOSTS_PROXY_LISTEN_ADDRESS` | [`\u003chost\u003e`]:`\u003cport\u003e` to listen for proxy requests on |\n| `ETC_HOSTS_PROXY_HOSTS_LIST` | comma-separated list of `\u003chost\u003e=\u003cip\u003e` pairs to redirect `\u003chost\u003e` to `\u003cip\u003e` |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjay7x%2Fetc-hosts-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjay7x%2Fetc-hosts-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjay7x%2Fetc-hosts-proxy/lists"}