SkillAgentSearch skills...

Paqctl

Unified proxy manager for bypassing firewalls - supports Paqet (KCP/raw socket) and GFW-Knocker (violated TCP/QUIC) with dual-backend simultaneous operation

GenerateConvertImprove

Install / Use

/learn @SamNet-dev/Paqctl
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

                            _   _
 _ __   __ _  __ _  ___| |_| |
| '_ \ / _` |/ _` |/ __| __| |
| |_) | (_| | (_| | (__| |_| |
| .__/ \__,_|\__, |\___|\__|_|
|_|             |_|

Version License Server Client

Bypass firewall restrictions and access the free internet

نسخه فارسی

What is this?

paqctl is a unified management tool for bypass proxies. It helps you connect to a server outside restricted networks (like behind the Great Firewall) and access the internet freely. You run the server component on a VPS, and the client on your Windows/Mac/Linux machine.

Two Methods

This tool supports two different bypass methods. Choose based on your situation:

| | Paqet | GFW-Knocker (GFK) | |---|---|---| | Difficulty | Easy ⭐ | Advanced ⭐⭐⭐ | | Best for | Most situations | Heavy censorship (GFW) | | Your proxy | 127.0.0.1:1080 | 127.0.0.1:14000 | | Technology | KCP over raw sockets | Violated TCP + QUIC tunnel | | Server needs | Just paqet | GFK + Xray |

Which should I use?

START HERE
     |
     v
+----------------------------------+
| Is your network heavily censored |
| (like Iran or China's GFW)?      |
+----------------------------------+
     |                |
    YES               NO
     |                |
     v                v
+-----------+    +-----------+
| Try GFK   |    | Use Paqet |
| first     |    |           |
+-----------+    +-----------+

Tip: You can install BOTH and have a backup! They use different ports.

How It Works

Paqet (Simple)

YOUR COMPUTER                YOUR VPS                   INTERNET
+--------------+            +--------------+           +----------+
|  Browser     |            |    Paqet     |           |  Google  |
|      |       |            |    Server    |           |  YouTube |
|      v       |  ---KCP--> |      |       |  -------> |  etc.    |
|  Paqet       | (random    |      v       |           |          |
|  Client      |    UDP)    |    SOCKS5    |           |          |
+--------------+            +--------------+           +----------+
  127.0.0.1:1080              your.vps.ip

How Paqet bypasses firewalls:

  1. Uses KCP protocol over raw TCP packets with custom TCP flags
  2. Sends packets via raw sockets, making them hard to fingerprint
  3. DPI systems can't easily identify it as proxy traffic

GFW-Knocker (Advanced)

YOUR COMPUTER                YOUR VPS                   INTERNET
+--------------+            +--------------+           +----------+
|  Browser     |            |  GFK Server  |           |  Google  |
|      |       | "Violated  |      |       |           |  YouTube |
|      v       |    TCP"    |      v       |           |  etc.    |
|  GFK Client  | ---------> | QUIC Tunnel  |  -------> |          |
|  (VIO+QUIC)  | (malformed |      |       |           |          |
|      |       |  +QUIC)    |      v       |           |          |
|  Port 14000  |            |    Xray      |           |          |
+--------------+            +--------------+           +----------+
  127.0.0.1:14000             your.vps.ip

How GFK bypasses firewalls:

  1. Violated TCP: Sends TCP packets that are intentionally "broken" - they have wrong flags, no proper handshake. Firewalls expect normal TCP and often pass these through.
  2. QUIC Tunnel: Inside these violated packets, there's a QUIC connection carrying your actual data.
  3. Xray Backend: On the server, Xray provides the actual SOCKS5 proxy service.
<details> <summary><strong>Click here if you want to set up GFK alongside an Xray panel (3x-ui, Marzban, etc.) — includes server-to-server bridge setup</strong></summary>

If your foreign server already has an Xray panel (3x-ui, Marzban, etc.), paqctl detects it and works alongside it. Your panel stays untouched — paqctl only adds what's needed.

What paqctl does when it detects Xray:

| Scenario | What paqctl does | |---|---| | No Xray installed | Installs Xray with SOCKS5 proxy automatically (nothing to configure) | | Xray panel running | Keeps your panel, adds a SOCKS5 inbound on a free port (e.g. 10443), appends an extra port mapping automatically | | Xray installed but not running | Installs its own SOCKS5 (same as fresh install) |

When a panel is detected, paqctl gives you two connections automatically:

  • Panel mapping (14000:443) — for server-to-server panel traffic (vmess/vless)
  • SOCKS5 mapping (14001:10443) — for direct proxy use from Windows/Mac (no v2rayN needed)

Setup A: Server-to-Server (Iran panel to Foreign panel)

This is for when you have a panel on both servers (Iran + foreign) and want to route the Iran panel's outbound through the GFK tunnel instead of a direct connection.

1. Install paqctl on the foreign server (server role):

curl -fsSL https://raw.githubusercontent.com/SamNet-dev/paqctl/main/paqctl.sh | sudo bash
  • Choose server role
  • Set port mapping: 14000:443 (where 443 is your panel's inbound port)
  • paqctl detects Xray and adds SOCKS5 alongside your panel (e.g. 14001:10443)

2. Install paqctl on the Iran server (client role):

curl -fsSL https://raw.githubusercontent.com/SamNet-dev/paqctl/main/paqctl.sh | sudo bash
  • Choose client role
  • Use the exact same port mappings shown in the server output (e.g. 14000:443,14001:10443)
  • Use the same auth code from the server setup

3. Update your Iran panel outbound to route through GFK:

In your Iran panel (3x-ui, Marzban, etc.), change the outbound that connects to the foreign server:

Before (direct connection — blocked by DPI):

{
  "tag": "vmess_out",
  "protocol": "vmess",
  "settings": {
    "vnext": [{
      "address": "FOREIGN_SERVER_IP",
      "port": 443,
      "users": [{"id": "your-uuid", "security": "auto"}]
    }]
  }
}

After (routed through GFK tunnel):

{
  "tag": "vmess_out",
  "protocol": "vmess",
  "settings": {
    "vnext": [{
      "address": "127.0.0.1",
      "port": 14000,
      "users": [{"id": "your-uuid", "security": "auto"}]
    }]
  }
}

In 3x-ui: go to Xray Configs → Outbounds → Add Outbound (or edit existing), and fill in:

  • Address: 127.0.0.1
  • Port: 14000 (the VIO port, NOT the original server port)
  • Protocol/ID/encryption: keep the same as before (from your foreign panel's inbound)
  • Security: None (traffic is already encrypted inside the GFK tunnel)

Where do I get the UUID? From your foreign server's panel — go to Inbounds, find the inbound you're connecting to, and copy its UUID/ID. If you already had a working outbound before, just change the address and port — everything else stays the same.

Traffic flow:

End user --> Iran panel inbound --> Iran panel outbound (127.0.0.1:14000)
  --> GFK client (VIO port) --> QUIC tunnel over violated TCP
  --> Foreign GFK server --> 127.0.0.1:443 (foreign panel inbound) --> Internet

Setup B: Direct Client (Windows/Mac to Foreign server)

This is for when you don't have an Iran server — you connect directly from your Windows or Mac to the foreign server through GFK. paqctl auto-adds a SOCKS5 proxy so you can use it as a simple browser proxy.

1. Install paqctl on the foreign server (same as above)

2. On your Windows/Mac, install the GFK client and use the SOCKS5 mapping:

  • The server output will show something like: Mappings: 14000:443,14001:10443
  • Use 14001 as your proxy port — this is the direct SOCKS5 (no panel/v2rayN needed)
  • Configure your browser or system proxy to SOCKS5 127.0.0.1:14001

Traffic flow:

Browser (SOCKS5 127.0.0.1:14001) --> GFK client
  --> QUIC tunnel over violated TCP
  --> Foreign GFK server --> 127.0.0.1:10443 (SOCKS5 proxy) --> Internet

Multiple ports: If your panel uses multiple ports, map them all:

14000:443,14001:8080,14002:2020

paqctl will add SOCKS5 on the next available port and append it automatically.

Note: The "Firewall: VIO port blocked" status message (shown in green) is normal and correct. It means the firewall is properly configured for GFK's raw socket to work.

</details>

Quick Start

1. Server Setup (Linux VPS)

Run this on your VPS (requires root):

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

The installer automatically downloads the latest paqet release from GitHub.

Then open the interactive menu:

sudo paqctl menu

After setup, get your connection info:

sudo paqctl info

This will show you the Server IP, Port, and Key/Auth Code you need for the client.

2. Client Setup

<details> <summary><h3>🪟 Windows Client Setup (Click to expand)</h3></summary>

Windows Client - Complete Guide

Prerequisites

  • Windows 10 or 11
  • Administrator access
  • Your server's connection info (from paqctl info on server)

🚀 Easy Method (Recommended) - Using .bat Files

The simplest way to get started - just download, double-click, and connect!

Step 1: Download

  1. Go to: https://github.com/SamNet-dev/paqctl
  2. Click the green "Code" button → "Download ZIP"
  3. Extract the ZIP file anywhere (e.g., Desktop)
  4. Open the windows folder inside

Step 2: Install Protocol

You'll see two .bat files:

  • Paqet-Client.bat - For Paqet protocol (simple, recommended)
  • GFK-Client.bat - For GFW-knocker protocol (advanced)

Right-click your chosen `.b

SamNet-dev

View profile

View on GitHub
GitHub Stars789
CategoryCustomer
Updated2d ago
Forks121
SamNet-dev/paqctl

Languages

Shell

Security Score

100/100

Audited on Mar 25, 2026

No findings