Aluvia quickstart

Name: Aluvia
Price: 2 USD

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.

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.

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

1. Install Aluvia

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.

Command

npx aluvia-cli setup

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.

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.

Command

aluvia proxy-on --geo US

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.

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`

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

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.

Command

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.

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.

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 for the complete instructions without the page layout. Agent reference lists commands and links to all guides. Setup installs the Aluvia skill for supported agents.

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

Checked against Aluvia CLI 1.4.12 · September 10, 2026