rird 2.1.231 → 2.3.0

package/docs/PRODUCTION_SETUP.md

@@ -0,0 +1,633 @@
+# RIRD CLI Production Setup Guide
+
+Production-grade installation and configuration for RIRD AI Agent.
+
+## System Requirements
+
+### Minimum Requirements
+
+- **CPU**: Dual-core processor (x86-64 or ARM64)
+- **RAM**: 2GB for basic operations, 4GB+ recommended
+- **Disk Space**: 500MB for RIRD installation + 1GB for cache/logs
+- **Network**: Stable internet connection for LLM and MCP communication
+
+### Supported Platforms
+
+| Platform | Architecture | Status |
+|----------|--------------|--------|
+| Linux    | x64, x64-baseline, ARM64, ARM64-musl, x64-musl | Supported |
+| macOS    | ARM64 (Apple Silicon), x64 (Intel) | Supported |
+| Windows  | x64, x64-baseline | Supported |
+| WSL      | All | Supported |
+
+### Required Software
+
+- **Node.js** (optional): v18+ for npm installation method only
+- **npm** (optional): v9+ for npm installation, or use curl installer
+- **Python**: 3.8+ (installed automatically during setup)
+- **Bash** (on Windows): Git Bash, WSL, or MSYS2
+
+## Installation Methods
+
+### Method 1: Universal Installer (Recommended)
+
+Works on macOS, Linux, and WSL without requiring npm or Node.js.
+
+```bash
+curl -fsSL https://rird.ai/install.sh | bash
+```
+
+**Features**:
+- Automatic platform detection
+- Single binary installation
+- No Node.js dependency
+- Installs Python dependencies automatically
+- Sets up MCP servers and configuration
+
+**Output Location**: `~/.rird/bin/rird`
+
+### Method 2: npm Global Installation
+
+For users with Node.js and npm already installed.
+
+```bash
+npm install -g rird-ai
+```
+
+**Benefits**:
+- Updates via `npm install -g rird-ai@latest`
+- Works with npm workspaces
+- Easy version pinning
+
+**Requires**: Node.js 18+, npm 9+
+
+### Method 3: Manual Installation
+
+For advanced users or CI/CD pipelines.
+
+```bash
+# 1. Download platform-specific binary
+cd ~/.rird/bin
+curl -L https://rird.ai/releases/rird-<platform>-<arch> -o rird
+chmod +x rird
+
+# 2. Run setup
+~/.rird/bin/rird --setup
+
+# 3. Activate license
+~/.rird/bin/rird activate YOUR_LICENSE_KEY
+```
+
+**Platforms**: Replace `<platform>-<arch>` with one of:
+- `linux-x64`, `linux-arm64`, `linux-x64-baseline`
+- `darwin-arm64`, `darwin-x64`
+- `windows-x64`
+
+## Configuration
+
+### Initial Setup
+
+After installation, RIRD creates the following directory structure:
+
+```
+~/.rird/
+├── bin/
+│   └── rird                 # Executable binary
+├── engine/
+│   ├── config.yaml          # LLM and MCP configuration
+│   ├── rird.json            # Provider settings
+│   └── stealth-browser-mcp/ # Browser automation MCP
+├── license.key              # Your license key
+└── license_cache.json       # Cached license validation
+```
+
+### Configuration File: ~/.rird/engine/config.yaml
+
+Main configuration file for LLM providers and execution modes.
+
+```yaml
+# LLM Configuration
+llm:
+  mode: remote                          # 'remote' or 'local'
+  remote_url: https://rird.ai/api/llm
+  main_model: 0000/ui-tars-1.5-7b:latest
+  fast_model: 0000/ui-tars-1.5-7b:latest
+  vision_model: 0000/ui-tars-1.5-7b:latest
+  temperature: 0.7
+  max_tokens: 4096
+
+# Browser Automation
+browser:
+  headless: true                        # Show browser window
+  timeout: 30000                        # Milliseconds
+  stealth_mode: true                    # Anti-detection
+  proxy: null                           # Optional proxy URL
+
+# MCP Configuration
+mcp:
+  servers:
+    - name: stealth-browser-mcp
+      command: python
+      args: ~/.rird/engine/stealth-browser-mcp/main.py
+  enabled: true
+
+# Execution
+execution:
+  max_retries: 3
+  retry_delay: 1000
+  circuit_breaker:
+    enabled: true
+    failure_threshold: 5
+    reset_timeout: 60000
+
+# Logging
+logging:
+  level: info                           # debug, info, warn, error
+  format: json                          # json or text
+  file: ~/.rird/logs/rird.log
+```
+
+### Configuration File: ~/.rird/engine/rird.json
+
+Provider API keys and model overrides.
+
+```json
+{
+  "provider": {
+    "openai": {
+      "enabled": true,
+      "options": {
+        "apiKey": "sk-..."
+      }
+    },
+    "anthropic": {
+      "enabled": true,
+      "options": {
+        "apiKey": "sk-ant-..."
+      }
+    },
+    "google": {
+      "enabled": false,
+      "options": {
+        "apiKey": ""
+      }
+    }
+  },
+  "models": {
+    "main": "gpt-4",
+    "fast": "gpt-3.5-turbo"
+  }
+}
+```
+
+### Environment Variables
+
+Override configuration with environment variables (highest priority):
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `RIRD_HOME` | Custom installation directory | `/opt/rird` |
+| `RIRD_CONFIG` | Custom config file path | `/etc/rird/config.yaml` |
+| `RIRD_ENGINE_DIR` | Custom engine directory | `/var/rird` |
+| `RIRD_LICENSE_KEY` | License key (overrides file) | `rird_...` |
+| `RIRD_API_KEY` | API key for license validation | `sk-...` |
+| `DEBUG` | Enable debug logging | `1` |
+| `RIRD_SKIP_AUTO_UPDATE` | Disable auto-updates | `1` |
+| `ANTHROPIC_API_KEY` | Anthropic API key | `sk-ant-...` |
+| `OPENAI_API_KEY` | OpenAI API key | `sk-...` |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | Google API key | `...` |
+
+## License Activation
+
+### Activate License
+
+After installation, activate your license:
+
+```bash
+rird activate YOUR_LICENSE_KEY
+```
+
+**Steps**:
+1. Visit https://rird.ai/dashboard
+2. Copy your license key
+3. Run `rird activate <key>`
+4. System validates key and stores locally
+5. Run `rird` to start using
+
+### License Status
+
+Check current license status anytime:
+
+```bash
+rird status
+```
+
+**Output Example**:
+```
+Status: Active
+Account: user@example.com
+Plan: Pro
+Cache expiry: 2026-01-15
+```
+
+### Device Fingerprinting
+
+License validation uses secure device fingerprinting:
+
+```
+SHA256(hostname + platform + arch + memory + cpu_count)
+```
+
+Device fingerprint is:
+- Computed locally only
+- Used for validation only
+- Never transmitted in plaintext
+- Cached for 24 hours locally
+
+## Troubleshooting
+
+### Installation Issues
+
+#### Binary Not Found
+
+```
+Error: Binary for your platform not found
+```
+
+**Solutions**:
+1. Check platform: `uname -m` (macOS/Linux) or `systeminfo` (Windows)
+2. Verify internet connection
+3. Manual install: Download from https://rird.ai/releases/
+4. Use npm fallback: `npm install -g rird-ai`
+
+#### Permission Denied
+
+```
+Error: Permission denied: ~/.rird/bin/rird
+```
+
+**Solution**:
+```bash
+chmod +x ~/.rird/bin/rird
+```
+
+#### Python Dependency Missing
+
+```
+Error: Python 3.8+ required but not found
+```
+
+**Solutions**:
+- macOS: `brew install python3`
+- Ubuntu/Debian: `sudo apt-get install python3`
+- Windows: Download from https://www.python.org/downloads/
+
+### License Issues
+
+#### License Key Invalid
+
+```
+Error: Invalid license key format
+```
+
+**Solutions**:
+1. Get key from https://rird.ai/dashboard
+2. Verify key format: `rird_` prefix required
+3. Check for trailing spaces: `echo -n "key" > ~/.rird/license.key`
+
+#### Could Not Reach License Server
+
+```
+Error: Could not reach license server
+```
+
+**Solutions**:
+1. Check internet connection: `ping rird.ai`
+2. Check firewall: Port 443 (HTTPS) required
+3. Verify DNS: `nslookup rird.ai`
+4. Use VPN if geographically restricted
+
+#### License Cache Corrupted
+
+```bash
+# Clear cache and re-validate
+rm ~/.rird/license_cache.json
+rird status
+```
+
+### Configuration Issues
+
+#### Config File Not Found
+
+```
+Error: Configuration file not found at ~/.rird/engine/config.yaml
+```
+
+**Solution**:
+```bash
+rird --setup  # Regenerate configuration
+```
+
+#### Invalid YAML Syntax
+
+```
+Error: Failed to parse configuration
+```
+
+**Solutions**:
+1. Validate YAML: `yamllint ~/.rird/engine/config.yaml`
+2. Use online validator: https://www.yamllint.com/
+3. Check indentation (YAML requires 2 spaces)
+4. Regenerate: `rird --setup`
+
+### Runtime Issues
+
+#### Out of Memory
+
+```
+Error: JavaScript heap out of memory
+```
+
+**Solutions**:
+1. Increase Node.js heap:
+   ```bash
+   NODE_OPTIONS=--max-old-space-size=4096 rird <task>
+   ```
+2. Close other applications
+3. Upgrade system RAM
+
+#### Timeout Errors
+
+```
+Error: Task timed out after 30 seconds
+```
+
+**Solutions**:
+1. Increase timeout in config:
+   ```yaml
+   browser:
+     timeout: 60000  # 60 seconds
+   ```
+2. Check network speed: `speedtest-cli`
+3. Reduce task complexity
+4. Enable retry mechanism:
+   ```yaml
+   execution:
+     max_retries: 5
+   ```
+
+## Performance Tuning
+
+### Optimize for Speed
+
+For interactive tasks requiring fast response:
+
+```yaml
+browser:
+  headless: true
+  timeout: 15000        # Faster timeout
+
+execution:
+  max_retries: 1       # Fewer retries
+  retry_delay: 500
+
+llm:
+  temperature: 0.3     # More deterministic
+  max_tokens: 2048     # Shorter responses
+```
+
+### Optimize for Accuracy
+
+For complex analysis tasks:
+
+```yaml
+browser:
+  headless: false       # Visual feedback
+  timeout: 60000        # More time
+
+execution:
+  max_retries: 5        # More retries
+  retry_delay: 2000
+
+llm:
+  temperature: 0.7      # More creative
+  max_tokens: 8192      # Longer reasoning
+```
+
+### Optimize for Reliability
+
+For production deployments:
+
+```yaml
+browser:
+  stealth_mode: true
+  proxy: "http://proxy.company.com:8080"
+
+execution:
+  circuit_breaker:
+    enabled: true
+    failure_threshold: 5
+    reset_timeout: 300000  # 5 minutes
+
+logging:
+  level: debug
+  file: /var/log/rird/rird.log
+```
+
+### Resource Monitoring
+
+Monitor resource usage:
+
+```bash
+# CPU and memory
+rird --stats
+
+# Detailed metrics
+rird --debug
+```
+
+## Scaling Considerations
+
+### Single Machine
+
+Suitable for: Personal use, small teams, 1-5 concurrent tasks
+
+Configuration:
+```yaml
+execution:
+  max_concurrent: 5
+  memory_limit: 2GB
+```
+
+### Multiple Machines (Distributed)
+
+For scaling to multiple users/tasks:
+
+1. **Shared Configuration Server**:
+   ```bash
+   rird serve --config-server
+   ```
+
+2. **Cloud Task Queue**:
+   ```bash
+   rird --cloud          # Execute on cloud servers
+   ```
+
+3. **Load Balancing**:
+   - Use API server mode: `rird --server`
+   - Route requests via load balancer
+   - Monitor health: `curl localhost:8765/health`
+
+### Cloud Deployment
+
+#### Docker Deployment
+
+```dockerfile
+FROM node:18-alpine
+RUN curl -fsSL https://rird.ai/install.sh | bash
+ENV RIRD_LICENSE_KEY=your_key_here
+ENV RIRD_HOME=/app/rird
+ENTRYPOINT ["rird"]
+```
+
+Build and run:
+```bash
+docker build -t rird-app .
+docker run -e RIRD_LICENSE_KEY=your_key -it rird-app <task>
+```
+
+#### Kubernetes Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: rird-agent
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: rird
+  template:
+    metadata:
+      labels:
+        app: rird
+    spec:
+      containers:
+      - name: rird
+        image: rird-app:latest
+        env:
+        - name: RIRD_LICENSE_KEY
+          valueFrom:
+            secretKeyRef:
+              name: rird-secrets
+              key: license-key
+        resources:
+          requests:
+            memory: "1Gi"
+            cpu: "500m"
+          limits:
+            memory: "4Gi"
+            cpu: "2000m"
+```
+
+## Maintenance
+
+### Regular Updates
+
+Auto-update is enabled by default. Manual update:
+
+```bash
+rird upgrade
+```
+
+Or with npm:
+```bash
+npm install -g rird-ai@latest
+```
+
+### Backup Configuration
+
+Backup important files:
+
+```bash
+# Backup license and configuration
+tar -czf ~/rird-backup.tar.gz ~/.rird/
+
+# Restore from backup
+tar -xzf ~/rird-backup.tar.gz -C ~/
+```
+
+### Clean Logs and Cache
+
+```bash
+# Remove old logs (older than 30 days)
+find ~/.rird/logs -mtime +30 -delete
+
+# Clear cache
+rm -rf ~/.rird/cache/*
+
+# Full cleanup (preserves license)
+rird --clean
+```
+
+### Verify Installation Health
+
+```bash
+# Run health check
+rird health-check
+
+# Expected output:
+# [OK] License valid
+# [OK] Python environment ready
+# [OK] MCP servers running
+# [OK] Network connectivity
+```
+
+## Support
+
+### Getting Help
+
+1. **Documentation**: https://rird.ai/docs
+2. **Status Page**: https://status.rird.ai
+3. **GitHub Issues**: https://github.com/rird-ai/rird
+4. **Community Forum**: https://community.rird.ai
+5. **Email Support**: support@rird.ai
+
+### Reporting Issues
+
+When reporting issues, include:
+
+```bash
+# System information
+rird --version
+rird status
+uname -a  # (macOS/Linux)
+
+# Configuration validation
+cat ~/.rird/engine/config.yaml
+
+# Recent logs
+tail -100 ~/.rird/logs/rird.log
+
+# Error output with debug enabled
+DEBUG=1 rird <command>
+```
+
+### Debug Mode
+
+Enable verbose debugging:
+
+```bash
+DEBUG=1 rird <task>
+```
+
+Logs are saved to: `~/.rird/logs/rird.log`
+
+## Next Steps
+
+1. Activate your license: `rird activate YOUR_KEY`
+2. Run first task: `rird "what is 2+2?"`
+3. Configure LLM: Edit `~/.rird/engine/config.yaml`
+4. Explore commands: `rird help`
+5. Check documentation: https://rird.ai/docs/cli-reference