A HomeProxy OpenWrt setup adds a LuCI interface that generates a sing-box client configuration and steers router traffic into it. Install the package from your firmware's own feed, route one test client through one node you are allowed to use, and confirm that stopping the service returns the network to direct routing. This procedure is based on the official sources listed below; a complete end-to-end test has not been performed.

Key Takeaways

HomeProxy is a LuCI app; sing-box does the proxy work underneath it.

The project has no tagged releases, so pin the firmware and package versions you install.

Start with one listed client, because DNS changes reach every client that uses the router.

A stopped service should remove its routing rules, firewall chains and dnsmasq changes.

Which HomeProxy OpenWrt setup does this procedure cover?

The project describes HomeProxy as a modern ImmortalWrt proxy platform for ARM64 and AMD64 devices, powered by sing-box. Its README is a short to-do list rather than an installation manual, and the repository has no tagged releases. That is why this guide reads the code at commit 98a6ad9 and only describes options found there.［1］

The package definition declares four dependencies: sing-box, firewall4, kmod-nft-tproxy and ucode-mod-digest. It also lists the files kept as configuration during upgrades, including /etc/config/homeproxy and the direct and proxy domain lists.［2］

The baseline here is ImmortalWrt 24.10.6, an OpenWrt-based firmware whose LuCI feed ships luci-app-homeproxy version 26.236.50592~9b8ee64, alongside sing-box 1.12.25-r1 in the packages feed.［3］［4］ Stock OpenWrt does not provide an official HomeProxy release package, so this procedure does not cover installing builds from unknown mirrors.

Before you start, decide whether you want to run a router gateway at all. The self-hosting responsibilities guide explains what you take on when you operate the path yourself, and it helps to weigh maintaining your own server against a managed VPN service before committing a router to it. If HomeProxy is not a fit, the OpenClash installation and recovery walkthrough covers another plugin family, and a plain tunnel is covered in the OpenWrt WireGuard client procedure.

What does HomeProxy change on the router?

When the service starts with a main node selected, its init script generates /var/run/homeproxy/sing-box-c.json and runs sing-box check against it. A failed check stops the start and writes the reason to /var/run/homeproxy/homeproxy.log.［5］

The same script changes three router layers. It writes a dnsmasq configuration directory and restarts dnsmasq, adds policy routing rules (table 100 and mark 101 by default for TProxy), and reloads firewall4 with HomeProxy chains. It also reloads the service when the WAN interface comes up.［5］

Layer	What starts with the service	What the stop routine removes
Proxy process	sing-box client from the generated JSON	Generated JSON and client log
DNS	dnsmasq forwarding to `127.0.0.1#5333` in Global mode	HomeProxy dnsmasq directory, then a dnsmasq restart
Routing	`ip rule` and local routes in table 100	The same rules and routes for IPv4 and IPv6
Firewall	`homeproxy_*` chains and sets in `inet fw4`	Flushed and deleted chains and sets

The DNS row matters for planning. In Global, Bypass mainland China and Custom routing modes, the script tells dnsmasq to stop using its normal upstreams and forward queries to the local sing-box DNS port, so every client that asks the router for DNS is affected, not only the client you list for proxying.［5］

Step 1: Check firmware, architecture and space

Use a router you own or administer, with a wired client on a known LAN port and a recovery method documented for your model. Record the firmware release, CPU architecture and free space before installing anything.

cat /etc/openwrt_release
uname -m
opkg print-architecture
df -h /overlay /tmp

Compare the architecture with the package index you plan to use. The LuCI package is architecture-independent, but sing-box and the kernel module are built per target, so an AMD64 router and an aarch64_cortex-a53 router need different binaries from the same release.［3］［4］

Stop if the firmware is not ImmortalWrt 24.10.6 and you cannot confirm a matching official feed. Mixing packages from another release can break kernel module dependencies, and this guide does not establish compatibility outside its baseline.

Step 2: Back up and complete the HomeProxy installation

In LuCI, open System → Backup / Flash Firmware and download a configuration backup to another device. Also note your current DNS forwarders and the LAN address of the test client. Keep the wired management session open throughout.

On the router, refresh package lists and install the LuCI app from the official feed. Package lists live in RAM under /tmp/opkg-lists and disappear on reboot, so run opkg update again before any later install.［6］

opkg update
opkg list-installed | grep -E 'homeproxy|sing-box'
opkg install luci-app-homeproxy

The install pulls in the declared dependencies. Read the transaction output: if opkg reports a dependency or kernel module conflict, stop and resolve it with your firmware's documentation instead of forcing the install.［2］［6］ After the install, reload LuCI; the app appears under Services → HomeProxy with Client Settings, Node Settings, Server Settings and Service Status pages.［1］

Avoid upgrading every package on the router to make the install work. The opkg documentation warns that mass upgrades are strongly discouraged because they can soft-brick a device.［6］

Step 3: Import one authorized node

Open Services → HomeProxy → Node Settings. On the Nodes tab, add a node manually by choosing its Type and filling in Address and Port, or paste a share link through Import share links. The import dialog lists Hysteria, Shadowsocks, Trojan, VMess (v2rayN format) and VLESS links as supported.［7］

Use only a node you run yourself or have permission to use. Leave Allow insecure off; turning off certificate checks hides a mismatch instead of fixing it. Do not paste subscription URLs or share links into public forums or screenshots, because they work as credentials.

HomeProxy builds sing-box configuration from these fields. When a protocol setting is unclear, check the matching outbound in the sing-box documentation for the version installed on the router rather than guessing values.［8］

Step 4: Choose a HomeProxy routing mode for one client

Open Client Settings → Routing Settings. Set Main node to the node you imported; while it stays at Disable, the client service does not start.［5］［9］ Leave Main UDP node at its default, which reuses the main node.

Routing mode offers GFWList, Bypass mainland China (the default), Only proxy mainland China, Custom routing and Global.［9］ For a bounded first test, Global gives the simplest expectation: traffic from the listed client should leave through the node. Keep the default Proxy mode, Redirect TCP + TProxy UDP; the Tun options appear only when ip-full and kmod-tun are installed.［9］

Setting	Value for the first test	Why
Main node	The imported node	Required for the client service to start
Routing mode	Global	One clear expectation per client
Proxy mode	Redirect TCP + TProxy UDP	Package default; no extra modules
IPv6 support	Your planned scope	Adds IPv6 rules when enabled
Proxy filter mode	Proxy listed only	Limits capture to one client

Then open the Access Control tab, choose LAN IP Policy, and set Proxy filter mode to Proxy listed only. Add the test client's address under Proxy IPv4 IP-s (and Proxy IPv6 IP-s if you test IPv6), and keep your management computer off the list.［9］ Save and apply, then confirm Service Status shows the client running.

Step 5: Verify client exit, DNS and IPv6

Check each path separately on the test client, then repeat the key checks on an unlisted client. Use the table as expected observations, and write down your own results.

Check method	Expected observation	If it fails
Open the IP check page on the listed client	The node's public address appears	Read `homeproxy.log` and the node fields
Same page on an unlisted client	Your normal ISP address appears	Recheck Proxy filter mode and the list
Resolve a name on both clients	Answers return through the router	Stop the service and compare dnsmasq
Test an IPv6-only site on the listed client	Matches your IPv6 support choice	Narrow the scope or disable IPv6 support
Reach LuCI over the wired client	Management still works	Stop the service immediately

For the exit check, compare the visible public address on each client. A changed address on the listed client proves only that its web traffic reaches the node; DNS and IPv6 still need their own checks.

Look at the router state as well. ip rule show should list the HomeProxy mark rule, and nft list ruleset | grep homeproxy should show its chains while the service runs.［5］ If IPv6 support is enabled, the script adds matching IPv6 rules; if your clients have IPv6 but the test shows a direct IPv6 path, record that limit before widening the list.

Step 6: Stop the service and confirm direct recovery

Stop HomeProxy through its init script, and disable autostart if you are ending the trial. This affects only HomeProxy on the router.

/etc/init.d/homeproxy stop
/etc/init.d/homeproxy disable
ip rule show
nft list ruleset | grep homeproxy

The stop routine deletes its policy rules and routes, flushes and deletes the homeproxy_* chains and sets, removes its dnsmasq directory and restarts dnsmasq.［5］ The two check commands should therefore show no HomeProxy entries. On the test client, the IP check page should show your normal address again, and name resolution should use your original forwarders.

If management is lost at any point, use the wired client to stop the service first, then restore the configuration backup from Step 2. Do not flush the whole firewall or factory-reset as the first response.

How do you upgrade or uninstall HomeProxy safely?

Upgrade only within the same firmware release feed, after opkg update, and check the installed version afterward. The package marks /etc/config/homeproxy, certificates, rule sets and the direct and proxy lists as configuration files, so they are meant to survive an upgrade; still keep your own backup.［2］［6］

To uninstall, stop and disable the service, confirm the recovery checks above, then remove the app. opkg remove --autoremove luci-app-homeproxy also removes packages installed only as its dependencies; review the list it prints before confirming, because sing-box may be needed by something else.［6］ Revoke any node credential that was exposed during the trial instead of only deleting the local copy.

Summary

Pin the firmware, LuCI package and sing-box versions, since the project has no tagged releases.
Install from the firmware's official feed and stop on dependency conflicts.
Proxy one listed client in Global mode, knowing DNS changes affect all router clients.
Verify exit, DNS, IPv6 and management separately, then prove the stop routine restores direct routing.

FAQ

Is HomeProxy the same thing as sing-box?

No. HomeProxy is a LuCI app that writes sing-box configuration, routing rules and dnsmasq settings, while sing-box is the separate proxy program that carries the traffic.

Can I install HomeProxy on stock OpenWrt?

The project ships no tagged release packages, and stock OpenWrt feeds do not include it. This guide covers ImmortalWrt 24.10.6, whose official LuCI feed provides the package.

Why does DNS change for clients I did not list?

In Global and similar modes, HomeProxy points dnsmasq at the local sing-box DNS port. Every device that uses the router for DNS goes through that path, even when its traffic is not proxied.

Which routing mode should I start with?

Global with Proxy listed only gives one clear expectation for one client. Move to another mode only after the first test and the rollback both work.

Do I need Tun mode?

Not for a first test. The default Redirect TCP + TProxy UDP mode needs no extra modules, and Tun options appear only after installing ip-full and kmod-tun.

What should I do if the service will not start?

Check that Main node is not set to Disable, then read /var/run/homeproxy/homeproxy.log. A failed sing-box configuration check stops the start and is recorded there.

Does uninstalling the app restore my network by itself?

Stopping the service is what removes its rules and dnsmasq changes. Stop it, confirm the router shows no HomeProxy rules, test a client, and only then remove the package.

Disclaimer: This article is for general informational purposes only and does not constitute legal, technical, or other professional advice. We make no guarantees regarding the accuracy, completeness, or timeliness of the content. Use only networks, routers and proxy nodes you own or are authorized to use.

Sources:

ImmortalWrt — HomeProxy repository (commit 98a6ad9) — https://github.com/immortalwrt/homeproxy/tree/98a6ad9e71484528008ff435694fd107591f3a1d
HomeProxy — package definition (Makefile) — https://github.com/immortalwrt/homeproxy/blob/98a6ad9e71484528008ff435694fd107591f3a1d/Makefile
ImmortalWrt — 24.10.6 LuCI feed (aarch64_cortex-a53) — https://downloads.immortalwrt.org/releases/24.10.6/packages/aarch64_cortex-a53/luci/
ImmortalWrt — 24.10.6 packages feed (aarch64_cortex-a53) — https://downloads.immortalwrt.org/releases/24.10.6/packages/aarch64_cortex-a53/packages/
HomeProxy — service init script — https://github.com/immortalwrt/homeproxy/blob/98a6ad9e71484528008ff435694fd107591f3a1d/root/etc/init.d/homeproxy
OpenWrt — opkg package manager — https://openwrt.org/docs/guide-user/additional-software/opkg
HomeProxy — node settings view — https://github.com/immortalwrt/homeproxy/blob/98a6ad9e71484528008ff435694fd107591f3a1d/htdocs/luci-static/resources/view/homeproxy/node.js
sing-box — Configuration — https://sing-box.sagernet.org/configuration/
HomeProxy — client settings view — https://github.com/immortalwrt/homeproxy/blob/98a6ad9e71484528008ff435694fd107591f3a1d/htdocs/luci-static/resources/view/homeproxy/client.js

Sources checked 14 October 2026.

Related articles:

HomeProxy OpenWrt Setup: Install, Verify and Roll Back