Web Scraping & Browser

This page covers the built-in tools that read web pages, extract article text, crawl sites, call hosted scraping APIs, and drive a browser. Use it to pick a tool, configure it, and understand why a URL was refused.

Choosing a Tool

Each credential can be stored as the tool's api_key (or apify_api_token, username, and password) through the dashboard or credential store, or supplied as the environment variable shown. Keep password fields out of inline YAML. crawl4ai, agentql, browserbase, and browser need a working Playwright browser runtime. For a visible, persistent browser that the user can watch or control in MindRoom Chat, see Worker Computer and Agent Chat UI Actions.

Network Access

Tools that fetch pages from MindRoom itself (website, trafilatura, newspaper, crawl4ai, agentql, and the browser host target) reach only public HTTP(S) addresses. Private, loopback, link-local, multicast, reserved, and cloud-metadata targets are refused, and so are redirects, crawled links, and page resources that lead to them. Unless a worker egress proxy is set, DNS answers that change after a URL is checked cannot redirect the connection to an internal service. Only the browser tool can opt into private networks, with allow_private_networks. In Computer mode, the browser tool also opens worker-local loopback previews such as http://localhost:5173 without that option; see Preview a local web app.

Egress Proxy for Browsers

crawl4ai, agentql, the browser host target, and browser_mcp in a Worker Computer send every connection through an operator egress proxy set with http_proxy, https_proxy, or all_proxy, using HTTP CONNECT. In the primary process, http_proxy applies to port 80, https_proxy to every other port, and all_proxy to either when its own variable is unset. The proxy must allow CONNECT to ports 80 and 443, because plain-HTTP pages are tunneled too; Squid's default http_access deny CONNECT !SSL_ports rule refuses plain HTTP. In the primary process it must also allow CONNECT to IP addresses, so proxies that allow only hostnames are unsupported there. Loopback destinations are always dialed directly, and no_proxy is honored only when allow_private_networks is enabled; it never makes a refused destination reachable. A refused tunnel fails that connection without a direct fallback and logs browser_egress_proxy_refused_tunnel. The primary process logs a warning and dials directly when the proxy is SOCKS, has credentials or a path in its URL, or is set through auto_proxy or socks_server. In a worker, every set proxy variable must name the same HTTP(S) proxy, or the browser does not start; hostnames must also resolve in the worker's DNS. That proxy receives hostnames and resolves them itself, so it must block private and metadata addresses and resist DNS rebinding. WebRTC cannot send UDP from these browsers.

No-Key Scrapers

[website]

website exposes read_url(url) and returns JSON page documents from MindRoom's WebsiteReader variant, which drops search UI, navigation, headers, footers, sidebars, hidden content, and modals before choosing the page text. Pages larger than 2 MiB fail, as do pages a server sends compressed.

agents:
  assistant:
    tools:
      - website

[trafilatura]

trafilatura exposes extract_text(), extract_metadata_only(), crawl_website(), html_to_text(), and extract_batch(). extract_batch() returns one JSON payload listing successes and failures. crawl_website() stops with an error when it reaches a refused target, while extract_content=True reports each refused page individually. A server that sends a compressed body fails the download.

agents:
  analyst:
    tools:
      - trafilatura:
          output_format: markdown
          with_metadata: true
          include_links: true

[newspaper]

newspaper exposes read_article(url) and returns JSON with whichever of title, authors, text, and publish date were extracted. It is tuned for article pages, not arbitrary sites, and returns no image fields. Use newspaper in tools:, not newspaper4k.

[crawl4ai]

crawl4ai exposes crawl(url, search_query=None), where url is one URL or a list, and returns readable text for each page from a local headless browser. With search_query, the text is filtered toward that query; without one, use_pruning trims noisy content. Results skip Crawl4AI's cache and are truncated to max_length.

agents:
  researcher:
    tools:
      - crawl4ai:
          max_length: 8000
          use_pruning: true
          wait_until: networkidle

[jina]

jina exposes read_url(url) through Jina Reader and, when enabled, search_query(query). It works without a key for public reads; a key helps with paid plans and rate limits. Returned content is truncated to max_content_length.

Hosted Scraping APIs

[firecrawl]

firecrawl exposes scrape_website(), crawl_website(), map_website(), and search_web(). It requires api_key or FIRECRAWL_API_KEY.

agents:
  research:
    tools:
      - firecrawl:
          enable_crawl: true
          enable_search: true
          limit: 5

[spider]

spider exposes search_web(query, max_results=5), scrape(url), and crawl(url, limit=None), returning Markdown. Search results do not include full page content. It requires SPIDER_API_KEY in the environment even though the dashboard lists it as needing no setup, and it has no api_key field.

[scrapegraph]

scrapegraph turns pages into structured answers from natural-language prompts. smartscraper(url, prompt) extracts data from one page, markdownify() converts a page to Markdown, crawl() applies a prompt and JSON schema across a crawl, searchscraper() searches the web before extracting, and scrape() returns raw HTML. It requires api_key or SGAI_API_KEY. Keep at least one function enabled, or set all: true. The upstream headers option is not supported in config.yaml.

[apify]

apify registers one tool function per configured Apify Actor, with parameters from the Actor's input schema, and returns the Actor's dataset items as JSON. Without actors, it provides no functions. Function names derive from the Actor ID, so check the agent's tool list for the exact name.

agents:
  extractor:
    tools:
      - apify:
          actors: apify/rag-web-browser

[brightdata]

brightdata exposes scrape_as_markdown(), get_screenshot(), search_engine() for Google, Bing, and Yandex, and web_data_feed() for Bright Data's supported source types. get_screenshot() returns the image directly to the model rather than a file path. It requires api_key or BRIGHT_DATA_API_KEY.

[oxylabs]

oxylabs exposes search_google(), get_amazon_product(), search_amazon_products(), and scrape_website(). search_google() returns organic results with title, URL, description, and position. Pass domain_code, such as com or de, to choose the regional Google or Amazon domain. It requires both a username and password.

Browser Tools

[agentql]

agentql exposes scrape_website(url), which extracts generic page text, and custom_scrape_website(url), which runs your agentql_query and returns the extracted values as JSON. Setting agentql_query registers custom_scrape_website() even when enable_custom_scrape_website is false. It opens only HTTP(S) URLs and launches a visible browser window, so it needs a GUI-capable runtime or virtual display. It requires api_key or AGENTQL_API_KEY; AgentQL SDK settings and CLI credential files do not override that key.

agents:
  extractor:
    tools:
      - agentql:
          agentql_query: |
            {
              title
              links[]
            }

[browserbase]

browserbase exposes navigate_to(), screenshot(), get_page_content(), and close_session() against a hosted Browserbase session that it creates automatically. It still needs local Playwright to connect to the remote browser. It requires an API key and project ID. Use it when you need remote navigation, screenshots, and page reads without the full action set of browser.

[browser]

browser exposes one function, browser_control(action=...), for multi-step browser sessions. It can drive two targets:

• target="host" (default) controls MindRoom's own Chromium on the MindRoom host, or in the agent's worker when browser is listed in worker_tools.
• target="desktop" controls the user's own signed-in Chrome or Brave profile through the Matrix Desktop Bridge, which owns extension installation, the local control lease, and the trust model.

Call action="help" or action="actions" to list the actions and act request kinds.

On the host target, snapshot() returns ai or aria format with element refs that later act() and screenshot() calls can use. act() takes request.kind set to click, type, press, hover, drag, select, fill, resize, wait, evaluate, or close. The desktop target returns the browser's native accessibility snapshot and rejects targetId and host-only options such as profile, snapshot format hints, inputRef, and timeoutMs. Desktop-target calls always run in the primary process, so routing browser to a worker isolates only host-target calls. To show the worker browser to the user, see Agent Chat UI Actions.

Screenshots and Files

Screenshots are shown to the model by default; host screenshots are also saved, and saveOnly=True saves without showing. Large images may be resized before the model sees them. Model-visible screenshots can be kept in the agent's session history. On the desktop target, returnAttachment=True with action="screenshot" also returns an att_* handle, valid until the turn ends, that matrix_message can send.

Host screenshots, PDFs, and other artifacts go to output_dir. In the primary process it defaults to browser/ in the agent's state root: <storage>/agents/<agent>/browser for a shared agent, or the requester's private-instance root for a private agent. In a worker it defaults to browser/ in the worker workspace, and a custom output_dir must stay inside that workspace. output_dir must not point at runtime state, and it does not affect the desktop target.

Which files upload may read follows the agent's file_access setting. With the default workspace, upload accepts files in the artifact directory, files in the agent's workspace, and att_* IDs of attachments in the current conversation; use ./ for a workspace file whose name starts with att_. Everything else is refused, including credentials, encryption keys, Matrix state, sessions, and other agents' workspaces; in a worker only the worker workspace is readable. With unrestricted, upload accepts any file its process can read. One browser holds at most 256 MiB of uploaded files until their tabs close, so a larger upload is refused until a tab is closed.

On the host target, open also takes one HTML file in paths instead of targetUrl, read under the same rules as upload, so an agent can check a page it wrote with screenshot, console (which also lists uncaught errors), and act. The file is UTF-8 text of at most 16 MiB. The page cannot load or navigate to other local files, and relative links in it do not resolve; its network requests follow the same checks as any page.

browser_control(action="open", paths=["slides/deck.html"])
browser_control(action="screenshot")

Profiles and Signed-In Sessions

Host-target profiles are named, with mindroom as the default; names starting with a dot are rejected. In the primary process a profile lives at browser-profiles/<profile> under the agent's state root, so every requester of a shared agent shares its signed-in sessions, while different agents never share them. This holds even with worker_scope: user or user_agent unless browser is in worker_tools, which gives each worker scope its own profiles. Use a private agent when requesters need separate browser sessions. Chromium is taken from BROWSER_EXECUTABLE_PATH, chromium, or google-chrome-stable.

Browser Configuration

agents:
  browser_worker:
    tools:
      - browser:
          default_target: desktop
          device_user_id: "@my-laptop:example.org"
          device_id: "ABCDEFGHIJ"
          device_ed25519: "desktop-device-fingerprint"

browser_control(action="start", target="desktop")
browser_control(action="open", target="desktop", targetUrl="https://matrix.org/blog/")
browser_control(action="screenshot", target="desktop", fullPage=True, returnAttachment=True)

[web_browser_tools]

web_browser_tools exposes open_page(url, new_window=False), which opens an http or https URL in a tab or window of the host computer's browser for a person to use. It refuses file: paths, other schemes, and scheme-less strings, and returns no page content, so it is not a scraper. It only works on a host with a desktop browser.

Related Docs

• Tools Overview
• Per-Agent Tool Configuration