outcrawlai/scout

Scout by Outcrawl – An Open‑Source Browser‑Agent

What it is

• A TypeScript/Node library (@outcrawl/scout) that lets you describe a web‑task in plain English. Scout then drives a real Chrome/Chromium browser, clicks, types, scrolls and extracts information, returning the answer (or a partial result) together with a replay link.
• The core idea is a hands‑on AI model that decides each browser action, optionally assisted by a planning model (brain) and a vision model (eyes). The library itself contains no model; you plug in any service that implements the standard chat‑completion API (OpenAI, Anthropic, local LLM, etc.).

How to get started

1. Install the npm package (Node 22+).

   npm i @outcrawl/scout
   

2. Set environment variables for:
   • OUTCRAWL_API_KEY – a free Outcrawl browser key (1 000 credits/month).
   • SCOUT_BASE_URL, SCOUT_API_KEY, SCOUT_HANDS_MODEL – point to the LLM you want to use for the hands job.
3. Write a short script that creates a Scout instance and calls run('your natural‑language task').
   The example in the README shows a one‑liner that fetches the top three Hacker News stories.

Running locations

• Outcrawl cloud (recommended): the library connects to a remote browser that appears to come from a residential IP, solves captchas, and records every step. You only need the API key; no local browser install.
• Local machine: install Playwright’s Chromium (npm i playwright-core && npx playwright install chromium) and set browser: { launch: {} }. You can also attach to any existing Chrome via CDP.

What you can ask it to do

• Research (e.g., scrape top news items).
• Fill out forms (e.g., order a pizza and report the order confirmation).
• Compare items across pages.
• Log in to a site and read a protected message.
• Anything you would normally do manually in a browser, expressed as a natural‑language instruction.

Model architecture

Job	Role
hands	Reads the page and decides the next low‑level action (click, type, scroll). Needs a fast model because it runs on every step.
brain	High‑level planner that sketches the overall sequence of pages. Optional but useful for long, multi‑page tasks.
eyes	Vision model that can interpret screenshots when visual cues are required.
extract	Structured extraction model; if omitted, hands falls back to plain text extraction.

You supply a separate model configuration for each job, all using the same chat‑completion API format.

Output A result object contains:

• status (completed, partial, capped, failed).
• data – the answer, optionally shaped by a JSON Schema you provide.
• error – description of what could not be obtained.
• steps – a timeline of every browser interaction.
• costUsd – model‑call spend (when known).
• replayUrl – a link to a step‑by‑step video of the run (cloud only).

Performance claim Outcrawl’s cloud version reached 92.5 % success on the Browser Use 80‑site benchmark (Oct 2026), beating the next best open‑source solution (81.4 %).

Repository layout

• packages/scout – public API (new Scout(...).run).
• packages/runtime – the agent loop that repeatedly observes the page, calls the model, and executes actions.
• packages/model – prompt templates, job splitting, and provider‑agnostic client code.
• packages/scout-cdp – thin wrapper around Chrome DevTools Protocol for navigation and interaction.
• packages/agenthands – local‑only input‑planning utilities (MIT‑licensed).

Who it’s for

• Developers who need a programmable web‑agent without building a browser‑automation stack from scratch.
• Researchers experimenting with LLM‑driven agents that require real‑browser fidelity (captchas, dynamic JS, etc.).
• Teams that want to run tasks on a managed cloud browser to avoid anti‑bot blocks.

License Apache‑2.0 for the main code; the agenthands sub‑package is MIT.

---

All information above is taken directly from the repository’s README; no additional features have been inferred.