Skip to content
Documentation

Proxy Setup

If you want to hide your IP address from metadata providers (TMDB/TVDB), you can configure Norri to route API requests through a proxy. This is useful if you’re privacy-conscious or already use a VPN.

Configuration

Navigate to Settings → Server → Privacy and enter your proxy URL in the Metadata Proxy field.

Supported Formats

socks5://hostname:port
socks5://username:password@hostname:port
http://hostname:port
http://username:password@hostname:port

VPN Provider Setup

Most VPN providers offer SOCKS5 proxies as part of their service. Here’s how to configure common providers:

NordVPN

  1. Generate a service credential at my.nordaccount.com
  2. Find a SOCKS5 server from the server list
  3. Enter: socks5://username:password@hostname:1080

Private Internet Access (PIA)

  1. Generate a username/password in the PIA client
  2. Use the SOCKS5 proxy server for your region (e.g., proxy-nl.privateinternetaccess.com)
  3. Enter: socks5://username:password@proxy-nl.privateinternetaccess.com:1080

Mullvad

  1. Find your account number (this is your username)
  2. Use any Mullvad server with SOCKS5 (port 1080)
  3. Enter: socks5://account-number:x@xx-xxx-wg-001.mullvad.net:1080

IPVanish

  1. Use your IPVanish login credentials
  2. Choose a SOCKS5 server from the server list
  3. Enter: socks5://username:password@hostname:1080

Windscribe

  1. Generate a SOCKS5 username/password in your account settings
  2. Choose a server from the list
  3. Enter: socks5://username:password@hostname:1080

Using Tor

For maximum anonymity, you can route requests through Tor. This is slower but prevents any correlation of requests.

macOS (Homebrew)

Terminal window
brew install tor
brew services start tor

Proxy URL: socks5://127.0.0.1:9050

Linux

Terminal window
sudo apt install tor
sudo systemctl start tor

Proxy URL: socks5://127.0.0.1:9050

Docker

Terminal window
docker run -d -p 9050:9050 dperson/torproxy

Proxy URL: socks5://127.0.0.1:9050

Self-Hosted Options

If you run your own VPN, you can set up a SOCKS5 proxy to route Norri traffic.

WireGuard + Dante

Install Dante SOCKS server on your VPN server:

Terminal window
sudo apt install dante-server

Configure /etc/danted.conf:

internal: 0.0.0.0 port = 1080
external: wg0
method: none
client pass {
    from: 0.0.0.0/0 to: 0.0.0.0/0
}
socks pass {
    from: 0.0.0.0/0 to: 0.0.0.0/0
}

Proxy URL: socks5://your-vpn-server:1080

Gluetun (Docker)

If you use Gluetun for container VPN routing:

services:
  gluetun:
    image: qmcgaw/gluetun
    cap_add:
      - NET_ADMIN
    environment:
      - VPN_SERVICE_PROVIDER=your_provider
      - VPN_TYPE=wireguard
      - SOCKS5=on
      - SOCKS5_LISTENING_ADDRESS=:1080
    ports:
      - "1080:1080"

Proxy URL: socks5://localhost:1080

Providers Without SOCKS5 Support

Some VPN providers don’t offer SOCKS5 proxies:

  • ExpressVPN — No SOCKS5
  • Surfshark — No SOCKS5
  • CyberGhost — No SOCKS5
  • ProtonVPN (Free tier) — No SOCKS5 (paid tiers have it)

For these providers, you’d need to set up your own proxy on a device connected to the VPN, or route all server traffic through the VPN at the network level.

Troubleshooting

Connection Refused

  • Verify the proxy server is running and accessible
  • Check firewall rules allow the connection
  • Confirm the port number is correct

Authentication Failed

  • Double-check username and password
  • Some providers require regenerating credentials
  • Ensure special characters are URL-encoded

Slow Scans

  • Tor is slow by design — expect 2-5x longer scan times
  • Try a proxy server geographically closer to you
  • Consider whether the privacy tradeoff is worth the speed hit

TMDB Rate Limiting

If you’re sharing a proxy with many users, TMDB may rate limit. Consider:

  • Using your own dedicated proxy
  • Spacing out large library scans
  • Accepting slower scan speeds

What This Does and Doesn’t Do

Does

  • Hides your IP address from TMDB/TVDB
  • Routes metadata requests through your VPN
  • Provides additional privacy for API calls

Doesn’t

  • Hide what titles you’re searching (TMDB still sees queries)
  • Anonymise you completely (your proxy provider sees requests)
  • Affect playback or local operations
  • Change anything about your library data

For most users, the default behaviour is private enough. Only configure a proxy if you specifically want to hide your IP from metadata providers.