Aluvia

Unattended browser on a datacenter IP

This page as markdown: https://aluvia.io/resources/unattended-browser-course.md

Updated · Aluvia

Learn to diagnose a region mismatch, distinguish a network block from a browser or account problem, and test one IP change. Each lesson ends with a task on the existing cloud browser. Start with what setup changes if Aluvia is new to you, or use the triage guide for a current failure.

The command

Command
npx aluvia-cli setup

First 10 MB free without an account, API key or payment, then 2 USD per GB. Run on the browser's machine with Node.js 18 or later and usable local Chrome or Chromium. Initial setup can restart Chrome. Read JSON and follow next for recovery before selecting a country. Reload the page and verify its content; ready: true is not target access. Complete quickstart.

Day 1 — Geo: the site is choosing the datacenter's country

A browser on a US VM may receive a US catalog or prices because of its IP. A saved country, shipping address, language preference or account rule can produce a similar result. Check the site’s own country controls and account settings before testing a different IP.

Aluvia is a local CLI on the browser host. It routes existing Chrome through a residential IP in a selected country. This can help when the site uses IP location; reload and verify the page. It does not set GPS, timezone, language or saved shipping details. Omit --geo only when the global pool fits the task.

GB is the usual example when a US VM needs Britain. Replace it with the code for the market you actually need; aluvia geos lists what is available. Sticky sessions last up to 30 minutes. Keep the same exit through browse, cart, and checkout so the shop does not see the country flip mid-flow.

Leave streaming and live video alone. A content licence that forbids the region regardless of IP is outside this tool. If the screen is a challenge or Error 16 rather than a region string, use Day 2 or Day 3 instead of forcing a geo-only story. Further reading: Grok Bot and not available in your region.

Today's action: on the agent machine, run npx aluvia-cli setup, then aluvia geos, and write down the country code for the market you actually need.

Day 2 — Cloudflare and CAPTCHA: sometimes the exit is enough

Cloudflare scores the connection before origin HTML is served. Strings you may see include "Verify you are human," "Checking if the site connection is secure," "Please verify you are a human," "Sorry, you have been blocked," Error 1020, Error 1015, or a CAPTCHA that returns after every solve. A Ray ID in the page footer means the edge decided; it does not mean the next load will pass.

IP reputation is one possible input. A repeated challenge does not tell you its weight or rule. Error 1015 is a rate limit: wait and reduce requests. Error 1010 concerns the browser signature, which Aluvia does not change.

Aluvia changes one input: the exit IP. A residential address sometimes lets the page through. Sometimes. Not a promise. Linux Chrome, TLS, canvas, and fingerprint can still fail after the address looks residential. Do not write or imply a guaranteed Cloudflare pass.

A cleared CAPTCHA followed by a silent Create button is not a diagnosis. Check the failed request or page error before deciding whether IP, session state, or the application caused the failure.

Reload the page after proxy-on. For an IP-related refusal, try aluvia rotate-ip once and reload; stop if it fails. For a rate limit, wait and reduce requests. Add --geo US when the page also needs a specific country (geo and edge blocks often stack on a US VM opening a foreign shop). Do not use Aluvia for a normal login wall that already needs credentials, SSO, or 2FA. An IP-triggered soft page that only appeared because the client looked like cloud hosting is change-IP territory; a form waiting for secrets is not. Further reading: Cloudflare and CAPTCHA.

Today's action: capture the exact challenge string (and Ray ID if present) from one failing page, then try aluvia proxy-on and one rotate-ip if needed. Record whether the page loaded, still challenged, or failed for a non-IP reason.

Day 3 — Imperva Error 16: not Cloudflare, not a 403 from origin

Imperva sits in front of some trade and retail origins. Error 16 is its card. You may see "This request was blocked by our security service," "Access denied," "Your IP," "Proxy IP," "Incident ID," or "Powered by imperva." The hostname can remain on the card while the catalog never loads. This is not a Cloudflare Ray ID flow and not a 403 returned by the application server after HTML started.

A US cloud VM opening a New Zealand trade site is a common shape. The security service classified a datacenter client, often in the wrong country for the merchant. A residential exit sometimes reaches the origin. Hedge that sentence every time you say it aloud or in a runbook.

Reload after proxy-on --geo NZ. If Error 16 returns, run aluvia rotate-ip and reload again. One exit can be blocked on its own; rotation is the next lever, not a second Chrome. Once a residential exit clears the card, stay inside the sticky window (up to 30 minutes) for search, cart, or account steps so you do not jump onto a new blocked address mid-flow.

Watch the login false friend. The address bar can show /login while the card is still Imperva's security service. Changing the exit IP is in scope so a real login form might appear. Filling or skipping username, password, SSO, or 2FA is out of scope. If a credential form is already on screen and waiting, stop — that is a normal login wall, and Aluvia is the wrong tool. Further reading: Imperva Error 16 and Grok Bot.

Today's action: if you have an Imperva-backed URL in your workflow, run proxy-on with the right --geo, reload once, rotate once if needed, and write the outcome in one sentence (cleared / still Error 16 / reached login form / non-IP failure).

Day 4 — Operating a home exit, Aluvia or manual takeover

Taking over the computer can help with diagnosis or a one-off challenge in your own browser. It requires operator time and does not provide an unattended recovery path.

Take over the computer: you clear "Verify you are human" yourself, or you finish the job in your own browser. xAI-style advice often lands here for a stuck session. It works for debugging. It fails as a workflow the moment the agent must run alone. Every future challenge becomes a page for you.

A Tailscale home exit needs an available exit node, device authentication and configuration on the browser host. Those steps can be automated, including when a VM is replaced. Aluvia needs setup on the new browser host and data on its network; it does not require a home exit node. Both approaches can need recovery. Tailscale automated provisioning.

Plan how the browser host will be configured after replacement. With Aluvia, run setup again and inspect its recovery output. Successful setup does not prove target access; paid continuation needs the operator.

Aluvia is not a human VPN product and not for streaming. It is egress for the agent's existing Chrome. Prefer aluvia proxy-off when you want the machine IP again without stopping the browser.

Day 5 — Setup, trial, and claim_url

Put the week into one machine path the agent can repeat after every replace. Use the country from Day 1 if it is still listed by aluvia geos; US below is an example. If aluvia is not on PATH, replace aluvia with npx aluvia-cli in every command, for example npx aluvia-cli status. Every command prints JSON on stdout with a next field — read next and run it. Never print API keys. Initial browser configuration can restart Chrome; do not launch a second Chrome afterward.

First 10 MB is free from an install id on the machine. No account and no API key to start. Then $2/GB on the Aluvia network. When the trial is used up, a command that needs the network returns code: payment_required and a claim_url on dashboard.aluvia.io. The operator opens that URL on their own machine, claims the account, and buys data. The agent then runs aluvia auth login. The agent cannot fix payment alone. Show claim_url. Never invent a key or paste secrets into chat.

Bring-your-own proxy is available with aluvia proxy-provider <url> and is free for bandwidth on Aluvia's side; switch back with aluvia proxy-provider aluvia.

Reminders that still apply on Day 5: country only; residential IPs; sometimes for Cloudflare / CAPTCHA / Imperva; no fingerprint / TLS / canvas claims; not streaming; not MCP; not login bypass; docs at https://aluvia.io/docs. If the page still fails after a residential exit and names fingerprint, Linux Chrome, TLS, or canvas, stop treating IP as the only lever and escalate with the exact error string instead of rotating forever.

Start page: https://aluvia.io. Geo walkthrough: Grok Bot. Imperva card: the Imperva security-service card. Payment handover: the free trial is used up.

Today's action: run npx aluvia-cli setup on the agent VM (or confirm it is already installed), complete one real page load through proxy-on --geo US, and if you hit payment_required, open the claim_url yourself rather than pasting secrets into chat.

After the five days

Record the page outcome, chosen country and any recovery step. Keep a successful setup separate from a successful browser task. Use the triage guide for a new failure and aluvia proxy-off when the task is complete.