ur-wizard

URnetwork (proxy-vpn) Skill

URnetwork is a decentralized privacy network where users can either:

1. Consume - Use the network for secure, anonymous internet access via HTTPS/SOCKS/WireGuard proxies
2. Provide - Share egress bandwidth and earn rewards (USDC payouts)

Official Docs: https://docs.ur.io

Endpoints

---

Authentication

All API calls require a JWT token in the Authorization header:

# Get auth code from human (from https://ur.io web UI)
# Then exchange for JWT:
curl -X POST https://api.bringyour.com/auth/code-login \
  -d '{"auth_code": "<AUTH CODE>"}' | jq ".by_jwt"

Store the JWT and reuse. To refresh, get a new auth code and repeat.

---

Consumer Mode: Creating Proxies

Proxy Types

SOCKS5 Note: Use access_token as username, empty password. Supports SOCKS5H (remote DNS resolution).

WireGuard Note: Must set proxy_config.enable_wg: true in the auth-client request.

Method 1: MCP Skill (Recommended)

The MCP skill simplifies location search and proxy creation:

1. Ask user for desired location (country/region/city)
2. Search and create proxy via MCP
3. If no matches, broaden search (city → region → country)
4. If still no matches, show top 10 available countries

Method 2: API - By Country

# Step 1: Find locations
curl -X POST -H 'Authorization: Bearer <JWT>' \
  https://api.bringyour.com/network/find-locations \
  -d '{"query": "Germany"}' | jq '.locations'

# Step 2: Note country_code (e.g., "DE")

# Step 3: Create proxy
curl -X POST -H 'Authorization: Bearer <JWT>' \
  https://api.bringyour.com/network/auth-client \
  -d '{
    "proxy_config": {
      "initial_device_state": {
        "country_code": "DE"
      }
    }
  }'

Method 3: API - By Location ID

# Step 1: Find locations
curl -X POST -H 'Authorization: Bearer <JWT>' \
  https://api.bringyour.com/network/find-locations \
  -d '{"query": "Berlin"}' | jq '.locations'

# Step 2: Note location_id

# Step 3: Create proxy with specific location
curl -X POST -H 'Authorization: Bearer <JWT>' \
  https://api.bringyour.com/network/auth-client \
  -d '{
    "proxy_config": {
      "initial_device_state": {
        "location": {
          "connect_location_id": {
            "location_id": "<LOCATION_ID>"
          }
        }
      }
    }
  }'

Method 4: API - Enumerate Egress IPs

For rotating through multiple providers in a location:

# Step 1-2: Get location_id as above

# Step 3: Find providers (egress IPs) for location
curl -X POST -H 'Authorization: Bearer <JWT>' \
  https://api.bringyour.com/network/find-providers2 \
  -d '{
    "specs": [{"client_id": "<CLIENT_ID>"}],
    "count": 10
  }' | jq '.providers'

# Step 4: Create proxy for each client_id
curl -X POST -H 'Authorization: Bearer <JWT>' \
  https://api.bringyour.com/network/auth-client \
  -d '{
    "proxy_config": {
      "initial_device_state": {
        "location": {
          "connect_location_id": {
            "client_id": "<CLIENT_ID>"
          }
        }
      }
    }
  }'

Location Types

When searching, filter by location_type:

---

Provider Mode: Earning by Sharing Bandwidth

Advanced: Providers Through Shadowsocks Proxy

Advanced: Providers Through SOCKS5 Proxy (Transparent Routing)

Run URnetwork providers through an upstream SOCKS5 proxy for added anonymity or to match specific egress IPs.

Architecture:

┌─────────────────────────────────────────┐
│        URnetwork Provider Container     │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ Provider     │──│ Redsocks     │────┼───▶ Upstream SOCKS5
│  │ (egress)     │  │ (iptables)   │    │    (residential/datacenter)
│  └──────────────┘  └──────────────┘    │
└─────────────────────────────────────────┘

Dockerfile Setup:

FROM bringyour/community-provider:g4-latest

USER root
RUN apt-get update && apt-get install -y redsocks iptables supervisor curl

# Copy configs
COPY redsocks.conf /etc/redsocks/redsocks.conf
COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
COPY start-proxied.sh /usr/local/bin/start-proxied.sh
RUN chmod +x /usr/local/bin/start-proxied.sh

EXPOSE 80
ENTRYPOINT ["/usr/local/bin/start-proxied.sh"]

redsocks.conf:

base {
    log_debug = off;
    log_info = on;
    daemon = off;
    redirector = iptables;
}

redsocks {
    local_ip = 0.0.0.0;
    local_port = 12345;
    ip = <SOCKS5_PROXY_IP>;
    port = <SOCKS5_PROXY_PORT>;
    type = socks5;
    login = "<USERNAME>";
    password = "<PASSWORD>";
}

start-proxied.sh:

#!/bin/bash
set -e

# Configure iptables to redirect all TCP through redsocks
iptables -t nat -N REDSOCKS 2>/dev/null || true
iptables -t nat -F REDSOCKS 2>/dev/null || true

# Exclude local networks and proxy server
iptables -t nat -A REDSOCKS -d <SOCKS5_PROXY_IP> -j RETURN
iptables -t nat -A REDSOCKS -d 0.0.0.0/8 -j RETURN
iptables -t nat -A REDSOCKS -d 10.0.0.0/8 -j RETURN
iptables -t nat -A REDSOCKS -d 127.0.0.0/8 -j RETURN
iptables -t nat -A REDSOCKS -d 172.16.0.0/12 -j RETURN
iptables -t nat -A REDSOCKS -d 192.168.0.0/16 -j RETURN

# Redirect to redsocks
iptables -t nat -A REDSOCKS -p tcp -j REDIRECT --to-ports 12345
iptables -t nat -A OUTPUT -p tcp -j REDSOCKS

# Start supervisor (manages redsocks + provider)
exec /usr/bin/supervisord -c /etc/supervisor/conf.d/supervisord.conf

Run Container:

docker run --name urnetwork-proxied \
  --cap-add=NET_ADMIN \
  --mount type=bind,source=$HOME/.urnetwork,target=/root/.urnetwork \
  --restart always \
  -d urnetwork-proxied:latest

Requirements:

• --cap-add=NET_ADMIN (required for iptables)
• Same JWT file mounted at /root/.urnetwork/jwt
• Container uses supervisor to manage redsocks + provider

Verification:

# Check egress IP from inside container
docker exec urnetwork-proxied curl -s http://ipinfo.io/ip
# Should match your SOCKS5 proxy IP

Resilience:

• Provider auto-restarts on failure
• Redsocks auto-restarts via supervisor
• Container --restart always for boot persistence
• Retry wrapper handles proxy outages gracefully

---

Standard Provider Mode: Earning by Sharing Bandwidth

What is a Provider?

A provider shares egress capacity (internet connection) with the URnetwork. Users connect through providers to access the internet securely. Providers earn USDC payouts for participating.

Payout Structure:

• 10% of premium revenue + $0.10 minimum per MAU (Monthly Active User)
• Referral bonus: 50% of referred user's earnings + 50% of their referral bonus
• Payouts in USDC on Polygon or Solana
• Weekly payout sweeps

Installation Methods

Option 1: One-line Install (Linux)

curl -fSsL https://raw.githubusercontent.com/urnetwork/connect/refs/heads/main/scripts/Provider_Install_Linux.sh | sh

Uninstall:

curl -fSsL https://raw.githubusercontent.com/urnetwork/connect/refs/heads/main/scripts/Provider_Uninstall_Linux.sh | sh

Option 2: Windows (PowerShell)

powershell -c "irm https://raw.githubusercontent.com/urnetwork/connect/refs/heads/main/scripts/Provider_Install_Win32.ps1 | iex"

Uninstall:

powershell -c "irm https://raw.githubusercontent.com/urnetwork/connect/refs/heads/main/scripts/Provider_Uninstall_Win32.ps1 | iex"

Option 3: Build from Source

mkdir urnetwork && cd urnetwork
git clone https://github.com/urnetwork/connect
git clone https://github.com/urnetwork/protocol
cd connect/provider
go build  # Binary at ./provider

Option 4: Docker Container

Images: bringyour/community-provider:g1-latest through g4-latest (g4 = most stable)

# Initialize (first time)
docker run --mount type=bind,source=$HOME/.urnetwork,target=/root/.urnetwork \
  bringyour/community-provider:g4-latest auth

# Run provider
docker run --mount type=bind,source=$HOME/.urnetwork,target=/root/.urnetwork \
  --restart no -d bringyour/community-provider:g4-latest provide

Setting Up a Provider

1. Get auth code:

   • Visit https://ur.io
   • Create/login to network
   • Click "Copy an Auth Code"

2. Authenticate:

   ./provider auth
   # Paste auth code when prompted
   # Saved to ~/.urnetwork/jwt
   

3. Run provider:

   ./provider provide
   # "Provider XXX started"
   

4. Set up wallet in app for payouts (USDC on Polygon/Solana)

Running as Background Service

Linux (systemd):

systemctl --user start urnetwork    # Start
systemctl --user stop urnetwork     # Stop
systemctl --user enable urnetwork   # Auto-start on login
systemctl --user disable urnetwork  # Disable auto-start

macOS (launchd):

# Download launchd template from GitHub
# Edit paths and user
sudo cp urnetwork-provider.plist /Library/LaunchAgents/
sudo launchctl load /Library/LaunchAgents/urnetwork-provider.plist
sudo launchctl start /Library/LaunchAgents/urnetwork-provider.plist

# Check logs
tail -f /var/log/system.log | grep -i provider

Windows:

• Installer asks about startup programs
• Or run manually in background:

powershell -NoProfile -WindowStyle Hidden -Command \
  "Start-Process urnetwork.exe -ArgumentList 'provide' -WindowStyle Hidden"

Multi-Platform Builds

Build for multiple architectures:

cd connect/provider
make build

# Outputs to:
# build/darwin/amd64/provider
# build/darwin/arm64/provider
# build/linux/amd64/provider
# build/linux/arm64/provider
# build/linux/arm/provider
# build/linux/386/provider
# build/windows/amd64/provider
# build/windows/arm64/provider

Or download pre-built binaries from nightly releases.

---

Additional CLIs

---

Trust and Safety

• Providers follow trust and safety rules
• Network is free with data cap
• Supporters get higher data cap + priority speeds
• Supports email, SMS, Google, Apple auth
• Aggressive deletion of user info after payout (1 week retention)

---

Economic Model Summary

For Users:

• Free tier with data cap
• Premium: ~$5/month for higher cap + priority

For Providers:

• 10% of premium revenue + $0.10/MAU minimum
• Up to 20% of premium revenue paid to community
• 50% referral bonus on referred users
• Target margins: 70-80% at scale

Company Phases:

1. Phase 0: Build scalable network
2. Phase 1: Break-even at 4% premium conversion
3. Phase 2: Scale with fixed costs
4. Phase 3: Profitable expansion

---

Quick Reference

Get JWT:

curl -X POST https://api.bringyour.com/auth/code-login \
  -d '{"auth_code": "<CODE>"}' | jq ".by_jwt"

Find Locations:

curl -X POST -H 'Authorization: Bearer <JWT>' \
  https://api.bringyour.com/network/find-locations \
  -d '{"query": "Germany"}' | jq '.locations'

Create Proxy:

curl -X POST -H 'Authorization: Bearer <JWT>' \
  https://api.bringyour.com/network/auth-client \
  -d '{"proxy_config": {"initial_device_state": {"country_code": "DE"}}}'

Install Provider:

curl -fSsL https://raw.githubusercontent.com/urnetwork/connect/refs/heads/main/scripts/Provider_Install_Linux.sh | sh

---

Router/IoT Platforms

• Raspberry Pi: See docs
• Ubiquiti EdgeOS: See docs
• MikroTik RouterOS: See docs

All support provider binary deployment.

Advanced: Providers Through Shadowsocks Proxy

Run URnetwork providers through a Shadowsocks proxy for enhanced privacy or specific egress routing.

Shadowsocks vs SOCKS5:

• Shadowsocks uses encryption (AES-256-GCM, etc.) — harder to detect/block
• Better for bypassing firewalls (e.g., China, corporate networks)
• Slightly more overhead than plain SOCKS5

Architecture:

┌─────────────────────────────────────────┐
│        URnetwork Provider Container     │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ Provider     │──│ ss-local     │────┼───▶ Shadowsocks Server
│  │ (egress)     │  │ (SOCKS5:1080)│    │    (encrypted tunnel)
│  └──────────────┘  └──────────────┘    │
└─────────────────────────────────────────┘

Shadowsocks Config Format:

Shadowsocks/proxy/server/port/method/country/password

Example:
Shadowsocks/proxy/138.249.106.2/64619/aes-256-gcm/France/NedyYDqp

Dockerfile Setup:

FROM bringyour/community-provider:g4-latest

# Install shadowsocks-libev
RUN apt-get update && apt-get install -y \
    shadowsocks-libev \
    && rm -rf /var/lib/apt/lists/*

# Copy config
COPY shadowsocks.json /etc/shadowsocks-libev/config.json

# Copy startup script
COPY start-shadowsocks.sh /start-shadowsocks.sh
RUN chmod +x /start-shadowsocks.sh

EXPOSE 1080

ENTRYPOINT ["/start-shadowsocks.sh"]

shadowsocks.json:

{
    "server": "YOURIP",
    "server_port": YOURPORT,
    "local_port": YOURPORT,
    "local_address": "YOURIP",
    "password": "YOURpass",
    "timeout": 300,
    "method": "YOURMETHOD"
}

start-shadowsocks.sh:

#!/bin/bash
set -e

# Start shadowsocks client
ss-local -c /etc/shadowsocks-libev/config.json &
SS_PID=$!
echo "Shadowsocks client started (PID: $SS_PID)"

# Wait for shadowsocks to be ready
sleep 3

# Verify shadowsocks is listening
if ! netstat -tlnp 2>/dev/null | grep -q ':1080' && \
   ! ss -tlnp 2>/dev/null | grep -q ':1080'; then
    if ! pgrep -x "ss-local" > /dev/null; then
        echo "ERROR: Shadowsocks not running"
        exit 1
    fi
fi
echo "Shadowsocks proxy ready on 127.0.0.1:1080"

# Start URnetwork provider with proxy environment
export HTTP_PROXY="socks5://127.0.0.1:1080"
export HTTPS_PROXY="socks5://127.0.0.1:1080"
export ALL_PROXY="socks5://127.0.0.1:1080"

exec /usr/local/sbin/bringyour-provider provide

Build Image:

docker build -t urnetwork-shadowsocks:latest .

Run Shadowsocks Provider:

# Create JWT directory
mkdir -p ~/.urnetwork-ss-1
echo "<JWT>" > ~/.urnetwork-ss-1/jwt

# Run container
docker run -d \
  --name urnetwork-shadowsocks-1 \
  --restart always \
  -v ~/.urnetwork-ss-1:/root/.urnetwork \
  -e WARP_ENV=community \
  urnetwork-shadowsocks:latest

Scale to Multiple Providers:

JWT="<YOUR_JWT>"

for i in $(seq 1 10); do
  mkdir -p ~/.urnetwork-ss-$i
  echo "$JWT" > ~/.urnetwork-ss-$i/jwt
  
  docker run -d \
    --name urnetwork-shadowsocks-$i \
    --restart always \
    -v ~/.urnetwork-ss-$i:/root/.urnetwork \
    -e WARP_ENV=community \
    urnetwork-shadowsocks:latest
done

Verification:

# Check container status
docker ps --filter "name=urnetwork-shadowsocks"

# Check shadowsocks logs
docker logs urnetwork-shadowsocks-1 | grep "listening"
# Should show: "listening at 0.0.0.0:1080"

# Check provider logs
docker logs urnetwork-shadowsocks-1 | grep "Provider"
# Should show: "Provider XXX started"

Common Shadowsocks Methods:

Troubleshooting:

• 401 Unauthorized: URnetwork API issue (not Shadowsocks-related)
• Connection refused: Check Shadowsocks server IP/port
• Method not supported: Ensure method matches server config

---

Quick Reference: Proxied Provider

Build Image:

docker build -t urnetwork-proxied:latest .

Run Proxied Provider:

docker run --name urnetwork-proxied \
  --cap-add=NET_ADMIN \
  --mount type=bind,source=$HOME/.urnetwork,target=/root/.urnetwork \
  --restart always \
  -d urnetwork-proxied:latest

Verify Egress IP:

docker exec urnetwork-proxied curl -s http://ipinfo.io/ip

Files Needed:

• Dockerfile - extends provider image with redsocks/iptables
• redsocks.conf - SOCKS5 proxy configuration
• start-proxied.sh - iptables setup + supervisor launch
• supervisord.conf - manages redsocks + provider

Proxy Format:

socks5/45.91.198.75:7778/username/password

---

Quick Reference: Shadowsocks Provider

Build Image:

docker build -t urnetwork-shadowsocks:latest .

Run Shadowsocks Provider:

docker run -d \
  --name urnetwork-shadowsocks-1 \
  --restart always \
  -v ~/.urnetwork-ss-1:/root/.urnetwork \
  -e WARP_ENV=community \
  urnetwork-shadowsocks:latest

Shadowsocks Config Format:

Shadowsocks/proxy/server/port/method/country/password

Example:
Shadowsocks/proxy/138.249.106.2/64619/aes-256-gcm/France/NedyYDqp

Files Needed:

• Dockerfile - extends provider image with shadowsocks-libev
• shadowsocks.json - Shadowsocks client config
• start-shadowsocks.sh - starts ss-local + provider

---

Provider Monitoring

Quick Status Check

# All URnetwork containers
docker ps --format "table {{.Names}}\t{{.Status}}" | grep urnetwork

# Count by type
docker ps --format "{{.Names}}" | grep -c "urnetwork-provider"
docker ps --format "{{.Names}}" | grep -c "urnetwork-proxied"
docker ps --format "{{.Names}}" | grep -c "urnetwork-shadowsocks"

Verify Actually Providing vs Restarting

Check for authentication errors:

# Count "Unauthorized" errors in logs
docker logs urnetwork-provider-1 2>&1 | grep -c "Unauthorized"

# Check recent restarts
docker ps --format "table {{.Names}}\t{{.Status}}" | grep urnetwork-provider

# "Up X minutes" = healthy, "Restarting" = auth/connection issues

Check provider logs for success:

# Good: "Provider XXX started" without errors
docker logs urnetwork-proxied-1 2>&1 | grep "Provider.*started"

# Bad: Stack traces with "401 Unauthorized"
docker logs urnetwork-provider-1 2>&1 | tail -20

Provider Health Summary Script

#!/bin/bash
echo "=== URnetwork Provider Health ==="
for container in $(docker ps -a --format "{{.Names}}" | grep urnetwork | sort); do
  status=$(docker ps --filter "name=$container" --format "{{.Status}}")
  errors=$(docker logs $container 2>&1 | grep -c "Unauthorized" || echo "0")
  if echo "$status" | grep -q "Restarting"; then
    echo "❌ $container: $status (Errors: $errors)"
  else
    echo "✅ $container: $status"
  fi
done

---

Multi-VPS Deployment

Architecture Pattern

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   VPS 1 (Host)  │  │   VPS 2 (DE)    │  │   VPS 3 (US)    │
│  ┌───────────┐  │  │  ┌───────────┐  │  │  ┌───────────┐  │
│  │ Providers │  │  │  │ Providers │  │  │  │ Providers │  │
│  │ (10 reg)  │  │  │  │ (10 reg)  │  │  │  │ (10 reg)  │  │
│  └───────────┘  │  │  └───────────┘  │  │  └───────────┘  │
│  ┌───────────┐  │  │                 │  │                 │
│  │ Proxied   │  │  │                 │  │                 │
│  │ (10 sock) │  │  │                 │  │                 │
│  └───────────┘  │  │                 │  │                 │
└─────────────────┘  └─────────────────┘  └─────────────────┘
         │                    │                    │
         └────────────────────┴────────────────────┘
                              │
                    Single JWT on each VPS
                    /root/.urnetwork/jwt

Deployment Steps

1. Prepare JWT on Host VPS:

# Host VPS (source of truth)
mkdir -p /root/.urnetwork
echo "<VALID_JWT>" > /root/.urnetwork/jwt

2. Deploy to Remote VPS:

VPS_IP="YOURIP"
VPS_USER="YOURuser"
VPS_PASS="YOURpassword"

# Copy JWT to remote
sshpass -p "$VPS_PASS" scp /root/.urnetwork/jwt $VPS_USER@$VPS_IP:/home/$VPS_USER/.urnetwork/jwt

# SSH and create /root/.urnetwork (if needed)
sshpass -p "$VPS_PASS" ssh $VPS_USER@$VPS_IP 'sudo mkdir -p /root/.urnetwork && sudo cp /home/'$VPS_USER'/.urnetwork/jwt /root/.urnetwork/jwt'

# Launch providers on remote
sshpass -p "$VPS_PASS" ssh $VPS_USER@$VPS_IP '
  for i in $(seq 1 10); do
    docker run -d --name urnetwork-provider-vps-$i \
      -v /root/.urnetwork:/root/.urnetwork \
      --restart always \
      bringyour/community-provider:g4-latest provide
  done
'

3. Scale Pattern:

# Launch N providers on current host
launch_providers() {
  local count=$1
  local prefix=$2
  for i in $(seq 1 $count); do
    docker run -d --name ${prefix}-$i \
      -v /root/.urnetwork:/root/.urnetwork \
      --restart always \
      bringyour/community-provider:g4-latest provide
  done
}

# Usage
launch_providers 10 "urnetwork-provider"
launch_providers 10 "urnetwork-proxied"

---

Troubleshooting Guide

401 Unauthorized Errors

Symptoms:

• Container status shows "Restarting"
• Logs contain: "401 Unauthorized: Not authorized"
• Provider never stays up for more than a few seconds

Causes & Fixes:

Quick Fix:

# 1. Get new auth code from https://ur.io
# 2. Exchange for JWT
curl -X POST https://api.bringyour.com/auth/code-login \
  -d '{"auth_code": "YOUR_CODE"}' | jq -r ".by_jwt" > /root/.urnetwork/jwt

# 3. Restart all providers
docker restart $(docker ps -q --filter "name=urnetwork")

Restart Loops

Check restart count:

docker ps --format "table {{.Names}}\t{{.Status}}" | grep urnetwork

Common causes:

Debug restart loop:

# Watch real-time logs
docker logs -f urnetwork-provider-1

# Check exit code
docker inspect urnetwork-provider-1 --format='{{.State.ExitCode}}'

Proxy Connection Issues (Proxied Providers)

Symptoms:

• Shadowsocks logs show connection refused
• Redsocks can't connect to upstream
• Egress IP doesn't match expected proxy IP

Diagnose:

# Test SOCKS5 proxy manually
curl -x socks5://username:password@proxy_ip:port http://ipinfo.io/ip

# Check shadowsocks is listening
docker exec urnetwork-shadowsocks-1 ss -tlnp | grep 1080

# Verify iptables rules (for proxied containers)
docker exec urnetwork-proxied-1 iptables -t nat -L REDSOCKS

Fix proxy config:

# Update shadowsocks.json and rebuild
docker build -t urnetwork-shadowsocks:latest .
docker restart urnetwork-shadowsocks-{1..10}

Container Won't Start

Check:

# Port conflicts
docker logs urnetwork-provider-1 2>&1 | grep "bind"

# Mount issues
docker logs urnetwork-provider-1 2>&1 | grep "mount"

# Disk space
df -h

# Docker daemon
docker system info

Mass Operations

Restart all providers:

docker restart $(docker ps -q --filter "name=urnetwork")

Stop all providers:

docker stop $(docker ps -q --filter "name=urnetwork")

Remove all providers (destructive):

docker rm -f $(docker ps -aq --filter "name=urnetwork")

View all logs:

for c in $(docker ps --format "{{.Names}}" | grep urnetwork); do
  echo "=== $c ==="
  docker logs $c 2>&1 | tail -5
done

---

Full docs: https://docs.ur.io