paqctl: one shell script for two firewall bypass backends

Two backends with different difficulty and different ports

paqctl is described as a unified management tool for bypass proxies, helping you connect to a server outside a restricted network and reach the internet freely. The deployment model is the familiar one: the server component runs on a VPS, the client on your Windows, Mac or Linux machine.

What is new is that it manages two different bypass methods behind one interface, and the project makes the choice explicit in a comparison table.

Paqet is rated easy and is best for most situations. Its local proxy is 127.0.0.1:1080, the technology is KCP over raw sockets, and the server needs only paqet itself.

GFW-Knocker, abbreviated GFK, is rated advanced and is aimed at heavy censorship such as the Great Firewall. Its local proxy is 127.0.0.1:14000, the technology is violated TCP plus a QUIC tunnel, and the server needs GFK plus Xray.

The decision procedure in the README is a simple flowchart. If your network is heavily censored, as in Iran or behind China's GFW, try GFK first. If it is not, use Paqet.

There is also a tip that reflects how these tools are actually used in practice. You can install both and keep one as a fallback, because they use different ports and therefore do not conflict.

How Paqet avoids fingerprinting

The Paqet path is the simpler of the two and the diagram makes the shape clear: a browser on your machine talks to a local Paqet client on 127.0.0.1:1080, which sends KCP over random UDP to the Paqet server on your VPS, and the server exposes a SOCKS5 proxy to the internet.

The mechanism is described in three steps. It uses the KCP protocol over raw TCP packets with custom TCP flags. It sends packets via raw sockets, which makes them hard to fingerprint. And the result is that DPI systems cannot easily identify it as proxy traffic.

That last point is the design goal stated plainly. A DPI classifier is looking for recognisable signatures, and the technique here is to avoid having one. Randomised UDP framing and custom TCP flags mean the packets do not look like the traffic they carry.

The cost is that raw sockets require elevated privileges, which is why the server install runs under sudo. This is a technique with a real fingerprinting downside in general, and the README does not make a claim about the traffic being invisible. It claims it is hard to fingerprint, which is a weaker and more defensible statement.

How GFW-Knocker breaks the handshake on purpose

The GFK path is more aggressive and the diagram shows an extra hop in the middle: the local client on port 14000 sends violated TCP to the GFK server, which tunnels it over QUIC, and Xray on the server side provides the actual SOCKS5 service.

The three components work like this. Violated TCP sends TCP packets that are intentionally broken, with wrong flags and no proper handshake, because firewalls expect normal TCP and often pass these through. The QUIC tunnel runs inside those violated packets and carries your actual data. And the Xray backend on the server provides the real SOCKS5 proxy service.

This is a different strategy from Paqet rather than a faster version of the same one. Paqet hides the payload in a protocol that does not look like proxy traffic. GFK relies on the firewall not caring that the TCP is malformed, because middleboxes which expect a valid handshake frequently fail closed on the check or pass the packet through rather than drop it.

The cost is complexity. You now have two protocols stacked, a non standard TCP layer and QUIC, and a dependency on Xray on the server. That is why the project rates it advanced and routes heavy censorship cases to it while sending everyone else to Paqet.

Detection of an existing Xray panel

The part of the design that is most thoughtful is what happens when you already run an Xray based panel such as 3x-ui or Marzban on the server.

The README states that paqctl detects the panel and works alongside it, that your panel stays untouched, and that paqctl only adds what is needed. A table then gives the three scenarios. With no Xray installed, paqctl installs Xray with a SOCKS5 proxy automatically and there is nothing to configure. With an Xray panel running, it keeps the panel and adds a SOCKS5 inbound on a free port such as 10443, appending an extra port mapping automatically. With Xray installed but not running, it installs its own SOCKS5, the same as a fresh install.

When a panel is detected, you get two connections automatically. The panel mapping of 14000 to 443 is for server to server panel traffic carrying vmess or vless, and the SOCKS5 mapping of 14001 to 10443 is for direct proxy use from Windows or Mac without needing v2rayN.

That dual mapping is the key insight in the design. Rather than asking you to restructure your existing panel, it adds a parallel path, and the existing outbound configuration keeps working while a second route is available.

Installing it: one curl into sudo bash on both ends

Installation is the same command on the server and the client, with the role chosen at run time.

curl -fsSL https://raw.githubusercontent.com/SamNet-dev/paqctl/main/paqctl.sh | sudo bash

On the foreign server you choose the server role and set the port mapping, for example 14000 to 443 where 443 is your panel's inbound port. paqctl detects Xray and adds a SOCKS5 alongside your panel, for instance 14001 to 10443.

On the Iran server you choose the client role, and the instruction is to use the exact same port mappings shown in the server output, such as 14000 to 443 and 14001 to 10443, and to use the same auth code from the server setup.

The last step is to change one outbound in the Iran panel so it routes through the tunnel rather than connecting directly. Before, the outbound points at the foreign server address on port 443. After, it points at 127.0.0.1 on port 14000, with the protocol and identifier unchanged from the foreign panel's inbound and the security set to None because the traffic is already encrypted inside the GFK tunnel.

In 3x-ui the path is Xray Configs, then Outbounds, then Add Outbound, and the guidance stresses that the port is the VIO port and not the original server port.

What the repository holds and what to watch

The repository is small in a way that matches the tool. The top level contains paqctl.sh, which is the installer and manager, a gfk/ directory for the GFW-Knocker pieces, a windows/ directory for the Windows client, the LICENSE file, and the README, which is unusually long and carries a Persian version at the top with a link anchor for it.

The project is written in Shell, which is stated in the repository metadata, and the whole design is one script that you run as root on both ends. That is the honest description and it has real consequences: the security of the installation depends on trusting the script, and the install command pipes a remote file straight into a root shell.

The release history is short and recent. The listed releases are v1.1.0 on 2026-07-11, described as supercharged performance with universal cross platform hardening and a self healing watchdog, and v1.0.1 on 2026-07-07, described as a feature expansion and stability release. The repository is not archived and the last push was on 2026-07-17.

The licence is AGPL-3.0, recorded in the LICENSE file and in the badge.

Two things to keep in mind before deploying this. First, the local proxy ports, 1080 for Paqet and 14000 for GFK, are listening on the loopback interface as described, and you need to check that nothing else on your machine is bound to them. Second, the topics attached to the repository include socks5, tunnel, vpn and raw socket, and the whole point of the tool is to defeat inspection, which is a legitimate personal use in many places and a regulated one in others.

Editorial conclusion

Adopt paqctl if you are running a personal proxy for a censored network and want the choice between a simple KCP based tunnel and a more aggressive violated TCP transport without wiring up two separate toolsets, since the same script covers the server role, the client role and the Xray detection on both ends. Do not expect it to be a general purpose VPN client or a hardened service for multi user deployment, since it is a single shell script whose installation is a curl pipe into sudo bash. Verify first that you understand the AGPL-3.0 licence and the legal position in your jurisdiction, that you can run a root install script on your VPS and read what it does before running it, and that your server has Xray installed or that you are happy to let the script install it, since the GFK backend depends on it.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. SamNet-dev/paqctl on GitHub