Aluvia Claude Code

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

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, tell the user to set ALUVIA_API_KEY from the Aluvia dashboard. If aluvia is not found, run npm install @aluvia/cli. If Playwright is missing, run npm install playwright.

Core Commands Quick Reference

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 (a Playwright or Puppeteer client that supports attaching to an existing CDP endpoint).
• If available, attach the tool to the browser 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];

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

aluvia session set-geo us_ca --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.
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