Firecrawl Gives Mastra Agents a Hosted Browser for Logged-in Pages

A browser as one field on the agent

Firecrawl argues that most writing about agents and the web assumes the page is public. Its example of what falls outside that is the vendor portal an ops team logs into every morning, or a report that only exists after a date range is picked and Export is clicked. Opening the inventory page of Swag Labs, the Sauce Labs demo store, without logging in returns an error: "You can only access '/inventory.html' when you are logged in."

The new FirecrawlBrowser class attaches to a Mastra agent through a browser field, the same way tools and memory are attached. It extends AgentBrowser, so the agent gets the 16 browser tools that AgentBrowser exposes by default, including browser_goto, browser_snapshot, browser_click and browser_type. The difference, according to Firecrawl, is where the page runs: Mastra asks the Firecrawl API for a session and talks to it over CDP.

Firecrawl's example agent is configured with maxSteps set to 40. Mastra stops an agent after five steps by default, and Firecrawl says a login-to-checkout run takes around twenty-five, because every action gets its own snapshot.

How the agent reads and operates a page

Instead of raw HTML, the model receives a snapshot of the page's interactive elements, each with a ref such as @e1. On the demo login page the snapshot contains a username textbox, a password textbox and a Login button. The agent types and clicks using those refs, then takes a new snapshot.

Refs only hold within a snapshot, not across navigations. Firecrawl notes that the same login page can assign different refs, for example when a "Dismiss error" button appears and pushes Login from @e3 to @e4. For that reason the instructions tell the model never to guess a ref from a previous page.

Default snapshots list interactive elements only. To read text such as an order confirmation, the model passes interactiveOnly: false. In Firecrawl's demo the agent logged in, added the Sauce Labs Backpack to the cart, checked out and returned the confirmation line, with no hand-written selectors or page-specific code.

Sessions, threads and profiles

FirecrawlBrowser defaults to scope: 'thread'. The first browser call in a Mastra thread creates a Firecrawl session, later calls reuse it while it is alive, and the remote session is deleted when the thread's browser closes. Two users on different thread ids get isolated browsers and separate logins. Skipping the thread id means all callers share one default session. Passing scope: 'shared' creates one session deliberately shared by everything.

Sessions expire. Firecrawl closes one after ttl seconds of total lifetime (default 600, max 3600) or activityTtl seconds idle (default 300). A thread returning later starts with no cookies.

To stay logged in between runs, Firecrawl offers named profiles under the firecrawl key. With saveChanges: true, cookies and login state are written back when the session closes, so the next session starts signed in. Firecrawl lists two caveats:

• The nested firecrawl.profile is stored on Firecrawl's side. The top-level profile comes from AgentBrowser and points to a local Playwright user-data directory.
• Only one session can save to a profile at a time. A second session opening it with saveChanges: true is refused with a 409.

The recommended pattern is to log in once with saveChanges: true, then run normal traffic with saveChanges: false. One profile equals one login, so portals with per-user accounts need one profile per user, for example portal-${userId}.

What it means for developers

Firecrawl says profiles also answer the credentials question. A person or setup script types the password once into the session that saves the profile, and the agent only opens the profile. According to Firecrawl, nothing sensitive reaches the model, the traces or memory.

The provider was built by the Firecrawl team and lives in the Mastra monorepo. Setup involves installing @mastra/core, @mastra/memory, @mastra/libsql, @mastra/browser-firecrawl and [email protected], then setting FIRECRAWL_API_KEY plus a model provider key such as OPENAI_API_KEY. Memory needs a storage provider on the Mastra instance, which the create-mastra scaffold already includes.

For teams building agents that must work inside authenticated tools, the package removes the need to run and maintain a local browser while keeping the same tool interface.