Configuring sessions

A session is one isolated cloud machine. It runs in its own gVisor sandbox and is never shared with another customer. Inside, it can have:

• a Chrome browser you control over the Chrome DevTools Protocol (see Connect with Playwright);
• a bash shell with Python, Node, ffmpeg, ImageMagick and poppler built in (see Shell);
• the shared /workspace disk, used by both (see File uploads and downloads).

A session needs a browser, a shell, or both: see Three kinds of session. There is one kind of machine, so you never pick an image. Sessions start from a pool of ready machines; the target is under one second from request to a running session.

Create a session

POST /v1/sessions starts a session and returns it with status RUNNING. See Create a session in the API reference.

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

import { Boxline } from "@boxline/sdk";const bx = new Boxline();const session = await bx.sessions.create({ browser: true, shell: true, timeout: 900 });console.log(session.id, session.liveUrl);

from boxline import Boxlinebx = Boxline()session = bx.sessions.create(browser=True, shell=True, timeout=900)print(session.id, session.live_url)

Three kinds of session

What you ask for when you create a session decides what it has. A session always has at least one of a browser and a shell, and always has the /workspace disk.

All three URLs are null unless the session is RUNNING. The kind is fixed when the session is created. GET /v1/sessions filters by it with kind=browser, kind=shell or kind=combined (both); see Find sessions.

A browser only

The default. Chrome, plus /workspace for downloads. Connect Playwright or Puppeteer to connectUrl, or watch it at liveUrl. There is no shell: a command call answers 409 shell_disabled.

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

import { Boxline } from "@boxline/sdk";const bx = new Boxline();const session = await bx.sessions.create({});console.log(session.connectUrl, session.liveUrl); // terminalUrl is null

from boxline import Boxlinebx = Boxline()session = bx.sessions.create()print(session.connect_url, session.live_url)  # terminal_url is None

session_create{ "shell": false }

boxline sessions create

A shell only

A bash shell with Python, Node, ffmpeg, ImageMagick and poppler, and /workspace. There is no browser, so connectUrl and liveUrl are null. A call that needs a browser (browser actions, computer use, scripts, export cookies), the live view and the CDP connection answer 409 browser_disabled. Files, events and everything else work as on any session.

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

import { Boxline } from "@boxline/sdk";const bx = new Boxline();const session = await bx.sessions.create({ browser: false, shell: true });console.log(session.terminalUrl); // connectUrl and liveUrl are null

from boxline import Boxlinebx = Boxline()session = bx.sessions.create(browser=False, shell=True)print(session.terminal_url)  # connect_url and live_url are None

session_create{ "browser": false, "shell": true }

boxline sessions create --no-browser --shell

A browser and a shell

Both, on one machine and one disk: a file the browser downloads lands in /workspace/downloads, where the shell can use it. All three URLs are set. Your plan must include shell sessions.

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

import { Boxline } from "@boxline/sdk";const bx = new Boxline();const session = await bx.sessions.create({ shell: true });console.log(session.connectUrl, session.liveUrl, session.terminalUrl);

from boxline import Boxlinebx = Boxline()session = bx.sessions.create(shell=True)print(session.connect_url, session.live_url, session.terminal_url)

session_create{ "shell": true }

boxline sessions create --shell

Options

Every option is optional. Leave the body out for a browser session with the defaults. An agent run or a task takes these same fields, as its session.

The API reference lists every field with its type and allowed values: Create a session.

Some options can change while the session runs, with Update a session. Turning the browser or the shell on or off, viewport, profile, recordSession, setup, extensions, env and credentials are fixed when the session is created.

Ads, cookie banners and extensions

curl -X POST https://api.boxline.dev/v1/sessions \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "content-type: application/json" \  -d '{"blockAds": true, "cookieBanners": "reject", "extensions": ["ext_Q2x9L0aPz7NmK3Jb"]}'

import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst session = await bx.sessions.create({  blockAds: true, // refuse ad and tracker sites  cookieBanners: "reject", // the default; "off" leaves banners alone  extensions: ["ext_Q2x9L0aPz7NmK3Jb"], // uploaded before (Hobby plan and up)});await session.update({ blockAds: false }); // blockAds and cookieBanners change at any time

from boxline import Boxlinebx = Boxline()  # reads BOXLINE_API_KEY and BOXLINE_API_URLsession = bx.sessions.create(    block_ads=True,  # refuse ad and tracker sites    cookie_banners="reject",  # the default; "off" leaves banners alone    extensions=["ext_Q2x9L0aPz7NmK3Jb"],  # uploaded before (Hobby plan and up))session.update(block_ads=False)  # block_ads and cookie_banners change at any time

See Ad and cookie-banner blocking and Extensions.

Common setups

The session object

Every session endpoint returns this object (201 on create):

{  "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d0b7a1c4e88",  "status": "RUNNING",  "projectId": "…",  "region": "…",  "browser": true,  "shell": false,  "keepAlive": false,  "timeout": 300,  "idleTimeout": null,  "createdAt": "2026-09-28T12:00:00.000Z",  "startedAt": "2026-09-28T12:00:00.000Z",  "expiresAt": "2026-09-28T12:05:00.000Z",  "stoppedAt": null,  "stopReason": null,  "deletesAt": null,  "deletedAt": null,  "deleteReason": 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,  "blockAds": false,  "blockedRequests": 0,  "cookieBanners": "reject",  "extensions": [],  "browserSettings": { "mode": "standard", "locale": null, "timezone": null },  "viewport": { "width": 1280, "height": 720 },  "trajectoriesEligible": false,  "workspacePath": "/workspace",  "profileId": null,  "profilePersist": false,  "userMetadata": {},  "checkpointAt": null,  "recoveries": 0,  "error": null,  "recordSession": true,  "hasRecording": false,  "setup": [],  "setupStatus": "none",  "setupError": null,  "env": [],  "credentials": [],  "usage": { "seconds": 0, "costUsd": 0 }}

Reading a session (GET /v1/sessions/:id, a list, or any call that returns it) signs connectUrl, liveUrl and terminalUrl afresh every time. They are null unless the session is RUNNING, and null for a part the session was created without (see Three kinds of session). The SDK’s session.refresh() reads them again.

To change a running session, see Update a session. To change or remove its proxy, or give it a new IP, see Proxies. For what to do when attention is set, see CAPTCHAs. For trajectoriesEligible, see Trajectories. For browserSettings, see Browser mode.

Limits

Your plan sets how many sessions can run at once and the largest timeout you can ask for. Creating (or resuming) a session beyond your plan’s sessions at once returns 429 concurrency_limit; a timeout above your plan’s maximum returns 402 plan_limit. When no machine is free, the start waits for one (see When no machine is free).

Only running sessions count: a stopped session is free and does not count towards your sessions at once. A stopped session is kept for your plan’s retention days, then deleted (see Lifecycle). The plan belongs to your organization, so the running sessions of all its projects count together. A project can also have a lower cap of its own (concurrencyCap): at the cap, a new session gets 429 concurrency_limit with “this project allows N sessions at the same time”. See Organizations, projects and team members.

Your plan also caps the data you can use through the platform’s proxies each month. Once it is used up, asking for one of those proxies returns 402 spend_limit; see Proxies.

Your plan also decides which features you can use, such as a shell, the platform’s proxies, browser mode or automatic CAPTCHA solving. Creating or changing a session with a feature your plan does not include returns 402 feature_not_in_plan. See Plans and features.

You can create up to 120 sessions per minute per project. See Rate limits.

When no machine is free

Sessions start from a pool of ready machines. When none is idle, the start waits while the platform adds one. It waits up to 110 seconds: about 70 seconds when a new server has to start first. Only then do you get 503 no_capacity.

So a burst of sessions starts a little slower instead of failing. The same wait applies when you resume a session, and to the web APIs that open a browser, such as fetch, screenshot and PDF.

• Set your own client’s time limit above 110 seconds. The SDKs use 120 seconds for one request. They also try a create again after a 503 (see Retries in the Node SDK and Python SDK), so a start that finds no machine can take several minutes before it throws.
• After no_capacity, try again with backoff. Starting fewer sessions at once also helps.

Billing

Sessions are billed per second while they run, with no per-session fee. Each session reports its own running time and cost in usage. The rates, and how shell sessions, proxies and stopped sessions are billed, are on Pricing. Plans are on the pricing page.

Every Boxline session runs in its own sandbox. The security page describes the isolation model.