lokinet-proxy

Lokinet Proxy

A lightweight Docker image for running Lokinet as a SOCKS5 proxy - a decentralized, privacy-preserving network built on the Oxen blockchain.

This project provides an optimized Docker container that runs Lokinet as a SOCKS5 proxy, enabling you to route all your traffic through the Lokinet decentralized network with minimal configuration. Perfect for privacy-conscious users who want to leverage Lokinet’s anonymous routing capabilities through a simple Docker deployment.

Features

Quick Start

  1. Clone this repository:
    git clone https://github.com/pasabanov/lokinet-proxy
    cd lokinet-proxy
    
  2. Update the image address in docker-compose.yml:
    image: ghcr.io/pasabanov/lokinet-proxy:latest
    
  3. Start the container:
    docker-compose up -d
    
  4. Verify Lokinet is running:
    docker-compose logs lokinet
    

Using Docker CLI

  1. Pull the image:
    docker pull ghcr.io/pasabanov/lokinet-proxy:latest
    
  2. Run a container from the image:
    docker run -d \
      --name lokinet-proxy \
      --cap-add NET_ADMIN \
      --cap-add NET_BIND_SERVICE \
      --device /dev/net/tun:/dev/net/tun \
      --sysctl net.ipv6.conf.all.disable_ipv6=0 \
      -p 127.0.0.1:1051:1051 \
      -e SOCKS_PORT=1051 \
      -e LOKINET_WORKER_THREADS=1 \
      -e LOKINET_HOPS=3 \
      -e LOKINET_PATHS=6 \
      -e LOKINET_UPSTREAM_DNS=9.9.9.9 \
      -e LOKINET_EXIT_NODE=exit.loki \
      -v lokinet-data:/var/lib/lokinet \
      --restart unless-stopped \
      ghcr.io/pasabanov/lokinet-proxy:latest
    

Configuration

Environment Variables

Docker Compose Configuration

The docker-compose.yml file includes several important settings:

Network Capabilities

cap_add:
  - NET_ADMIN          # Allow container to configure network and routing (required for lokitun0)
  - NET_BIND_SERVICE   # Allow binding to lower SOCKS5 ports

TUN Device

devices:
  - /dev/net/tun:/dev/net/tun  # Required for Lokinet's virtual network interface

IPv6 Support

sysctls:
  - net.ipv6.conf.all.disable_ipv6=0  # Lokinet requires IPv6 support

Environment Variables

environment:
  - SOCKS_PORT=1051
  - LOKINET_WORKER_THREADS=1
  - LOKINET_HOPS=3
  - LOKINET_PATHS=6
  - LOKINET_UPSTREAM_DNS=9.9.9.9
  - LOKINET_EXIT_NODE=exit.loki

DNS Configuration

dns:
  - 127.3.2.1   # For resolving .loki darknet domains
  - 9.9.9.9     # Backup DNS for fallback to public internet

Data Persistence

volumes:
  - ./data:/var/lib/lokinet  # Persists node keys and state to prevent identity reset after restart

Port Mapping

By default, the SOCKS5 port is exposed to localhost only. Choose one of these approaches:

Local Testing Only

The default configuration exposes the port only to localhost:

ports:
  - "127.0.0.1:1051:1051"

Integration with Other Containers

If using with Xray/Marzban on the same Docker network, comment out the ports section and access via lokinet:1051 directly:

# ports:
#   - "127.0.0.1:1051:1051"

Custom Network

To connect to an existing Docker network:

networks:
  default:
    name: proxy_net
    external: true

Tuning Lokinet Performance

For VPS with Limited Resources

environment:
  - LOKINET_WORKER_THREADS=1    # Limit CPU usage
  - LOKINET_HOPS=2              # Reduce latency
  - LOKINET_PATHS=4             # Reduce memory usage

For Maximum Anonymity

environment:
  - LOKINET_WORKER_THREADS=2    # More processing power
  - LOKINET_HOPS=4              # More routing hops
  - LOKINET_PATHS=8             # More backup paths

For Balanced Performance

environment:
  - LOKINET_WORKER_THREADS=1    # Default
  - LOKINET_HOPS=3              # Default (recommended)
  - LOKINET_PATHS=6             # Default

Usage Examples

Using with curl

# Test SOCKS5 proxy (if port is exposed)
curl --socks5-hostname 127.0.0.1:1051 https://example.com

Using with Firefox (or its forks)

  1. Open Browser Preferences → Network Settings
  2. Configure SOCKS5 proxy: 127.0.0.1:1051
  3. Enable “Proxy DNS when using SOCKS v5”

Additional settings for maximum privacy:

  1. Open about:config page
  2. Find network.proxy.allow_bypass
  3. Switch it to false

Integration with Xray/Marzban

If running Xray/Marzban in the same Docker network:

# In your Xray config
"outbounds": [
  {
    "protocol": "socks",
    "settings": {
      "servers": [
        {
          "address": "lokinet",
          "port": 1051
        }
      ]
    }
  }
]

Architecture

How It Works

  1. Lokinet Daemon: Runs the Lokinet client with configurable parameters, creating a virtual lokitun0 network interface
  2. Configuration Generation: Dynamically generates lokinet.ini from environment variables for worker threads, hops, and paths
  3. DNS Configuration: Sets up DNS resolution for .loki domains via Lokinet’s DNS server (127.3.2.1) with fallback to public DNS
  4. Dante SOCKS5 Server: Listens on the configured port and routes traffic through lokitun0
  5. Docker Entrypoint: Orchestrates startup, waits for the TUN interface, configures DNS, and starts Dante dynamically

Startup Sequence

The docker-entrypoint.sh script performs the following steps:

  1. Configures DNS resolvers (/etc/resolv.conf) with Lokinet’s DNS server and fallback
  2. Creates the /var/lib/lokinet directory for node data
  3. Generates lokinet.ini configuration file with environment variables:
    • worker-threads: CPU thread limit
    • hops: Routing hops for anonymity
    • paths: Backup path count
    • upstream: Fallback DNS server
  4. Starts the Lokinet daemon in the background
  5. Waits for the lokitun0 interface to become available
  6. Dynamically generates Dante SOCKS5 configuration using the SOCKS_PORT environment variable
  7. Starts the Dante SOCKS5 server

Image Details

Image Tag Examples

Troubleshooting

Container won’t start

# Check logs
docker-compose logs lokinet

# Verify TUN device is available
ls -la /dev/net/tun

SOCKS5 proxy not responding

# Check if Dante is running
docker-compose exec lokinet ps aux | grep danted

# Test connectivity
docker-compose exec lokinet curl --socks5-hostname 127.0.0.1:1051 https://example.com

DNS resolution issues

# Check DNS configuration inside container
docker-compose exec lokinet cat /etc/resolv.conf

# Test DNS resolution for .loki domains
docker-compose exec lokinet nslookup example.loki 127.3.2.1

High CPU usage

If the container is consuming too much CPU:

# Reduce worker threads
docker-compose down
# Edit docker-compose.yml and set LOKINET_WORKER_THREADS=1
docker-compose up -d

Slow connection

If experiencing slow speeds:

# Try reducing hops for lower latency
# Edit docker-compose.yml and set LOKINET_HOPS=2
# Or increase paths for better path switching
# Edit docker-compose.yml and set LOKINET_PATHS=8

IPv6 issues

Ensure the host system supports IPv6 and the sysctl setting is applied:

docker-compose exec lokinet sysctl net.ipv6.conf.all.disable_ipv6

Security Considerations

Building Locally

# Build the image
docker build -t lokinet-proxy:local .

# Run with Docker Compose
docker-compose up -d

License

See the LICENSE file.

References

Contributing

Contributions are welcome! Feel free to submit issues and pull requests.


Privacy First - Route your traffic through a decentralized network with Lokinet Proxy.