Skip to main content

​
Overview

BrowserSessionConfig controls how a browser session is created. Use it to set the viewport size, choose a backend, enable video recording, or allocate more memory and disk for browser-heavy workloads. If you create a BrowserSession without a config, SmolVM uses sensible defaults that work for most use cases.

​
Import

from smolvm import BrowserSessionConfig

​
Fields

​
backend
str | None
default:"None"
Runtime backend. Options: "firecracker", "qemu", or None (auto-detect). Firecracker is used on Linux with KVM, QEMU elsewhere.
​
browser
str
default:"chromium"
Browser engine to use. Currently "chromium" is the only supported value.
​
mode
str
default:"headless"
Browser launch mode. Options: "headless" or "headed". Headed mode enables the noVNC live-view.
​
profile
str | None
default:"None"
Persistent browser profile name. When set, browser state (cookies, localStorage) persists across sessions that share the same profile name.
​
viewport
BrowserViewport | None
default:"None"
Browser window dimensions. Defaults to 1280x720 if omitted.
​
enable_video_recording
bool
default:"False"
Record a video of the browser session. Recordings can be retrieved with collect_artifacts().
​
enable_downloads
bool
default:"True"
Allow file downloads inside the browser.
​
mem_size_mib
int
default:"1024"
Guest memory in MiB. Browser sessions default to 1024 MiB, which is higher than a basic sandbox.
​
disk_size_mib
int
default:"512"
Root filesystem size in MiB.

​
BrowserViewport

Controls the browser window dimensions. 
from smolvm import BrowserViewport
​
width
int
default:"1280"
Viewport width in pixels.
​
height
int
default:"720"
Viewport height in pixels.

​
Examples

​
Default configuration

from smolvm import BrowserSession

# Uses sensible defaults: 1280x720, headless, 1024 MiB RAM
with BrowserSession() as session:
    browser = session.connect_playwright()
    # ...

​
High-resolution viewport

from smolvm import BrowserSession, BrowserSessionConfig, BrowserViewport

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

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

​
Video recording

from smolvm import BrowserSession, BrowserSessionConfig

config = BrowserSessionConfig(
    enable_video_recording=True,
    mode="headed",
)

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

    # Retrieve the recording
    artifacts = session.collect_artifacts()
    print(f"Artifacts saved to {artifacts}")

​
Persistent browser profile

from smolvm import BrowserSession, BrowserSessionConfig

config = BrowserSessionConfig(profile="my-profile")

# First session: log in to a website
with BrowserSession(config=config) as session:
    browser = session.connect_playwright()
    page = browser.new_page()
    page.goto("https://example.com/login")
    # ... log in
    browser.close()

# Second session with same profile: still logged in
with BrowserSession(config=config) as session:
    browser = session.connect_playwright()
    page = browser.new_page()
    page.goto("https://example.com/dashboard")
    # Cookies and localStorage persist from the previous session
    browser.close()
Last modified on April 6, 2026