Sessions
A session is a live browser you hold open. You create one, connect to it over CDP with Playwright or Puppeteer, drive it interactively, and release it when you are done. Banana Peel provisions and proxies the browser, but there is no task attached — what happens inside the session is entirely up to your code.
Runs vs. sessions
Shorthand: runs are what you asked for; sessions are what you're holding.
- A run is a unit of work. You describe a task with
POST /api/v1/responses, Banana Peel routes it to a runner, and you get back a result with attempts, cost, duration, and a verdict. Runs are billed per executed attempt, and benchmarks and smart routing are built from run outcomes. See Responses & runs. - A session is a live browser with no task known to Banana Peel. You get a CDP connect URL and drive the browser yourself. Because a session is one concrete browser, it is not smart-routed. Sessions are the natural surface for keeping a logged-in browser open, watching it through a live view, or stepping in by hand.
A completed run also reports metadata about the browser it used under banana_peel.session— live view, replay, and provider ids. That is a record of the run's browser, not a session you manage: the run provisions and releases it for you.
Creating sessions
Sessions live on the provider-compatible surfaces: /api/v1/sessions (Browserbase-shaped — see the Browserbase wrapper) and /api/wrappers/steel/v1/sessions (Steel-shaped — see the Steel wrapper). Existing Playwright/Puppeteer code keeps working: point the SDK at Banana Peel, authenticate with a bp_live_… key, and connect over CDP as before.
If you want Banana Peel to do the work — pick a runner, execute the task, fall back, and report cost and outcome — create a run with POST /api/v1/responses instead of managing a session yourself.