> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser and desktop options

> Options for SmolVM.browser() and SmolVM.desktop(), including viewport size, profiles, recording, resources, and shared folders.

## 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 to `SmolVM.browser()` or `SmolVM.desktop()`.

## Import

```python theme={null}
from smolvm import BrowserViewport, SmolVM
```

## Common options

<ParamField path="backend" type="str" default="auto">
  Runtime backend. Options are `"firecracker"`, `"qemu"`, `"libkrun"`, and `"auto"`.
</ParamField>

<ParamField path="session_id" type="str | None" default="None">
  Existing sandbox ID to reconnect to. Omit it to create a new sandbox.
</ParamField>

<ParamField path="profile_id" type="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.
</ParamField>

<ParamField path="persistent" type="bool" default="False">
  Keep the sandbox record after the current Python process exits. This lets another process reconnect with `session_id`.
</ParamField>

<ParamField path="timeout_minutes" type="int" default="30">
  Maximum session lifetime in minutes.
</ParamField>

<ParamField path="memory_mb" type="int" default="2048">
  Guest memory in MiB.
</ParamField>

<ParamField path="disk_size_mb" type="int" default="4096">
  Root filesystem size in MiB.
</ParamField>

<ParamField path="boot_timeout" type="float" default="90.0">
  Maximum seconds to wait for the sandbox and display services to become ready.
</ParamField>

<ParamField path="env_vars" type="dict[str, str] | None" default="None">
  Environment variables to set inside the sandbox.
</ParamField>

<ParamField path="workspace_mounts" type="list[WorkspaceMount] | None" default="None">
  Folders to share with the sandbox.
</ParamField>

## Advanced local options

<ParamField path="data_dir" type="Path | None" default="None">
  Local directory for sandbox state. Omit it to use SmolVM's default state directory.
</ParamField>

<ParamField path="socket_dir" type="Path | None" default="None">
  Local directory for runtime sockets. Omit it to use SmolVM's default socket directory.
</ParamField>

<ParamField path="ssh_key_path" type="str | None" default="None">
  SSH private key path used for setup and file transfer inside the sandbox.
</ParamField>

<ParamField path="on_progress" type="Callable[[str], None] | None" default="None">
  Callback that receives progress messages while the sandbox starts.
</ParamField>

## Browser-only option

<ParamField path="headless" type="bool" default="True">
  `SmolVM.browser()` only. Use `True` for CDP-only browser automation. Use `False` to also start `viewer_url` and `display_url`.
</ParamField>

<Tip>
  CDP means Chrome DevTools Protocol, the browser connection used by Playwright and similar automation tools.
</Tip>

## Display and artifact options

<ParamField path="viewport" type="BrowserViewport | dict | None" default="None">
  Browser or desktop screen size. You can pass `BrowserViewport(width=1440, height=900)` or `{"width": 1440, "height": 900}`.
</ParamField>

<ParamField path="viewport_width" type="int" default="1280">
  Screen width in pixels when `viewport` is omitted.
</ParamField>

<ParamField path="viewport_height" type="int" default="720">
  Screen height in pixels when `viewport` is omitted.
</ParamField>

<ParamField path="record_video" type="bool" default="False">
  Record the visible session. Retrieve recordings with `collect_artifacts()` before the sandbox stops.
</ParamField>

<ParamField path="allow_downloads" type="bool" default="True">
  Allow Chromium downloads inside the browser sandbox.
</ParamField>

## BrowserViewport

`BrowserViewport` is a small helper for screen dimensions.

```python theme={null}
from smolvm import BrowserViewport
```

<ParamField path="width" type="int" default="1280">
  Screen width in pixels.
</ParamField>

<ParamField path="height" type="int" default="720">
  Screen height in pixels.
</ParamField>

## Examples

### Larger visible browser

```python larger_browser.py theme={null}
from smolvm import BrowserViewport, SmolVM

with SmolVM.browser(
    headless=False,
    viewport=BrowserViewport(width=1440, height=900),
    memory_mb=3072,
) as browser:
    print(browser.viewer_url)
```

### Persistent browser profile

```python browser_profile.py theme={null}
from smolvm import SmolVM

with SmolVM.browser(profile_id="daily-reports", persistent=True) as browser:
    print(browser.cdp_url)
```

Use the same `profile_id` again when you want Chromium to reuse saved browser state.

### Full desktop with a larger screen

```python desktop_viewport.py theme={null}
from smolvm import SmolVM

with SmolVM.desktop(viewport={"width": 1440, "height": 900}) as desktop:
    print(desktop.viewer_url)
    print(desktop.display_url)
```

## Related

* [Browser and desktop sandboxes](/smolvm/api/browsersession) - Start browser and desktop modes
* [Display sandbox object](/smolvm/api/browsersessioninfo) - Read returned URLs and lifecycle state