# Global proxy IPs for AI agents.

Aluvia makes it dead simple for agents to change their own IP address to access geo-specific content. Use our global network of premium IPs, or bring your own proxies. Setup in seconds.

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

## 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

An agent with an IP address from one country needs to access location-specific content in another country. It gets geo-blocked and sees "content is not available in your region" errors. Aluvia gives the agent a reputable proxy IP address in the required country. The agent is no longer geo-blocked and can access location-specific content. 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.

## 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/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 leaves through 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. Move the browser onto 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/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 leaves through 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. Move the browser onto 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. (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/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