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 toSmolVM.browser() or SmolVM.desktop().
Import
Common options
str
default:"auto"
Runtime backend. Options are
"firecracker", "qemu", "libkrun", and "auto".str | None
default:"None"
Existing sandbox ID to reconnect to. Omit it to create a new sandbox.
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.
bool
default:"False"
Keep the sandbox record after the current Python process exits. This lets another process reconnect with
session_id.int
default:"30"
Maximum session lifetime in minutes.
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 and display services to become ready.
dict[str, str] | None
default:"None"
Environment variables to set inside the sandbox.
list[WorkspaceMount] | None
default:"None"
Folders to share with the sandbox.
Advanced local options
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.
Browser-only option
bool
default:"True"
SmolVM.browser() only. Use True for CDP-only browser automation. Use False to also start viewer_url and display_url.Display and artifact options
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 browser sandbox.
BrowserViewport
BrowserViewport is a small helper for screen dimensions.
int
default:"1280"
Screen width in pixels.
int
default:"720"
Screen height in pixels.
Examples
Larger visible browser
larger_browser.py
Persistent browser profile
browser_profile.py
profile_id again when you want Chromium to reuse saved browser state.
Full desktop with a larger screen
desktop_viewport.py
Related
- Browser and desktop sandboxes - Start browser and desktop modes
- Display sandbox object - Read returned URLs and lifecycle state