# 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. 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 for opening a site as the US or the UK. Install Aluvia on the cloud machine so the agent's browser uses a residential or mobile IP in the country you set.
- https://aluvia.io/geo/playwright — Playwright or Puppeteer Chrome on a cloud VM is seen as that VM's country. 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 — OpenClaw on a VPS or cloud VM opens sites from the host IP. Aluvia sends the browser through a residential or mobile IP in the country the restricted page expects.
- https://aluvia.io/geo/hermes — When a Hermes cloud agent drives Chrome, the website sees the VM's country. Use Aluvia only for that browser case, not for model-API region blocks.

## Without a VPN

- https://aluvia.io/geo/without-a-vpn — Put a cloud agent's browser in a country without installing a human VPN. Aluvia runs on the VM and sends traffic through a residential or mobile IP in the country you set.

## Pages

- https://aluvia.io/geo — Cloud agents browse from the datacenter they run in. 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 — Put a cloud agent's browser in a country without installing a human VPN. Aluvia runs on the VM and sends traffic through 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. 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 for opening a site as the US or the UK. Install Aluvia on the cloud machine so the agent's browser uses a residential or mobile IP in the country you set. (markdown: /geo/cursor.md)
- https://aluvia.io/geo/playwright — Playwright or Puppeteer Chrome on a cloud VM is seen as that VM's country. 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 — OpenClaw on a VPS or cloud VM opens sites from the host IP. 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 — When a Hermes cloud agent drives Chrome, the website sees the VM's country. 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/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 agent is stuck with the country of the datacenter it runs in. 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. 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 — The site refused the request at the edge. 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 that repeats 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 — The site is describing traffic on this network. 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 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 — The limit is often counted against the IP. A different exit starts a fresh count when neighbours on the same cloud range already spent the budget. (markdown: /unblock/rate-limit.md)
- https://aluvia.io/unblock/imperva-security-service — Imperva's security service dropped a cloud or datacenter IP and showed Error 16. A residential or mobile exit sometimes reaches the origin. Not a 403, not Cloudflare, not a login form. (markdown: /unblock/imperva-security-service.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