Browser

The official Browser plugin runs headless Chromium through Playwright. You write a Web page step in Python that opens pages, clicks through them and returns rows, like any other step. When a step fails, the plugin saves a screenshot and the HTML of the page as run artifacts.

Set up the plugin

You do not need Python or a browser on your Mac. The plugin package carries uv, which downloads Python 3.12, Playwright and the Chromium headless shell into the plugin folder.

1. Install Browser in Settings > Plugins. See Using plugins.
2. Confirm the permissions: Network access, Downloads components and Runs programs.
3. Wait while the status shows Installing components and Getting ready. The Mac must be online for these downloads.

If a download fails, the plugin page shows the error and a Set up button to try again. On the plugin page, Downloaded components shows how much space the runtime and browser take, and Reinstall downloads them again.

Write a step

1. In the job editor, add a step and choose Web page as its type.
2. Edit the starter code. It opens a page and returns one row per link.
3. Run the step and check the rows in the result.

The code defines one coroutine, async def run(ctx), and returns a list of flat dicts. Each dict becomes a row. A single dict or None also works.

async def run(ctx):
    page = await ctx.new_page()
    await page.goto("https://example.com")
    rows = []
    for position, link in enumerate(await page.locator("a").all(), start=1):
        rows.append({
            "position": position,
            "text": (await link.inner_text()).strip(),
            "href": await link.get_attribute("href"),
        })
    return rows

Only the Python standard library and Playwright are available.

The code is not a template: ${...} stays as written. Read job variables from ctx.variables instead, and keep URLs and credentials there rather than in the code.

What ctx offers

Member	What it does
await ctx.new_page()	Opens a new tab
ctx.variables	Job variables
ctx.inputs	Results of earlier steps in the run
ctx.settings	Plugin settings for this step
await ctx.pause()	Waits for Pause plus or minus Pause jitter
await ctx.map(items, worker)	Runs async def worker(page, item) for each item on up to Parallel pages tabs, each on a fresh tab, and returns results in item order
ctx.emit(rows)	Sends rows right away, for example one batch per page of a long crawl
ctx.log(message), ctx.progress(message, current, total)	Shows a log line or progress while the step runs
ctx.context, ctx.browser	The run's Playwright browser context and browser

Every run starts in a fresh browser context that closes when the run ends.

Settings

Browser settings live on the plugin page. Change them for one step with Step settings.

• Browser identity: User-Agent mode (Fixed, Random for each run or New one for each page), User-Agent, User-Agent list, Viewport width and Viewport height (1366 × 900 by default), Locale (en-US by default) and Time zone.
• Network: Proxy and Blocked resources (Images, Fonts, Audio and video, Stylesheets).
• Pacing: Pause (1000 ms) and Pause jitter (500 ms) for ctx.pause(), Parallel pages for ctx.map() (1 by default, up to 8), and Navigation timeout for page loads (30 seconds).
• Session: Keep session and Session name.
• Debugging: Screenshot on failure, on by default.

Keep a session

With Keep session on, the plugin saves cookies and local storage after a run and restores them in the next one. Steps with the same Session name share them. A step can sign in once with credentials from job variables, and later runs reuse the session.

To sign in from scratch, open the plugin page and click Clear next to Saved sessions.

When a step fails

With Screenshot on failure on, a failed or timed-out step saves a screenshot and the HTML of the last open page. Both appear under Artifacts in the run history, where Open and Show in Finder open them. See Runs and artifacts.

The step timeout comes from the job step (10 minutes by default for plugin steps). Page loads also stop after Navigation timeout.

The Telegram plugin can send these files to a chat.

Let the assistant write the step

The assistant can explore a site with the plugin's tools: open a page, outline its elements, test selectors, run code in the tab, list network requests and take screenshots. It asks before each call and then writes the step for you. Its browser tabs are separate from step runs, so the step must open and click through every page itself.

The plugin guide tells the assistant not to bypass CAPTCHAs, sign-in walls, bot protection or rate limits. When a page shows one, the step should stop with an error that says what it saw.