# Aluvia quickstart

Aluvia gives your agent a different IP address to browse from another country or help it get past a website block.

Try the first 10 MB free, with no account or payment. Then pay 2 USD per GB. [Pricing](/pricing).

## Before you start

Your agent needs permission to install software on its browser's computer, with Chrome or Chromium and Node.js 18 or later. Ask it to check before starting. [Check compatibility](/compatibility).

Save unfinished browser work first. Initial setup may restart Chrome.

## 1. Install Aluvia

```sh
npx aluvia-cli setup
```

Ask your agent to run this command, or run it yourself in a terminal on the browser's computer. Setup connects the browser to Aluvia and installs instructions for your agent. No website address is needed.

<a id="check-the-setup-result"></a>

## Know when setup is ready

Ask your agent to confirm setup finished. In the command response, `ready: true` means the browser and proxy connection checks passed. It does not mean your target website is accessible yet. If setup is incomplete, `next` gives the action to take before continuing.

<a id="use-aluvia-ips"></a>

## 2. Choose a country

Setup already turns Aluvia on. Skip this step if you do not need a particular country.

Ask your agent to run `aluvia geos` to list available countries. Then choose one. This example selects the United States; replace `US` with the country code you need.

```sh
aluvia proxy-on --geo US
```

<a id="check-the-result"></a>

## 3. Open your website

Ask your agent to reload the page and check the content you need, such as local prices or a product catalog. An IP change does not replace a required login or remove every website restriction.

If the page works, continue your task. If it does not, see the troubleshooting help below.

<a id="return-to-your-original-ip"></a>

## Everyday commands

Ask your agent to run these as needed. Turning Aluvia on or off and changing IPs keeps the browser open. Reload the page after changing the connection.

| What you need | Command |
| --- | --- |
| Turn Aluvia on without choosing a country | `aluvia proxy-on` |
| Return to the browser's original connection | `aluvia proxy-off` |
| Check the connection | `aluvia status` |
| Use a new IP in a chosen country | `aluvia rotate-ip --geo US` |

<a id="troubleshooting"></a>

## If something goes wrong

- Setup did not finish: follow the response's `next` instruction, then run setup again. If it asks for a browser restart, use the supplied `chromeCommand` before rerunning setup.
- Command not found: use `npx aluvia-cli` in place of `aluvia`. For example, `npx aluvia-cli status`.
- Website still blocked: run `aluvia status`. If the connection works and the IP seems to be the cause, try `aluvia rotate-ip` once and reload. If it still fails, stop and use the [blocked-page guides](/unblock).
- Too many requests (429 or 1015): wait for the site's retry period and reduce requests. Repeated IP changes are not the fix.
- Wrong country on the page: check the selected IP country, then the site's account or saved location settings. Aluvia selects a country, not a city, and does not change GPS, timezone, or browser language.

<a id="use-your-own-proxy"></a>

## Use your own proxy

Already have an HTTP or HTTPS proxy? Give your agent its connection details. Replace `PROXY_URL` with the address from your provider and keep any password in it private. Aluvia does not charge for that data; your provider's charges and country options apply.

```sh
aluvia proxy-provider PROXY_URL
```

To return to Aluvia's network, run `aluvia proxy-provider aluvia`, then `aluvia proxy-on` or choose a country as in step 2.

<a id="when-the-trial-ends"></a>

## When the trial ends

Your agent gives you a link to set up your account and buy more data. You choose whether to continue at 2 USD per GB.

For agents: when the response says `payment_required`, show the actual `claim_url` to the user. Never invent a link or reveal an API key. Run `aluvia auth login` to wait, then check the response before retrying. [Payment help](/e/payment_required).

<a id="more-help"></a>

## Reference and agent access

Every command returns a structured response called JSON. Agents should read `next` for the next action and use `aluvia status` to check the connection. Confirm success by checking the requested webpage, not connection status alone.

[Read this guide as Markdown](/docs.md) for the complete instructions without the page layout. [Agent reference](/llms.txt) lists commands and links to all guides. Setup installs the Aluvia skill for supported agents.

[Setup details](/setup) cover browser changes, repeat setup, the optional website address, and removal. [Country guide](/geo) covers available locations. [Host compatibility](/compatibility) records what has been tested. If you found older SDK or MCP instructions, read [moving from older setup](/legacy). [Contact support](/contact) if you need help.

---

Source: https://aluvia.io/docs