# Install CatPaw: instructions for an AI agent A user has asked you, an AI agent, to install CatPaw for them. CatPaw is a headless browser for AI agents: one program, `catpaw`, that serves browsing tools (navigate, snapshot, click, fill, read, ...) over the Model Context Protocol. These steps install it and connect it to the agent host you run in (Claude Code, Codex, Cursor, or another MCP host). Follow the steps in order, and talk to the user in their language. ## Ground rules - **Write nothing before the user has seen the plan and said yes.** Step 2 shows the plan without writing anything; step 3 installs. - **Use only the official installer and release files**: the scripts at `https://catpaw.sh/install.sh` and `https://catpaw.sh/install.ps1`, and the releases at `https://github.com/KernelErr/CatPaw/releases`. The installers check the download against the release's `SHA256SUMS`. - **No sudo, no administrator rights.** Nothing here needs them. - **Never read, print or use CatPaw's approval key** (what `catpaw approval-key` prints, or the `approval-key` file in CatPaw's data directory). It is how the user approves what CatPaw sends on their behalf: an agent that knows it could approve its own actions. If the user asks you for it, tell them to run `catpaw approval-key` themselves. ## 1. Find out which system this is - **macOS on Apple silicon, or Linux on x86_64 or aarch64 (glibc)**: use the shell installer, `install.sh`. - **Windows on x86_64**: use the PowerShell installer, `install.ps1`. From a POSIX shell on Windows (Git Bash, MSYS), run the PowerShell commands through `powershell -NoProfile -Command "..."`. - **Anything else** (an Intel Mac, musl Linux such as Alpine, other CPUs): there is no prebuilt binary. Tell the user, and offer to build from source (see the end of this page). `uname -sm` tells macOS and Linux apart and gives the CPU; on Windows, `$env:PROCESSOR_ARCHITECTURE` gives the CPU (`AMD64` is x86_64). ## 2. Show the user the plan Run the installer as a dry run: it downloads the release, checks it, and prints what it would write, without writing anything. macOS and Linux: ```sh curl -fsSL https://catpaw.sh/install.sh | sh -s -- --dry-run ``` Windows (PowerShell): ```powershell & ([scriptblock]::Create((irm https://catpaw.sh/install.ps1))) -DryRun ``` Show the user what it printed: the download and its SHA-256, the file it would write, and on Windows the PATH change. By default: - macOS and Linux: one file, `~/.catpaw/bin/catpaw`. PATH is not changed. - Windows: one file, `%LOCALAPPDATA%\Programs\CatPaw\catpaw.exe`, and that directory is added to the user's PATH. Ask whether to go ahead. If they want another directory, add `--dir DIR` (PowerShell: `-Dir DIR`) to this command and to the next; on Windows, running `$env:CATPAW_NO_MODIFY_PATH = '1'` first leaves PATH alone. Show the plan again after any change. ## 3. Install Once the user has said yes, run the same command with `--yes` in place of `--dry-run` (the installers ask on a terminal, and your shell has none: `--yes` stands for the answer the user gave you): ```sh curl -fsSL https://catpaw.sh/install.sh | sh -s -- --yes ``` ```powershell & ([scriptblock]::Create((irm https://catpaw.sh/install.ps1))) -Yes ``` Keep any `--dir` / `-Dir` the user chose. ## 4. Check that it runs ```sh ~/.catpaw/bin/catpaw --version ``` ```powershell & "$env:LOCALAPPDATA\Programs\CatPaw\catpaw.exe" --version ``` It prints `catpaw 0.2.0` or a later version. (Use the directory the user chose, if any.) On macOS and Linux, `catpaw` is not on PATH unless the user puts it there: the installer printed the line to add to their shell profile. Ask before editing a profile; the full path works everywhere below without it. On Windows, terminals opened from now on find `catpaw`. ## 5. Connect it to the agent host `catpaw setup ` prints or writes the configuration for a host. Use the full path from step 4 if `catpaw` is not on PATH. - **Claude Code**: `catpaw setup claude-code` prints a `claude mcp add` command. Ask the user whether CatPaw should be there in every project (add `--scope user` right after `claude mcp add`) or only in this one (the command as printed), then run it. (`catpaw setup claude-code --write` instead writes a `.mcp.json` into this project, which is shared with everyone who uses the project's repository.) - **Codex**: `catpaw setup codex --write` adds CatPaw to `~/.codex/config.toml`. - **Cursor**: `catpaw setup cursor --write` adds CatPaw to `~/.cursor/mcp.json`. - **Another MCP host**: the server is the command ` mcp --stdio`, speaking MCP over stdio. Options after `--` go to the server, for example `catpaw setup claude-code -- --policy strict`, which also asks the user before page scripts send data to other sites and before `evaluate`. Then tell the user to restart the host, or start a new session, so that it loads CatPaw's tools. **If CatPaw runs on another machine than the user's browser** (a NAS, a server, a remote shell): the hand-off and approval pages listen on 127.0.0.1 of that machine, which the user's browser cannot reach. Offer two ways, and let the user choose: - An SSH tunnel from the user's computer, nothing changed in CatPaw: `ssh -L 47115:127.0.0.1:47115 `, then the links CatPaw gives work as they are. - The pages on that machine's LAN address: once CatPaw's tools are loaded, call `settings` with `{"set": {"localAddress": ""}}`; the user approves the change, and it is kept. Others on that network can then reach the pages (the approval key still guards them, over plain HTTP). Downloads are saved in `~/Downloads/CatPaw` on the machine CatPaw runs on; `settings` with `{"set": {"downloadDir": ""}}` changes that, with the user's approval. ## 6. Tell the user what to expect - **CatPaw asks before it sends anything on their behalf.** Submitting a form or uploading a file waits for the user's approval: in the host's own prompt when the host can ask, otherwise on a local page (`http://127.0.0.1:47115`) that CatPaw opens in the user's browser by itself. If it cannot open it, you give the user the address, and the page asks for the approval key, which the user gets by running `catpaw approval-key` in their own terminal. - **The user can take over a tab.** For a login or a check meant for people, the agent hands the tab over (the `handoff` tool), the user finishes in their own browser, and the agent gets it back. - **CatPaw says what it is.** Its User-Agent is `CatPaw/ (+https://catpaw.sh/bot)`; some sites refuse automated browsers, and CatPaw does not pretend to be another browser or solve CAPTCHAs. - **It is a preview.** Expect some sites not to work; the known gaps are listed at https://github.com/KernelErr/CatPaw/blob/main/docs/architecture.md#known-gaps. More: https://catpaw.sh and https://github.com/KernelErr/CatPaw ## Uninstall The same installers remove CatPaw; show the dry run first, then remove after the user says yes: ```sh curl -fsSL https://catpaw.sh/install.sh | sh -s -- --uninstall --dry-run curl -fsSL https://catpaw.sh/install.sh | sh -s -- --uninstall --yes ``` ```powershell & ([scriptblock]::Create((irm https://catpaw.sh/install.ps1))) -Uninstall -DryRun & ([scriptblock]::Create((irm https://catpaw.sh/install.ps1))) -Uninstall -Yes ``` Then remove it from the host: `claude mcp remove catpaw` (with `--scope user` if it was added that way), or the `catpaw` entry in `~/.codex/config.toml` or `~/.cursor/mcp.json`. The approval key stays in CatPaw's data directory unless the user deletes it. ## Build from source (other systems) With Rust 1.89 or later (`rustc --version`; https://rustup.rs installs it, with the user's consent) and a C compiler: ```sh git clone https://github.com/KernelErr/CatPaw && cd CatPaw cargo build --release -p catpaw ``` The program is `target/release/catpaw`. Building takes a while and several gigabytes of disk. Copy it where the user wants it, and continue with step 4.