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 Browser);
• a bash shell with Python, Node and ffmpeg built in (see Shell);
• the shared /workspace disk, used by both (see Files).

A session needs a browser, a shell, or both. Sessions start from a warm pool of ready machines; our target is under one second from request to a running session.

Create a session

POST/v1/sessions

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,
    "shell": true,
    "timeout": 900
  }'

Body parameters

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,
  "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,
  "workspacePath": "/workspace",
  "contextId": null,
  "userMetadata": {},
  "moves": 0,
  "error": null,
  "usage": { "seconds": 0, "costUsd": 0 }
}

The signed URLs expire. For fresh liveUrl and terminalUrl values, call GET /v1/sessions/:id/live.

How long a session lives

• Every session ends when it reaches its timeout (endReason: "timeout"), unless you release or pause it first.
• A browser-only session without keepAlive ends about 5 seconds after its last CDP client disconnects ("disconnected"). The short grace period lets a client reconnect. Set keepAlive: true to keep it running between connections.
• A session with a shell keeps running until you release it or it times out, whether or not a browser client is connected.

Get and list sessions

GET/v1/sessions/:id

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

GET/v1/sessions?status=&limit= returns { data: [Session] }, optionally filtered by status.

Release a session

POST/v1/sessions/:id/release or DELETE /v1/sessions/:id

Ends the session and returns it with status COMPLETED. Billing stops at that second. If the session uses a context with persist: true, its browser state is saved first.

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

Plan 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 concurrency returns 429 concurrency_limit; a timeout above your plan’s maximum returns 403 plan_limit.

Billing

Sessions are billed per second while they run, with no per-session fee. A browser session costs $0.045 per hour. Sessions with a shell are billed by sandbox resources: $0.045 per vCPU-hour plus $0.013 per GiB-hour, about $0.084 per hour for a browser and shell on 1 vCPU and 3 GiB. Each session reports its own usage; GET /v1/usage in the API reference totals your account. See pricing for plans.

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