Open app

Get started

Core concepts

Scripts

The core unit on Reduck is a script: deterministic code that automates a flow on a browser.

Scripts can be discovered through the official scripts, run with MCP or the API, or built with our MCP.

Reduck offers two visibility levels for scripts:

  • Public scripts can be discovered by the Reduck community and may eventually be featured in the official scripts.
  • Private scripts remain yours alone. To share them with your team, assign them to a project and grant your team access to that project.

A script is a line of versions. A draft is edited and tested, then promoted, and a promoted version never changes, so an input that worked last week works today.

Every script is a module. Its default export is a function that receives builtins, page, args, files and ai as one object, and what it returns is the output. A script can be written in JavaScript or in TypeScript. A new script starts in TypeScript, and a new version keeps the language of the version it comes from. Reduck removes the types when the script runs, so only syntax that can be removed is allowed: no enum and no namespace.

export default async ({ page, builtins, args }) => {
    await builtins.goto("https://example.com");
    return { title: await page.title() };
};

The exec_code and exec_trace tools take code in the same form. They refuse code with no default export, before anything runs.

A TypeScript version goes live only when it passes the type check: promote_script_version refuses a draft with errors, and so does create_script without draft. The answer gives each error with its line and column, and says what to write instead. A JavaScript version is not checked.

import type { Scope } from "reduck:sandbox";
import type { Args, Output } from "reduck:contract";

export default async ({ page, builtins, args }: Scope<Args>): Promise<Output> => {
    await builtins.goto(`https://example.com/search?q=${encodeURIComponent(args.q)}`);
    return { title: await page.title() };
};
  • Args and Output are the types of the version’s input and output schemas. A property with a default is always in args.
  • The script runs outside the page. document, window, location and fetch exist only in a page function: the function you give to page.evaluate.
  • These are not allowed: any (use unknown and narrow it), @ts-ignore and the other @ts- comments, eval and new Function, Buffer.
  • A script imports lib:<site> and types from playwright, reduck:sandbox and reduck:contract, and nothing else.
  • Each top-level name of the script serves its default export. A function, a constant, a type or an import that the default export does not use, directly or through other code, is named in a warning. The version still goes live.

Handles

Every script belongs to an owner identified by a handle. When your agent calls list_scripts, passing a handle scopes the results to that owner’s public scripts. Optional owner scope: @user (with @) for a user, or a project handle (without @), e.g. reduck for the official scripts. Omit for a cross-owner search.

Official scripts

The official scripts at reduck.ai/explore

Reduck’s team maintains official scripts for the most common websites (LinkedIn, Airbnb, Instagram, etc.) that you can find at reduck.ai/explore.

Your agent discovers them by calling list_scripts with the handle "reduck".

Projects

You can create your own custom scripts that end up in a project: a private workspace for scripts you build yourself, as opposed to the official scripts that Reduck’s team maintains. A project is also a handle. Pass it to list_scripts to see that project’s scripts.

Projects let you automate flows specific to your own stack that you want to share with your team without exposing them to the broader Reduck community.

  1. Create a project at reduck.ai/projects/create.
  2. Assign scripts to a project: either ask your agent to assign it during creation, or move an existing script afterward from your script list into the project and set its visibility to team-only.

Browser

Reduck runs scripts on two types of browser:

  • Default: your browser. Browser automation happens on your browser through the Reduck extension. The script uses your browser state: the sites where you are signed in, your browser fingerprint for stealth, and so on. It requires your browser to be open. See Stealth and signed-in sessions. Each browser you pair is a device with its own id: pair several, and a run can name which one.
  • Cloud browser. Browser automation happens in Reduck’s cloud, so you can run scripts 24/7 without your browser, and at a larger scale than your machine allows. A run on your own browser spends one run from your plan; a run on a cloud browser also spends cloud browser time, so it costs more. See the pricing page.

What a cloud browser can run today, how the two modes compare, and how to set up each browser: see Supported browsers.

Parallel runs

One execution of one script on one browser is a run. It gets an id, and that id is how you read back the output, the error, or the step-by-step trace with screenshots.

Pass a list of scripts instead of one and they run at the same time, a browser each, up to 20 in a single call. They share nothing, one failing does not stop the others, and you get one outcome per script.

Each device runs 4 scripts at a time by default. Ask for more and the rest queue and start as slots free up: a run sitting in queued is waiting its turn, not failing. Raise or lower the number per device at reduck.ai/devices.

Type to search the documentation.