Skip to main content

​
Overview

BrowserSession gives you a real Chromium browser running inside a SmolVM sandbox. You can automate it with Playwright, take screenshots, transfer files, or watch the session live through noVNC — all without installing a browser on your host. Use browser sessions when your agent or script needs to interact with websites, fill out forms, capture screenshots, or perform computer-use tasks.

​
Import

from smolvm import BrowserSession

​
Constructor

BrowserSession(
    config: BrowserSessionConfig | None = None,
    *,
    session_id: str | None = None,
)
​
config
BrowserSessionConfig | None
default:"None"
Configuration for a new browser session. Mutually exclusive with session_id. If omitted (and session_id is omitted), SmolVM creates a session with sensible defaults.
​
session_id
str | None
default:"None"
ID of an existing session to reconnect to. Mutually exclusive with config.

​
Raises

  • ValueError: If both config and session_id are provided.

​
Class methods

​
from_id

Reconnect to an existing browser session by its ID. 
@classmethod
BrowserSession.from_id(session_id: str) -> BrowserSession
​
session_id
str
required
The session identifier returned when the session was first created.
​
return
BrowserSession
A BrowserSession instance connected to the existing session.

​
Lifecycle methods

​
start

Boot the sandbox, launch the browser, and expose the Chrome DevTools Protocol (CDP) endpoint on localhost. 
def start(self) -> BrowserSession
​
return
BrowserSession
Returns self for method chaining.
After start() completes you can access the CDP URL from the session’s info property and connect Playwright or any other CDP client.

​
stop

Stop the browser and shut down the underlying sandbox. The session can be restarted later. 
def stop(self) -> BrowserSession
​
return
BrowserSession
Returns self for method chaining.

​
delete

Permanently remove the session and its sandbox. 
def delete(self) -> None

​
Browser automation

​
connect_playwright

Connect a Playwright Browser instance to the running browser session over CDP. 
def connect_playwright(self) -> Browser
​
return
Browser
A Playwright Browser object you can use to create pages, navigate, click, and extract content.
You need playwright installed locally. Install it with pip install playwright.
Example: 
from smolvm import BrowserSession

with BrowserSession() as session:
    browser = session.connect_playwright()
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

​
screenshot

Capture a screenshot of the current browser viewport and save it to a local file. 
def screenshot(self, destination: str | Path) -> Path
​
destination
str | Path
required
Local file path where the screenshot will be saved (PNG format).
​
return
Path
The path to the saved screenshot.

​
open_live_view

Open the noVNC live-view URL in your default web browser. This lets you watch the browser session in real time. 
def open_live_view(self) -> None
Live view is useful for debugging agent workflows. You can watch what the agent sees and does inside the browser.

​
File transfer

​
push_file

Copy a local file into the browser session’s sandbox. 
def push_file(self, local_path: str | Path, remote_path: str) -> None
​
local_path
str | Path
required
Path to the file on your host machine.
​
remote_path
str
required
Destination path inside the sandbox.

​
pull_file

Copy a file from the sandbox to your host machine. 
def pull_file(self, remote_path: str, local_path: str | Path) -> None
​
remote_path
str
required
Path to the file inside the sandbox.
​
local_path
str | Path
required
Destination path on your host machine.

​
Diagnostics

​
collect_artifacts

Package guest logs, downloads, and recordings into a tar archive. 
def collect_artifacts(self) -> Path
​
return
Path
Path to the tar archive on your host.

​
logs

Retrieve combined host and guest logs for the session. 
def logs(self, tail: int | None = None) -> str
​
tail
int | None
default:"None"
Return only the last N lines. If omitted, returns all available logs.
​
return
str
Combined log output.

​
Context manager

BrowserSession supports the with statement for automatic lifecycle management: 
with BrowserSession() as session:
    browser = session.connect_playwright()
    page = browser.new_page()
    page.goto("https://example.com")
    # session automatically stops and deletes on exit
On entry (__enter__): starts the session if it was newly created. On exit (__exit__): stops and deletes the session, releasing all resources.

​
Usage examples

​
Basic browser session

from smolvm import BrowserSession

with BrowserSession() as session:
    browser = session.connect_playwright()
    page = browser.new_page()
    page.goto("https://news.ycombinator.com")
    titles = page.query_selector_all(".titleline > a")
    for t in titles[:5]:
        print(t.text_content())
    browser.close()

​
Take a screenshot

from smolvm import BrowserSession

with BrowserSession() as session:
    browser = session.connect_playwright()
    page = browser.new_page()
    page.goto("https://example.com")
    session.screenshot("example.png")
    browser.close()

​
Custom browser configuration

from smolvm import BrowserSession, BrowserSessionConfig, BrowserViewport

config = BrowserSessionConfig(
    viewport=BrowserViewport(width=1920, height=1080),
    mem_size_mib=2048,
    enable_video_recording=True,
)

with BrowserSession(config=config) as session:
    browser = session.connect_playwright()
    page = browser.new_page()
    page.goto("https://example.com")
    browser.close()

​
Reconnect to an existing session

from smolvm import BrowserSession

# First, create and keep a session running
session = BrowserSession()
session.start()
session_id = session.info.session_id

# Later, reconnect from another script
restored = BrowserSession.from_id(session_id)
browser = restored.connect_playwright()
# ...
restored.stop()
restored.delete()
Last modified on April 6, 2026