What npx aluvia-cli setup does

This page as markdown: https://aluvia.io/setup.md

Everything setup does to the machine, and the command that reverses each part.

The command

npx aluvia-cli setup

Run on the machine where the agent's Chrome or Chromium browser runs. Needs Node.js 18 or later and a usable local browser runtime. No target page URL is required. Initial browser configuration can restart Chrome; save unfinished work first. Follow the quickstart and read the JSON next field before continuing. If aluvia is not on PATH, replace aluvia with npx aluvia-cli, for example npx aluvia-cli status.

What it starts

Both listen on loopback. Nothing is opened on another interface, so nothing outside the machine can reach either one.

• A proxy on 127.0.0.1:18787 — the one the browser is aimed at.
• A control server on 127.0.0.1:18788 — the one the aluvia commands talk to.

What it writes

• The aluvia command launcher, so later commands can use aluvia when it is on PATH.
• Its home directory: /workspace/.aluvia when /workspace exists, otherwise ~/.aluvia. The configuration and the install id live there.
• The aluvia agent skill, into the skill folder of the agent runtimes already on the machine, so the agent knows when to reach for it.

What changes in Chrome

Setup configures Chrome to use the local proxy. Initial configuration can restart Chrome. When a restart is needed, setup opens https://example.com/, a small HTTPS test page. Optional --url <page> opens a specific page instead; no target page URL is required.

On Linux, setup retains the discovered browser's launch settings, including its profile and TCP debugging port. When an existing debugging connection is available, setup asks Chrome to close cleanly before relaunching. This does not guarantee that all browser state survives on every platform or automation runtime.

Readiness and repeat setup

Setup enables proxy traffic and checks the upstream connection. ready: true means the browser reached the local proxy and the upstream connection check passed. It is not proof that a target website allows access or that an agent task succeeded. If setup cannot finish, the JSON next field gives the recovery action.

Running setup again on a working setup checks the connection again and enables proxy traffic without restarting the browser or changing the live proxy session.

After setup is ready, choose a country with aluvia geos and aluvia proxy-on --geo US, or use your own proxy with aluvia proxy-provider PROXY_URL. These commands select the desired configuration; successful setup already enables proxy traffic. Reload the target page, check its content, then run aluvia status and follow next.

aluvia proxy-on, aluvia proxy-off, and aluvia rotate-ip keep Chrome running with its tabs and cookies.

What it sends

The first setup starts a free trial from a sticky install id on the machine. No account or API key is required — the id is what the trial is counted against. Setup can still need a recovery action.

While egress is on, browser traffic leaves through Aluvia's network. While it is off, traffic goes straight out of the machine exactly as it did before setup ran.

How to undo it

• aluvia proxy-off — back to the machine's own IP. The daemon stays up and the browser is untouched.
• aluvia proxy-provider PROXY_URL — keep the setup, send traffic through a proxy you already have instead.
• aluvia stop — stop the local proxy.
• Delete the home directory above to remove the configuration and the install id.
• Relaunch the browser without setup's proxy setting to aim it back at the network directly.

Check your setup

aluvia status prints what is actually running, and explains every field it prints. It is the answer to give a human who asks what changed.

This page lists what Aluvia publishes about setup. It is not a decompilation of the binary: if a detail matters to your threat model and is not here, ask for it before running the command.

After this command, pick a country on change a cloud agent's IP location. Muse Secure VM has its own page at Muse Secure VM. Grok Bot has its own page at Grok Bot.

To match a block string such as Cloudflare, CAPTCHA, Imperva, or a region message, start at Unblock a page from a cloud VM. The triage field note maps those strings to a command.

Check host compatibility and test evidence before a new install. Older SDK or MCP package listings are covered on moving from older setup.

aluvia status