netptop/siteproxy: A Self-Hosted Web Proxy with Built-In Duck.ai Chat

What SiteProxy Actually Solves, and Who It Is Built For

SiteProxy is a reverse proxy that sits between a browser and the wider web. The user opens one URL, the proxy fetches the destination, rewrites the response, and returns it. The README's own diagram shows a single siteproxy node fanning out to google/youtube, wikipedia and "chinese forums", with the user's browser talking only to the proxy. The practical audience is narrow and specific: someone who wants a private entry point to sites that are blocked or inconvenient on their network, and who is willing to run that entry point themselves. It is not a consumer VPN product and it is not a scraping framework. The README markets convenience, listing zero client configuration as a feature, and that framing is accurate: there is nothing to install on the user's machine, only a URL to open. The trade is that the operator carries all the work and all the exposure. Whoever deploys it owns a public endpoint that other people's traffic passes through, and the README's caution block says the project must not be used for any illegal purpose. That sentence is doing more work than it appears to. A self-hosted open proxy is a liability surface, and the password gate described below is the only access control the documentation describes.

How the Proxy Rewrites Pages and Keeps Links Inside Itself

The mechanism visible in the release notes is HTML and CSS rewriting on the way back to the browser. Version v2.7.9 states it rewrites url() inside style attributes so runtime-built background images load through the proxy. Version v2.7.8 states it escapes backslashes when embedding client scripts so regex escape sequences reach the browser intact. Version v2.7.11 states it stopped treating a comma in a URL as a list separator. Read together, these three releases describe a project whose main engineering effort goes into interception: every URL the page can produce, whether in an attribute, in an inline style, or assembled at runtime by JavaScript, has to be caught and redirected through the proxy host, or the page breaks. That is why the project bundles client-side scripts into the response rather than relying on the origin's own JavaScript. The server itself is Hono, which the README says replaced Express, and the repository's package.json lists no runtime dependencies at all, only wrangler as a dev dependency. That is an unusual and deliberate shape: the application code is bundled by bundle.mjs into a single artifact that runs on Node.js, Cloudflare Workers and Cloudflare Pages without a node_modules tree behind it. The cost of that shape is that you cannot inspect what you are running from package.json alone.

Installing SiteProxy on a VPS and Making the First Request

The README recommends a VPS or Docker deployment, and notes that Cloudflare deployment may leave some sites unreachable because Cloudflare IPs are already restricted by some sites. The VPS path assumes you already have a domain, nginx and certbot. Node.js 22 or higher is required by package.json's engines field. The README gives this sequence for installing Node through nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install v22

After cloning the repository and entering the directory, the README says to run the bundler once as a smoke test and stop it with Ctrl+C:

node bundle.mjs

If that exits without errors, edit config.json. The README gives this exact structure, with proxy_url and token_prefix as the two fields that matter:

{
  "proxy_url": "https://your-proxy.domain.name",
  "token_prefix": "/user-SetYourPasswordHere/",
  "local_listen_port": 5006,
  "description": "token_prefix is the site password"
}

The README says not to change local_listen_port, because nginx proxies to it. The corresponding nginx block in the README points location / at http://localhost:5006. Once nginx is restarted, the README starts the process under forever:

npm install -g forever
forever stopall && forever start bundle.mjs

The URL you open is proxy_url plus token_prefix, so with the values above it is https://your-proxy.domain.name/user-SetYourPasswordHere/ . The README stresses that the trailing slash must be present. If token_prefix is empty, the README says the proxy is reachable with no password at all, which is worth pausing on before you deploy anything public.

Cloudflare Pages, Workers and Docker Change the Deployment, Not the Model

The Cloudflare paths follow the same shape with different plumbing. For Pages, the README says to clone the repository, run npm install, install wrangler globally, then either upload the build/cf_page directory through the dashboard or deploy from the command line after editing wrangler.jsonc. The two fields to change are name and the vars block:

"vars": {
  "proxy_url": "https://your-proxy-domain.com",
  "token_prefix": "/default/"
}

The README states the leading and trailing slashes must be kept, and that an empty password means no password is required. Deployment runs through the repository's own npm scripts, which wrap wrangler:

npm run wrangler-login
npm run deploy-cf-page

For Workers the file is wrangler.worker.jsonc and the script is npm run deploy-cf-worker, which the package.json shows expands to wrangler deploy --config wrangler.worker.jsonc. For Docker, the README says to configure SSL and nginx against port 5006, edit config.json the same way, then run sudo docker compose up from the docker-node subdirectory. The Dockerfile is four lines: it starts from node:22, copies the repository to /app, and runs node bundle.mjs. There is no build step and no exposed port declaration in the Dockerfile itself, so port 5006 comes from config.json and the nginx layer in front. That is consistent across all four targets, and it also means a misconfigured proxy_url or token_prefix fails the same way everywhere: the app starts, but the URL you hand out does not resolve to it.

The Password Gate Is a Path Prefix, and That Is the Whole Access Control

SiteProxy does not have user accounts. Access control is a secret string embedded in the URL path, which the README calls token_prefix and describes as equivalent to a site password. Anyone who has the full URL has access. There is no session, no per-user revocation, and no rate limiting described anywhere in the README. If the link leaks, the only remedy the documentation supports is editing config.json or wrangler.jsonc to a new token_prefix and redeploying, which invalidates every copy of the old link at once. For a single operator sharing with a handful of people, that is workable. For anything resembling a team, it is not: you cannot remove one person without rotating the secret for everyone. The README also notes that the default homepage URL cannot be modified, and that the code has been obfuscated since 2.x specifically to reduce phishing risk, given that the proxy handles logins for multiple sites. The reasoning is understandable, since a proxy that intermediates a login page is a phishing target by construction, but the consequence is that you are deploying a public-facing endpoint whose internals you cannot read. The README's own warning about not logging in through an untrusted proxy applies most sharply here: you are the operator, so you are the one who has to trust the build.

Where SiteProxy Is the Wrong Tool

The README is unusually candid about failure modes, and two are worth taking literally. First, Google Search and YouTube have added anti-ad and anti-bot mechanisms, so access through the proxy may be restricted; the README recommends DuckDuckGo for search instead. If your primary reason for wanting a proxy is YouTube, the project's own documentation is telling you it may not deliver. Second, Cloudflare-hosted deployments may fail on sites that already block Cloudflare IP ranges, which is why the README steers toward a VPS or Docker. Beyond those, the architecture sets a ceiling. A reverse proxy that rewrites HTML and CSS has to intercept every URL construction pattern a site uses, which is why three consecutive patch releases in August 2026 were all rewriting fixes: style attributes, escaped backslashes, and comma handling. Sites that build requests in ways the rewriter does not anticipate will break, and the fix arrives as a new release rather than as a configuration option. Sites that pin themselves to their own origin through JavaScript, service workers or strict CORS will be hostile to this approach in general. And because the project obfuscates its code, you cannot patch around a break yourself in any practical way. You wait for upstream.

How It Compares to a Conventional Forward Proxy

The obvious alternative is a standard forward proxy such as Squid or a SOCKS proxy over SSH, and the difference is not performance, it is where the rewriting happens. A forward proxy requires the client to be configured, either in browser settings or at the operating system level, and it forwards requests largely untouched. SiteProxy inverts that: the client needs no configuration at all, but the server must parse and rewrite every response, because the browser believes it is talking to one origin. That inversion is what makes the zero-configuration claim true, and it is also the source of every compatibility problem described above. If you control the client devices and just need traffic to leave through a different address, a forward proxy is simpler and has no rewriting layer to break. If you need to hand someone a URL and have it work in whatever browser they already have, SiteProxy's approach is the one that fits. The README also bundles Duck.ai, formerly DuckDuckGo AI Chat, which the README says provides free access to GPT-4o mini, GPT-5 mini, Claude 4.5 Haiku, Llama 4 and Mistral. That is a feature a plain forward proxy does not have, and it is a separate reason someone might pick this project over a generic proxy.

Editorial conclusion

Deploy SiteProxy if you want a personal, password-gated web proxy you control and you are comfortable with a Cloudflare account or a VPS running Node.js 22 behind nginx. Do not adopt it if you need an audited, readable codebase, because the README states the code is obfuscated from 2.x onward to reduce phishing risk, and do not adopt it if you expect Google or YouTube to work reliably, since the README itself warns those sites have anti-bot and anti-ad mechanisms. Before committing, verify three things: that your Node.js version is 22 or higher, that proxy_url uses https, and that the token_prefix slashes are intact in both config.json and your nginx location block.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. netptop/siteproxy on GitHub
4. README
5. Releases