aluvia-web-proxy_skill

Overview

This skill routes an AI agent's browser traffic through real US mobile carrier IPs to avoid anti-bot blocks and make the agent appear like a normal mobile user. It combines managed headless Chromium via Playwright with automatic block detection, one-command IP rotation, and JSON-first CLI controls designed for programmatic use. Use it to recover from 403s, CAPTCHAs, 429s, empty responses, and other WAF challenges.

How this skill works

The skill monitors each page load and scores block risk (0.0–1.0). When a page is flagged as suspected or blocked, it automatically reroutes traffic through a clean mobile carrier exit IP and reloads the page. It exposes a JSON CLI to start and manage named browser sessions, rotate IPs, set US geo-targeting, and add domain-specific routing rules without manual proxy configuration.

When to use it

• Agent receives 403 Forbidden, 429 rate limits, or empty responses during browser automation.
• Cloudflare, DataDome, PerimeterX, Akamai Bot Manager, or similar systems are blocking requests.
• You need to appear as a mobile user from a specific US state for location-sensitive content.
• Persistent site blocks that may be solved by rotating to a fresh mobile carrier IP mid-session.
• You want managed Playwright Chromium sessions with automatic proxying and JSON output for programmatic control.

Best practices

• Always start sessions with a named --browser-session and enable --auto-unblock for automatic remediation.
• Check account balance and bandwidth usage before large scraping jobs to avoid unexpected costs.
• Limit IP rotation retries to three attempts; escalate if blocks persist to avoid fingerprint-based defenses.
• Use headless mode for production runs; enable headful only for debugging and visual inspection.
• Always close sessions when finished and never expose the ALUVIA_API_KEY value in logs or outputs.

Example use cases

• Recover an AI scraping pipeline that suddenly returns Cloudflare challenges by enabling auto-unblock.
• Run a headless Playwright task that needs US-state-specific content by setting geo-targeting to us_ca or us_ny.
• Append new hostnames to proxy rules on the fly when an agent discovers third-party API endpoints.
• Rotate to a fresh mobile IP mid-session to bypass persistent rate limits without restarting the browser.
• Integrate with an agent that requires structured JSON CLI responses for automation and monitoring.