# What npx aluvia-cli setup does

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

## The command

```sh
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](/docs) 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](/geo). Muse Secure VM has its own page at [Muse Secure VM](/geo/muse). Grok Bot has its own page at [Grok Bot](/geo/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](/unblock). The [triage field note](/resources/triage-geo-cloudflare-imperva) maps those strings to a command.

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

```sh
aluvia status
```

---

Source: https://aluvia.io/setup