Skip to main content

​
Overview

SmolVM.browser() and SmolVM.desktop() return a sandbox object that is ready to use. Read its URLs to connect tools, use its lifecycle methods to stop it, and use browser helpers when the sandbox runs Chromium. The same object works as a context manager, so the sandbox stops when the with block exits.

​
URLs and identifiers

​
session_id
str
Stable browser or desktop sandbox ID.
​
vm_id
str
ID of the underlying SmolVM sandbox.
​
cdp_url
str | None
Browser automation URL for Playwright or another Chrome DevTools Protocol client. Available in browser mode.
​
browser_cdp_url
str | None
Alias for cdp_url.
​
viewer_url
str | None
Web URL you can open in your own browser to watch or interact with the screen. Available for visible browser and desktop modes.
​
display_url
str | None
VNC URL for desktop viewers and computer-use agents. VNC means Virtual Network Computing, a standard way to view and control a remote screen. Available for visible browser and desktop modes.
​
artifacts_dir
Path | None
Local folder where collected logs, downloads, recordings, and other session artifacts are stored.
​
status
str
Current lifecycle state for the sandbox, such as created, starting, ready, stopping, or error.

​
Lifecycle methods

​
stop

def stop() -> DisplaySandboxProtocol
Stops the sandbox and releases its VM resources.

​
delete

def delete() -> None
Alias for stop(). Use it when you want the same naming style as regular SmolVM sandboxes.

​
close

def close() -> None
Releases local client resources, such as an open Playwright connection, while leaving a persistent sandbox record available for reconnect.

​
open_viewer

def open_viewer() -> bool
Opens viewer_url in your default browser and returns whether the local browser accepted the request.

​
Browser helpers

These helpers are available when the object came from SmolVM.browser().

​
connect_playwright

def connect_playwright() -> Browser
Connects Playwright to the running Chromium browser over cdp_url.
Install Playwright locally before calling this method: pip install playwright.

​
screenshot

def screenshot(destination: str | Path, *, full_page: bool = True) -> Path
Captures the current browser page and saves a PNG on your machine.
​
destination
str | Path
required
Local file path for the screenshot.
​
full_page
bool
default:"True"
Capture the full page when possible.

​
push_file

def push_file(local_path: str | Path, guest_path: str) -> None
Copies a file from your machine into the sandbox.

​
pull_file

def pull_file(guest_path: str, local_path: str | Path) -> Path
Copies a file from the sandbox to your machine.

​
collect_artifacts

def collect_artifacts() -> Path | None
Collects guest logs, downloads, and recordings into artifacts_dir. Returns the archive path when artifacts are available.

​
logs

def logs(tail: int = 100) -> str
Returns recent host and guest logs for the sandbox.

​
Example

display_sandbox.py
from smolvm import SmolVM

with SmolVM.browser(headless=False) as browser:
    print(browser.session_id)
    print(browser.cdp_url)
    print(browser.viewer_url)
    print(browser.display_url)
Last modified on June 12, 2026