How to Configure Holy Unblocker: Complete Beginner's Guide

Holy Unblocker is an open-source, browser-based web proxy. Its configuration decides how the app runs, which supporting technologies it uses and how it handles browsing. If you run your own instance, understanding these settings helps you diagnose errors, manage server resources and keep a deployment reliable.

What Configuration Covers

It may involve startup, production settings, proxy engines, transports, web server settings and optional routing. For example, you might configure:

• The port the app uses and whether it runs in production mode
• How static assets are processed
• Which transports are available and how Wisp connections are handled
• How the app is exposed through a domain, and whether optional routing is on

Not every setting lives in one file. Some are application config, some are browser-side JavaScript and some belong to the hosting environment. The right configuration depends on the exact version and branch you installed.

Before You Start

• A working installation, and access to the project directory
• A basic understanding of JSON and JavaScript config files
• The Node.js version and package manager your release requires
• A backup of every file you plan to change

If you haven't installed it yet, read How to Self-Host Holy Unblocker first, and confirm instructions against the current InvisiProxy repository.

Step 1: Locate the Configuration Files

A typical InvisiProxy checkout contains config.json, ecosystem.config.js, package.json and backend.js, plus browser-side files under views.

• config.json: application-level options. Depending on the release, these include production behavior, script minification, identifier randomization, DOM processing and diagnostic output. Not every option exists in every historical version.
• ecosystem.config.js: server and process configuration, including the application port and production process settings. Read the comments and current docs before editing.
• package.json: the scripts and dependencies, which shows the supported commands. Don't hand-edit dependency versions unless you're following the project's development instructions.
• Browser-side config: the docs identify views/assets/js/register-sw.js for some service-worker and transport settings. It isn't the server's main config, and edits affect every visitor to your deployment.

Step 2: Back Up Your Configuration

cp config.json config.json.backup
cp ecosystem.config.js ecosystem.config.js.backup

If a file doesn't exist in your version, don't create it because a guide lists it. Check your repository's real structure first. Keep production backups somewhere not publicly reachable from the website.

Step 3: Production Mode

Production mode is for running the app as a deployed service rather than a development environment. The docs describe a production option tied to process management and other deployment behavior. Verify which file controls it in your release. It can affect how the app starts, whether a process manager is used, how assets are prepared, caching and request handling. Don't enable it blindly: confirm dependencies are installed and your reverse proxy is configured first. Use development instructions locally and the stable release's instructions for public deployments.

Step 4: The Application Port

The documented default address is localhost:8080. A port is the network endpoint where an app accepts connections, so localhost:8080 means port 8080 on the same machine. Other versions may differ. If you change it, find the setting for your release, because the app and any reverse proxy in front of it must agree. If the app listens on 8080 but Nginx forwards to 3000, expect a 502 error.

• Save the file and check the syntax is valid.
• Restart using the documented process.
• Update the reverse-proxy config if needed.
• Test locally before testing the public domain.

Don't expose internal ports directly to the internet unless you've deliberately secured that access.

Step 5: The Main config.json Options

The repository documents several options. Always verify behavior against your installed release.

Step 6: Proxy Engines and Transports

The documentation names Scramjet, Ultraviolet, Wisp, Bare-Mux, EpoxyTransport and LibcurlTransport. They serve different purposes (see how Holy Unblocker works).

• Scramjet: interception-based engine. Follow the docs for the version bundled with your install.
• Ultraviolet: service-worker-based engine. Sites can behave differently between it and Scramjet (see Holy Unblocker vs Scramjet).
• Wisp: communication infrastructure. Its configuration must agree with the rest of your deployment.
• Bare-Mux: helps manage transport choices. It doesn't replace correct server, network and dependency setup.
• EpoxyTransport and LibcurlTransport: transport implementations. Availability depends on release and configuration, and not every one suits every hosting environment.

If your Settings menu lets users choose a transport, make sure the selected one is supported and configured before investigating anything else.

Step 7: register-sw.js and Service Workers

The docs identify views/assets/js/register-sw.js as a significant place for browser-side proxy settings. Depending on the release, that can include transport choices, Wisp endpoints, service-worker configuration and proxy options.

A service worker is a browser script that can handle certain network requests and support caching and offline behavior. Proxy apps use them to intercept and process requests within the browser's security model, so a wrong change can stop the proxy loading or make it behave inconsistently. Only edit this file with a clear reason:

• Back it up and identify the exact option you need.
• Check that the option is documented for your release.
• Change one thing at a time and test after each change.
• Don't copy snippets from unrelated forks, which may use different formats.

Step 8: Wisp and Transport Endpoints

If you use Wisp and configurable transports, their endpoints must match services available in your environment. A client may try an endpoint that isn't running, uses the wrong port, or isn't reachable through the reverse proxy. Verify that:

• The endpoint matches the current deployment, and the required service is running.
• The port and path are correct.
• The reverse proxy supports the connection behavior the app needs.
• The browser isn't using stale cached configuration.

Don't swap in arbitrary public proxy addresses. Only use endpoints you're authorized to use and that are compatible with the project.

Step 9: Optional Tor Routing

Some versions can use Tor or compatible proxy endpoints. This needs extra configuration and a correctly installed supporting service, so follow the repository's dedicated Tor instructions and confirm the service is running and the app points at the intended endpoint. It's optional, and basic browser proxying doesn't need it. Enabling Tor doesn't automatically make activity anonymous or protect your device's other traffic (see our disclaimer).

Step 10: Nginx and HTTPS

For a public instance, the reverse proxy and HTTPS are separate from the app's internal settings: Visitor → HTTPS → Nginx → Application. The InvisiProxy README warns about reverse-proxy configuration and Wisp-related loopback behavior, so review it before choosing a setup. Don't assume a generic Nginx or Caddy config will work unchanged. Check that:

• The domain points to the correct server and HTTPS uses a valid certificate.
• The app listens on the intended local address and port, and Nginx forwards to it.
• Required connection upgrades are handled.
• Private application endpoints aren't exposed unnecessarily.

sudo nginx -t
sudo systemctl reload nginx    # only if the test passes

Step 11: Restart and Test

Changes may not apply until the app restarts or browser-side assets are rebuilt. The repository documents commands such as these, though they aren't universal to every historical version:

pnpm restart
pnpm run test

Afterwards check that:

• The app starts and the homepage loads.
• The browser console shows no errors, and service endpoints are reachable.
• The problem affects every site or only one.
• Nginx and app logs show nothing useful.

Don't make several unrelated changes at once, since one change at a time makes the cause easy to find.

Common Configuration Problems

• Config file doesn't exist: your version uses a different structure. Check the README and the files actually present. Don't create a file with guessed options.
• JSON syntax error: a missing or extra comma, an unmatched quote or a wrong value type breaks it. Use a validator, and remember JSON doesn't allow comments like JavaScript.
• App won't start after editing: restore the backup or undo the last change, then check startup output for config errors, missing dependencies, unsupported options or port conflicts.
• 502 Bad Gateway: Nginx can't reach the app. Verify it's running and the upstream address and port match.
• Proxy loads but sites fail: this may be compatibility, not configuration. Test several sites first (see common problems and fixes).
• Transport connection errors: check the transport is supported, its service is available, its endpoint is right, and the reverse-proxy rules allow upgrades.
• Changes don't show in the browser: cached assets or an old service-worker registration. Use developer tools to find stale resources, and clear site data only when appropriate, since it can remove saved sessions.

Best Practices

• Use the right version's docs for the branch and release you installed.
• Back up before editing, and keep changes reversible.
• Avoid unnecessary changes, because each one is another possible failure.
• Monitor logs to find startup failures and connection problems.
• Protect secrets: never publish passwords or private keys in a public repository.
• Keep dependencies updated using the supported upgrade procedure and release notes.
• Use HTTPS for public deployments.
• Don't confuse privacy with configuration. A working proxy isn't anonymity or system-wide VPN protection (see Holy Unblocker vs VPN).
• Test in a separate environment before changing a public instance.

Frequently Asked Questions

Conclusion

Configuring Holy Unblocker means understanding how application settings, proxy engines, transports, browser-side scripts and your hosting environment work together. Identify your exact version, locate its supported configuration files, back them up, change one thing at a time and test after each change. For public deployments, also verify the domain, HTTPS, reverse proxy and logs.

Related Guides