nstbrowser-ai-agent 0.0.1

package/skills/nstbrowser-ai-agent/references/proxy-configuration.md

@@ -0,0 +1,460 @@
+# Proxy Configuration Guide
+
+Detailed guide for configuring and managing proxies in Nstbrowser profiles.
+
+## Table of Contents
+
+- [Proxy Types](#proxy-types)
+- [Proxy Configuration](#proxy-configuration)
+- [Proxy Testing](#proxy-testing)
+- [Rotating Proxies](#rotating-proxies)
+- [Common Issues](#common-issues)
+
+## Proxy Types
+
+### HTTP Proxies
+
+HTTP proxies are the most common type, suitable for web browsing.
+
+**Characteristics:**
+- Protocol: HTTP/1.1
+- Port: Usually 8080, 3128, or 80
+- Authentication: Basic auth (username/password)
+- Encryption: No (traffic is not encrypted)
+- Use case: General web browsing, scraping
+
+**Example:**
+```bash
+nstbrowser-ai-agent profile proxy update my-profile \
+  --host proxy.example.com \
+  --port 8080 \
+  --type http \
+  --username user \
+  --password pass
+```
+
+### HTTPS Proxies
+
+HTTPS proxies provide encrypted connections.
+
+**Characteristics:**
+- Protocol: HTTP/1.1 over TLS
+- Port: Usually 443 or 8443
+- Authentication: Basic auth (username/password)
+- Encryption: Yes (traffic is encrypted)
+- Use case: Secure browsing, sensitive data
+
+**Example:**
+```bash
+nstbrowser-ai-agent profile proxy update my-profile \
+  --host secure-proxy.example.com \
+  --port 443 \
+  --type https \
+  --username user \
+  --password pass
+```
+
+### SOCKS5 Proxies
+
+SOCKS5 proxies support any protocol (HTTP, HTTPS, FTP, etc.).
+
+**Characteristics:**
+- Protocol: SOCKS5
+- Port: Usually 1080
+- Authentication: Username/password or no auth
+- Encryption: Optional (depends on implementation)
+- Use case: Advanced use cases, UDP support
+
+**Example:**
+```bash
+nstbrowser-ai-agent profile proxy update my-profile \
+  --host socks-proxy.example.com \
+  --port 1080 \
+  --type socks5 \
+  --username user \
+  --password pass
+```
+
+## Proxy Configuration
+
+### Setting Proxy for Single Profile
+
+Update proxy configuration for one profile:
+
+```bash
+nstbrowser-ai-agent profile proxy update <name-or-id> \
+  --host proxy.example.com \
+  --port 8080 \
+  --type http \
+  --username user \
+  --password pass
+```
+
+**Parameters:**
+- `--host`: Proxy server hostname or IP address (required)
+- `--port`: Proxy server port (required)
+- `--type`: Proxy type - http, https, or socks5 (required)
+- `--username`: Authentication username (optional)
+- `--password`: Authentication password (optional)
+
+### Batch Proxy Updates
+
+Update proxy for multiple profiles at once:
+
+```bash
+nstbrowser-ai-agent profile proxy batch-update id-1 id-2 id-3 \
+  --host proxy.example.com \
+  --port 8080 \
+  --type http \
+  --username user \
+  --password pass
+```
+
+**Benefits:**
+- Faster than updating profiles individually
+- Consistent configuration across profiles
+- Atomic operation (all or nothing)
+
+### Proxy Authentication
+
+#### With Username and Password
+
+```bash
+nstbrowser-ai-agent profile proxy update my-profile \
+  --host proxy.example.com \
+  --port 8080 \
+  --type http \
+  --username myuser \
+  --password mypass
+```
+
+#### Without Authentication
+
+```bash
+nstbrowser-ai-agent profile proxy update my-profile \
+  --host proxy.example.com \
+  --port 8080 \
+  --type http
+```
+
+#### Using Environment Variables
+
+Store credentials securely:
+
+```bash
+# Set environment variables
+export PROXY_USERNAME="myuser"
+export PROXY_PASSWORD="mypass"
+
+# Use in command
+nstbrowser-ai-agent profile proxy update my-profile \
+  --host proxy.example.com \
+  --port 8080 \
+  --type http \
+  --username "$PROXY_USERNAME" \
+  --password "$PROXY_PASSWORD"
+```
+
+### Resetting Proxy
+
+Remove proxy configuration from profiles:
+
+```bash
+# Reset single profile
+nstbrowser-ai-agent profile proxy reset profile-id
+
+# Reset multiple profiles (batch)
+nstbrowser-ai-agent profile proxy batch-reset id-1 id-2 id-3
+```
+
+## Proxy Testing
+
+### Viewing Proxy Configuration
+
+Check current proxy settings:
+
+```bash
+nstbrowser-ai-agent profile proxy show my-profile --json
+```
+
+**Response includes:**
+- Proxy configuration (type, host, port, credentials)
+- Proxy check result (IP, location, timezone)
+
+### Verifying Proxy Connection
+
+The `proxy show` command automatically tests the proxy:
+
+```json
+{
+  "success": true,
+  "data": {
+    "proxy": {
+      "type": "http",
+      "host": "proxy.example.com",
+      "port": 8080,
+      "username": "user",
+      "enabled": true
+    },
+    "proxyCheck": {
+      "ip": "203.0.113.1",
+      "location": "United States",
+      "timezone": "America/New_York"
+    }
+  }
+}
+```
+
+### Manual Proxy Testing
+
+Test proxy manually before assigning to profile:
+
+```bash
+# Test HTTP proxy
+curl -x http://user:pass@proxy.example.com:8080 https://api.ipify.org
+
+# Test HTTPS proxy
+curl -x https://user:pass@proxy.example.com:443 https://api.ipify.org
+
+# Test SOCKS5 proxy
+curl --socks5 user:pass@proxy.example.com:1080 https://api.ipify.org
+```
+
+### Checking IP and Location
+
+Verify the proxy is working correctly:
+
+```bash
+# Launch browser with profile
+nstbrowser-ai-agent --profile my-profile open https://api.ipify.org
+
+# Get the displayed IP
+nstbrowser-ai-agent get text body
+
+# Should show proxy IP, not your real IP
+```
+
+## Rotating Proxies
+
+### Strategy 1: Profile-Based Rotation
+
+Use different profiles with different proxies:
+
+```bash
+# Create profiles with different proxies
+nstbrowser-ai-agent profile create profile-1
+nstbrowser-ai-agent profile proxy update profile-1 --host proxy1.com --port 8080 --type http
+
+nstbrowser-ai-agent profile create profile-2
+nstbrowser-ai-agent profile proxy update profile-2 --host proxy2.com --port 8080 --type http
+
+nstbrowser-ai-agent profile create profile-3
+nstbrowser-ai-agent profile proxy update profile-3 --host proxy3.com --port 8080 --type http
+
+# Rotate by switching profiles
+nstbrowser-ai-agent --profile profile-1 open https://example.com
+nstbrowser-ai-agent close
+
+nstbrowser-ai-agent --profile profile-2 open https://example.com
+nstbrowser-ai-agent close
+
+nstbrowser-ai-agent --profile profile-3 open https://example.com
+nstbrowser-ai-agent close
+```
+
+### Strategy 2: Batch Update Rotation
+
+Update proxies for multiple profiles:
+
+```bash
+# Get profile IDs
+PROFILE_IDS=$(nstbrowser-ai-agent profile list --json | jq -r '.data.profiles | map(.profileId) | join(" ")')
+
+# Update all profiles to proxy 1
+nstbrowser-ai-agent profile proxy batch-update $PROFILE_IDS \
+  --host proxy1.com --port 8080 --type http
+
+# Later, update all profiles to proxy 2
+nstbrowser-ai-agent profile proxy batch-update $PROFILE_IDS \
+  --host proxy2.com --port 8080 --type http
+```
+
+### Strategy 3: Script-Based Rotation
+
+Automate proxy rotation with a script:
+
+```bash
+#!/bin/bash
+
+PROXIES=(
+  "proxy1.com:8080"
+  "proxy2.com:8080"
+  "proxy3.com:8080"
+)
+
+PROFILES=(
+  "profile-id-1"
+  "profile-id-2"
+  "profile-id-3"
+)
+
+# Assign proxies to profiles in round-robin
+for i in "${!PROFILES[@]}"; do
+  PROXY="${PROXIES[$i % ${#PROXIES[@]}]}"
+  HOST="${PROXY%:*}"
+  PORT="${PROXY#*:}"
+  
+  nstbrowser-ai-agent profile proxy update "${PROFILES[$i]}" \
+    --host "$HOST" \
+    --port "$PORT" \
+    --type http
+done
+```
+
+### Performance Considerations
+
+**Batch Operations:**
+- Use batch commands for multiple profiles
+- Reduces API calls and improves speed
+- Atomic operations ensure consistency
+
+**Proxy Pool Size:**
+- Larger pool = better distribution
+- Smaller pool = easier management
+- Balance based on your needs
+
+**Rotation Frequency:**
+- Rotate per request (most aggressive)
+- Rotate per session (balanced)
+- Rotate per day (conservative)
+
+## Common Issues
+
+### Connection Failures
+
+**Symptom:** Cannot connect to proxy server
+
+**Causes:**
+- Incorrect host or port
+- Proxy server is down
+- Firewall blocking connection
+- Network connectivity issues
+
+**Solutions:**
+```bash
+# Test proxy manually
+curl -x http://proxy.example.com:8080 https://api.ipify.org
+
+# Check proxy status
+ping proxy.example.com
+
+# Verify port is open
+nc -zv proxy.example.com 8080
+
+# Try different proxy
+nstbrowser-ai-agent profile proxy update my-profile \
+  --host backup-proxy.com --port 8080 --type http
+```
+
+### Authentication Errors
+
+**Symptom:** 407 Proxy Authentication Required
+
+**Causes:**
+- Incorrect username or password
+- Credentials not provided
+- Proxy requires different auth method
+
+**Solutions:**
+```bash
+# Verify credentials
+nstbrowser-ai-agent profile proxy show my-profile --json
+
+# Update with correct credentials
+nstbrowser-ai-agent profile proxy update my-profile \
+  --host proxy.example.com \
+  --port 8080 \
+  --type http \
+  --username correct-user \
+  --password correct-pass
+
+# Test manually
+curl -x http://user:pass@proxy.example.com:8080 https://api.ipify.org
+```
+
+### Timeout Issues
+
+**Symptom:** Proxy connection times out
+
+**Causes:**
+- Slow proxy server
+- Network latency
+- Proxy overloaded
+- Default timeout too short
+
+**Solutions:**
+```bash
+# Increase timeout
+export NSTBROWSER_AI_AGENT_DEFAULT_TIMEOUT=45000
+
+# Test proxy speed
+time curl -x http://proxy.example.com:8080 https://api.ipify.org
+
+# Try faster proxy
+nstbrowser-ai-agent profile proxy update my-profile \
+  --host faster-proxy.com --port 8080 --type http
+```
+
+### IP Leaks
+
+**Symptom:** Real IP is exposed instead of proxy IP
+
+**Causes:**
+- WebRTC leak
+- DNS leak
+- Proxy not properly configured
+- Browser fingerprint mismatch
+
+**Solutions:**
+```bash
+# Verify proxy is working
+nstbrowser-ai-agent --profile my-profile open https://api.ipify.org
+nstbrowser-ai-agent get text body
+
+# Check for leaks
+nstbrowser-ai-agent --profile my-profile open https://browserleaks.com/ip
+
+# Verify proxy configuration
+nstbrowser-ai-agent profile proxy show my-profile --json
+```
+
+### Proxy Blocked
+
+**Symptom:** Target website blocks proxy IP
+
+**Causes:**
+- Proxy IP is blacklisted
+- Too many requests from proxy
+- Proxy is known datacenter IP
+- Website has strict anti-bot measures
+
+**Solutions:**
+```bash
+# Rotate to different proxy
+nstbrowser-ai-agent profile proxy update my-profile \
+  --host different-proxy.com --port 8080 --type http
+
+# Use residential proxy instead of datacenter
+nstbrowser-ai-agent profile proxy update my-profile \
+  --host residential-proxy.com --port 8080 --type http
+
+# Reduce request rate
+# Add delays between requests in your automation script
+```
+
+## See Also
+
+- [NST API Reference](nst-api-reference.md)
+- [Profile Management Guide](profile-management.md)
+- [Batch Operations Guide](batch-operations.md)
+- [Troubleshooting Guide](troubleshooting.md)