Aluvia

Aluvia: Unblock Web Requests with Mobile Carrier Proxies

The Problem

Anti-bot systems block cloud-based and datacenter traffic. You get 403 Forbidden, CAPTCHAs, 429 rate limits, IP bans, or empty responses.

The Solution

Aluvia routes traffic through real mobile carrier IPs — the same IPs used by millions of people on their phones. Websites cannot distinguish your requests from legitimate mobile users.

The CLI manages headless Chromium sessions with automatic block detection and bypass. Every command returns structured JSON to stdout.

Why Aluvia

Aluvia provides browser session infrastructure for AI agents.

Some tools such as Browserbase, Steel, Hyperbrowser, and Browserless provide hosted cloud browsers. Aluvia instead runs locally and exposes a direct Chrome DevTools Protocol (CDP) endpoint for the active session.

Some platforms such as Apify or fully managed browser agents abstract the browser behind higher-level APIs. Aluvia does not abstract browser control. The agent connects directly to the CDP endpoint and retains full control using any compatible client such as Playwright, Puppeteer, OpenClaw, agent-browser, or other CDP tools.

Aluvia focuses on network-layer block mitigation using mobile carrier IP routing, automatic block detection, IP rotation, and dynamic proxy rules, while keeping the existing browser automation stack unchanged.

Installation

1. 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

2. Authentication: Run aluvia auth. The CLI prints a link and a short verification code:

aluvia auth
#   1. Open: https://dashboard.aluvia.io/cli-auth?cli_code=...
#   2. Confirm this code matches: ABCD-1234

The user opens that link in any browser (same machine or not — phone, laptop, anywhere), signs in if needed, confirms the code matches, and clicks Authorize. The CLI polls in the background and, once approved, stores the API key in ~/.aluvia/config.json. There is no browser auto-launch and no extra flags — this single flow works on desktops, headless servers, SSH, and containers alike.

Alternatively, set ALUVIA_API_KEY from dashboard.aluvia.io (useful for CI; the env var takes precedence over a stored key). Never log or expose the key value.

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 CDP or a compatible 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. Verify the CLI binary is available
aluvia help --json

# 2. Check authentication (never prints the key value)
aluvia auth status

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

If aluvia auth status reports {"authenticated": false}, run aluvia auth so the user can authorize via the browser (open the printed link in any browser, confirm the code, Authorize), or tell the user to set ALUVIA_API_KEY from the Aluvia dashboard. Do not proceed until authenticated. 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	Example
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 status	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 country	aluvia session set-geo gb --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 countries	aluvia geos
auth	Authorize via browser, store API key	aluvia auth
auth status	Check auth (never prints the key)	aluvia auth status
auth logout	Remove the stored API key	aluvia auth logout
help	Show help (--json for structured)	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

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.

2. CDP Connection

aluvia session start returns JSON containing a cdpUrl. This is the Chrome DevTools Protocol (CDP) endpoint for the active browser session.

cdpUrl is NOT a website URL. Do not navigate to it.

• Check available tools for a CDP-compatible client (Playwright, Puppeteer, OpenClaw browser, agent-browser, or other CDP attach clients).
• If available, attach using cdpUrl. Only use tools that support CDP attach; skip tools that launch a new browser.
• Reuse the existing browser context and page.
• If no CDP-compatible tool is available, connect programmatically using Playwright:

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0];

Platform integrations (step-by-step in linked docs):

• OpenClaw browser tool: Create a remote CDP profile with this session's cdpUrl. See OpenClaw browser integration.
• agent-browser: Pass cdpUrl via --cdp. See agent-browser integration.

3. Monitor for blocks

aluvia session get --browser-session my-task

Check the lastDetection object. Block scores: blocked >= 0.7, suspected >= 0.4, clear < 0.4. With --auto-unblock, blocks are remediated automatically.

4. Rotate IP if blocked

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

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

5. Set geo-targeting if needed

Use a country code from aluvia geos (ISO 3166-1 alpha-2, e.g. us, gb, de, jp):

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

6. Expand routing rules

If navigating to new domains that need proxying:

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

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. Use aluvia auth status to check authentication — it never reveals the key.
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.
6. Prefer headless mode. Only use --headful for debugging.
7. Parse exit codes. Exit code 0 = success, 1 = error with {"error": "message"}. Do not blindly retry on failure.
8. Use named sessions. Always pass --browser-session <name> to avoid ambiguity.
9. Clean up on failure. 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.

References

For detailed command specs, workflows, and troubleshooting:

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