Quick Start

Installation

Golang Version

go install github.com/linksocks/linksocks/cmd/linksocks@latest

Or download pre-built binaries from releases page.

Docker

docker run --rm -it jackzzs/linksocks --help

Python Version

pip install linksocks

INFO

The python version is a wrapper of the Golang implementation. See: Python Bindings

Forward Proxy

In forward proxy mode, the server provides network access and the client runs the SOCKS5 interface.

Server Side:

# Start server with WebSocket on port 8765
linksocks server -t example_token

Client Side:

# Connect to server and provide SOCKS5 proxy on port 9870
linksocks client -t example_token -u ws://localhost:8765 -p 9870

Test the proxy:

curl --socks5 127.0.0.1:9870 http://httpbin.org/ip

Reverse Proxy

In reverse proxy mode, the server runs the SOCKS5 interface and clients provide network access.

Server Side:

# Start server with SOCKS5 proxy on port 9870
linksocks server -t example_token -r -p 9870

Client Side:

# Connect as network provider
linksocks client -t example_token -u ws://localhost:8765 -r

Test the proxy:

curl --socks5 127.0.0.1:9870 http://httpbin.org/ip

Agent Proxy

In agent proxy mode, the server acts as a relay between two types of clients: providers (who share network access) and connectors (who use the proxy). Each type uses different tokens for controlled access.

Server Side:

# Start server with both provider and connector tokens
linksocks server -t provider_token -c connector_token -p 9870 -r

Provider Side:

# Connect as network provider
linksocks provider -t provider_token -u ws://localhost:8765

Connector Side:

# Connect to use the proxy
linksocks connector -t connector_token -u ws://localhost:8765 -p 1180

Test the proxy:

curl --socks5 127.0.0.1:1180 http://httpbin.org/ip

Autonomy Mode

Autonomy mode is a special type of agent proxy with the following characteristics:

1. The server's SOCKS proxy will not start listening
2. Providers can specify their own connector tokens
3. Load balancing is disabled - each connector's requests are routed only to its corresponding provider

Server Side:

# Start server in autonomy mode
linksocks server -t provider_token -r -a

Provider Side:

# Provider sets its own connector token
linksocks provider -t provider_token -c my_connector_token -u ws://localhost:8765

Connector Side:

# Use the specific connector token to access this provider
linksocks connector -t my_connector_token -u ws://localhost:8765 -p 1180

Use Our Public Server

You can use our public LinkSocks server at linksocks.zetx.tech for intranet penetration:

Step 1: On machine A (inside the network you want to access)

linksocks provider -t any_token -u wss://linksocks.zetx.tech -c your_token

Step 2: On machine B (where you want to access the network)

linksocks connector -t your_token -u wss://linksocks.zetx.tech -p 1080

Test the connection:

curl --socks5 127.0.0.1:1080 http://httpbin.org/ip

Server Deployed on Cloudflare Workers

Deploy LinkSocks server on Cloudflare Workers for serverless operation:

The server will be started in autonomy mode. After deployment, connect using:

linksocks client -t your_token -u wss://your-worker.your-subdomain.workers.dev -p 9870

P2P Direct Mode (QUIC)

In any relay-based proxy mode (e.g., Reverse Proxy, Agent Proxy, Autonomy Mode), P2P Direct Mode is enabled by default with --direct-mode auto, and candidate discovery defaults to --direct-discovery stun. When the provider and the connector can establish direct UDP connectivity, the data is no longer relayed through the server but is transmitted directly over the encrypted QUIC protocol, greatly reducing latency and increasing throughput.

Note: With the default STUN discovery enabled and no server specified, the program concurrently probes a built-in pool of public STUN servers and picks the fastest responding node. You can also specify a custom STUN server with --stun-server, or override the defaults with --direct-mode and --direct-discovery when needed.

Performance Optimization Tip (Linux): When running high-throughput QUIC direct connections on Linux, you might see a warning like failed to sufficiently increase receive buffer size due to small default UDP buffers. Although the program will function, if you want the best performance (the ideal 7MB buffer), we recommend modifying the following sysctl kernel parameters before running:

sudo sysctl -w net.core.rmem_max=2500000
sudo sysctl -w net.core.wmem_max=2500000

API Server

LinkSocks server provides an HTTP API for dynamic token management, allowing you to add/remove tokens and monitor connections without restarting the server.

# Start server with API enabled
linksocks server --api-key your_api_key

For detailed API usage and examples, see: HTTP API

Common Options

Authentication

# Server with SOCKS authentication
linksocks server -t token -r -p 9870 -n username -w password

# Client with SOCKS authentication
linksocks client -t token -u ws://localhost:8765 -n username -w password

Debug Mode

# Enable debug logging
linksocks server -t token -d
linksocks client -t token -u ws://localhost:8765 -d

Custom Addresses

# Server listening on all interfaces
linksocks server -t token -H 0.0.0.0 -P 8765

# Client with custom SOCKS address
linksocks client -t token -u ws://localhost:8765 -h 0.0.0.0 -p 1080

Next Steps

• Learn about Command-line Options for advanced configuration
• Understand Authentication and security options
• Explore Python Library for integration
• Check HTTP API for dynamic management