# Aluvia

Aluvia is a local CLI and proxy daemon for an existing cloud browser. Use it for a wrong-country page, or when the site is reacting to the cloud IP or country. It routes Chrome or Chromium through residential IPs.

Requires Node.js 18+, usable local Chrome or Chromium, and command access to the browser's host. Initial setup can restart Chrome. Ordinary login, browser-signature restrictions and rate limits need their own remedies.

First 10 MB free without an account, API key or payment; then $2/GB. Paid continuation needs the operator.

Before setup, inspect the [current source skill](https://github.com/aluvia-connect/aluvia/blob/main/skills/aluvia/SKILL.md) and [runtime evidence](https://aluvia.io/compatibility). Setup installs the skill bundled with its CLI version.

## Install

```
npx aluvia-cli setup
```

Node.js 18 or later. Run on the machine where the agent's Chrome or Chromium browser runs, with Node.js 18 or later and a usable local browser runtime. No target page URL is required. Setup installs the command launcher and agent skill, starts the local proxy, configures the browser, enables proxy traffic, and checks the upstream connection. Initial browser configuration can restart Chrome. Check the JSON result: `ready: true` means the browser reached the local proxy and the upstream connection check passed, not that a target website allows access or an agent task succeeded. If setup cannot finish, follow `next` to recover. Then choose a country with `aluvia geos` and `aluvia proxy-on --geo US`, or use `aluvia proxy-provider PROXY_URL` for your own proxy. Reload the target page, check its content, then run `aluvia status`. Complete instructions and optional flags: [Quickstart](https://aluvia.io/docs). If `aluvia` is not on PATH, replace `aluvia` with `npx aluvia-cli`, for example `npx aluvia-cli status`.

## Common cases

- Muse Secure VM showing the wrong country's catalog: [Muse Secure VM](https://aluvia.io/geo/muse)
- Grok Bot UK site blocked from US datacenter IP: [Grok Bot](https://aluvia.io/geo/grok-bot)
- Cloud Chrome shows not available in your region or we do not ship to your location: [not available in your country](https://aluvia.io/unblock/geo-restricted). The same mismatch as a wrong catalog from a cloud machine: [change the cloud browser country without a VPN](https://aluvia.io/geo/without-a-vpn).
- Cloud agent Chrome looping on Please verify you are a human or Captcha required (version 2): [CAPTCHA](https://aluvia.io/unblock/captcha). The same widget can say verify you are human. A residential or mobile country exit sometimes stops that loop when the site is scoring a datacenter ASN. Grok Bot Cloudflare Sorry you have been blocked or Error 1015: [Cloudflare](https://aluvia.io/unblock/cloudflare). Failed to verify your browser Code 11 on Vercel Security Checkpoint: [Vercel Security Checkpoint](https://aluvia.io/unblock/vercel-security-checkpoint). Sometimes, not a promise.
- Playwright synthetic user sent to the wrong regional site from a single datacenter region: [Playwright](https://aluvia.io/geo/playwright). A cloud agent not available in your country Playwright result is Playwright Chrome presenting that datacenter region's IP.
- Operator field notes for geo, Cloudflare, CAPTCHA, and Imperva triage: [https://aluvia.io/resources](https://aluvia.io/resources)

## Commands

Every command prints JSON on stdout with a `next` field. Read `next` and run it. Never print API keys.

| Command | What it does |
| --- | --- |
| `aluvia setup` | Set up Aluvia and connect your agent's browser. |
| `aluvia proxy-on` | Turn Aluvia on for all browser tabs, then reload the page. |
| `aluvia proxy-on --geo US` | Browse with a US IP address. Your agent can choose another available country. |
| `aluvia proxy-off` | Return to the browser's original connection without closing it. |
| `aluvia rotate-ip` | Switch to a different IP address. |
| `aluvia status` | Show what is running. Every field is explained in the output. |
| `aluvia geos` | List the available countries. |
| `aluvia auth KEY` | Save an API key the operator pasted. |
| `aluvia auth login` | Wait while the operator claims the account and buys data. |
| `aluvia proxy-provider PROXY_URL` | Use a proxy URL the operator already has. |
| `aluvia proxy-provider aluvia` | Go back to the Aluvia network. |
| `aluvia stop` | Stop the local proxy. Prefer `proxy-off`. |

> Cloud-based agents like Grok Bot and Meta Muse use datacenter IPs. Aluvia lets agents change their IP address. Use residential IPs from around the world to avoid bot blocks and geo blocks.

Aluvia is a local CLI and proxy daemon. An AI agent running in a cloud VM installs it, changes the agent's IP location, and sends the browser through a residential IP there so the site returns that country's page.

The first setup starts a free trial from an install id on the machine. No account or API key is required. Setup can still need a recovery action. When the trial data runs out, the CLI returns a claim link for the operator to open.

## Use cases

Browse from the country you need. See local prices, products, and pages.

Your agent's cloud computer may be in a different country from you. Websites can use that location to decide which prices and products to show, or whether to let the agent in.

Tell your agent which country you need. Aluvia gives its browser an IP address there, so it can try the local version of the site.

Help your agent get past website blocks. Give it another way to reach the page.

A website may open for you but block your agent because it recognizes the agent's cloud connection. Aluvia lets the agent try again with a residential IP address.

When the IP address is the reason for the block, this can help your agent continue its work. It cannot remove every block or replace a required login.

Global residential IPs, not US-only. Country only, not city. Built for cloud agents such as Grok Bot, Codex, Claude, OpenClaw, Hermes, and Muse, and browser automation with Playwright.

Sticky sessions last up to 30 minutes.

Complete quickstart and result checks: https://aluvia.io/docs (markdown: /docs.md)

## Trial and payment

The first 10 MB of proxy data is free, started from an install id on the machine. Paid data is 2 USD per GB. When the trial is used up, a command that needs the network returns:

```json
{
  "code": "payment_required",
  "claim_url": "<use the URL returned by the CLI>",
  "next": "Show claim_url to the human. Then run `aluvia auth login` to wait."
}
```

Show `claim_url` to the operator. They open it on their own machine, enter an email address, type the six-digit code from the email, authorize, and buy data. Then run `aluvia auth login` to wait, and retry. Full handover: https://aluvia.io/e/payment_required

## Pages

- https://aluvia.io/compatibility — Browser-host compatibility and test evidence (markdown: /compatibility.md)
- https://aluvia.io/legacy — Moving from older Aluvia SDK and MCP instructions (markdown: /legacy.md)
- https://aluvia.io/geo — Change a cloud agent's IP location (markdown: /geo.md)
- https://aluvia.io/geo/without-a-vpn — change cloud agent browser country without a VPN (markdown: /geo/without-a-vpn.md)
- https://aluvia.io/geo/grok-bot — Grok Bot UK site blocked from US datacenter IP (markdown: /geo/grok-bot.md)
- https://aluvia.io/geo/codex — Change the IP country of a Codex-controlled browser (markdown: /geo/codex.md)
- https://aluvia.io/geo/cursor — Change a Cursor cloud browser's IP country (markdown: /geo/cursor.md)
- https://aluvia.io/geo/playwright — Playwright synthetic user sent to the wrong regional site from a single datacenter region (markdown: /geo/playwright.md)
- https://aluvia.io/geo/claude — Claude computer use wrong country shipping (markdown: /geo/claude.md)
- https://aluvia.io/geo/openclaw — OpenClaw agent geo-restricted content datacenter IP (markdown: /geo/openclaw.md)
- https://aluvia.io/geo/hermes — Change the country of a Hermes cloud browser (markdown: /geo/hermes.md)
- https://aluvia.io/geo/muse — Meta Muse Secure VM geo-restricted content datacenter IP (markdown: /geo/muse.md)
- https://aluvia.io/setup — What npx aluvia-cli setup does (markdown: /setup.md)
- https://aluvia.io/docs — Aluvia quickstart (markdown: /docs.md)
- https://aluvia.io/pricing — Pricing (markdown: /pricing.md)
- https://aluvia.io/landing/global-proxy — Proxy IPs for AI agents. (markdown: /landing/global-proxy.md)
- https://aluvia.io/landing/cloud-server — Your AI agent looks like a cloud server. (markdown: /landing/cloud-server.md)
- https://aluvia.io/resources — Field notes when a datacenter IP hits the wrong country, Cloudflare, CAPTCHA, or Imperva. (markdown: /resources.md)
- https://aluvia.io/resources/tailscale-vs-aluvia — Tailscale home exit vs Aluvia vs take over the computer (markdown: /resources/tailscale-vs-aluvia.md)
- https://aluvia.io/resources/triage-geo-cloudflare-imperva — Is it geo, Cloudflare, Imperva, or a login wall? (markdown: /resources/triage-geo-cloudflare-imperva.md)
- https://aluvia.io/resources/us-vm-uk-nz-field-kit — US VM to UK catalog and NZ trade sites (markdown: /resources/us-vm-uk-nz-field-kit.md)
- https://aluvia.io/resources/unattended-browser-course — Unattended browser on a datacenter IP (markdown: /resources/unattended-browser-course.md)
- https://aluvia.io/resources/cloud-vm-blocks-skill — Skill pack for cloud VM blocks (markdown: /resources/cloud-vm-blocks-skill.md)
- https://aluvia.io/unblock — Identify a blocked-page message, check whether a different IP can help, and choose the next step. (markdown: /unblock.md)
- https://aluvia.io/unblock/geo-restricted — this content is not available in your country AI agent browser VM (markdown: /unblock/geo-restricted.md)
- https://aluvia.io/unblock/cloudflare — Grok Bot Cloudflare Sorry you have been blocked Error 1015 (markdown: /unblock/cloudflare.md)
- https://aluvia.io/unblock/access-denied — Access Denied and Cloudflare Error 1010 (markdown: /unblock/access-denied.md)
- https://aluvia.io/unblock/captcha — cloud agent CAPTCHA loop Please verify you are a human (markdown: /unblock/captcha.md)
- https://aluvia.io/unblock/unusual-traffic — Google unusual traffic from your computer network on a cloud VM (markdown: /unblock/unusual-traffic.md)
- https://aluvia.io/unblock/403 — 403 Forbidden opening a site from a cloud VM (markdown: /unblock/403.md)
- https://aluvia.io/unblock/rate-limit — 429 Too Many Requests and Cloudflare Error 1015 (markdown: /unblock/rate-limit.md)
- https://aluvia.io/unblock/imperva-security-service — Grok Bot Imperva This request was blocked by our security service (markdown: /unblock/imperva-security-service.md)
- https://aluvia.io/unblock/vercel-security-checkpoint — Failed to verify your browser Code 11 Vercel Security Checkpoint cloud agent (markdown: /unblock/vercel-security-checkpoint.md)
- https://aluvia.io/e/payment_required — The free trial is used up (markdown: /e/payment_required.md)

## Links

- Current source skill: https://github.com/aluvia-connect/aluvia/blob/main/skills/aluvia/SKILL.md (setup installs the skill bundled with its CLI version)

- Runtime evidence: https://aluvia.io/compatibility

- Older SDK/MCP instructions: https://aluvia.io/legacy

- Residential proxy IPs: https://aluvia.io/landing/global-proxy

- Cloud connection blocks: https://aluvia.io/landing/cloud-server

- Docs: https://aluvia.io/docs
- llms.txt: https://aluvia.io/llms.txt
- Host compatibility: https://aluvia.io/compatibility
- Older SDK/MCP setup: https://aluvia.io/legacy
- Residential proxy IPs: https://aluvia.io/landing/global-proxy
- Cloud connection blocks: https://aluvia.io/landing/cloud-server
- Source: https://github.com/aluvia-connect/aluvia
- Package: https://www.npmjs.com/package/aluvia-cli
- Dashboard: https://dashboard.aluvia.io
- Home: https://aluvia.io