# Global proxy IPs for AI agents.

Aluvia lets agents change their IP address using a global network of residential IPs.

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

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

## When to use it

### Access geo-blocked content

Give agent an IP from a different country.

When a cloud agent opens a website, the site sees the datacenter's country. That can return the wrong prices or catalog, or a page that says the content is unavailable in that region.

Aluvia lets the agent use a residential or mobile IP in the country the task requires. Run `aluvia proxy-on --geo US`, then reload the page to check the result. Replace `US` with the country you need; `aluvia geos` lists available countries.

### Use residential IPs instead of the agent's datacenter IP

Agents in the cloud use datacenter IPs that often get blocked.

Aluvia routes the agent's existing browser through a residential or mobile IP. If a site is blocking the datacenter IP, changing the IP can help the agent continue.

A different IP sometimes clears a 403, CAPTCHA, or Cloudflare challenge. It does not resolve every block; browser checks and login requirements can still apply.

## 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` | Configure the browser and enable proxy traffic. Repeat to check a working setup without restarting the browser or changing its live proxy session. |
| `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

## FAQs

### How do I start the free trial?

Ask your agent to run `npx aluvia-cli setup` on the machine where its Chrome or Chromium browser runs. No target page URL is required. Setup needs Node.js 18 or later and a usable local browser runtime. Initial configuration can restart Chrome. Check the JSON result and follow `next` if recovery is needed. The first 10 MB is free. No account, API key, or payment is required.

### What happens when the free data runs out?

The CLI gives you a link to claim the account and buy data. Aluvia network traffic costs $2/GB after the free trial. You choose whether to continue.

### Can I use my own proxy?

Yes. Run `aluvia proxy-provider PROXY_URL` with an HTTP or HTTPS proxy URL you already have. You do not pay Aluvia for that bandwidth. To switch back, run `aluvia proxy-provider aluvia`.

### Which countries can I use?

Run `aluvia geos` to see the countries available on Aluvia's global residential and mobile IP network. Use `aluvia proxy-on --geo US` to choose a country. Omit `--geo` to use the global pool. Country only, not city. Sticky sessions last up to 30 minutes. With your own proxy, the location depends on your provider.

### Will I lose my open tabs or cookies?

Initial browser configuration can restart Chrome. Save unfinished work first; state preservation is not guaranteed across every platform or automation runtime. Running setup again on a working setup checks the connection and enables proxy traffic without restarting the browser or changing the live proxy session. After setup, `aluvia proxy-on`, `aluvia proxy-off`, and `aluvia rotate-ip` keep Chrome running with its open tabs and cookies.

### Will a different IP solve every block?

No. A residential or mobile IP in the right country sometimes clears a block associated with the current IP. Aluvia does not claim to change browser fingerprint, TLS, canvas, GPS, timezone, or Accept-Language, and it is not for a normal login wall.

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

## By agent

- https://aluvia.io/geo/grok-bot — Change the country used by a Grok Bot browser on a cloud machine. Check a UK catalog without moving the browser.
- https://aluvia.io/geo/codex — Use Aluvia for a Codex browser task when Chrome runs on a machine you control. Choose an IP country and verify the page.
- https://aluvia.io/geo/cursor — Set up Aluvia where your Cursor agent's Chrome browser runs. Choose a country for the browser, not for your laptop.
- https://aluvia.io/geo/playwright — Use a selected IP country for Playwright browser automation. Check the browser's proxy configuration before running a regional test.
- https://aluvia.io/geo/claude — Choose an IP country for Chrome used by Claude computer use. Set up on the browser host and verify the storefront.
- https://aluvia.io/geo/openclaw — OpenClaw agent geo-restricted content follows the cloud VM's datacenter IP. Install the CLI on that machine and send the existing Chrome through a residential or mobile IP in the country the page expects.
- https://aluvia.io/geo/hermes — Use Aluvia for Hermes tasks that drive Chrome on a cloud machine. Distinguish a website region problem from a model API error.

## Without a VPN

- https://aluvia.io/geo/without-a-vpn — A VPN on your laptop does not change a separate cloud browser's IP. Set up Aluvia on the browser's machine and choose a country.

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

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