Product stage: Alpha
Get started

Examples

Each example describes one complete task. Select TypeScript, Python, or CLI in any panel to update every example on the page. When the selected client does not support a workflow, the panel states that boundary explicitly.

Install and configure a customer environment

Installs the registry package, prepares branded Google Chrome, and makes the API key available to the client through the process environment.

npm install node-mantis@0.1.0-alpha.10
npx playwright install chrome
export NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>"

Validate a customer installation

Checks a customer environment before a workload starts. TypeScript uses the SDK preflight. The published Python package uses its installation smoke, which checks credentials, hosted usage, platform compatibility, Chrome, and a bundled fixture.

import { NodeMantis } from "node-mantis";

const report = await NodeMantis.preflight({
  checkBrowser: true,
  timeoutMs: 5000,
});

if (!report.ok) {
  console.error(report.checks);
  process.exit(1);
}

Run a goal and read the agent's summary

Launches a managed browser and lets the agent click and navigate through as many steps as the goal needs. With no schema, the result's reasonis the agent's own plain-language summary of what it found.

import { NodeMantis } from "node-mantis";

const mantis = await NodeMantis.start();

try {
  const result = await mantis.run(
    "Go to books.toscrape.com, open the Travel category, open the first book, and report its title and price.",
  );
  console.log(result.reason);
  // → The first Travel book is "It's Only the Himalayas", priced £45.17.
} finally {
  await mantis.close();
}

Run the same goal with a schema for structured data

Pass a resultSchema and the run returns a structured object in value instead of prose — the same multi-step clicking, now with machine-readable output.

import { z } from "zod";
import { NodeMantis } from "node-mantis";

const mantis = await NodeMantis.start();

try {
  const result = await mantis.run(
    "Go to books.toscrape.com, open the Travel category, open the first book, and report its title and price.",
    { resultSchema: z.object({ title: z.string(), price: z.string() }) },
  );
  console.log(result.value);
  // → { title: "It's Only the Himalayas", price: "£45.17" }
} finally {
  await mantis.close();
}

Drive the browser step by step, then retrieve

To control the path yourself, navigate with go, take each action with step, then read the final page into a typed result with retrieve.

import { z } from "zod";
import { NodeMantis } from "node-mantis";

const mantis = await NodeMantis.start();

try {
  await mantis.go("https://books.toscrape.com");
  await mantis.step("Open the Travel category.");
  await mantis.step("Open the first book.");

  const result = await mantis.retrieve("the book's title and price", {
    schema: z.object({ title: z.string(), price: z.string() }),
  });
  console.log(result.data);
  // → { title: "It's Only the Himalayas", price: "£45.17" }
} finally {
  await mantis.close();
}

Attach to an existing Playwright page

Adds Node Mantis to browser infrastructure your application already owns. Closing the Node Mantis session does not close an attached page or browser; the application remains responsible for that lifecycle.

import { chromium } from "playwright";
import { NodeMantis } from "node-mantis";

const browser = await chromium.launch({ channel: "chrome", headless: true });
const page = await browser.newPage();
await page.goto("https://example.com");

const mantis = await NodeMantis.attach(page);

try {
  const result = await mantis.check("Is this the Example Domain page?");
  console.log(result.ok, result.reason);
} finally {
  await mantis.close();
  await browser.close();
}