Skip to main content

​
Overview

SmolVM can start a browser or a full desktop inside a disposable sandbox. You can give an agent a connection address for automation, open a web viewer to watch the screen, or connect a desktop-control tool. Use SmolVM.browser() when your agent needs Chromium for web tasks. Use SmolVM.desktop() when your agent needs the whole desktop environment, such as a window manager, visible apps, or a VNC-compatible computer-use driver. VNC means Virtual Network Computing, a standard way for tools to view and control a remote screen.

​
Import

from smolvm import SmolVM

​
Choose a mode

FactoryBest forURLs returned
SmolVM.browser(headless=True)Browser automation with Playwright or another automation clientcdp_url
SmolVM.browser(headless=False)Browser automation plus a visible screencdp_url, viewer_url, display_url
SmolVM.desktop()Full desktop computer-use agentsviewer_url, display_url
is for browser automation. is for screen viewing and desktop control.

​
Start a headless browser

Headless browser mode gives automation tools a Chromium connection address. It is the smallest browser mode because it does not start the live screen viewer.
browser_headless.py
from smolvm import SmolVM

with SmolVM.browser(headless=True) as browser:
    print(browser.cdp_url)
​
cdp_url
str
Local browser automation URL for Playwright or another browser automation client.

​
Start a visible browser

Visible browser mode gives you both automation and a live screen. Use it when you want an agent to drive Chromium while a person can watch what happens.
browser_visible.py
from smolvm import SmolVM

with SmolVM.browser(headless=False) as browser:
    print(browser.cdp_url)
    print(browser.viewer_url)
    print(browser.display_url)
​
viewer_url
str
Web URL you can open in your own browser to watch or interact with the sandbox screen.
​
display_url
str
VNC URL for desktop viewers and computer-use agents that need direct screen control.

​
Start a full desktop

Desktop mode starts the full display environment instead of only Chromium. Use it for agents that need desktop apps, window focus, or a VNC-compatible driver such as a computer-use agent driver.
desktop.py
from smolvm import SmolVM

with SmolVM.desktop() as desktop:
    print(desktop.viewer_url)
    print(desktop.display_url)
Desktop sandboxes focus on screen access. They return None for cdp_url; use SmolVM.browser() when you need a browser automation address.

​
Class methods

​
SmolVM.browser

@classmethod
SmolVM.browser(
    *,
    headless: bool = True,
    session_id: str | None = None,
    backend: Literal["firecracker", "qemu", "libkrun", "auto"] = "auto",
    profile_id: str | None = None,
    persistent: bool = False,
    timeout_minutes: int = 30,
    viewport: BrowserViewport | dict[str, Any] | None = None,
    viewport_width: int = 1280,
    viewport_height: int = 720,
    record_video: bool = False,
    allow_downloads: bool = True,
    env_vars: dict[str, str] | None = None,
    workspace_mounts: list[WorkspaceMount] | None = None,
    memory_mb: int = 2048,
    disk_size_mb: int = 4096,
    data_dir: Path | None = None,
    socket_dir: Path | None = None,
    ssh_key_path: str | None = None,
    boot_timeout: float = 90.0,
    on_progress: Callable[[str], None] | None = None,
) -> DisplaySandboxProtocol
Starts a Chromium browser sandbox and returns it when it is ready.
​
headless
bool
default:"True"
Use True for browser automation only. Use False to also start the visible viewer and VNC display endpoint.
​
session_id
str | None
default:"None"
Existing browser sandbox ID to reconnect to. Omit it to create a new sandbox.
​
backend
str
default:"auto"
Runtime backend. Options are "firecracker", "qemu", "libkrun", and "auto".
​
profile_id
str | None
default:"None"
Browser profile name. Reuse a profile ID to keep browser state such as cookies and local storage across persistent sessions.
​
persistent
bool
default:"False"
Keep the sandbox record after the current Python process exits. Use this when another script needs to reconnect later with session_id.
​
timeout_minutes
int
default:"30"
Maximum session lifetime in minutes.
​
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 sandbox.
​
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.
​
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, display services, and browser to become ready.
​
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.

​
SmolVM.desktop

@classmethod
SmolVM.desktop(
    *,
    session_id: str | None = None,
    backend: Literal["firecracker", "qemu", "libkrun", "auto"] = "auto",
    profile_id: str | None = None,
    persistent: bool = False,
    timeout_minutes: int = 30,
    viewport: BrowserViewport | dict[str, Any] | None = None,
    viewport_width: int = 1280,
    viewport_height: int = 720,
    record_video: bool = False,
    allow_downloads: bool = True,
    env_vars: dict[str, str] | None = None,
    workspace_mounts: list[WorkspaceMount] | None = None,
    memory_mb: int = 2048,
    disk_size_mb: int = 4096,
    data_dir: Path | None = None,
    socket_dir: Path | None = None,
    ssh_key_path: str | None = None,
    boot_timeout: float = 90.0,
    on_progress: Callable[[str], None] | None = None,
) -> DisplaySandboxProtocol
Starts a full desktop sandbox and returns it when the viewer and VNC display endpoint are ready. It accepts the same resource, viewport, persistence, and artifact options as SmolVM.browser().

​
Use Playwright with browser mode

playwright_browser.py
from smolvm import SmolVM

with SmolVM.browser(headless=True) as sandbox:
    browser = sandbox.connect_playwright()
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()
Install Playwright in your local Python environment before using connect_playwright(): pip install playwright.
Last modified on June 12, 2026