REST API and SDKs

Use the REST API for local scripts. The dependency-free SDKs live in sdk/python and sdk/node in the supplied source checkout. They are not advertised here as published pip or npm packages.

Start Swarmtab first. Pass its actual loopback URL and agent token from the owner-only port and token files. Set SWARMTAB_URL and SWARMTAB_AGENT_TOKEN privately in your script environment. Never put the token in arguments, logs or source files. The window token cannot open REST agent sessions.

Python

Python 3.11 or later. Run from sdk/python, or add that folder to your import path:

import os
from swarmtab import Swarmtab

with Swarmtab(os.environ['SWARMTAB_URL'], os.environ['SWARMTAB_AGENT_TOKEN']) as browser:
    browser.open('https://example.com')
    result = browser.read(format='markdown')

Node

Node 20 or later. Run from sdk/node in the supplied checkout:

import { Swarmtab } from './index.mjs';

const browser = new Swarmtab({
  baseUrl: process.env.SWARMTAB_URL,
  token: process.env.SWARMTAB_AGENT_TOKEN
});
try {
  await browser.open('https://example.com');
  const result = await browser.read({ format: 'markdown' });
} finally {
  await browser.close();
}

Both SDKs offer open, read, click, type, site and screenshot. Use call(tool, arguments) for any of the twenty tools. The result retains MCP content and structuredContent; tool errors retain the result in SwarmtabError.

Routes and sessions

Send POST /v1/<tool> with the tool’s JSON arguments and Authorization: Bearer using the agent token. The first call creates a session. Keep its Swarmtab-Session-Id response header and send it on later requests. DELETE /v1/session closes it.

Sessions use a configurable 600-second reconnect grace and a 6-hour maximum lifetime by default. Server restart also ends them. Limits are 32 sessions, 20 starts per minute and eight pending calls per session. Requests and responses are capped at 4 MiB. SDK calls are serialized and actions are never retried. A lost answer may mean the action happened; inspect before retrying. Redirects are refused. Python also refuses inherited proxy settings.

REST obeys the same license, permissions, leases and human-control gates as MCP. It has no model sampling channel. Use read with format: "json" and schema, omitting token_budget, for deterministic extraction without a model. CSS fields also work. Check complete, missing and truncated before using schema results. Summaries still need a sampling-capable MCP client and a token budget.

The window API is separate

/api and /ws are for the human window, using its separate window token. The agent token opens /mcp and the agent REST routes; it cannot change human-only settings through the window API. Do not use window credentials in an agent script.