Display sandbox object

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)

Browser and desktop sandboxes - Start browser and desktop modes
Browser and desktop options - Configure viewport, resources, profiles, and recording

Celesto CLI

SmolVM API

SmolVM CLI

Agentor API

Display sandbox object

Overview

URLs and identifiers

Lifecycle methods

stop

delete

close

open_viewer

Browser helpers

connect_playwright

screenshot

push_file

pull_file

collect_artifacts

logs

Example

​Overview

​URLs and identifiers

​Lifecycle methods

​stop

​delete

​close

​open_viewer

​Browser helpers

​connect_playwright

​screenshot

​push_file

​pull_file

​collect_artifacts

​logs

​Example

​Related

Overview

URLs and identifiers

Lifecycle methods

stop

delete

close

open_viewer

Browser helpers

connect_playwright

screenshot

push_file

pull_file

collect_artifacts

logs

Example

Related