HevSocks5Server is a small SOCKS5 server you can embed in an app

A proxy server that is also a library for your own app

HevSocks5Server is described as a simple, lightweight socks5 server, and the README is only a page or two long, which is unusual for a project that also ships a C API for embedding. The distinction is in the API section. There are two entry points, hev_socks5_server_main_from_file which takes a config file path and hev_socks5_server_main_from_str which takes the configuration as a string with a length, and both block until hev_socks5_server_quit is called or an error occurs. Both are documented as returning zero on success and minus one otherwise, and as available since version 2.6.7. The same library is also exposed to Java and Kotlin through JNI, with a Socks5Service class that loads a native library and offers start, stop and is-running calls. That is what makes this more than a daemon, and it is why the Android and iOS apps in the use cases section exist.

The protocol coverage is broader than the standard CONNECT case

The feature list is short and every line is a protocol decision. IPv4 and IPv6 are both supported, described as dual stack. The standard CONNECT command is supported, which is the ordinary TCP forwarding case. The standard UDP ASSOCIATE command is supported as well. There is also an extended FWD UDP command, described as UDP in TCP, and the footnote points to a protocol specification in the hev-socks5-core repository, noting that the hev-socks5-tunnel and hev-socks5-tproxy clients support UDP relay over TCP. The first footnote carries an important limitation: Windows is not supported at this time for that standard UDP command. The second footnote explains that the extended mode is how UDP gets carried inside a TCP connection, which is what makes the proxy usable over networks that block or mangle UDP. A client that only speaks CONNECT gets TCP, a client that speaks the extended FWD UDP gets both.

The configuration file is a YAML document with sockets, timeouts and routing marks

The sample config is the best documentation of the behaviour, and it is worth reading line by line. Under main, workers sets the number of worker threads at 4, port is the listen port at 1080, and listen-address is the bind address given as :: for dual stack, with a separate listen-ipv6-only switch. The UDP side has its own port, listen address and public addresses for each IP version, and a domain-address-type setting that chooses ipv4, ipv6 or unspec for how the server reports addresses to clients. There are bind-address, bind-address-v4 and bind-address-v6 entries for the source address, and a bind-interface option. A socket mark setting takes a hexadecimal, decimal or octal value, and tcp-fastopen is available. Under auth there is a file, username and password option for a single credential, and under misc sit the buffer sizes, the timeouts for connect, TCP read-write and UDP read-write, the log file and level, a pid file for daemon mode and a nofile limit.

Credentials live in a file that can carry a routing mark per user

The authentication file has a deliberately simple line format, with the username, a space, the password, a space, the mark and a line feed. The username and password are strings of up to 255 characters, and the mark is hexadecimal. That third field is the interesting one, because it is what makes per-user routing possible without a second proxy. The mark is set on the outbound socket, and the documentation shows how to use it with iptables, matching packets by their mark to apply a connection limit per user. The example limits the number of connections for the user jerry to 2, with the auth file entry reading jerry pass 1a and the iptables rule rejecting outbound TCP SYN packets above the limit when the mark matches 0x1a. The server itself enforces nothing, it tags the traffic, and the packet filter does the limiting.

Reloading credentials does not need a restart

The live updating mechanism is a signal, which is the kind of detail that separates a server you can run in production from one you cannot. After the authentication file is updated, you send SIGUSR1 to the socks5 server process and it reloads:

killall -SIGUSR1 hev-socks5-server

That matters because the alternative, restarting the proxy, drops every in-flight connection and every tunnel, and for a phone proxy on a mobile network that is a visible interruption. A reload signal means you can rotate a credential or add a user without dropping the sessions that are already running through the server. It is worth noting what the signal does not do, because the documentation is limited here: the mechanism is described as a live update of the authentication file, and there is no discussion of what happens to connections that were authenticated under a credential that has just been removed.

Building covers Unix, Android, Apple platforms and Windows, and a static build is one flag

The build instructions are per platform, and the Unix path is the shortest. The clone is recursive because the project has submodules, and the make target produces the binary in bin:

git clone --recursive https://github.com/heiher/hev-socks5-server
cd hev-socks5-server
make

A statically linked build is the same command with a variable set, which is what you want for a binary you copy onto a router:

make ENABLE_STATIC=1

For Android, the repository is cloned into a directory called jni and built with ndk-build, with the Application.mk file allowing the package and class names to be overridden, for example setting PKGNAME to hev/socks5 and CLSNAME to Socks5Service. For iOS and macOS, a script called build-apple.sh generates an xcframework. For Windows under MSYS2, the environment variable MSYS is set to winsymlinks:native before the clone and make, because the build links against msys-2.0 and ws2_32. The Makefile itself is a hand written one that produces a static library, a shared library and the executable, with a stack overflow detector enabled in the task library.

The Makefile shows a small C project with vendored dependencies

The build file gives an accurate picture of the engineering constraints. The compiler flags are -O3 with -pipe, -Wall and -Werror, so warnings are errors, and the include paths point at the miscellaneous sources, the core headers, the vendored YAML library and the task system library. The linker flags pull in -lyaml and -lhev-task-system, and the static target is libhev-socks5-server.a while the shared target is libhev-socks5-server.so, with the shared build adding -fPIC and -shared -pthread. There is a conditional flag for -fno-stack-clash-protection, applied only if the compiler accepts it, which is the kind of check that gets written when a toolchain version varies between distributions. The vendored YAML parser and the task system library both live in a third-part/ directory, with the repository listing third-part/ and a .gitmodules file, so the two are submodules rather than copies. The source itself is under src/, with conf/ holding the sample configuration and docker/ holding a container setup.

Where HevSocks5Server is the wrong choice

Three situations argue against it. The first is a deployment where you want a proxy as a standalone service with its own access control and logging. This is a small server library with a YAML file and a credentials file, and while it does have a pid file and a daemon mode, the access control story is the mark and the packet filter, which means you are expected to bring iptables along. A general purpose proxy daemon with per-user quotas, session accounting and a management API is a different product. The second is a client that only speaks the standard UDP ASSOCIATE command on Windows, because the documentation says that path is not supported on Windows at all. The third is a use case that needs encryption inside the protocol, since SOCKS5 itself has no confidentiality, and the answer is to run the traffic through a TLS or WireGuard layer rather than expecting the proxy to provide it. The honest alternative for most people is a mature general purpose SOCKS5 implementation, and the difference in approach is exactly this: HevSocks5Server is a compact embeddable component that assumes you already have a transport and a policy layer, and it is deliberately small enough to read.

Editorial conclusion

Adopt HevSocks5Server when you need a SOCKS5 server embedded in your own application, on Android, iOS, macOS, Linux, FreeBSD or Windows, and use a general purpose proxy daemon instead when you want a service that runs independently of any client application. Verify first which SOCKS5 UDP mode your clients speak, since the standard UDP ASSOCIATE command is not supported on Windows and the extended FWD UDP mode requires clients that implement it.

Frequently asked questions

Official sources

1. heiher/hev-socks5-server on GitHub
2. Issues
3. License: MIT
4. README
5. Releases