Before You Give an AI Agent a Browser, Define the Puppeteer Boundary

Puppeteer is one of the most practical tools you can give an AI coding agent. It lets a Node.js workflow control Chrome or Firefox through a high-level JavaScript API, which makes it useful for browser automation, screenshots, scraping, page checks, and repeatable web tasks.

That power is also the risk.

Once an agent can open a browser, it may touch live web sessions, read page content, follow links, download files, submit forms, or capture screenshots that contain private state. The first question should not be "Can the agent use Puppeteer?" The better question is:

What is the smallest browser task the agent can run while producing evidence and staying inside a clear boundary?

This is the first-use checklist I would apply before loading a Puppeteer-oriented capability into an AI coding host.

1. Separate the Two Install Paths

Puppeteer has two common install paths:

• npm i puppeteer: the full package, including browser download behavior.
• npm i puppeteer-core: the lighter core library, where you provide the browser executable yourself.

That choice matters for agent workflows.

If the agent is only checking a known local page or a CI preview, puppeteer-core plus an explicit executablePath may be easier to reason about. If the agent needs a bundled browser path for a quick isolated smoke test, the full package can be convenient, but it also changes the install surface.

Do not let the agent choose this casually. Ask it to state:

• which package it wants;
• whether browser download is expected;
• where temporary files and browser cache will live;
• whether the run needs network access;
• what command proves the first task worked.

2. Make the First Run Evidence-Oriented

A useful first Puppeteer run should produce a small artifact, not just a confident explanation.

Good first-run evidence can be:

• a screenshot from a local test page;
• a saved HTML excerpt from a controlled URL;
• a list of network requests for a single page;
• a console log capture;
• a short JSON report containing URL, status, title, selector result, and timestamp.

Bad first-run evidence is:

• "I inspected the page and it looks fine";
• "the automation should work";
• "Puppeteer is installed";
• a screenshot from a logged-in personal account;
• a run that requires production credentials before proving the basic path.

For AI coding agents, the rule should be simple: if no artifact is produced, the browser task is not verified yet.

3. Treat Browser Access as a Permission Boundary

The Doramagic Puppeteer boundary card recommends starting with minimal permissions, a temporary directory, and rollbackable configuration. That is the right default.

Before the agent runs Puppeteer, define the boundary in plain language:

• allowed URLs or domains;
• whether login state may be used;
• whether screenshots may be captured;
• whether downloads are allowed;
• whether form submission is allowed;
• where browser data and temporary files may be written;
• what must stop the run immediately.

For example:

Use Puppeteer only against http://localhost:3000.
Do not use existing browser profiles.
Do not submit forms.
Save one screenshot and one JSON report under ./artifacts/browser-smoke/.
If the page redirects outside localhost, stop and report.

This keeps the agent from turning a simple UI check into an open-ended web session.

4. Watch the Real First-Use Pitfalls

The Doramagic Puppeteer pack records source-linked pitfalls around install behavior, browser versions, package alerts, flaky tests, cache behavior, Firefox viewport behavior, and browser binary availability. These should not be exaggerated into "Puppeteer is unsafe" or "Puppeteer is broken." They are check points.

The useful habit is to turn each risk into a verification question:

• Which Node version is being used?
• Is the project installing puppeteer or puppeteer-core?
• Was Chrome downloaded, skipped, or supplied externally?
• Does the browser executable exist where the agent thinks it exists?
• Is the cache directory temporary and disposable?
• Does the smoke test work on the target browser, not just on the agent's assumption?

That is especially important in CI, containers, and remote development environments where browser dependencies differ from a developer laptop.

5. Use GO / HOLD / NO-GO for Agent Runs

For a first Puppeteer capability run, I would use this decision rule:

• GO: the task uses a controlled URL, produces a screenshot or report, avoids existing user profiles, and can be rerun.
• HOLD: the browser opens, but install path, cache path, executable path, or target URL is unclear.
• NO-GO: the agent needs production login state, private data, or external form submission before proving a minimal browser smoke test.

The point is not to make the agent timid. The point is to keep browser automation inspectable.

6. A Safer First Instruction

Instead of asking an AI coding agent to "set up browser automation," start with a smaller instruction:

Using the Puppeteer capability notes, design the smallest safe browser smoke test for this repo.
Use only a local or explicitly approved URL.
Do not use an existing browser profile.
Do not submit forms or use credentials.
Return the planned command, expected artifact, stop conditions, and rollback path before running anything.

That instruction forces the agent to expose the boundary before it touches the browser.

7. What This Helps With

This workflow is useful when you want an AI host to use Puppeteer for screenshots, scraping, browser checks, or UI automation without quietly expanding its permissions.

It does not replace the official Puppeteer documentation. It does not prove production readiness. It does not mean the Puppeteer maintainers endorse this pack.

The useful mental model is:

Puppeteer gives the agent browser hands. Your boundary gives it judgment about where those hands are allowed to go.

Reference: the independent Doramagic Puppeteer project page and manual are here: https://doramagic.ai/en/projects/puppeteer/manual/

Upstream project: https://github.com/puppeteer/puppeteer

Disclosure: this is based on an independent Doramagic capability pack for Puppeteer. It is not affiliated with or endorsed by Puppeteer or Google unless explicitly stated.