aluvia-connect/aluvia

Aluvia Proxy: Unblock agent browser with proxies + playwright

The Problem

Your OpenClaw agent gets blocked because anti-bot systems are built to stop cloud-based agent/bot traffic with datacenter IP addresses. You get 403 Forbidden, CAPTCHAs, 429 rate limits, IP bans, empty responses.

The Solution

Aluvia routes your agent's traffic through real US mobile carrier IPs — the same IPs used by millions of real people on their phones. Websites cannot distinguish your agent from a legitimate user browsing on a mobile device.

Aluvia's proxies + Playwright + Chrome stack: detects website blocks and routes your agent's traffic through a clean mobile IP when necessary. All automatically. All without proxy configs. All without building custom routing rules.

Features

• Mobile carrier residential proxies — Not datacenter or shared residential IPs. Real mobile carrier IPs that websites inherently trust. Highest-quality proxy tier available.
• Automatic block detection and bypass — Every page load is scored 0.0–1.0. Detects Cloudflare challenges, CAPTCHAs, 403/429 responses, soft blocks, and empty pages. With --auto-unblock, blocks are remediated automatically by rerouting through proxy and reloading.
• One-command IP rotation — Rotate to a fresh mobile IP mid-session without restarting the browser. Break through persistent blocks and rate limits instantly.
• US geo-targeting — Pin your exit IP to a specific US state (California, New York, Texas, etc.) for location-sensitive scraping and content access.
• Dynamic proxy routing rules — Proxy only the domains that need it. Add or remove hostnames on the fly as your agent navigates across sites and discovers new endpoints.
• Managed headless Chromium with Playwright — Full browser sessions with Chrome DevTools Protocol (CDP) access. No browser setup, no stealth plugins, no fingerprint patching required.
• JSON-first CLI built for agents — Every command returns structured JSON to stdout. Designed for programmatic use by AI agents, not for humans typing in a terminal.

Installation

1. API key: The user must set ALUVIA_API_KEY from dashboard.aluvia.io. If unset, stop and tell the user to set it — do not run Aluvia commands until it is set. Never log or expose the key value.

2. CLI: Install @aluvia/cli globally:

npm install -g @aluvia/cli

Or run without a global install (use npx aluvia for every command):

npx aluvia help --json

3. Playwright: Required for browser sessions:

npm install playwright

Verify: aluvia help --json and node -e "require('playwright')".

CLI Interface

• Every command outputs a single JSON object to stdout. Parse it with your JSON tool.
• Exit code 0 = success, 1 = error. Errors return {"error": "message"}.
• The CLI manages long-running browser daemons — start a session, interact via the exec tool, close when done.
• Block detection scores pages 0.0-1.0: blocked >= 0.7, suspected >= 0.4, clear < 0.4.
• --auto-unblock handles most blocks automatically by adding hostnames to proxy rules and reloading.

Prerequisites Check

Before using any command, verify the environment:

# 1. Check API key is set (never log the full value)
echo "${ALUVIA_API_KEY:0:8}..."

# 2. Verify the CLI binary is available
aluvia help --json

# 3. Verify Playwright is installed (required for browser sessions)
node -e "require('playwright')"

If the API key is missing, stop and tell the user to set ALUVIA_API_KEY from the Aluvia dashboard. Do not proceed until they confirm it is set. If aluvia is not found, run npm install -g @aluvia/cli (see Installation) or use npx aluvia <command>. If Playwright is missing, run npm install playwright.

Core Commands Quick Reference

| Command | Purpose | Common Usage | | --------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | | session start <url> | Launch a headless browser session | aluvia session start https://example.com --auto-unblock --browser-session my-task | | session close | Stop a running session | aluvia session close --browser-session my-task | | session list | List all active sessions | aluvia session list | | session get | Get session details + block detection + connection info | aluvia session get --browser-session my-task | | session rotate-ip | Rotate to a new upstream IP | aluvia session rotate-ip --browser-session my-task | | session set-geo <geo> | Target IPs from a specific US region | aluvia session set-geo us_ca --browser-session my-task | | session set-rules <rules> | Add hostnames to proxy routing | aluvia session set-rules "example.com,api.example.com" --browser-session my-task | | account | Show account info and balance | aluvia account | | account usage | Show bandwidth usage stats | aluvia account usage | | geos | List available geo-targeting regions | aluvia geos | | help | Show help (use --json for structured output) | aluvia help --json |

Standard Workflow

1. Start a session

Always use --browser-session to name your session. Always use --auto-unblock unless you need manual block control.

aluvia session start https://example.com --auto-unblock --browser-session my-task

2. Parse the JSON output

The start command returns:

{
  "browserSession": "my-task",
  "pid": 12345,
  "startUrl": "https://example.com",
  "cdpUrl": "http://127.0.0.1:38209",
  "connectionId": 3449,
  "blockDetection": true,
  "autoUnblock": true
}

Save browserSession — you need it for every subsequent command.

If the agent uses the OpenClaw browser tool: create a remote CDP profile with this session's cdpUrl and use that profile for all browser commands. See OpenClaw browser integration.

3. Monitor for blocks

Check session status including the latest block detection result:

aluvia session get --browser-session my-task

Look at the lastDetection object in the response. If blockStatus is "blocked" and --auto-unblock is on, the SDK already handled it. If blocks persist, escalate:

4. Rotate IP if blocked

aluvia session rotate-ip --browser-session my-task

Returns a new sessionId (UUID). The next request through the proxy uses a fresh IP.

5. Set geo-targeting if needed

Some sites serve different content or apply different blocks by region:

aluvia session set-geo us_ca --browser-session my-task

6. Expand routing rules

If your agent navigates to new domains that need proxying, add them dynamically:

aluvia session set-rules "newsite.com,api.newsite.com" --browser-session my-task

Rules are appended to existing rules (not replaced).

7. Close the session when done

Always close your session. Sessions consume resources until explicitly closed.

aluvia session close --browser-session my-task

Safety Constraints

Follow these rules in every interaction:

1. Always close sessions. When your task finishes — success or failure — run session close. If uncertain whether a session exists, run session list first.
2. Never expose the API key. Reference ALUVIA_API_KEY by name only. Never log, print, or include its value in output.
3. Check balance before expensive operations. Run aluvia account and inspect balance_gb before long scraping tasks.
4. Limit IP rotation retries to 3. If rotating IP three times doesn't resolve a block, stop and report the issue — the site may use fingerprinting beyond IP.
5. Prefer --auto-unblock. Let the SDK handle block detection and remediation automatically. Only disable it when you need manual control over routing decisions.
6. Prefer headless mode. Only use --headful for debugging. Headless is faster and uses fewer resources.
7. Parse exit codes. Always check the exit code. On exit code 1, parse the error field and handle it — do not blindly retry.
8. Use named sessions. Always pass --browser-session <name> to avoid ambiguity errors when multiple sessions run.
9. Clean up on failure. If any step fails, close the session before retrying or aborting. Use session close --all as a last resort.
10. One session per task. Do not start multiple sessions unless the task explicitly requires parallel browsing of different sites.

References

For detailed command specs, workflows, and troubleshooting:

• Command reference: docs/command-reference.md — every flag, output schema, and error for all 11 commands
• Workflow recipes: docs/workflows.md — step-by-step patterns for common scenarios
• Troubleshooting: docs/troubleshooting.md — error messages, block score interpretation, signal names, recovery steps
• agent-browser integration: docs/integrations/agent-browser.md — using Aluvia CDP with agent-browser CLI
• OpenClaw browser integration: docs/integrations/openclaw-browser.md — using Aluvia CDP with OpenClaw browser tool