Browser and desktop sandboxes

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

Factory	Best for	URLs returned
`SmolVM.browser(headless=True)`	Browser automation with Playwright or another automation client	`cdp_url`
`SmolVM.browser(headless=False)`	Browser automation plus a visible screen	`cdp_url`, `viewer_url`, `display_url`
`SmolVM.desktop()`	Full desktop computer-use agents	`viewer_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)

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)

str

Web URL you can open in your own browser to watch or interact with the sandbox screen.

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.

bool

default:"True"

Use True for browser automation only. Use False to also start the visible viewer and VNC display endpoint.

str | None

default:"None"

Existing browser sandbox ID to reconnect to. Omit it to create a new sandbox.

str

default:"auto"

Runtime backend. Options are "firecracker", "qemu", "libkrun", and "auto".

str | None

default:"None"

Browser profile name. Reuse a profile ID to keep browser state such as cookies and local storage across persistent sessions.

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.

int

default:"30"

Maximum session lifetime in minutes.

BrowserViewport | dict | None

default:"None"

Browser or desktop screen size. You can pass BrowserViewport(width=1440, height=900) or {"width": 1440, "height": 900}.

int

default:"1280"

Screen width in pixels when viewport is omitted.

int

default:"720"

Screen height in pixels when viewport is omitted.

bool

default:"False"

Record the visible session. Retrieve recordings with collect_artifacts() before the sandbox stops.

bool

default:"True"

Allow Chromium downloads inside the sandbox.

dict[str, str] | None

default:"None"

Environment variables to set inside the sandbox.

list[WorkspaceMount] | None

default:"None"

Folders to share with the sandbox.

int

default:"2048"

Guest memory in MiB.

int

default:"4096"

Root filesystem size in MiB.

float

default:"90.0"

Maximum seconds to wait for the sandbox, display services, and browser to become ready.

Path | None

default:"None"

Local directory for sandbox state. Omit it to use SmolVM’s default state directory.

Path | None

default:"None"

Local directory for runtime sockets. Omit it to use SmolVM’s default socket directory.

str | None

default:"None"

SSH private key path used for setup and file transfer inside the sandbox.

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.

Browser and desktop options - Configure viewport, resources, profiles, and recording
Display sandbox object - Read returned URLs and lifecycle state
SmolVM - General sandbox management
AI agent integration - Use SmolVM with agent frameworks

Celesto CLI

SmolVM API

SmolVM CLI

Agentor API

Browser and desktop sandboxes

Overview

Import

Choose a mode

Start a headless browser

Start a visible browser

Start a full desktop

Class methods

SmolVM.browser

SmolVM.desktop

Use Playwright with browser mode

​Overview

​Import

​Choose a mode

​Start a headless browser

​Start a visible browser

​Start a full desktop

​Class methods

​SmolVM.browser

​SmolVM.desktop

​Use Playwright with browser mode

​Related

Overview

Import

Choose a mode

Start a headless browser

Start a visible browser

Start a full desktop

Class methods

SmolVM.browser

SmolVM.desktop

Use Playwright with browser mode

Related