iKuai Bypass: syncing split routing rules onto iKuai routers

What the tool actually synchronises

iKuai Bypass is a rule synchronisation tool written for iKuai routers. The project description gives the intent plainly: it downloads IP and domain lists from the internet and syncs them into your router so that traffic automatically takes the right line. The examples of what that produces are the reason the tool exists. Mainstream sites and domestic IP traffic can be sent straight through the optical modem, while specific traffic goes via a bypass router or gateway, and the tool can sync and update that arrangement automatically while remaining compatible with split routing rules you maintain by hand. The other capabilities listed in the description cover domain based splitting, port based splitting through IP group routing, custom carrier selection, and ad blocking. In other words, the unit of work is a router configuration, not a packet filter on your laptop, which is why the tool is tied to one router platform rather than being a general purpose proxy.

Four ways to install it, one Rust core

The README lists several deployment shapes, and the split is driven by where the tool has to run. There is a GUI, a graphical tool supporting desktop and mobile apps across Windows, macOS, Linux, Android and iOS, which is the Tauri front end. There is a CLI with an optional web interface, aimed at servers, OpenWrt, NAS, PVE and Docker deployments. OpenWrt users can manage it from the LuCI web interface with a one click IPK install. And there is an iKuai plugin in the ipkg format used by the iKuai plugin market, so it can be installed straight into iKuai. Underneath, the code is a Cargo workspace whose members are `crates/core`, `apps/cli`, `apps/gui` and `apps/integration-tests`, which is the usual shape for a Rust core with separate front ends. The README also asks contributors to follow strict rules for Rust and TypeScript code: zero Clone, zero implicit panic and zero Any.

Firmware versions decide which release you need

The README carries a version selection note that saves a lot of confusion. For iKuai v3.7x the project points at release v4.2.0, and the older Go implementation is archived at v4.4.13, with an upgrade guide linked for existing users of that Go version. The repository layout shows the same history: there is a `golang_archive/` directory next to the Rust `crates/`, so the language rewrite is visible in the tree rather than implied. The Rust rewrite also brought a much wider deployment surface, since the archived Go tool ran in fewer environments than the CLI, GUI, LuCI and Docker forms the project supports now. The most recent tags tell the same story about release cadence, with ikuai-bypass-v4.4.111-alpha.1 on 2026-10-01 and ikuai-bypass-v4.4.110 on 2026-09-15, so alpha and stable builds are published from the same line and the version numbers run well past v4.4.

The Docker image exposes a config volume and a cron mode

The Dockerfile in the repository is short and shows the container contract. It is based on alpine:3.20, installs ca-certificates, tzdata and unzip, and sets the timezone to Asia/Shanghai. The binary is copied from a per-architecture directory selected from the `TARGETPLATFORM` build argument, with explicit handling for linux-amd64, linux-386, linux-arm64, linux/arm/v7, linux/arm/v6, linux-ppc64le and linux-riscv64, and an explicit failure for anything else. Configuration lives in a volume at `/etc/ikuai-bypass`, the image exposes port 19001, and the default command is a cron mode:

FROM alpine:3.20

ARG TARGETPLATFORM

RUN apk add --no-cache ca-certificates tzdata unzip

ENV TZ=Asia/Shanghai

WORKDIR /opt/ikuai-bypass

COPY docker/bin /opt/ikuai-bypass/docker/bin
COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
COPY config.yml /opt/ikuai-bypass/config.yml
COPY docker/frontends/app/dist /opt/ikuai-bypass/frontends/app/dist

The default container command is `CMD ["-r", "cron"]`, so the container is meant to run a scheduled sync loop rather than to be a long lived service you drive by hand. The separate `docker/` and `frontends/` directories in the repository hold the image build inputs and the prebuilt web assets the image copies in, which is why the front end arrives precompiled rather than built inside the container.

Routing modes are the decision you have to make first

The documentation table in the README splits the project into a getting started guide, a routing mode page, a CLI parameter page, a deployment page and an update log. The routing mode page is the one that matters for correctness, because it explains the difference between carrier based splitting combined with domain based splitting, and IP group and port based splitting. Those are different topologies: the first separates traffic by operator and by name, the second separates it by which group and port a rule belongs to, and getting that wrong on a live router is a good way to lose connectivity for half your traffic. The CLI parameter page covers run mode, routing mode and cleanup parameters, and the cleanup flags are what you want on the first run, since a tool that writes rules into a router should be able to remove the rules it wrote before it starts replacing them with something else. The README points to the quickstart page for one click install of the Linux CLI service, the LuCI panel, and Docker and GUI deployment.

Where this does not apply to your network

Two boundaries are visible. The first is platform specificity. The tool targets iKuai routers, and the iKuai plugin in ipkg form only makes sense inside that platform's plugin market. The OpenWrt path exists through the LuCI panel and the CLI, but the rule model being written is still iKuai's. If your network runs a different router software, the deployment is a general CLI and Docker story at best, and you should confirm from the deployment documentation that your device is covered. The second is the upstream dependency. The tool downloads IP and domain lists from remote sources, and it applies them to your router, so the quality of the lists and the trust you place in the remote source is part of the risk. The README's approach to that is to let you host the configuration yourself, with `config.yml` at the repository root and a documented set of configuration files. Any deployment should also assume that a bad rule set can break routing, so the cleanup parameters are not optional extras.

Licence, support channels and what the project asks for

The project is licensed under AGPL-3.0, and that choice matters if you intend to run it as a service for others, since the copyleft terms reach network use. The README also asks for sponsorship, listing a TRX wallet address on the Tron TRC20 network, and it notes that starring the repository is a form of support. The feedback channels are GitHub Discussions for questions, GitHub Issues for bugs, and a Telegram group. Credit goes to ztc1997 for the original version idea and to the pull request contributors, and the repository carries a `CLA.md`, which indicates that contributions are made under a contributor licence agreement. Documentation lives in a `docs/` directory for the site and a `dev-docs/` directory for developer notes, and the site itself is published at joyanhui.github.io/ikuai-bypass with a quickstart page, a router mode page, a CLI parameters page, a deployment page and a changelog.

Editorial conclusion

iKuai Bypass fits a home lab or small office that runs an iKuai router and wants domain and IP based split routing maintained from a remote list rather than by hand, and it also suits OpenWrt users through the LuCI panel and the CLI build. It is the wrong tool if you have no iKuai router at all, or if your operator only exposes the router API in a way this tool does not cover, since the integration is specific to that platform. Before you deploy, read docs/router-mode.md to pick a routing mode, check docs/cli-params.md for the cleanup and run-mode flags, and confirm your iKuai firmware version against the version guidance in the README. The last push was on 2026-10-01 with ikuai-bypass-v4.4.111-alpha.1 tagged the same day, under AGPL-3.0.

Frequently asked questions

Official sources

1. joyanhui/ikuai-bypass on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases