konduit-public/docs/socks-modes.md

SOCKS5 Modes

Konduit is a VPN for reaching your own resources over the public internet — it is not a censorship-circumvention tool, and it doesn't try to disguise its traffic. If you need to get through a network that's actively blocking or fingerprinting VPN traffic, that's a job for a dedicated, purpose-built tool — an SSH SOCKS proxy (ssh -D), Xray, sing-box, or similar — not something konduit reimplements.

What konduit does provide is standard SOCKS5 support on both sides of the connection, so you can chain it with whichever of those tools you already trust.

Egress-dial: reaching the server through a proxy (use_proxy)

If you already have a SOCKS5 proxy that gets you out of a restrictive network (for example ssh -D 1080 jumphost), point konduit at it instead of dialing the server directly:

[client]
server_endpoint = "vpn.example.com:443"
use_proxy       = "socks5://127.0.0.1:1080"

Or via the CLI:

./konduit connect --config client.toml --use-proxy socks5://127.0.0.1:1080

Konduit dials the SOCKS5 proxy, asks it to CONNECT to your server, and then runs its normal protocol over that connection — the proxy is otherwise transparent to it. If the proxy is unreachable, or requires authentication konduit doesn't support, the connection attempt fails immediately; there is no silent fallback to a direct connection.

Listener: exposing a SOCKS5 proxy after the tunnel is up (listen_socks)

Once connected, konduit can also expose a local SOCKS5 listener so other tools (browsers, curl, Xray outbounds) can route traffic through the tunnel without needing their own TUN-level integration:

[client]
listen_socks = "127.0.0.1:1080"

Or via the CLI:

./konduit connect --config client.toml --listen-socks 127.0.0.1:1080

Connections accepted by the listener are plain outbound TCP connections, routed through the tunnel by the kernel's routing table — the same routes any other tunnelled traffic uses. The SOCKS code itself has no VPN-specific logic.

Notes:

• SOCKS5 only, CONNECT command only — no BIND, no UDP ASSOCIATE.
• No authentication — bind it to localhost (the default) unless you understand the exposure of doing otherwise.
• If no address is given, konduit falls back to 127.0.0.1:1080. Override the fallback itself with the KONDUIT_SOCKS_LISTEN_ADDR environment variable.

Using both together

use_proxy and listen_socks are independent and can be combined — for example, dial out through an SSH SOCKS proxy to reach your server, and also expose a local SOCKS5 listener once connected for other apps to use.