Reference

Install, and every option

How to get anoa onto each platform, and the complete command line — every flag the browser takes, every command you can send it.

macOS — Homebrew

One universal build serves both Intel and Apple Silicon.

$ brew tap porcupine-md/tap
$ brew trust porcupine-md/tap
$ brew install --cask anoa

It installs a single anoa shim on your PATH. That one executable is the whole product — the terminal viewer is its terminal subcommand, not a separate file. The app is Developer ID signed and notarized, so it opens with no Gatekeeper warnings.

Upgrading

brew update first, or the tap will not have seen the newest release.

$ brew update
$ brew upgrade --cask anoa

Linux

AppImage — recommended

One file. Download it, make it executable, run it. No unpacking, no install, no root.

$ chmod +x anoa-x86_64.AppImage          # or anoa-aarch64.AppImage
$ ./anoa-x86_64.AppImage --headless --port 9222
$ ./anoa-x86_64.AppImage open example.com

Built for x86_64 and aarch64 against the same Qt, so both run on anything with glibc 2.35 or newer — Ubuntu 22.04, Debian 12 and later, which is what an ARM board usually runs. It carries its own FUSE, so it does not need the libfuse2 package Ubuntu dropped in 22.04.

Download the latest release →

Install script — no root

Installs the portable bundle under your home directory and puts the launcher on your PATH. Re-running it upgrades in place.

$ curl -fsSL https://raw.githubusercontent.com/porcupine-md/anoa-browser/master/scripts/install-linux.sh | bash

~/.local/lib/anoa/     the unpacked bundle — self-contained, nothing system-wide
~/.local/bin/anoa  ->  ../lib/anoa/anoa.sh

The symlink points at the launcher, never at the raw binary: the launcher sets up the environment the bundled libraries need. It tells you if ~/.local/bin is not on your PATH.

Homebrew on Linux

$ brew tap porcupine-md/tap
$ brew install anoa

Nix

Then this needs nothing else installed beforehand:

$ nix run github:porcupine-md/anoa-browser -- --headless --port 9222
$ nix run github:porcupine-md/anoa-browser -- open example.com

Or install it into a profile:

$ nix profile install github:porcupine-md/anoa-browser

In your own flake

# flake.nix
inputs.anoa.url = "github:porcupine-md/anoa-browser";

# then, in a module or a devShell
environment.systemPackages = [ inputs.anoa.packages.${system}.anoa ];

nix develop gives a shell with Qt, CMake, Node and Python — everything the build and the test suites want.

Driving a remote box over SSH, note that a single-user Nix install puts nix on your PATH through ~/.nix-profile/etc/profile.d/nix.sh, which a non-interactive ssh host 'command' never sources. Use the full path, ~/.nix-profile/bin/nix, or source that script first.

Windows

Download anoa-windows-x86_64.zip from the releases page, unzip it, and run anoa.exe.

> anoa.exe --headless --port 9222
> anoa.exe open example.com

Container

$ docker run -d --name anoa -p 9222:9222 ghcr.io/porcupine-md/anoa-browser
$ docker exec anoa anoa open example.com
$ docker exec anoa anoa snapshot -i
$ docker exec anoa anoa click @e1

Publish 9224 as well if a CDP client outside the container needs to attach — that is where the WebSocket ends up. See the port layout.

From source

Prebuilt packages are above; building it yourself needs Qt 6.4 or newer with the WebEngine modules, and CMake. Prerequisites, targets, architecture and the release process are in docs/BUILDING.md.

$ cmake -B build -DCMAKE_BUILD_TYPE=Release
$ cmake --build build -j

Starting a browser

The browser is the session. Every command in the reference below attaches to one that is already running and leaves it running, so the page, the cookies and the scroll position survive between them.

$ anoa --headless --port 9222 &

Reaching a running browser

Agent commands take these wherever they appear — before the verb or after it, both work.

The port layout

One number gives three ports.

Sessions and profiles

Cookies and logins are kept between runs, in a profile named default under your platform's application data directory. A browser that forgot every login would not be one you could drive across separate commands.

# its own cookie jar and storage, kept on disk
$ anoa --headless --profile work

# keep profiles somewhere else
$ anoa --headless --profile-dir /srv/anoa-profiles

# keep nothing at all
$ anoa --headless --ephemeral

Tabs share one jar unless asked otherwise, which is what makes two logins to the same site possible at once — see tab new --profile and --isolated below.

Going through a proxy

The proxy belongs to the browser, and every tab in it goes through it.

$ anoa --headless --port 9222 --proxy http://proxy.example:3128
$ anoa --headless --port 9222 --proxy socks5://127.0.0.1:1080
$ anoa --headless --port 9222 \
      --proxy http://user:[email protected]:3128 \
      --proxy-bypass "localhost,127.0.0.1,*.internal"

--proxy takes host:port or scheme://host:port, where the scheme is http, https, socks5 or socks4; a bare host gets http://. Anything else is refused at startup rather than accepted and then failing every request with a message that blames the site.

Credentials go in the URL. Chromium's own --proxy-server takes none, so anoa passes it the origin and answers the proxy's authentication challenge itself — without that a password-protected proxy simply hangs, and nothing in the page says a password was wanted.

Memory with many tabs

Chromium gives every tab its own renderer process, and that is where the memory goes. Measured on one machine, nine tabs against one, same page in each:

One tab on its own was 117 MB of renderer, so the growth is almost entirely per-tab renderer processes rather than anything in the browser process, which moved only 156 → 255 MB across the same range.

Going further

Chromium's own flags pass through, so the more aggressive setting is available without a dedicated option. --process-per-site puts every tab of the same site in one process:

$ QTWEBENGINE_CHROMIUM_FLAGS=--process-per-site anoa --headless --port 9222

Cross-site isolation survives it — tabs on different sites still get different processes — but same-site parallelism does not, which is the 2921 ms above.

Terminal viewer

anoa terminal renders the live page in your terminal and forwards your clicks, scrolls and typing back to it. These options are CLI-only — they are never read from a config file — and they are named apart from --port and --auth-token so no flag changes meaning between modes.

Given no target at all, anoa terminal attaches to a browser already on 9222, and hosts its own only when there is none.

Tabs

$ anoa tab new [url]                open a tab, print its id
      --name <name>               call it something; --tab takes it after
      --profile <name>            give it its own persistent cookies
      --isolated                  a throwaway jar, gone with the tab
$ anoa tab list                     every tab; * marks the active one
$ anoa tab select <id>              make a tab the active one
$ anoa tab close <id>               close it (the last one cannot be closed)

--tab takes an id or a name, so --tab search and --tab t2 can be the same tab. A name is an alias; the id keeps working. Every other command takes --tab and acts on the active tab without it, so anoa --tab t2 get text reads tab 2 while tab 1 carries on with its own work.

Navigate

$ anoa open <url>                   go to a url (scheme optional)
$ anoa back | forward | reload      move through history
$ anoa wait --load                  wait for the page to finish loading
$ anoa wait --selector <css>        wait for an element to appear
$ anoa wait --ms <n>                wait a fixed time
$ anoa wait --text "<text>"         wait for text to appear
$ anoa wait --url "<fragment>"      wait for the url to contain something
$ anoa wait --fn "<js>"             wait for a JS expression to be truthy
$ anoa wait <css> --state hidden    wait for an element to go away
$ anoa wait --network-idle          fetch/XHR quiet (default 500ms)
      --network-idle-ms <n>       how long quiet counts as quiet
$ anoa wait --download              every download has finished
      --timeout <ms>              give up after this long (default 15000)

A bare argument is read as a duration when it is a number and as a selector otherwise, so anoa wait 500 and anoa wait "#results" both do what they look like.

Inspect

$ anoa snapshot                     page outline + interactive elements with refs
$ anoa snapshot -i                  interactive elements only
$ anoa find role <role>             locate by role (button, link, textbox, …)
$ anoa find text <text>             by visible text, deepest match wins
$ anoa find selector <css>          by CSS, returned as refs
      --nth <n>                   keep only the nth match (1-based)
$ anoa get text [<target>]          visible text of the page or one element
$ anoa get html <target>            outer HTML
$ anoa get value <target>           current form value
$ anoa get attr <target> <name>     one attribute
$ anoa eval <js>                    evaluate an expression in the page
$ anoa status                       what the browser is attached to right now

<target> is a ref from a snapshot (@e2) or any CSS selector. snapshot prints refs first, because the ref is what the next command needs:

  @e1   link       Documentation
  @e3   textbox    Search  [required]
  @e7   button     Sign in

Interact

$ anoa click <target>               click, hit-tested — fails if something covers it
$ anoa fill <target> <text>         set a field's value, fire input/change
$ anoa type <text>                  type into whatever has focus
$ anoa upload <target> <file...>    put files into a file input
$ anoa press <key>                  Enter, Tab, Escape, ArrowDown, …
$ anoa scroll [--up] [--by <px>]    scroll the page
$ anoa scroll --top | --bottom      jump to either end
$ anoa mouse move <x> <y>           move the pointer
$ anoa mouse down | up [x] [y]      press or release, for drags
$ anoa mouse wheel <dy> [x] [y]     wheel at a position

Batches — many commands, one connection

Every command is its own process and its own connection, about 130 ms of it before the page does anything. exec pays that once for a whole batch.

$ printf 'open example.com\nwait --selector h1\nget text h1\n' | anoa exec -
$ anoa exec steps.txt

Blank lines and # comments are skipped, quotes group arguments, and the batch stops at the first command that fails, naming the line — step five almost always depends on step four, and running the rest produces errors that point at the wrong place.

Downloads

A download is browser state, so eval cannot see it. Ask the browser.

$ anoa click @e4                    something that downloads a file
$ anoa wait --download
$ anoa downloads                    state, path, bytes
completed   /home/you/Downloads/report.pdf  (284120/284120 bytes)

--download-dir at startup chooses where files land. The path downloads reports is where the bytes actually went, which is not always the name the page asked for: a collision makes the browser rename.

Add --json for the same list as an array, with url, path, state, received and total.

Capture

$ anoa screenshot [file]            PNG of the viewport (default screenshot.png)
$ anoa pdf [file]                   PDF of the page (default page.pdf)

State — cookies, storage and emulation

$ anoa cookies                      list cookies
$ anoa cookies set <name> <value>   set one, scoped to the current page
      --url <url>                 scope it somewhere else instead
$ anoa cookies clear                clear them all

$ anoa storage local                everything in localStorage
$ anoa storage local <key>          one key
$ anoa storage local set <k> <v>    write one
$ anoa storage local remove <k>     delete one
$ anoa storage local clear          empty it
$ anoa storage session ...          the same, for sessionStorage

$ anoa set viewport <w> <h> [scale] resize the page
$ anoa set device [name]            a preset; no name lists them
$ anoa set geo <lat> <lng>          override geolocation
$ anoa set offline [on|off]         cut the page off from the network
$ anoa set headers '<json>'         extra HTTP headers on every request
$ anoa set media dark|light         emulate prefers-color-scheme

Debug — what the page did

$ anoa console [--level <lvl>]      console output, newest last
$ anoa errors                       uncaught exceptions and rejections
$ anoa network                      every request: kind or method, status, ms
      --clear                     forget what has been recorded so far

Agents

$ anoa skills list                  what skill documents this binary carries
$ anoa skills get core              the core workflow, for an agent to read
$ anoa skills get commands          every command, with its arguments
$ anoa close                        stop the browser; returns once it is gone

The skill documents are printed straight to stdout, meant to be pasted into a context window rather than read on a screen.

Output and exit codes

Add --json to any command for machine-readable output.

anoa help <group> prints one section on its own: browser, navigate, inspect, interact, state, debug, capture, agents.

Playwright, Puppeteer, and anything else that speaks CDP

There is no driver to install and no adapter to write. anoa serves the Chrome discovery endpoints and a WebSocket a CDP client connects to exactly as it would to Chrome.

// Playwright
const browser = await chromium.connectOverCDP('http://localhost:9222');

// Puppeteer
const browser = await puppeteer.connect({ browserURL: 'http://localhost:9222' });

Both suites run against every release. Named profiles with isolated cookie jars, unpacked Chromium extensions (manifest v2) and Page.printToPDF all work through the same connection.

With --auth-token set, pass it as a bearer token or as ?token= on the WebSocket URL.

Ports — one number gives three

--port moves all three. Leave N+1 and N+2 free — if something else holds the debugging port, discovery answers with output a client cannot parse.

The Browser domain

Chromium rejects these outright — the browser they describe is one Qt owns and it has no handle on it — so anoa answers them itself: setDownloadBehavior, grantPermissions, resetPermissions, getWindowForTarget, setWindowBounds and close.

They do the real thing. The download directory changes and deny refuses; the window resizes and the page sees the new viewport; a granted permission is one navigator.permissions.query reports as granted.

Emulation set over CDP behaves the way it does from the CLI: an override belongs to the tab and outlives the connection that applied it, so a client that reconnects finds the page as it left it.

MCP

POST /mcp speaks the Model Context Protocol over Streamable HTTP, so a client that cannot run a shell — Claude Desktop among them — drives this browser with typed tools instead of a remembered command line.

// the client's config
{
  "mcpServers": {
    "anoa": { "url": "http://localhost:9222/mcp" }
  }
}

Every verb on this page is a tool, named browser_* and carrying a JSON Schema for its arguments. One JSON-RPC message in, one JSON response out; the server pushes nothing, so GET /mcp answers 405 rather than holding a stream open forever.

It is the same browser the CLI drives. A tab opened from a shell is visible to a tool call, a ref from browser_snapshot resolves either way, and an override from browser_set outlives the call that made it.

Two guards. --auth-token covers it like every other endpoint, as a bearer token or ?token=. And an Origin that is not in --embed-origin is refused with 403: a page in someone's browser can reach localhost through DNS rebinding, and a request carrying no Origin at all — a real client, or curl — is the one that is allowed.