Feature Positioning: Why 8001 Exists and When You Need Another Port
kuailian ships with an optional local HTTP/SOCKS listener on port 8001 so that legacy apps that cannot import a PAC file still have a fixed proxy endpoint. The number 8001 is simply an IANA-unassigned port that rarely collides with common services; it is not hard-wired into the protocol. If you run another dev server, CI runner, or container that already binds 8001, the clash will stop kuailian from starting its helper process and the tray icon stays yellow. Moving the listener is therefore a conflict-resolution task, not a performance tweak.
Empirical observation: corporate laptops that pre-install Docker Desktop or Jenkins often reserve 8000–8010, so first-time kuailian users on those machines see the “Proxy helper offline” toast within 30 s of the first launch. Reassigning the port once eliminates 90 % of such support tickets.
Plan Tier Check: Who Can Actually Edit the Port
Port override is gated by the Listener Control permission, which is unlocked on the Pro and Team tiers only. Free tier users can toggle the proxy on/off but the numeric field is read-only. You can verify your tier from Settings → Account → Subscription; if the label says Basic, the file-editing method described below will be reverted at the next service restart.
Decision Tree in One Glance
- Need a custom port → upgrade to Pro (individual) or Team (5-seat min).
- Already Pro → proceed to file edit or in-app UI.
- Only need PAC URL → stay on Free and use the auto-generated PAC endpoint (no port change required).
This three-step filter keeps support overhead low: most Free users never touch the port, while power users get the flexibility they pay for.
UI Path: Changing the Port Inside the Apps
Windows / macOS Desktop (v6.3 as of this writing)
- Right-click the kuailian tray icon → Preferences.
- Sidebar: Advanced → Local Proxy.
- Change Listen Port from 8001 to your desired value (1024–65535, avoid well-known ports <1024 unless running as admin).
- Click Save & Restart Helper; the icon blinks green twice when the new socket is active.
The restart is near-instant because only the helper process reloads; your active tunnels stay intact.
Android / iOS
Mobile builds expose the same setting but tuck it under Settings → privacy tool & Apps → Local HTTP Proxy (Beta). Toggle it on first, then the port field becomes editable. Note that on iOS the keyboard defaults to the emoji keypad; tap 123 to enter digits. After confirmation the app cycles the tunnel for ~2 s; no system-wide restart is needed.
File-Level Method: Editing config.json When the UI Is Blocked
If the machine is headless or the GUI crashes on launch, you can still relocate the port before the service starts. Locate the profile folder:
- Windows:
%APPDATA%\KuaiLian\profile\config.json - macOS:
~/Library/Application Support/KuaiLian/profile/config.json - Linux (tarball install):
~/.local/share/kuailian/profile/config.json
Make sure kuailian is fully quit (tray icon gone), then open the file in a text editor with UTF-8 preservation. Find the block:
"localProxy": {
"enabled": true,
"listen": "127.0.0.1:8001",
"type": "http+socks"
}
Replace 8001 with your chosen port, save, and start the client. A successful launch writes an entry like Local proxy bound to 127.0.0.1:XXXX in logs/service-yyyy-mm-dd.log.
Verification & Troubleshooting
Quick Sanity Checks
- netstat -an | findstr LISTENING (Windows) or ss -ltnp (Linux) should show the new port on 127.0.0.1.
- curl test:
curl -x http://127.0.0.1:XXXX https://ipinfo.iomust return the privacy tool exit IP, not your ISP. - If you see
Address already in use, pick a different port; empirical observation: even numbers above 50 000 collide less.
These three commands together confirm that the socket is live, reachable, and correctly forwarding.
Common Failure Modes
Mode 1: Port resets to 8001 after reboot. Cause: the config file is Roaming-folder redirected and OneDrive restored an older copy. Fix: exclude the KuaiLian folder from Office backup or move the profile to a non-synced location via --profile-dir switch.
Mode 2: Android port field accepts the value but proxy apps timeout. Cause: battery saver killed the local helper. Add kuailian to the system “Unrestricted” battery bucket and re-toggle the proxy switch.
Trade-offs: When Not to Move the Port
Corporate firewalls that whitelist 8001/TCP for the privacy tool vendor will block any other port by default. If you are on a managed device, changing the listener may breach security policy and the agent will auto-revert the value at the next MDM sync. In that scenario ask the admin to add your desired port to the allowed list instead of editing the client.
Integration Examples
Example 1: Switching Port for Local Selenium Grid
A QA engineer runs Chrome nodes through kuailian to geo-test ads. The Grid hub already occupies 8000–8003. She sets kuailian to 8899, then exports http_proxy=127.0.0.1:8899 in the node startup script. Result: traffic from 60 parallel sessions exits in 12 countries without socket collision.
Example 2: Sharing the Proxy with a Docker Container
On macOS, Docker Desktop cannot see 127.0.0.1 of the host. The developer changes the listener to 0.0.0.0:8899 (bind-all) and adds --add-host=host.docker.internal:host-gateway. Containers now reach http://host.docker.internal:8899 and still enjoy the kill-switch if the tunnel drops.
Applicable / Non-applicable Scenario Checklist
| Scenario | Custom Port Recommended? | Rationale |
|---|---|---|
| Home user, no other servers | No | 8001 is free; avoid needless change. |
| Dev laptop with Docker | Yes | Prevent collision with app containers. |
| Corporate managed device | Ask IT | Policy may whitelist only 8001. |
| Running two kuailian copies | Mandatory | Each instance needs unique port. |
Best-Practice Recap
- Pick an unused high port (10 000–49 000) to stay clear of ephemeral ranges.
- Edit while the client is off to avoid race conditions.
- Verify with
curlandnetstatbefore rolling the change into CI pipelines. - Document the new port in your team run-book; otherwise the next teammate will spend an hour wondering why the proxy “disappeared”.
Frequently Asked Questions
Does changing the port improve speed?
No. The listener port is just a local socket; throughput depends on the server node and your ISP, not the port number.
Can I use port 443 to bypass a restrictive firewall?
Only if you run the client with admin rights (ports <1024 require elevation). Even then, DPI looks at packet content, not port, so the gain is minimal.
Why does the UI still show 8001 after I edited config.json?
The GUI caches values at launch. Fully quit the app (kill tray process) and restart; it will read the file again.
Next Steps
If the port change was only the first hurdle—say you also need to force certain apps not to use the proxy—head to Settings → Split Tunnelling and add their executables to the bypass list. For automation, store the desired port in an environment variable and reference it in scripts so future updates only require a single-line change. Finally, export your settings (Settings → Advanced → Export Profile) after everything works; restoring a known-good config beats retyping port numbers after the next reinstall.
