Open-Box
EN

Documentation

Install, upgrade and Pro

Installing, upgrading, rolling back and uninstalling the router side, plus Pro trials, activation and moving to a new router.

Install

Log in to your OpenWrt router over SSH as root and run:

curl -fsSL https://raw.githubusercontent.com/liandu2024/Open-Box/main/scripts/install.sh | sh

If GitHub is hard to reach, fetch the install script through a raw mirror and let the script download the release through the mirror too:

curl -fsSL https://gh-proxy.com/raw.githubusercontent.com/liandu2024/Open-Box/main/scripts/install.sh | sh -s -- --mirror

--mirror only affects the package download. If raw.githubusercontent.com itself is unreachable, adding --mirror to the original URL still won’t get you the script.

The installer asks once for the panel port (default 3036 — just press Enter). It checks that the port is free first; if another program uses it, or it clashes with ports Open-Box or the system needs, it explains why and asks again. You can also pass it directly with --port, e.g. append --port 3080 to the command above. You can change it later, see Change the panel port.

Requirements: OpenWrt, x86_64 or aarch64, at least 512 MB of storage and 512 MB of memory. The install / upgrade script checks for and tries to add system packages with opkg or apk (kmod-tun, kmod-nft-queue, kmod-nft-nat, kmod-veth, ip-full, ca-bundle). If the package feed is unreachable it only warns and keeps going, so you can install them by hand later; set OPENBOX_SKIP_DEPS=1 to skip this step.

When it’s done, open http://<router LAN address>:<panel port> in your browser (the script prints this address at the end) and set a panel password on first visit. If you ever forget it, there’s no need to reinstall — see Forgot the panel password.

Debian / Ubuntu

The same install, upgrade and uninstall commands work on Debian / Ubuntu (systemd required; tested on Ubuntu 24.04) — run them as root or with sudo. The script detects the system: services are handled by systemd (openbox.service for the core, openbox-panel.service for the panel) and the open-box command goes to /usr/local/bin. The bundled Node is the musl build for OpenWrt, so the installer downloads the matching official glibc build from nodejs.org (or npmmirror if that fails); the machine needs to reach one of them. Dependencies are installed with apt (nftables, xz-utils, iproute2, ca-certificates); the tun / nftables kernel modules come with the distribution kernel.

Differences from OpenWrt:

  • No LuCI page and no dnsmasq routing mode — DNS is either “firewall hijack” or “off”. If the machine uses systemd-resolved, its upstream queries are taken over by the core too; no changes to resolved are needed.
  • You manage the firewall yourself: the script writes no allow rules. With ufw / firewalld installed, allow the panel port yourself, and (as a bypass router) forwarding from the LAN to this machine.
  • The core turns on IP forwarding when it starts (net.ipv4.ip_forward=1, turned back off on stop if it was off before), so LAN devices can point their gateway / DNS at this machine and be routed by it. If it’s only for this machine, you can ignore this.
  • For troubleshooting, see journalctl -u openbox -u openbox-panel; to fall back to direct access in an emergency, run systemctl stop openbox.

Change the panel port

New installs default to port 3036. Machines installed with v0.1.216 or earlier keep their port after upgrading (still 2026) — the new default won’t move them.

Two ways, same result:

  • LuCI page: Router admin → Services → Open-Box, then click “Change port” at the end of the button row on the “Open-Box panel” card. Enter the new port and save; if there’s a conflict it won’t save and tells you why. A running panel restarts once automatically.
  • SSH: open-box port shows the current port, open-box port 3080 changes it to 3080.

Remember to open the panel at the new address afterwards.

Forgot the panel password

The panel password is stored on the router. If you can log in to the router as root you can look it up — no reinstall needed, and you won’t lose subscriptions or rules. Two places to look:

1. LuCI page: Router admin → Services → Open-Box. In the line at the top that points you to the Open-Box panel, the password is shown right after the panel address. If you just upgraded and don’t see it, log out of LuCI and back in.

2. SSH: after logging in over SSH, run open-box and choose 1:

root@OpenWrt:~# open-box

Open-Box v0.1.216
  1) Current password
  2) Restart
  3) Check for updates
  4) Uninstall
  5) Exit
Choose [1-5]: 1

  Panel address: http://192.168.1.1:3036
  Current password: ********

To print only the password, run open-box password. open-box check checks for a new version, open-box update upgrades right away, open-box restart restarts the core and the panel, and open-box uninstall uninstalls.

Both entry points are available from v0.1.210. On older versions, first upgrade over SSH with the command in “Upgrade” below (your password, subscriptions and rules are kept); the open-box command is available once the upgrade finishes.

To change the password after you’ve found it: log in to the panel and click “Change password” on the Settings page.

Upgrade

Check for updates in the panel under Settings → Backend Settings, or run this over SSH (same command on OpenWrt and Debian / Ubuntu):

curl -fsSL https://raw.githubusercontent.com/liandu2024/Open-Box/main/scripts/update.sh | sh

Upgrades keep your subscriptions, rules and panel password, and verify the Open-Box, sing-box and GeoSite / GeoIP components. Components that are identical and intact are reused; only changed, missing or damaged ones are downloaded from this repository’s Releases.

Roll back to the previous version

If the panel or core misbehaves after an upgrade, roll back with the command below. The script looks up the most recent stable Release before your current version on GitHub and reinstalls that version’s full package. The router keeps no local backup of old versions, so rolling back needs access to GitHub (or a mirror); data such as subscriptions, rules and the panel password is left untouched.

curl -fsSL https://raw.githubusercontent.com/liandu2024/Open-Box/main/scripts/update.sh | sh -s -- --rollback --direct

If GitHub is hard to reach, go through a proxy:

curl -fsSL https://gh-proxy.com/raw.githubusercontent.com/liandu2024/Open-Box/main/scripts/update.sh | sh -s -- --rollback --mirror https://gh-proxy.com

Both commands detect the router architecture, download the previous version’s full package, verify its SHA256 and then replace the current files; if verification or replacement fails, the current install is kept. --mirror only affects the package download — the GitHub API call that lists Releases tries direct first and falls back to the mirror.

Uninstall

By default this stops the services and keeps your subscriptions and settings:

curl -fsSL https://raw.githubusercontent.com/liandu2024/Open-Box/main/scripts/uninstall.sh | sh

To delete the data as well:

curl -fsSL https://raw.githubusercontent.com/liandu2024/Open-Box/main/scripts/uninstall.sh | sh -s -- --purge

Pro

Share network and the apps are part of Pro. One license covers one router, and you can pair unlimited phones and computers to it.

Free trial

Every router can try Pro free for 14 days: click “Free trial” on the Settings · Share network or Settings · App page in the panel — no sign-up needed. When the trial ends, Share network and the apps stop working, but your settings are kept and come back as soon as you activate.

Activate

  1. Buy on the website. Your license key appears right after payment and is also sent to your email.
  2. Open the router panel, go to Settings · Backend Settings, and click “Enter key” on the Pro card.
  3. Paste the key and click “Activate”. The router needs Internet access (the license service is reached through Destination routing, like any LAN device).

Once activated, the router renews its license automatically every day and keeps working for 30 days without Internet.

Move to a new router

Enter the same license key in the new router’s panel and follow the prompt to move it; the old router is deactivated automatically. You can move a license yourself 5 times a year, or unlink it first under My licenses.

Expiry and renewal

You get a reminder in the panel and by email 14 days and 3 days before a yearly license expires. After it expires, Share network and the apps stop working and every setting is kept; renewing adds one year from the original expiry date. Yearly users can upgrade to lifetime for $70 while their license is active.