Puppet Documentation

The programmable browser runtime for AI agents.
5 min read
Updated

Puppet is the programmable browser runtime for AI agents.

It allows your AI assistant to write browser automation once and reuse it as tools. These tools run inside a secure browser sandbox and can be called through the Model Context Protocol (MCP).

Instead of repeatedly generating fragile browser scripts during conversations, agents install persistent automation tools that reliably perform web tasks.

Puppet runs locally on your machine and works with assistants such as Claude Desktop, Cursor, and other MCP-compatible clients.

With Puppet, AI agents can:

  • interact with real websites
  • understand pages using compressed DOM representations
  • automate browser workflows
  • extract structured data
  • reuse automation tools across tasks

The result is fewer tokens, faster reasoning, and more reliable browser automation.

Core Concepts

Puppet is built around three core ideas. Understanding these concepts will help you understand how AI agents automate the web.

Programmable Browser

Puppet turns the browser into a programmable environment for AI agents. Agents can control a real browser to:

  • navigate websites
  • click buttons and links
  • fill forms
  • scroll pages
  • extract information

This allows AI assistants to interact with the web exactly as a user would. Unlike traditional scraping tools, Puppet works with dynamic websites and modern web apps.

Agent Page Understanding

Web pages are complex. A typical page contains thousands of DOM nodes, scripts, and styling information that are irrelevant for automation. Puppet helps AI agents understand pages efficiently.

DOM Compression

Puppet provides DOM compression for agents. Instead of exposing the full DOM tree, Puppet generates a compressed representation of the page that keeps only useful information.

The compressed representation preserves:

  • page structure
  • visible text
  • layout relationships
  • interactive elements

Unnecessary information is removed, including:

  • styling
  • scripts
  • deeply nested markup
  • irrelevant attributes

This dramatically reduces token usage while preserving the information agents need.

Interactive Elements

The compressed page representation highlights elements that agents can interact with, including:

  • buttons
  • links
  • form inputs
  • navigation controls

This makes it easier for agents to decide what actions they can perform on a page.

Faster Reasoning

Because the page representation is smaller and cleaner, agents can:

  • understand pages faster
  • identify target elements more reliably
  • generate more accurate browser actions

This leads to more reliable automation.

Reusable Automation Tools

Puppet allows agents to convert browser scripts into reusable tools. Instead of generating automation logic every time, the assistant installs a tool once and calls it whenever needed.

Example tools might:

  • scrape product listings
  • export dashboard reports
  • submit forms
  • monitor page changes

Reusable tools reduce token usage and make automation consistent across tasks.

How Puppet Works

The typical workflow looks like this:

AI Assistant
      ↓
Installs Browser Tool
      ↓
Puppet Browser Runtime
      ↓
Real Website
  1. The assistant writes a tool for a browser task
  2. The tool is installed into Puppet
  3. The assistant calls the tool when needed

This architecture makes browser automation predictable and repeatable.

Quick Start

Getting started takes only a few minutes.

Step 1 — Install Puppet

Download the desktop application for your platform.

Download Puppet

Step 2 — Connect Your Assistant

Puppet communicates with AI assistants through Model Context Protocol (MCP). Add the Puppet MCP server to your assistant configuration.

Example configuration for Claude Desktop:

{
  "mcpServers": {
    "puppet": {
      "command": "PASTE_COMMAND_PATH"
    }
  }
}

Once connected, your assistant can install and run Puppet tools.

Step 3 — Create Your First Tool

Ask your assistant to create a browser automation tool.

Example prompt:

Using Puppet, create a tool that opens a webpage and returns the page title.

Your assistant will:

  1. generate the tool
  2. install it
  3. execute it through MCP

After installation, the tool becomes reusable.

Tool Capabilities

Puppet tools allow AI agents to automate complex browser tasks.

Real Browser Automation

Tools can interact with websites using a real browser environment. Agents can:

  • navigate pages
  • click buttons
  • fill forms
  • scroll and wait for dynamic content
  • extract page data

This works even on modern JavaScript-heavy websites.

Structured Data Extraction

Tools can return structured outputs such as:

  • tables
  • metadata
  • product information
  • extracted content

Structured results allow assistants to reason about data more effectively.

File Processing

Tools can process uploaded files such as:

  • PDFs
  • images
  • documents

This allows workflows that combine web interaction and document analysis.

Safety Model

Puppet is designed so AI-generated tools can run safely on your computer.

Local Execution

All automation runs locally on your machine. Scripts are never executed on remote servers.

Browser Sandbox Isolation

Tools run inside an isolated browser sandbox. Scripts cannot access:

  • local files
  • system resources
  • other applications

This keeps your system protected while allowing agents to automate the web.

Permission-Based Access

Each tool declares the capabilities it requires. Examples include:

  • network access
  • allowed websites
  • downloads

Tools cannot access resources unless they are explicitly allowed.

Execution Guardrails

Puppet includes safeguards to ensure predictable behavior:

  • execution time limits
  • resource limits
  • domain allowlists
  • controlled downloads
  • task history

These guardrails make it safe to run automation tools created by AI assistants.

Automation & Scheduling

Puppet supports scheduled automation. Tools can run automatically using cron schedules.

Common use cases include:

  • daily reports
  • website monitoring
  • periodic data collection
  • automated workflows

Example schedules:

  • 0 9 * * * → every morning at 9:00
  • 0 0 * * 0 → every Sunday

MCP Integration

Puppet exposes all installed tools through Model Context Protocol (MCP). This allows assistants to:

  • list available tools
  • install new tools
  • execute tools
  • retrieve results
  • cancel running tasks

Puppet works with any MCP-compatible client. Examples include:

  • Claude Desktop
  • Cursor
  • custom agent frameworks

Support & Resources