How it works

The agent runs an iterative loop. Each turn perceives the page, asks the service for the next action, and executes it locally.

The loop

Perceive — locally extract the actionable elements and a screenshot of the current page.
Decide — send that context to the service; it returns the next tool call (click, type, scroll, navigate, …).
Act — your client executes the action against the real browser, then loops.

What runs where

Browser control, page capture, cookies, session storage, and action execution run locally. The service receives task instructions, selected page and DOM context, screenshots, action history, and model inputs and outputs as needed to return a decision or retrieval result. Browser cookies and session storage are not ordinarily sent, but transmitted page context can still contain sensitive information.

The hosted layer authenticates your API key, runs the models, and records usage. Native browser and SDK behavior lives in a versioned local client; hosted decision logic can improve independently.

Choose the operation

These operations are available now in the TypeScript SDK.

run handles a multi-step goal. step handles a bounded instruction with an action limit.
retrieve performs one schema-guided capture of the current live DOM. It does not click, search, paginate, or navigate. Use retrieval-enabled run or step when interaction is required.
extract is the compatibility current-page extraction API, and check evaluates a condition against visible page text.

Sessions and concurrency

Node Mantis operations on one session are serialized in arrival order. Direct access through mantis.page bypasses that queue. A session stays bound to its original page, so your application must own popup and multi-page coordination.

Coming with the native runtime, a session started with navigationOnly: true keeps agent perception out of the page. It supports go, direct read-only inspection, and close; agent, retrieval, extraction, and check methods reject on that session.

Packages

node-mantis on npm: TypeScript SDK for starting or attaching to a Playwright page, running agent goals, bounded steps, checks, and grounded retrieval.
node-mantis on PyPI: Python tools for configuring credentials, checking platform compatibility and the packaged runtime, installing Chrome or Chromium, running diagnostics, and validating an installation with the smoke tool.