Go SOCKS5 Proxy Add-on

Simple, lightweight SOCKS5 proxy server written in Go, based on serjs/socks5-server.

Features

• SOCKS5 Protocol: Standard SOCKS5 proxy support
• Authentication: Optional username/password authentication
• IP Allowlisting: Restrict access to specific client IPs
• Destination Filtering: Control which destinations can be accessed via regex patterns
• Lightweight: Minimal resource usage

Use Cases

1. Network Routing

Route traffic from Home Assistant or other services through a SOCKS5 proxy.

2. Access Control

Restrict proxy access to specific devices on your network.

3. Destination Filtering

Limit which external services can be accessed through the proxy.

Installation

1. Add the J0rsa repository to your Home Assistant
2. Search for “Go SOCKS5 Proxy” in the Add-on Store
3. Click Install and wait for the download to complete
4. Configure the add-on (see Configuration below)
5. Start the add-on

Configuration

# Example configuration
proxy_user: ""              # Username for authentication
proxy_password: ""          # Password for authentication
allowed_ips: []             # List of allowed client IPs
allowed_dest_fqdn: ""       # Regex pattern for allowed destinations

Configuration Options

Usage

Accessing the Proxy

After starting the add-on, configure your applications to use:

• Proxy Address: homeassistant.local:1080
• Protocol: SOCKS5

Example Configurations

Basic Setup (No Authentication)

proxy_user: ""
proxy_password: ""
allowed_ips: []
allowed_dest_fqdn: ""

Production Setup with Authentication

proxy_user: "myuser"
proxy_password: "mysecurepassword"
allowed_ips: []
allowed_dest_fqdn: ""

Restricted Setup with IP Allowlist

proxy_user: "myuser"
proxy_password: "mysecurepassword"
allowed_ips:
  - "192.168.1.100"
  - "192.168.1.101"
allowed_dest_fqdn: ""

Destination Filtering

Only allow connections to specific domains:

proxy_user: "myuser"
proxy_password: "mysecurepassword"
allowed_ips: []
allowed_dest_fqdn: ".*\\.example\\.com"

Testing the Proxy

Without authentication:

curl --socks5 homeassistant.local:1080 https://ipinfo.io

With authentication:

curl --socks5 myuser:mysecurepassword@homeassistant.local:1080 https://ipinfo.io

Integration with Home Assistant

Shell Command Example

Create a shell command to test connectivity through the proxy:

shell_command:
  test_socks_proxy: 'curl --socks5 homeassistant.local:1080 https://ipinfo.io'

Use with Other Add-ons

This proxy can be used with other add-ons that support SOCKS5, such as:

• SNI Socket Proxy - route traffic through this SOCKS5 proxy
• Aria2/Ariang - download through the proxy

Security Best Practices

1. Always use authentication in production environments
2. Use IP allowlist to restrict which clients can connect
3. Use destination filtering to limit accessible destinations
4. Limit network exposure - only expose ports if needed externally

Hardware Requirements

Minimum Requirements

• CPU: 1 core
• RAM: 64MB
• Storage: Minimal

Recommended

• CPU: 1 core
• RAM: 128MB

Troubleshooting

Add-on Won’t Start

• Check logs for error messages
• Ensure port 1080 is not in use by another service

Connection Refused

• Ensure the add-on is running
• Check if authentication is required
• Verify client IP is in the allowlist (if configured)

Authentication Failed

• Verify username and password are correct
• Ensure both proxy_user and proxy_password are set

Support

• GitHub Issues
• Upstream Repository