Quickstart · Docs

This guide takes you from an API key to a Playwright script running in a Boxline session. You need a terminal and a recent version of Node.js.

1. Get an API key

Create an account, then create an API key in the console. Export it in your shell so the examples below can use it:

Shell

export BOXLINE_API_KEY="your-api-key"

2. Create a session

A session is one isolated machine. This request asks for one with a browser and the default five-minute timeout:

Shell

curl -X POST https://api.staging.boxline.dev/v1/sessions \
  -H "x-api-key: $BOXLINE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"browser": true}'

The response is the new session:

Response (201)

{
  "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d0b7a1c4e88",
  "status": "RUNNING",
  "projectId": "…",
  "region": "…",
  "browser": true,
  "shell": false,
  "keepAlive": false,
  "timeout": 300,
  "createdAt": "2026-09-28T12:00:00.000Z",
  "startedAt": "2026-09-28T12:00:00.000Z",
  "endedAt": null,
  "expiresAt": "2026-09-28T12:05:00.000Z",
  "endReason": null,
  "connectUrl": "wss://…/v1/connect?sessionId=3f6c2a9e-8b1d-4c7a-9e2f-5d0b7a1c4e88&token=…",
  "liveUrl": "https://…/live/3f6c2a9e-8b1d-4c7a-9e2f-5d0b7a1c4e88?token=…",
  "terminalUrl": null,
  "proxy": null,
  "captcha": "ask",
  "attention": null,
  "browserSettings": { "mode": "standard", "locale": null, "timezone": null },
  "viewport": { "width": 1280, "height": 720 },
  "workspacePath": "/workspace",
  "contextId": null,
  "userMetadata": {},
  "moves": 0,
  "error": null,
  "usage": { "seconds": 0, "costUsd": 0 }
}

Keep the id (a UUID) for later calls. connectUrl is the Chrome DevTools Protocol endpoint for the session’s browser and liveUrl opens the live view. Both are signed URLs; treat them like credentials. The full list of fields is on the Sessions page.

3. Connect with Playwright

Install Playwright in a new project:

Shell

npm install playwright

Then connect to the session over CDP and drive the browser as usual. Put the connectUrl from step 2 in an environment variable first:

quickstart.mjs

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(process.env.CONNECT_URL);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());

await page.goto("https://example.com");
console.log("Title:", await page.title());

await browser.close();

Shell

CONNECT_URL="wss://…" node quickstart.mjs

While the script runs, open the liveUrl in your browser to watch the session. You can click in the live view too.

4. Release the session

Sessions are billed per second until they end. Release a session as soon as you are done; the response is the session with status COMPLETED:

Shell

curl -X POST https://api.staging.boxline.dev/v1/sessions/$SESSION_ID/release \
  -H "x-api-key: $BOXLINE_API_KEY"

Next steps

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