# 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 shops and to Spanish or Portuguese sites. Send the existing Chrome through a GB (or ES/PT) 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 — Install Aluvia on the Cursor cloud machine so every Agents-window tab uses a residential or mobile IP in the country you pick. Cursor has no control to set browser country IP geolocation, which is why US-based IPs stay blocked by geo-restrictions until the exit changes.
- https://aluvia.io/geo/playwright — A Playwright synthetic user sent to the wrong regional site from a single datacenter region still presents that region's IP. Point the existing Playwright Chrome at a residential or mobile IP in the country under test so the page is that market, not the host region.
- https://aluvia.io/geo/claude — Claude computer use on a cloud machine can show wrong country shipping because the shop's ship-to and catalog country follow the cloud VM datacenter IP. Send the browser through a residential or mobile IP in the country the checkout needs.
- 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 — How to change cloud agent browser geo country without VPN: install the CLI on the cloud VM and pick a country so Chrome uses a residential or mobile exit there. That is also how you change cloud Chrome geo without VPN software on a laptop.

## Resources

- https://aluvia.io/resources — Field notes when a datacenter IP hits the wrong country, Cloudflare, CAPTCHA, or Imperva.
- https://aluvia.io/resources/tailscale-vs-aluvia — Three ways to keep a cloud agent browsing when the site sees a datacenter IP: take over the computer, a Tailscale home exit, or Aluvia on the VM.
- https://aluvia.io/resources/triage-geo-cloudflare-imperva — Match the string on the screen to geo, Cloudflare, Imperva Error 16, or a login-shaped page, then run the commands that belong to that branch.
- https://aluvia.io/resources/us-vm-uk-nz-field-kit — Worked setup for a US cloud VM that needs a UK or EU catalog, or a New Zealand trade site sitting behind Imperva Error 16.
- https://aluvia.io/resources/unattended-browser-course — Five short lessons for operators whose Grok Bot or cloud agent runs Chrome on a US datacenter IP and must keep working without a human in the seat.
- https://aluvia.io/resources/cloud-vm-blocks-skill — An installable agent skill that reads the on-screen string and branches to geo, Cloudflare, CAPTCHA, Imperva, or a login wall.

## 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 — How to change cloud agent browser geo country without VPN: install the CLI on the cloud VM and pick a country so Chrome uses a residential or mobile exit there. That is also how you change cloud Chrome geo without VPN software on a laptop. (markdown: /geo/without-a-vpn.md)
- https://aluvia.io/geo/grok-bot — Grok Bot on a US VM presents a US address to UK shops and to Spanish or Portuguese sites. Send the existing Chrome through a GB (or ES/PT) 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 — Install Aluvia on the Cursor cloud machine so every Agents-window tab uses a residential or mobile IP in the country you pick. Cursor has no control to set browser country IP geolocation, which is why US-based IPs stay blocked by geo-restrictions until the exit changes. (markdown: /geo/cursor.md)
- https://aluvia.io/geo/playwright — A Playwright synthetic user sent to the wrong regional site from a single datacenter region still presents that region's IP. Point the existing Playwright Chrome at a residential or mobile IP in the country under test so the page is that market, not the host region. (markdown: /geo/playwright.md)
- https://aluvia.io/geo/claude — Claude computer use on a cloud machine can show wrong country shipping because the shop's ship-to and catalog country follow the cloud VM datacenter IP. Send the browser through a residential or mobile IP in the country the checkout needs. (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/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 — Three ways to keep a cloud agent browsing when the site sees a datacenter IP: take over the computer, a Tailscale home exit, or Aluvia on the VM. (markdown: /resources/tailscale-vs-aluvia.md)
- https://aluvia.io/resources/triage-geo-cloudflare-imperva — Match the string on the screen to geo, Cloudflare, Imperva Error 16, or a login-shaped page, then run the commands that belong to that branch. (markdown: /resources/triage-geo-cloudflare-imperva.md)
- https://aluvia.io/resources/us-vm-uk-nz-field-kit — Worked setup for a US cloud VM that needs a UK or EU catalog, or a New Zealand trade site sitting behind Imperva Error 16. (markdown: /resources/us-vm-uk-nz-field-kit.md)
- https://aluvia.io/resources/unattended-browser-course — Five short lessons for operators whose Grok Bot or cloud agent runs Chrome on a US datacenter IP and must keep working without a human in the seat. (markdown: /resources/unattended-browser-course.md)
- https://aluvia.io/resources/cloud-vm-blocks-skill — An installable agent skill that reads the on-screen string and branches to geo, Cloudflare, CAPTCHA, Imperva, or a login wall. (markdown: /resources/cloud-vm-blocks-skill.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 — Sorry you have been blocked, Error 1015, or verify you are human: Grok Bot hits Cloudflare from a cloud VM. A residential or mobile IP in the right country sometimes lets the page through. Aluvia does not claim to beat fingerprint, Linux Chrome, TLS, or canvas. (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 — This request was blocked by our security service, Error 16, Access denied, Powered by imperva: Grok Bot hits that card from a cloud Chrome. A residential or mobile IP in the right country sometimes reaches the origin. Aluvia does not claim to beat Imperva fingerprint, TLS, or challenge cookies. (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