Purroxy Documentation

Record what you do on any website. Securely automate it forever.

Overview

Purroxy is a desktop application that gives Claude secure access to websites behind your login. You walk through a site in Purroxy's built-in browser, and every action you take is recorded as a capability. At runtime, Purroxy replays those exact steps on your behalf using a headless browser. Your credentials never leave your machine and are never sent to any AI.

Purroxy connects to Claude Desktop via the Model Context Protocol (MCP). Once connected, your saved capabilities appear as tools that Claude can call, just like any other MCP tool. You ask Claude in natural language, and Purroxy executes the browser automation locally.

The lifecycle at a glance

1. Log in to a website Open a URL in Purroxy's built-in browser and log in normally. Purroxy captures your session cookies — never your password.
2. Record a capability Walk through the actions you want automated. Purroxy's AI guide watches and helps you refine the recording into a reusable capability with parameters.
3. Connect to Claude Desktop One click in Settings. Purroxy registers as an MCP server and your capabilities become tools Claude can call.
4. Ask Claude In Claude Desktop, ask for what you need in natural language. Claude calls the right capability, Purroxy replays it in a headless browser, and the results come back to the conversation.

Installation

Download the latest release for your platform:

Download Purroxy

Available for macOS, Windows, and Linux.

• macOS: Open the .dmg and drag Purroxy to Applications. On first launch, right-click and choose Open if macOS blocks it.
• Windows: Run the .exe installer. If SmartScreen warns you, click "More info" then "Run anyway".
• Linux: Run the .AppImage directly, or extract it. You may need to chmod +x the file first.

Purroxy runs in the background with a system tray icon. Closing the window minimizes it to the tray — the app stays running so Claude can reach it.

Getting Started

Create an account

When available: Open Purroxy and go to Settings > Account. Click Sign Up and enter your email and a password (8+ characters). You'll receive a verification email — click the link to confirm.

Add your Anthropic API key

Purroxy uses the Anthropic API for its AI guide — the assistant that helps you build capabilities. Go to Settings > Anthropic API Key and paste your key (starts with sk-ant-).

You can get an API key from console.anthropic.com. The key is stored locally on your machine and only used for AI guide features inside Purroxy.

Connect to Claude Desktop

This is the step that lets Claude call your capabilities.

1. Make sure Claude Desktop is installed.
2. In Purroxy, go to Settings > Claude Desktop.
3. Click Connect to Claude Desktop.
4. Restart Claude Desktop to pick up the new MCP server.

That's it. Purroxy writes a configuration entry to Claude Desktop's config file that points to Purroxy's MCP server. As long as Purroxy is running, Claude can discover and execute your capabilities.

Building Capabilities

What is a capability?

A capability is a recorded sequence of browser actions — clicks, typed text, navigation — that Purroxy can replay automatically. Each capability belongs to a site profile (which holds your encrypted session for that website) and can have parameters for variable inputs and extraction rules to pull structured data from the result page.

For example, a "Search emails" capability for Yahoo Mail might:

• Navigate to the inbox
• Click the search box
• Type a search term (parameter: search_term)
• Press Enter
• Extract the list of matching email subjects (extraction rule)

When Claude calls this capability with {"search_term": "tax documents"}, Purroxy opens a headless browser with your saved Yahoo session, replays those steps, and returns the extracted results.

Step 1: Log in to a website

On the Home screen, enter the URL of the website you want to automate and click Go. Purroxy opens the site in its built-in browser alongside an AI guide panel.

If the site requires authentication, the AI guide will detect the login page and prompt you to log in. Log in as you normally would — enter your username and password directly into the real website. Purroxy never intercepts or stores your password. It only captures the resulting session cookies after you've logged in.

Once you're logged in, the AI guide will show a "Done logging in" button. Click it to save your session. Your session cookies are encrypted using your operating system's keychain and stored locally.

Step 2: Record your actions

After saving your session, the AI guide will analyze the page and suggest capabilities you could build. Choose one, or describe what you'd like to do in the chat. When you're ready, the guide will show a "Start recording" button.

When recording starts:

• The window expands so the embedded browser shows the full desktop layout (this ensures recording matches what replay will see).
• A red indicator shows that recording is active.
• Every click, typed text, navigation, and selection you make is captured as an action.
• Purroxy records multiple selector strategies for each element (CSS, data-testid, ARIA role, structural path) to make replay resilient to minor page changes.

Walk through the exact steps you want automated. When you're done, the AI guide will show a "Stop recording" button. Click it to finish.

Step 3: Define parameters

After recording, the AI guide analyzes your actions and identifies which values should be parameters — inputs that change each time the capability runs.

For example, if you typed "tax documents" into a search box, the AI will suggest making that a parameter called search_term. At runtime, Claude (or you) can pass any value for that parameter.

The AI also suggests extraction rules — CSS selectors that pull structured data from the final page. This lets the capability return specific fields (like a list of email subjects or an account balance) rather than raw page content.

Step 4: Save the capability

When the AI guide shows the "Save capability" button, click it. Purroxy will:

1. Generate a structured definition from your recording and chat context.
2. Name and describe the capability based on what you did.
3. Annotate each action with an intent (used for self-healing if selectors break).
4. Save everything locally.

The capability immediately becomes available to Claude Desktop. If Claude is already running, it will discover the new capability within a few seconds (Purroxy's MCP server polls for changes every 5 seconds).

After saving, the AI guide will suggest how to use the capability with Claude — for example: "Search my Yahoo Mail for tax documents."

Testing capabilities

Go to the Library view to see all your saved capabilities organized by site. Each capability shows:

• Number of recorded actions and parameters
• Health status: healthy, degraded (some recent failures), or broken (consecutive failures)
• Last run date

You can test any capability two ways:

Test results show whether the run succeeded, any extracted data, execution time, a screenshot of the final page, and a detailed execution log.

Using Capabilities with Claude

Asking Claude

Once Purroxy is connected and running, your capabilities appear as tools in Claude Desktop. You don't need to use any special syntax — just ask naturally:

• "Search my Yahoo Mail for messages about tax documents."
• "Check my bank balance."
• "Look up plate number ABC-1234 on the DMV portal."

Claude will match your request to the right capability, fill in the parameters from your message, and call Purroxy to execute it. The results appear directly in the conversation.

You can also ask Claude to list available capabilities: "What Purroxy capabilities do I have?"

How execution works

When Claude calls a capability, here's what happens behind the scenes:

1. Claude sends the request via MCP Claude Desktop calls Purroxy's MCP server with the capability name and parameters.
2. Purroxy decrypts your session The MCP server sends the request to the Purroxy desktop app's local API. Purroxy retrieves the site profile and decrypts your saved session cookies using the OS keychain.
3. Headless browser launches Purroxy launches a headless Chromium browser (via Playwright), injects your session cookies, and navigates to the starting page.
4. Actions are replayed Each recorded action is replayed in sequence: clicks, typing (with parameter values substituted), navigation, waiting for elements to appear. If the capability uses vault values, those are injected directly into form fields.
5. Data is extracted and scrubbed Extraction rules pull structured data from the final page. Any vault values present in the page content are scrubbed before Claude sees them. The scrubbed results are sent back to the conversation.

Self-healing

Websites change their HTML structure over time. When a recorded selector no longer matches an element on the page, Purroxy doesn't just fail — it attempts to heal the selector automatically.

Purroxy sends the current page DOM and the original action's intent to Claude, which identifies the correct element in the updated layout. If healing succeeds, the capability continues running. Health status in the Library tracks how reliably each capability runs over time.

Features

Library

The Library is your dashboard for managing site profiles and capabilities. From here you can:

• View all sites and their capabilities, organized by hostname.
• Test capabilities (headless or visible).
• Rename capabilities.
• Monitor health status.
• Delete capabilities or entire site profiles.
• Navigate back to the Builder to create new capabilities for an existing site.

Vault

The Vault is encrypted storage for sensitive data that Purroxy types into form fields on your behalf — credit card numbers, social security numbers, account IDs, or anything you don't want Claude to see.

How the vault works:

• Add key-value pairs in the Vault view (e.g., credit_card = 4111...).
• Values are encrypted using your OS keychain and stored locally.
• During recording, if you type a vault value into a form field, Purroxy marks that action as vault-sourced.
• At runtime, vault values are injected directly into the browser — they are never sent to Claude.
• After execution, vault values are scrubbed from page content before results are returned to Claude.

You can peek at stored values (partially masked) or delete them from the Vault view.

App lock

If other people have access to your computer, enable App Lock in Settings. Set a 4+ digit PIN, and Purroxy will lock itself after a period of inactivity (configurable: 1, 5, 15, or 30 minutes).

When locked, all capability execution is blocked — even from Claude Desktop. The MCP server returns an error telling the user to unlock Purroxy. This prevents someone else from using your Claude Desktop session to trigger automations on your accounts.

Community library

When available: The Community view will let you share capabilities you've built and install capabilities shared by others.

• Install: Browse or search for community capabilities. Click Install to add one to your Library. You'll still need to log in to the target site yourself — community capabilities include the automation steps but not anyone's credentials.
• Publish: Submit one of your capabilities for review. Purroxy creates a GitHub pull request. Once approved, the capability appears in the community library for everyone.

Security

Security model

Purroxy's security is structural, not policy-based. Rather than telling AI "don't leak credentials," Purroxy removes sensitive data from the pipeline before AI ever sees it.

Verifying downloads

Every Purroxy release binary is signed with GitHub artifact attestations. This lets you cryptographically verify that the file you downloaded was built directly from this repository's source code by GitHub Actions — not tampered with in transit or by a third party.

gh attestation verify Purroxy-*.dmg --owner KuvopLLC

The npm package is published with provenance, which you can verify with npm audit signatures.

Troubleshooting

Common issues

Claude says "Purroxy is not running"

The Purroxy desktop app must be running for Claude to use it. Check:

• Is Purroxy open? Look for the tray icon. Closing the window minimizes to tray — it should still be running.
• If you just installed Purroxy and connected it, restart Claude Desktop. Claude only discovers new MCP servers at launch.

Capability fails or returns wrong data

• Session expired: If the website logged you out, re-log in through Purroxy's Builder. Navigate to the site, log in, and save the session again.
• Page layout changed: Purroxy will attempt self-healing, but if the site changed significantly, you may need to re-record the capability. Go to Library, delete the broken one, and record a fresh version.
• Test with the Eye button: In the Library, use the visible test (Eye icon) to watch the browser replay and see where it gets stuck.

AI guide isn't working

The AI guide requires an Anthropic API key. Go to Settings > Anthropic API Key and make sure you have a valid key entered. The key is used to call the Claude API for page analysis and capability generation.

Claude Desktop doesn't show Purroxy tools

1. Open Purroxy Settings > Claude Desktop and verify it shows "Connected."
2. Restart Claude Desktop.
3. In Claude Desktop, start a new conversation and ask "What Purroxy tools are available?"
4. If it still doesn't work, disconnect and reconnect in Purroxy Settings, then restart Claude Desktop again.

App is locked and I forgot my PIN

There is no PIN recovery. You'll need to reset the app data. On macOS, delete the Purroxy data folder at ~/Library/Application Support/purroxy. On Windows, it's in %APPDATA%/purroxy. This will erase all saved sessions, capabilities, and vault entries.

Getting help

If you're stuck or found a bug:

• Open a GitHub issue — describe what you expected, what happened, and your platform (macOS/Windows/Linux). Screenshots and execution logs (available in Library test results) help a lot.
• Browse the source — Purroxy is open source (Apache 2.0). PRs welcome.

Development

Purroxy is open source. To run it locally:

git clone https://github.com/KuvopLLC/purroxy2.git
cd purroxy2
npm install
npm run dev        # Vite dev server + Electron
npm test           # Run tests
npm run package    # Build distributable

For the backend (Cloudflare Worker):

cd backend
npm install
npm run dev        # Local dev server
npm test           # Run tests

The project uses React + TypeScript for the frontend, Electron for the desktop shell, Playwright for browser automation, and the MCP SDK for Claude Desktop integration.

Licensed under Apache 2.0. Contributions are welcome — check the issues for good places to start.