Skip to main content

​
Overview

You can tune browser and desktop sandboxes for the task your agent needs to complete. Start with the defaults, then adjust the screen size, memory, disk, profile, or recording options when your workflow needs them. Pass these options directly to SmolVM.browser() or SmolVM.desktop().

​
Import

from smolvm import BrowserViewport, SmolVM

​
Common options

​
backend
str
default:"auto"
Runtime backend. Options are "firecracker", "qemu", "libkrun", and "auto".
​
session_id
str | None
default:"None"
Existing sandbox ID to reconnect to. Omit it to create a new sandbox.
​
profile_id
str | None
default:"None"
Browser profile name. Reuse the same ID to keep browser state such as cookies and local storage across persistent browser sessions.
​
persistent
bool
default:"False"
Keep the sandbox record after the current Python process exits. This lets another process reconnect with session_id.
​
timeout_minutes
int
default:"30"
Maximum session lifetime in minutes.
​
memory_mb
int
default:"2048"
Guest memory in MiB.
​
disk_size_mb
int
default:"4096"
Root filesystem size in MiB.
​
boot_timeout
float
default:"90.0"
Maximum seconds to wait for the sandbox and display services to become ready.
​
env_vars
dict[str, str] | None
default:"None"
Environment variables to set inside the sandbox.
​
workspace_mounts
list[WorkspaceMount] | None
default:"None"
Folders to share with the sandbox.

​
Advanced local options

​
data_dir
Path | None
default:"None"
Local directory for sandbox state. Omit it to use SmolVM’s default state directory.
​
socket_dir
Path | None
default:"None"
Local directory for runtime sockets. Omit it to use SmolVM’s default socket directory.
​
ssh_key_path
str | None
default:"None"
SSH private key path used for setup and file transfer inside the sandbox.
​
on_progress
Callable[[str], None] | None
default:"None"
Callback that receives progress messages while the sandbox starts.

​
Browser-only option

​
headless
bool
default:"True"
SmolVM.browser() only. Use True for CDP-only browser automation. Use False to also start viewer_url and display_url.
CDP means Chrome DevTools Protocol, the browser connection used by Playwright and similar automation tools.

​
Display and artifact options

​
viewport
BrowserViewport | dict | None
default:"None"
Browser or desktop screen size. You can pass BrowserViewport(width=1440, height=900) or {"width": 1440, "height": 900}.
​
viewport_width
int
default:"1280"
Screen width in pixels when viewport is omitted.
​
viewport_height
int
default:"720"
Screen height in pixels when viewport is omitted.
​
record_video
bool
default:"False"
Record the visible session. Retrieve recordings with collect_artifacts() before the sandbox stops.
​
allow_downloads
bool
default:"True"
Allow Chromium downloads inside the browser sandbox.

​
BrowserViewport

BrowserViewport is a small helper for screen dimensions. 
from smolvm import BrowserViewport
​
width
int
default:"1280"
Screen width in pixels.
​
height
int
default:"720"
Screen height in pixels.

​
Examples

​
Larger visible browser

larger_browser.py
from smolvm import BrowserViewport, SmolVM

with SmolVM.browser(
    headless=False,
    viewport=BrowserViewport(width=1440, height=900),
    memory_mb=3072,
) as browser:
    print(browser.viewer_url)

​
Persistent browser profile

browser_profile.py
from smolvm import SmolVM

with SmolVM.browser(profile_id="daily-reports", persistent=True) as browser:
    print(browser.cdp_url)
Use the same profile_id again when you want Chromium to reuse saved browser state.

​
Full desktop with a larger screen

desktop_viewport.py
from smolvm import SmolVM

with SmolVM.desktop(viewport={"width": 1440, "height": 900}) as desktop:
    print(desktop.viewer_url)
    print(desktop.display_url)
Last modified on June 12, 2026