# Global proxy IPs for AI agents.

Aluvia lets an agent change its IP geolocation through a global network of residential and mobile IPs, or a proxy URL you already have. The site then serves that country's page. Setup is one command.

Use with agents such as [Grok Bot](/geo/grok-bot), [Codex](/geo/codex), [Cursor](/geo/cursor), [Claude computer use](/geo/claude), [OpenClaw](/geo/openclaw), [Hermes](/geo/hermes), or [Playwright](/geo/playwright).

## Install

```
npx aluvia-cli setup
```

Node.js 18 or later. No account, no API key, and the first 10 MB is free. Paid data is 2 USD per GB. Installs the `aluvia` binary and an agent skill. If `aluvia` is not on PATH, prefix every command with `npx aluvia-cli`.

## What it is

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 or mobile 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, no API key, and no human in the loop. When the trial data runs out, the CLI returns a claim link for the operator to open.

## When to use it

### Agents can change their IP location

Most sites infer country from the request IP. A cloud agent's IP is the datacenter's, so a UK catalog, a German price, or a not-available-in-your-region page is the machine, not the operator. Aluvia sends the existing browser through a residential or mobile IP in the country you set. The site infers location from that IP and returns that country's page. The pool is global residential and mobile IPs. Sticky sessions last up to 30 minutes. `aluvia proxy-on --geo US`. Run `aluvia geos` for the list. Omit `--geo` to use the global pool. Aluvia does not set GPS, timezone, or Accept-Language.

### Unblock browser workflows

A residential IP in the right country sometimes clears a 403, CAPTCHA, Cloudflare, Access Denied, unusual-traffic, or rate-limit page. Aluvia does not claim to beat fingerprint, Linux Chrome, TLS, or canvas. Do not use it for a normal login wall. If a login page appeared because the IP is a datacenter, changing to a residential or mobile IP is the job. A password, SSO, or 2FA problem is not.

## 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` | Sets up Aluvia on the agent's machine. Once per machine. |
| `aluvia proxy-on` | Send every tab through Aluvia, then reload the page. |
| `aluvia proxy-on --geo US` | Use an IP in a specific country. Omit `--geo` for the global pool. Run `aluvia geos` for the list. |
| `aluvia proxy-off` | Go back to the machine's own IP. The browser keeps running. |
| `aluvia rotate-ip` | Get a new exit IP when the current one is still blocked. |

Every command, including the ones a human rarely runs: https://aluvia.io/llms.txt

## 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": "https://dashboard.aluvia.io/cli-auth?cli_code=ABCD",
  "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

## By agent

- https://aluvia.io/geo/grok-bot — Grok Bot on a US VM presents a US address to UK and EU sites. A UK site blocked from a US datacenter IP, and Spanish or Portuguese sites that refuse that address, are reading the host. Send the browser through a GB residential or mobile IP when that is the country the page is choosing.
- https://aluvia.io/geo/codex — OpenAI Codex running as a cloud agent is seen as the VM's country. Send its traffic through a residential or mobile IP in the country you set so the site returns that country's page.
- https://aluvia.io/geo/cursor — Cursor has no control to set browser country IP geolocation for a cloud agent. Install Aluvia on the cloud machine so the Agents window uses a residential or mobile IP in the country you set, including when US-based IPs are blocked by geo-restrictions.
- https://aluvia.io/geo/playwright — A Playwright synthetic user from a single datacenter region is sent to the wrong regional site because Chrome is still the VM. Point the existing browser at a residential or mobile IP in the country the page needs.
- https://aluvia.io/geo/claude — Claude computer use opens pages from the computer it was given. On a cloud VM, set a residential or mobile exit IP in the ship-to or catalog country.
- https://aluvia.io/geo/openclaw — An OpenClaw agent opening geo-restricted content from a datacenter IP is presenting the VPS or cloud host. Aluvia sends the browser through a residential or mobile IP in the country the restricted page expects.
- https://aluvia.io/geo/hermes — A Hermes cloud agent that drives Chrome can see content not available in your region because the website is choosing a country from the VM. Use Aluvia only for that browser case, not for model-API region blocks.

## Without a VPN

- https://aluvia.io/geo/without-a-vpn — You can change a cloud agent browser country without a VPN by running Aluvia on the VM. The same path lets you change cloud Chrome geo without VPN software on a laptop: traffic uses a residential or mobile IP in the country you set.

## Pages

- https://aluvia.io/geo — An AI agent's browser can show Brazil prices when the operator needs a US catalog. That is the datacenter country versus a target country residential IP. Aluvia sends the browser through a residential or mobile IP in the country you set. Country only, not a human VPN. (markdown: /geo.md)
- https://aluvia.io/geo/without-a-vpn — You can change a cloud agent browser country without a VPN by running Aluvia on the VM. The same path lets you change cloud Chrome geo without VPN software on a laptop: traffic uses a residential or mobile IP in the country you set. (markdown: /geo/without-a-vpn.md)
- https://aluvia.io/geo/grok-bot — Grok Bot on a US VM presents a US address to UK and EU sites. A UK site blocked from a US datacenter IP, and Spanish or Portuguese sites that refuse that address, are reading the host. Send the browser through a GB residential or mobile IP when that is the country the page is choosing. (markdown: /geo/grok-bot.md)
- https://aluvia.io/geo/codex — OpenAI Codex running as a cloud agent is seen as the VM's country. Send its traffic through a residential or mobile IP in the country you set so the site returns that country's page. (markdown: /geo/codex.md)
- https://aluvia.io/geo/cursor — Cursor has no control to set browser country IP geolocation for a cloud agent. Install Aluvia on the cloud machine so the Agents window uses a residential or mobile IP in the country you set, including when US-based IPs are blocked by geo-restrictions. (markdown: /geo/cursor.md)
- https://aluvia.io/geo/playwright — A Playwright synthetic user from a single datacenter region is sent to the wrong regional site because Chrome is still the VM. Point the existing browser at a residential or mobile IP in the country the page needs. (markdown: /geo/playwright.md)
- https://aluvia.io/geo/claude — Claude computer use opens pages from the computer it was given. On a cloud VM, set a residential or mobile exit IP in the ship-to or catalog country. (markdown: /geo/claude.md)
- https://aluvia.io/geo/openclaw — An OpenClaw agent opening geo-restricted content from a datacenter IP is presenting the VPS or cloud host. Aluvia sends the browser through a residential or mobile IP in the country the restricted page expects. (markdown: /geo/openclaw.md)
- https://aluvia.io/geo/hermes — A Hermes cloud agent that drives Chrome can see content not available in your region because the website is choosing a country from the VM. Use Aluvia only for that browser case, not for model-API region blocks. (markdown: /geo/hermes.md)
- https://aluvia.io/setup — Everything setup does to the machine, and the command that reverses each part. (markdown: /setup.md)
- https://aluvia.io/docs — Install with npx aluvia-cli setup, then aluvia proxy-on --geo US to change the browser's IP location. No account, no API key, 10 MB free, then $2/GB. (markdown: /docs.md)
- https://aluvia.io/pricing — Residential and mobile proxy data at $2/GB. First 10 MB free, no account. Sticky sessions up to 30 minutes. Bring-your-own proxy is free. (markdown: /pricing.md)
- https://aluvia.io/landing/global-proxy — Send a cloud agent's browser through a global network of residential and mobile IPs. Country only. First 10 MB free, then $2/GB. (markdown: /landing/global-proxy.md)
- https://aluvia.io/landing/cloud-server — Cloud VM IPs make automated browsers easier to identify, block, or mis-locate. Aluvia sends the existing browser through a residential or mobile IP in the country you set. (markdown: /landing/cloud-server.md)
- https://aluvia.io/unblock — One page per block signal: what the site is reacting to, and the commands that get past it. (markdown: /unblock.md)
- https://aluvia.io/unblock/geo-restricted — The site says not available in your region, or we do not ship to your location, because cloud Chrome is still the datacenter country. Change the IP location to the country the page needs. (markdown: /unblock/geo-restricted.md)
- https://aluvia.io/unblock/cloudflare — Cloudflare challenged this cloud VM with Verify you are human, Error 1015, Error 1020, or a Turnstile infinite loop. A residential or mobile IP sometimes lets the page through. Fingerprint, TLS, and canvas can still fail. (markdown: /unblock/cloudflare.md)
- https://aluvia.io/unblock/access-denied — Cloudflare Error 1010 Access Denied is the edge refusing the request. A residential or mobile IP sometimes gets past that rule. It is not a promise. (markdown: /unblock/access-denied.md)
- https://aluvia.io/unblock/captcha — A CAPTCHA loop that returns Please verify you are a human after every solve is often reacting to a datacenter IP. A residential or mobile IP sometimes stops the loop. (markdown: /unblock/captcha.md)
- https://aluvia.io/unblock/unusual-traffic — Google is describing unusual traffic from your computer network. On a cloud VM that network is the datacenter range. A residential or mobile exit sometimes clears the message. Waiting on the same range rarely does. (markdown: /unblock/unusual-traffic.md)
- https://aluvia.io/unblock/403 — A 403 Forbidden opening a site from a cloud VM, on a page that needs no login, is often a network rule. A residential or mobile IP sometimes gets the page. Other signals can still 403 it. (markdown: /unblock/403.md)
- https://aluvia.io/unblock/rate-limit — 429 Too Many Requests is often counted against the IP. When Rate limit exceeded hits a cloud agent, a residential IP sometimes starts a fresh count because neighbours on the same cloud range already spent the budget. (markdown: /unblock/rate-limit.md)
- https://aluvia.io/unblock/imperva-security-service — Grok Bot and other cloud agents see Imperva Error 16: This request was blocked by our security service. A residential or mobile exit sometimes reaches the origin. (markdown: /unblock/imperva-security-service.md)
- https://aluvia.io/unblock/vercel-security-checkpoint — A Cursor agent that hits Vercel Security Checkpoint with We're verifying your browser is stuck before origin HTML. From a cloud VM that check often never finishes. A residential or mobile exit sometimes lets the site through. (markdown: /unblock/vercel-security-checkpoint.md)
- https://aluvia.io/e/payment_required — The agent's first 10 MB is spent. Open the `claim_url` from the CLI, buy data at $2/GB, then the agent runs `aluvia auth login` and retries. (markdown: /e/payment_required.md)

## Links

- Docs: https://aluvia.io/docs
- llms.txt: https://aluvia.io/llms.txt
- Source: https://github.com/aluvia-connect/aluvia
- Package: https://www.npmjs.com/package/aluvia-cli
- Dashboard: https://dashboard.aluvia.io
- Home: https://aluvia.io