Browser

Sessions have a Chrome browser unless you create them with "browser": false. The session’s connectUrl is a Chrome DevTools Protocol (CDP) WebSocket, so any CDP client can drive it.

Playwright

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(session.connectUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());

await page.goto("https://example.com");
await page.screenshot({ path: "example.png" });

Puppeteer

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: session.connectUrl,
});
const [page] = await browser.pages();
await page.goto("https://example.com");

Raw CDP

You can also speak the protocol directly over a WebSocket, which is useful for tools that do not use Playwright or Puppeteer:

import WebSocket from "ws";

const ws = new WebSocket(session.connectUrl);
ws.on("open", () => {
  ws.send(JSON.stringify({ id: 1, method: "Browser.getVersion" }));
});
ws.on("message", (data) => console.log(JSON.parse(data.toString())));

Disconnecting matters for browser-only sessions: without keepAlive, they end about 5 seconds after the last CDP client leaves. See session lifetime.

Live view

The session’s liveUrl is a page that shows the browser in real time. Open it to watch your agent, or click and type in it to take over when the agent is stuck, for example to solve a CAPTCHA. It is a signed URL: anyone who has it can control the browser, so share it only with people who should. Get a fresh one with GET /v1/sessions/:id/live.

Only Boxline’s own apps, such as the console, can frame the live view. Embedding it in an <iframe> on your own site needs embed origins set for your project, which are not available yet; open it in a new tab or window instead.

Downloads

Whatever triggers a download (Playwright, Puppeteer, the Actions API or a click in the live view), the file lands in /workspace/downloads. Wait for it with files/wait?pattern=downloads/*.csv, process it in the shell, or download it to your own machine. See Files. To reuse the browser’s login from the shell, export its cookies.

Actions API

POST/v1/sessions/:id/actions

The Actions API runs browser steps next to the browser, inside the session. Send one action or a whole list in a single request instead of one round trip per step, which keeps latency low for agents that plan several steps at a time.

curl -X POST https://api.staging.boxline.dev/v1/sessions/$SESSION_ID/actions \
  -H "x-api-key: $BOXLINE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "actions": [
      { "action": "goto", "url": "https://example.com/login" },
      { "action": "fill", "selector": "#email", "value": "agent@example.com" },
      { "action": "click", "selector": "button[type=submit]" },
      { "action": "content", "format": "markdown" }
    ]
  }'

Actions run in order. The response has one result per action:

{
  "results": [
    { "ok": true, "action": "goto", "value": { "url": "…", "title": "…", "status": 200 }, "ms": … },
    { "ok": true, "action": "fill", "ms": … },
    { "ok": true, "action": "click", "ms": … },
    { "ok": true, "action": "content", "value": { "content": "…", "url": "…", "title": "…" }, "ms": … }
  ]
}

A failed action has ok: false, an error message and, when there is one, a stable code (for example captcha_timeout). Available actions:

The SDK wraps the common ones: session.goto(url), click(selector), fill(selector, value), content(format) and screenshot(opts) and step(instruction), plus session.actions(list) for everything else. You can mix styles: drive the session with Playwright for complex flows and use actions for quick, latency-sensitive steps.