# Aluvia — Proxy IPs for cloud agents

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.

## Install

```
npx aluvia-cli setup
```

Node.js 18 or later. No account, no API key, and the first 10 MB is free. 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, 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.

## When to use it

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

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