# Aluvia

> Agents in the cloud use datacenter IPs that often get blocked or hit CAPTCHAs. Aluvia routes web traffic through residential or mobile IPs, unblocking browser workflows.

Aluvia is a local CLI and proxy daemon. An AI agent running in a cloud VM installs it, turns it on, and keeps working when a site blocks the VM's datacenter IP.

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.

## Install

```
npx aluvia-cli setup
```

Node.js 18 or later. Installs the `aluvia` binary and an agent skill. If `aluvia` is not on PATH, prefix every command with `npx aluvia-cli`.

## Use cases

Unblock browser workflows. Use Aluvia when a page returns 403, shows a CAPTCHA, shows a Cloudflare or Access Denied interstitial, reports unusual traffic, or throttles the request. Do not use it for a normal login wall.

Change the agent's geo. An agent is otherwise stuck with the country of the datacenter it runs in. `aluvia proxy-on --geo US` picks a country. Run `aluvia geos` for the list. Omit `--geo` to use every country.

## 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. 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. |
| `aluvia status` | Show what is running. Every field is explained in the output. |
| `aluvia geos` | List the available countries. |
| `aluvia auth <key>` | Save an API key the operator pasted. |
| `aluvia auth login` | Wait while the operator claims the account and buys data. |
| `aluvia proxy-provider <url>` | Use a proxy URL the operator already has. |
| `aluvia proxy-provider aluvia` | Go back to the Aluvia network. |
| `aluvia stop` | Stop the local proxy. Prefer `proxy-off`. |

## Trial and payment

The first 10 MB of proxy data is free, started from an install id on the machine. When it 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

## Pages

- https://aluvia.io/setup — Everything setup does to the machine, and the command that reverses each part. (markdown: /setup.md)
- https://aluvia.io/unblock/cloudflare — The challenge is aimed at the IP, not at the browser. Send the browser out through a residential or mobile IP and the page loads. (markdown: /unblock/cloudflare.md)
- https://aluvia.io/unblock/access-denied — The site refused the request at the edge because of where it came from. Change the exit IP and retry. (markdown: /unblock/access-denied.md)
- https://aluvia.io/unblock/captcha — A CAPTCHA that never ends is a verdict on the IP. Move the browser onto a residential or mobile IP and it stops being asked. (markdown: /unblock/captcha.md)
- https://aluvia.io/unblock/unusual-traffic — The site is describing the IP's neighbours, not the agent. A residential or mobile exit IP clears it. (markdown: /unblock/unusual-traffic.md)
- https://aluvia.io/unblock/403 — A 403 that a browser on a laptop does not get is an IP block. Route the browser through a residential or mobile IP and retry. (markdown: /unblock/403.md)
- https://aluvia.io/unblock/rate-limit — The limit is counted against the IP. A different exit IP starts a fresh count. (markdown: /unblock/rate-limit.md)
- https://aluvia.io/unblock/geo-restricted — The agent is stuck with the country of the datacenter it runs in. Pick the country the page needs. (markdown: /unblock/geo-restricted.md)
- https://aluvia.io/e/payment_required — The free trial data is used up. The agent cannot fix this alone — one human action is needed, and the CLI hands over the exact link for it. (markdown: /e/payment_required.md)

## Links

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