Node SDK

npm install @boxline/sdk playwright-core

export BOXLINE_API_KEY="your-api-key"export BOXLINE_API_URL="https://api.boxline.dev"

import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URL// Or set the options yourself.const custom = new Boxline({  apiKey: process.env.BOXLINE_API_KEY,  baseUrl: "https://api.boxline.dev",  maxRetries: 3,  timeoutMs: 60_000,});

import { Boxline } from "@boxline/sdk";import { chromium } from "playwright-core";const bx = new Boxline();const session = await bx.sessions.create({ timeout: 300 });try {  // A signed URL: treat it like a password.  const browser = await chromium.connectOverCDP(session.connectUrl!);  const page = browser.contexts()[0]!.pages()[0]!;  await page.goto("https://example.com");  console.log(await page.title());  // The actions API drives the same browser without Playwright.  const { title, content } = await session.content("markdown");  console.log(title, content.length);} finally {  await session.stop(); // billing stops here}

const browserOnly = await bx.sessions.create({});                               // the defaultconst shellOnly = await bx.sessions.create({ browser: false, shell: true });const both = await bx.sessions.create({ shell: true });

const session = await bx.sessions.create({ timeout: 300, proxy: { type: "residential", country: "DE" } });await session.update({ timeout: 900 });         // its length in seconds from its last start; expiresAt movesawait session.update({ idleTimeout: 120 });     // end it after 2 minutes without activityawait session.update({ rotateProxy: true });    // a new proxy IP now; open browser connections reconnect (400 without a proxy)await session.update({ proxy: null });          // remove the proxyawait session.update({ blockAds: true, cookieBanners: "reject", captcha: "ask" });await session.update({ rotateUrls: true });     // every earlier signed URL stops workingconsole.log(session.liveUrl);                   // the new one: share it only with people who may use it

import { Boxline } from "@boxline/sdk";import { chromium } from "playwright";const bx = new Boxline();const session = await bx.sessions.create({ shell: true, keepAlive: true });try {  // Browser: download a report. Downloads land in /workspace/downloads.  // (A demo page; on your own site, page.goto() your report page instead.)  const browser = await chromium.connectOverCDP(session.connectUrl!);  const context = browser.contexts()[0];  const page = context.pages()[0] ?? (await context.newPage());  await page.setContent(    `<a download="report.csv" href="data:text/csv,${encodeURIComponent("month,revenue\nJan,1200\nFeb,1850\nMar,2410")}">Download report</a>`,  );  await page.getByRole("link", { name: "Download report" }).click();  const csv = await session.files.waitFor("downloads/*.csv");  console.log("downloaded", csv.path, csv.size);  // Shell: add up the revenue column with Python, on the same machine.  const run = await session.exec(`mkdir -p output && python3 -c "import pandas as pd; print(pd.read_csv('downloads/report.csv')['revenue'].sum())" > output/total.txt`);  if (run.exitCode !== 0) throw new Error(run.stderr);  // Files: read the result.  const total = (await session.files.readText("output/total.txt")).trim(); // "5460"  // Actions: type it into the form and send it.  const results = await session.actions([    { action: "goto", url: "https://httpbin.org/forms/post" },    { action: "fill", selector: "input[name=custname]", value: total },    { action: "click", selector: "form button" },    { action: "content", format: "text" },  ]);  console.log(results.at(-1)?.value?.content); // what the form received  await browser.close();} finally {  await session.stop();}

import { writeFile } from "node:fs/promises";const tar = await session.files.archive("output");     // a folder as one .tar.gz (a Uint8Array)await writeFile("output.tar.gz", tar);await session.stop();console.log(await session.files.readText("output/total.txt")); // still readable while stoppedconst entries = await session.files.list("output");

const page = await bx.fetch("https://example.com", { format: "markdown", links: true });const png = await bx.screenshot("https://example.com", { fullPage: true }); // Uint8Arrayconst pdf = await bx.pdf("https://example.com", { paper: "A4" });const { data } = await bx.extract<{ plans: { name: string; price: string }[] }>({  url: "https://example.com/pricing",  prompt: "The name and monthly price of every plan",});const started = await bx.crawl.start({ url: "https://example.com/docs", maxPages: 20 });const crawl = await bx.crawl.wait(started.id); // every page in crawl.data

const { results, cached } = await bx.search({ query: "playwright connectOverCDP", limit: 5, recency: "year" });for (const r of results) console.log(r.title, r.url, r.publishedAt ?? "");// fetch: also open the top pages (true = 3, or 0 to 5) and get them as Markdown.const withPages = await bx.search({ query: "playwright connectOverCDP", limit: 3, fetch: 2 });console.log(withPages.results[0].content?.slice(0, 200), withPages.results[0].error);

const s = await bx.sessions.create();await s.goto("https://example.com");await s.mouse.move(400, 300, { steps: 10 });await s.mouse.click(400, 300, { button: "right", count: 2, modifiers: ["Shift"] });await s.mouse.drag("#card", "#done-column", { steps: 20 });                          // selectors: the element's centreawait s.mouse.drag([{ x: 100, y: 100 }, { x: 200, y: 150 }, { x: 300, y: 100 }]); // or a pathawait s.mouse.down();await s.mouse.up();await s.hover("#menu");await s.keyboard.key("ControlOrMeta+A");console.log(await s.cursor());                                                     // { x, y }const shot = await s.screenshot({ maxWidth: 640, cursor: true });                  // with width, height, scale// Every result says what happened; a bare string is a plain-English step.const results = await s.actions([{ action: "goto", url: "https://example.com" }, "click More information"]);console.log(results.map((r) => r.text));// One action exactly as a computer-use model gave it, and the screen after it.const screen = await s.computer({ action: "left_click", coordinate: [512, 300] }, { maxWidth: 1024 });

const run = await bx.agent.run({  task: "Sign in to https://example.com with %email% and %password%, then open the billing page.",  variables: {    email: "ada@example.com",    password: { value: process.env.SITE_PASSWORD!, origins: ["https://example.com"] },  },});for await (const event of bx.agent.stream(run.id)) {  if (event.type === "thought") console.log("…", event.text);     // what it is about to do  if (event.type === "tool") console.log(event.name, event.input); // placeholders, never values  if (event.type === "done") console.log(event.status, event.result);}

// A shell-only run: no browser, so the AI gets the shell and the files only.const run = await bx.agent.run({  task: "Convert every video in /workspace to MP4 with ffmpeg and list the new files",  session: { browser: false, shell: true },});const done = await bx.agent.wait(run.id);console.log(done.status, done.result);

const run = await bx.agent.run({ task: "Download the latest invoice from https://example.com/billing" });await bx.agent.pause(run.id, "I will sign in myself");     // the AI finishes its step, then waitsconst session = await bx.sessions.get(run.sessionId);console.log(session.liveUrl);                              // a signed link: share it only with that personawait bx.agent.resume(run.id, { note: "I signed in" });    // the same run goes onconst done = await bx.agent.wait(run.id);if (done.resumable) {  // It stopped at a limit. Give it more steps; the work so far is kept.  await bx.agent.resume(run.id, { maxSteps: 60, note: "The invoice page is already open" });}

const session = await bx.sessions.create({ shell: true });const { exitCode } = await session.runScript(  `  useModel("claude-haiku-5-5");                               // every later step() and extract() uses it  await page.goto("https://example.com/signup");  await step("type %email% into the email field");  await step("click Continue", { model: "claude-sonnet-5-5" }); // this call only  const plans = await extract("the plan names and prices");   // returns the data itself  console.log(JSON.stringify(plans));  `,  { env: { email: "ada@example.com" }, onData: (_stream, text) => process.stdout.write(text) },);console.log("exit code", exitCode);await session.stop();

const session = await bx.sessions.create({ captcha: "ask" });const stop = session.onCaptcha(({ state, kind, url }) => {  // Tell someone who may solve it; session.liveUrl is a signed link, so share it privately.  if (state === "detected") console.log(`${kind} on ${url}: solve it in the live view`);});await session.goto("https://example.com/signup");await session.waitForHuman({ timeoutMs: 5 * 60_000 }); // throws CaptchaTimeoutError if nobody solves itstop();

const s = await bx.sessions.create({ blockAds: true, cookieBanners: "reject" }); // "reject" is the defaultawait s.goto("https://example.com");await s.refresh();console.log(s.data.blockedRequests); // refused inside the machine, before any proxyawait s.update({ blockAds: false, cookieBanners: "off" });await bx.fetch("https://example.com", { blockAds: true }); // screenshot, pdf, extract, crawl.start and agent.run too

const ext = await bx.extensions.upload("./my-extension.zip"); // or its bytes, at most 10 MBconst withExt = await bx.sessions.create({ extensions: [ext.id] }); // loaded before the session is returnedfor await (const e of bx.extensions.list()) console.log(e.id, e.name, e.version, e.permissions);await bx.extensions.delete(ext.id);

import { CredentialCodeTimeoutError, CredentialLoginFailedError } from "@boxline/sdk";await bx.credentials.create({  name: "SHOP",  type: "password",  origins: ["https://shop.example.com"],  username: "ops@example.com",  password: process.env.SHOP_PASSWORD!,  codeSource: "push", // your system sends each code or sign-in link});const session = await bx.sessions.create();try {  // login waits as long as the server may (a code from your system included).  const page = await session.login("SHOP", { url: "https://shop.example.com/signin" });  console.log(page.url, page.title, page.runId);} catch (err) {  if (err instanceof CredentialLoginFailedError) console.log("could not sign in; run", err.runId); // also the timeout  else if (err instanceof CredentialCodeTimeoutError) console.log("no code arrived in time");  else throw err;}// In your webhook receiver, when credential.code_needed arrives (the run is waiting):await bx.credentials.pushCode("SHOP", { code: "123456" }); // what the site just emailed or texted

import { verifyWebhook, WebhookSignatureError } from "@boxline/sdk";const endpoint = await bx.webhooks.create({ url: "https://example.com/webhooks/boxline", events: ["session.stopped"] });// endpoint.secret ("whsec_…") is shown only now: store it with your other secrets.// In your receiver: the raw body, the Boxline-Signature header, and the secret (or [new, old] after a rotation).try {  const event = verifyWebhook(body, header, process.env.BOXLINE_WEBHOOK_SECRET!); // 5-minute window  // drop event.id if you have handled it already, then answer 200} catch (err) {  if (err instanceof WebhookSignatureError) console.log(err.reason); // answer 400}for await (const d of bx.webhooks.deliveries(endpoint.id, { status: "failed" })) console.log(d.id, d.errorCode);await bx.webhooks.test(endpoint.id);

const settings = await bx.project.settings(); // { captchaDefault, captchaDefaultEffective, trajectories, updatedVia, … }console.log(settings.trajectories);            // { enabled, noticeSeenAt, decidedBy }await bx.project.setSettings({ captchaDefault: "ignore" });      // for new sessions and runs without captchaawait bx.project.setSettings({ trajectories: { enabled: false } }); // the Trajectories program, for this project

const u = await bx.usage({ from: "2026-10-01", to: "2026-10-07" });console.log(`${u.running} of ${u.concurrencyLimit} sessions running`);console.log(u.sessions, u.agentRuns, u.modelCostUsd, u.ownKeyModelCostUsd, u.costUsd);for (const day of u.byDay) console.log(day.date, day.sessions, day.agentRuns, day.costUsd);

const page = await bx.sessions.list({ status: ["RUNNING", "STOPPED"], limit: 50 });console.log(page.data.length, page.total, page.next);for await (const s of bx.sessions.list({ status: "RUNNING", kind: "shell" })) console.log(s.id); // shell-only sessionsfor await (const e of bx.sessions.events("SESSION_ID", { types: ["console", "error"] })) console.log(e.text);for await (const p of page.iterPages()) console.log(p.data.length);

import { Boxline, BoxlineError, FeatureNotInPlanError, RateLimitError } from "@boxline/sdk";const bx = new Boxline();try {  const session = await bx.sessions.create({ shell: true });  try {    console.log((await session.exec("python3 --version")).stdout);  } finally {    await session.stop(); // a failure never leaves a session running  }} catch (err) {  if (err instanceof RateLimitError) console.log("busy, try again in", err.retryAfter, "s");  else if (err instanceof FeatureNotInPlanError) console.log("not on this plan:", err.message);  else if (err instanceof BoxlineError) console.log(err.code, err.message, "request", err.requestId);  throw err;}

const session = await bx.sessions.create({ timeout: 600 }, { idempotencyKey: "nightly-report-2026-09-30" });

await bx.sessions.get("SESSION_ID", { timeoutMs: 5_000, maxRetries: 0, clientRequestId: "trace-42" });const patient = bx.withOptions({ maxRetries: 6 }); // a copy of the client with other defaults