ur-wizard

What this skill does

# 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

| Service | URL |
|---------|-----|
| API | https://api.bringyour.com |
| MCP Server | https://mcp.bringyour.com |
| API Spec | https://github.com/urnetwork/connect/blob/main/api/bringyour.yml |
| Web UI | https://ur.io |

---

## Authentication

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

```bash
# 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

| Use Case | Protocol | Config Source |
|----------|----------|---------------|
| **Web Scraping/Browsing** | HTTPS | `proxy_config_result.https_proxy_url` |
| **Low-level Sockets/UDP** | SOCKS5 | `proxy_config_result.socks_proxy_url` |
| **System-wide/OS Level** | WireGuard | `proxy_config_result.wg_config.config` |

**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

```bash
# 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

```bash
# 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:

```bash
# 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`:

| Type | Description |
|------|-------------|
| `country` | Countries |
| `region` | States, provinces, metro areas |
| `city` | Cities |

---

## 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:**

```dockerfile
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:**
```bash
#!/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:**
```bash
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:**
```bash
# 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)

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

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

#### Option 2: Windows (PowerShell)

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

Uninstall:
```powershell
powershell -c "irm https://raw.githubusercontent.com/urnetwork/connect/refs/heads/main/scripts/Provide