A fast, lightweight TCP proxy server written in C with a Lua-powered routing engine. Ships with agent.lua, an optional module for building an autonomous overlay network across multiple LANs.

Status: Stable

• Features
• Usage
  • Protocol Modes
  • Proxy Chains
  • Lua Ruleset
  • Observability
• Distributed Virtual Network
• Installation
  • Runtime Dependencies
  • Building from Source
    • Dependencies
    • Building with CMake
• Credits

• Protocols: SOCKS4/SOCKS4A (Ying-Da Lee / NEC), SOCKS5 (RFC 1928, with RFC 1929 auth), HTTP CONNECT (RFC 9110 §9.3.6).
• Transparent proxy: Linux TPROXY.
• 10+ Gbps per x86 core on Linux with --pipe (measured in 2024).
• ~650 KiB executable on most platforms*. See Runtime Dependencies.
• Lua scripting on the control plane with extensive RPC support.
• RESTful API for live monitoring and hot-reloading Lua modules without restarts.
• Full IPv6 support; horizontal scalability.
• Standards-compliant: ISO C11 and POSIX.1-2008.
• No built-in encryption — pair with external tools for transport security. Supports basic authentication (plaintext credentials) only.

* Dynamically linked builds depend on libev and c-ares; see Runtime Dependencies. Statically linked executables may be larger due to bundled dependencies.

./neosocksd -l 0.0.0.0:1080  # SOCKS server
./neosocksd -4 -l 0.0.0.0:1080  # Prefer IPv4 in DNS resolution
./neosocksd -4 -l 0.0.0.0:1080 -i eth0  # Bind outbound to eth0
./neosocksd -l 0.0.0.0:1080 --http 0.0.0.0:8080  # SOCKS and HTTP server

# Transparent proxy (requires root)
sudo ./neosocksd --tproxy -l 0.0.0.0:50080 --api 127.0.1.1:9080 -r tproxy.lua \
    --max-startups 60:30:100 --max-sessions 0 -u nobody: -d

# Hardened load balancer (requires root)
sudo ./neosocksd --pipe -d -u nobody: --max-sessions 10000 --max-startups 60:30:100 \
    -t 15 -l :80 -f : -r lb.lua --api 127.0.1.1:9080

For all flags and options, run ./neosocksd --help.

Forward through an upstream chain and expose a different inbound protocol:

./neosocksd -l 0.0.0.0:12345 -f 192.168.2.2:12345 \
    -x "socks5://user:pass@192.168.1.1:1080,http://192.168.2.1:8080"

./neosocksd -l 127.0.0.1:1080 --http 0.0.0.0:8080 -x socks4a://203.0.113.1:1080

Binary releases include neosocksd.noarch.tar.gz with libruleset.lua, agent.lua, and the example/ scripts. Deploy neosocksd alongside libruleset.lua.

# Simple rule table
./neosocksd -d -l [::]:1080 --api 127.0.1.1:9080 -r ruleset_simple.lua

# Full ruleset with tracing
./neosocksd -l 0.0.0.0:1080 --api 127.0.1.1:9080 \
    -r ruleset.lua --traceback --loglevel 6

# Gzip-compressed Lua files
./neosocksd -l 0.0.0.0:1080 -r ruleset.lua.gz
./neosocksd -c config.lua.gz -r ruleset.lua.gz

-c and -r are unified: a single -c config.lua can configure the server and install the ruleset — the config script just sets _G.ruleset (or returns a ruleset field). -r remains as a shorthand for a ruleset-only file.

# One file does both: configure the server and set up the ruleset
./neosocksd -c config.lua

The ruleset routes each request, then actively forwards it with await.forward and learns whether the upstream connected — see await.forward for failover and retries.

Hot-reload without restart:

# Replace the active ruleset
curl "http://127.0.1.1:9080/ruleset/update?chunkname=%40ruleset.lua" \
    --data-binary @ruleset.lua

# Replace a module
curl "http://127.0.1.1:9080/ruleset/update?module=libruleset&chunkname=%40libruleset.lua" \
    --data-binary @libruleset.lua

# Execute arbitrary code
curl "http://127.0.1.1:9080/ruleset/invoke" -d "_G.some_switch = true"

# Push a gzip-compressed chunk
curl "http://127.0.1.1:9080/ruleset/invoke" \
    -H "Content-Encoding: gzip" --data-binary @biglist.lua.gz

Security note: The RESTful API (--api) has no built-in authentication — anyone who can reach it can execute arbitrary Lua code via /ruleset/invoke or hot-swap the running ruleset via /ruleset/update. Bind it to loopback or a trusted, firewalled network only; never expose --api to an untrusted network.

Provided scripts:

References: neosocksd API Reference · Lua 5.4 Manual

# Stateless snapshot
watch curl -s http://127.0.1.1:9080/stats

# Stateful: invokes the ruleset stats function if defined
watch curl -sX POST http://127.0.1.1:9080/stats

See neosocksd API Reference for the full API.

agent.lua builds an autonomous overlay across multiple LANs: peers discover each other via RPC, traffic is relayed across nodes, and remote resources are reachable through the local proxy endpoint.

Set up on each node:

1. Start neosocksd with the API enabled.
2. Load libruleset.lua and agent.lua.
3. The agent maintains peer state and relay paths automatically.
4. Access remote targets through the local SOCKS/HTTP endpoint.

The API must be reachable between nodes for peer discovery to work — see the security note above. Restrict it to a trusted network (e.g. a VPN or private LAN link between nodes), not the public internet.

Statically linked setup: Download a -static build from the Releases section — no additional runtime dependencies are needed.

Dynamically linked setup: Install the following runtime dependencies.

# Debian / Ubuntu
sudo apt install libev4 libc-ares2
# Alpine Linux
apk add libev c-ares
# OpenWrt
opkg install libev libcares

Note: Lua is always linked statically.

# Debian / Ubuntu
sudo apt install libev-dev liblua5.4-dev libc-ares-dev
# Alpine Linux
apk add libev-dev lua5.4-dev c-ares-dev

git clone https://github.com/hexian000/neosocksd.git
mkdir -p neosocksd-build && cd neosocksd-build
cmake -DCMAKE_BUILD_TYPE="Release" \
    ../neosocksd
cmake --build . --parallel

See m.sh for cross-compilation support.

Thanks to:

• libev
• Lua
• c-ares
• miniz