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.

Install the Node Mantis SDK into a project — or, to use it purely from the terminal, install the CLI globally (the same package carries both, plus the compiled agent runtime for your platform). 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.10
npx playwright install chrome

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

npm install -g node-mantis@0.1.0-alpha.10

# or via Homebrew (macOS and Linux)
brew install node-mantis/tap/nodemantis

nodemantis install-browser --browser chrome

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.

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

$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.

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. From the terminal, the CLI runs the same goal with no code at all, narrating each step on stderr while it works.

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();
}

from nodemantis import NodeMantis

with NodeMantis.start(start_url="https://example.com") as mantis:
    result = mantis.run("Open the More information link.", max_iterations=5)
    print(result.ok, result.reason)

nodemantis run "Open the More information link." \
  --url https://example.com --max-iterations 5

See the API reference for every option and return shape, the CLI reference for every command, flag, and the JSON output contract, or continue to examples for complete workflows.