Skip to main content
Mole presenting SOCKS5

SOCKS5 Proxy

Route any TCP application through your mesh - curl, SSH, browsers, database clients, or any tool that supports SOCKS5. Point your application at the proxy and traffic flows through the mesh to its destination.

# These just work once your mesh is running
curl -x socks5://localhost:1080 https://internal.example.com
ssh -o ProxyCommand='nc -x localhost:1080 %h %p' user@remote-host
Configuration

See SOCKS5 Configuration for all options including authentication, bind address, and connection limits.

Usage Examples​

cURL​

# Basic usage
curl -x socks5://localhost:1080 https://example.com

# With authentication
curl -x socks5://user1:password@localhost:1080 https://example.com

# With hostname resolution at exit agent (socks5h)
curl -x socks5h://localhost:1080 https://internal.corp.local
socks5 vs socks5h

Use socks5h:// (note the h) when the destination hostname should be resolved by the exit agent rather than locally. This is essential for accessing internal DNS names that aren't resolvable from your machine.

SSH​

# Using netcat (nc)
ssh -o ProxyCommand='nc -x localhost:1080 %h %p' user@remote-host

# Using ncat (from nmap)
ssh -o ProxyCommand='ncat --proxy localhost:1080 --proxy-type socks5 %h %p' user@remote-host

# Add to ~/.ssh/config for permanent use
# Host internal-*
#     ProxyCommand nc -x localhost:1080 %h %p

Firefox​

  1. Preferences -> Network Settings -> Manual proxy configuration
  2. SOCKS Host: localhost, Port: 1080
  3. Select SOCKS v5
  4. Check "Proxy DNS when using SOCKS v5" for internal DNS resolution
  5. Enter username/password if authentication is enabled

Git​

# Clone via SOCKS5
git -c http.proxy=socks5://localhost:1080 clone https://github.com/repo/name

# Configure globally
git config --global http.proxy socks5://localhost:1080

# Remove global config
git config --global --unset http.proxy

Python​

import socks
import socket

# Configure default socket to use SOCKS5
socks.set_default_proxy(socks.SOCKS5, "localhost", 1080)
socket.socket = socks.socksocket

# Now all socket connections go through the proxy
import urllib.request
urllib.request.urlopen("https://example.com")

Requires PySocks: pip install pysocks

proxychains​

Configure /etc/proxychains.conf or ~/.proxychains/proxychains.conf:

[ProxyList]
socks5 127.0.0.1 1080

Run any application through the proxy:

proxychains4 curl https://example.com
proxychains4 nmap -sT -Pn 192.168.1.0/24
proxychains4 sqlmap -u "http://target/page?id=1"

wget​

# Via environment variable
ALL_PROXY=socks5://localhost:1080 wget https://example.com/file.tar.gz

# Or in ~/.wgetrc
# use_proxy = on
# http_proxy = socks5://localhost:1080
# https_proxy = socks5://localhost:1080

Verifying the Proxy​

Check Proxy is Running​

# Health check
curl http://localhost:8080/healthz | jq '{socks5: .socks5}'

# Test connection
nc -zv localhost 1080

Test Connectivity​

# Check your exit IP
curl -x socks5://localhost:1080 https://httpbin.org/ip

# Test internal connectivity
curl -x socks5h://localhost:1080 http://internal-server/health

View Active Connections​

# Via health endpoint
curl http://localhost:8080/healthz | jq '.streams'

Transparent Proxying​

For applications that don't support SOCKS5, use Mutiauk (Linux only) to create a TUN interface that transparently routes all traffic through the proxy. No per-app configuration needed.

UDP Support​

SOCKS5 UDP ASSOCIATE is supported for tunneling UDP traffic (DNS, NTP) through the mesh.

See UDP Relay for details and examples.

Troubleshooting​

Connection Refused​

curl: (7) Failed to connect to localhost port 1080: Connection refused

Causes:

  • SOCKS5 server not enabled in config
  • Agent not running
  • Wrong port number

Solutions:

# Check agent is running
curl http://localhost:8080/health

# Verify SOCKS5 is enabled
curl http://localhost:8080/healthz | jq '.socks5'

Authentication Failed​

curl: (7) User was rejected by the SOCKS5 server (1 1)

Causes:

  • Wrong username or password
  • Authentication required but not provided

Solutions:

  • Verify credentials: curl -x socks5://user:pass@localhost:1080 ...
  • Check if auth is enabled in config

No Route to Host​

curl: (7) Can't complete SOCKS5 connection to example.com:443

Causes:

  • No exit agent with matching route
  • Exit agent not connected to mesh
  • Destination unreachable from exit

Solutions:

# Check routes exist
curl http://localhost:8080/healthz | jq '.routes'

# Verify peer connections
curl http://localhost:8080/healthz | jq '.peers'

DNS Resolution Failed​

curl: (6) Could not resolve host: internal.corp.local

Cause: Using socks5:// instead of socks5h://

Solution: Use socks5h:// to resolve DNS at the exit agent:

curl -x socks5h://localhost:1080 https://internal.corp.local