Quickstart

Before you begin, you need a Node Mantis account, an API key, and Google Chrome installed. Each link explains how to create or install that prerequisite.

1. Install the SDK

Install the Node Mantis SDK, then install the browser it will control. Installing the package does not download a browser for you.

npm install node-mantis@0.1.0-alpha.6
npx playwright install chrome

python -m pip install "node-mantis[browser]==0.1.0a1"
python -m nodemantis install-browser --browser chrome

2. Make the API key available

Run the command for your shell in a terminal before starting your application from that same terminal. It creates an environment variable for the current shell session and programs launched by it. Closing the terminal removes the variable.

macOS and Linux

export NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>"

Windows PowerShell

$env:NODEMANTIS_API_KEY = "sk_live_<copy-from-dashboard>"

Replace sk_live_<copy-from-dashboard> with the complete secret copied from the dashboard. Anyone who obtains this key can make authenticated requests against your account and consume its usage balance, so do not commit it to source control, place it in browser-side code, paste it into logs, or include it in a built application.

3. Run a browser goal

Start a managed local Chrome session, give the agent a goal, inspect the result, and always close the session. start owns the managed context; use attach when your application already owns a Playwright page.

import { NodeMantis } from "node-mantis";

const mantis = await NodeMantis.start({
  startUrl: "https://example.com",
});

try {
  const result = await mantis.run("Open the More information link.", {
    maxIterations: 5,
  });
  console.log(result.ok, result.reason, mantis.page.url());
} finally {
  await mantis.close();
}

See the API reference for every option and return shape, or continue to examples for complete workflows.