TypeScript SDK · Docs

The TypeScript SDK wraps the REST API with typed methods and adds helpers such as streaming exec output. It works in Node 18+ and modern browsers (it uses the global fetch); keep your API key on the server.

Install

Shell

npm install @boxline/sdk

Create a client

By default the client reads BOXLINE_API_KEY and BOXLINE_API_URL from the environment:

Shell

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

TypeScript

import { Boxline } from "@boxline/sdk";

const client = new Boxline();

// Or pass both explicitly.
const explicit = new Boxline({
  apiKey: process.env.BOXLINE_API_KEY,
  baseUrl: "https://api.staging.boxline.dev",
});

A complete example

Download a report with the browser, then analyse it in the shell on the same machine:

report.ts

import { readFile } from "node:fs/promises";
import { Boxline } from "@boxline/sdk";
import { chromium } from "playwright";

const client = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URL
const session = await client.sessions.create({
  browser: true,
  shell: true,
});

try {
  // Browser: export a report. Downloads land in /workspace/downloads.
  const browser = await chromium.connectOverCDP(session.connectUrl!);
  const page = browser.contexts()[0].pages()[0];
  await page.goto("https://example.com/reports");
  await page.getByRole("link", { name: "Export CSV" }).click();
  const csv = await session.files.waitFor("downloads/*.csv");

  // Files: put a script next to the download.
  await session.files.write("summarise.py", await readFile("summarise.py"));

  // Shell: run it with Python, on the same machine.
  const result = await session.exec(`python3 summarise.py ${csv.path}`);
  console.log(result.stdout);
} finally {
  await session.release();
}

Methods

Each method maps to an endpoint in the API reference.

Client

Method	Maps to
`client.sessions.create(params)`	POST /v1/sessions → Session
`client.sessions.get(id)`	GET /v1/sessions/:id → Session
`client.sessions.list({ status, limit })`	GET /v1/sessions → Session[]
`client.contexts.create() / get(id) / delete(id)`	/v1/contexts
`client.fetch(url, { format, timeoutMs, waitUntil })`	POST /v1/fetch
`client.agent.run({ task, … }) / get(id) / wait(id)`	/v1/agent/runs
`client.usage({ from, to })`	GET /v1/usage
`client.me()`	GET /v1/auth/me: your project and its plan limits

Session

Method	Maps to
`session.id, status, connectUrl, liveUrl, terminalUrl, workspacePath`	Fields of session.data
`session.refresh()`	GET /v1/sessions/:id
`session.release()`	POST …/release
`session.pause() / session.resume()`	POST …/pause, …/resume
`session.move()`	POST …/move → { captureMs, acquireMs, restoreMs, totalMs }
`session.actions(list \| one)`	POST …/actions → results[]
`session.goto(url) / click(selector) / fill(selector, value)`	Single actions
`session.content(format) / screenshot(opts)`	Single actions
`session.exec(command, { timeoutMs, cwd, env, shell })`	POST …/exec → ExecResult
`session.execStream(command, (stream, data) => …, opts)`	POST …/exec with stream: true
`session.shell.restart(name?)`	POST …/shell/restart
`session.files.read / readText / write / list / delete / waitFor`	…/files, …/files/wait
`session.browser.exportCookies(path?)`	POST …/browser/cookies/export

Errors

A failed request rejects with a BoxlineError that has the HTTP status, the API’s error code (such as concurrency_limit or plan_limit) and a message. Release sessions in a finally block so a failure does not leave one running:

TypeScript

import { Boxline, BoxlineError } from "@boxline/sdk";

const client = new Boxline();
try {
  const session = await client.sessions.create({ browser: true });
  try {
    await session.goto("https://example.com");
    console.log((await session.content("markdown")).content);
  } finally {
    await session.release();
  }
} catch (err) {
  if (err instanceof BoxlineError && err.code === "concurrency_limit") {
    // wait for a running session to end, then retry
  }
  throw err;
}

Prefer another language? Everything the SDK does is available over the plain HTTP API that the rest of the Boxline docs use.

These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.