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

# Browser and desktop sandboxes

> Start browser and desktop sandboxes with Celesto.browser() and Celesto.desktop(), then connect automation tools or open a live viewer.

## Overview

Celesto 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 `Celesto.browser()` when your agent needs Chromium for web tasks. Use `Celesto.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

```python theme={null}
from celesto import Celesto
```

## Choose a mode

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

> [!TIP]
>
> CDP (Chrome DevTools Protocol, a local connection address used by Playwright and browser automation tools) is for browser automation. VNC (Virtual Network Computing, a standard way for tools and viewers to control a remote screen) 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.

```python browser_headless.py theme={null}
from celesto import Celesto

with Celesto.browser(headless=True) as browser:
    print(browser.cdp_url)
```

**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.

```python browser_visible.py theme={null}
from celesto import Celesto

with Celesto.browser(headless=False) as browser:
    print(browser.cdp_url)
    print(browser.viewer_url)
    print(browser.display_url)
```

**viewer\_url** `str`

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

**display\_url** `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.

```python desktop.py theme={null}
from celesto import Celesto

with Celesto.desktop() as desktop:
    print(desktop.viewer_url)
    print(desktop.display_url)
```

> [!NOTE]
>
> Desktop sandboxes focus on screen access. They return `None` for `cdp_url`; use `Celesto.browser()` when you need a browser automation address.

## Class methods

### Celesto.browser

```python theme={null} theme={null}
@classmethod
Celesto.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.

**headless** `bool` (default: True)

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

**session\_id** `str | None` (default: None)

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

**backend** `str` (default: auto)

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

**profile\_id** `str | None` (default: None)

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

**persistent** `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`.

**timeout\_minutes** `int` (default: 30)

Maximum session lifetime in minutes.

**viewport** `BrowserViewport | dict | None` (default: None)

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

**viewport\_width** `int` (default: 1280)

Screen width in pixels when `viewport` is omitted.

**viewport\_height** `int` (default: 720)

Screen height in pixels when `viewport` is omitted.

**record\_video** `bool` (default: False)

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

**allow\_downloads** `bool` (default: True)

Allow Chromium downloads inside the sandbox.

**env\_vars** `dict[str, str] | None` (default: None)

Environment variables to set inside the sandbox.

**workspace\_mounts** `list[WorkspaceMount] | None` (default: None)

Folders to share with the sandbox.

**memory\_mb** `int` (default: 2048)

Guest memory in MiB.

**disk\_size\_mb** `int` (default: 4096)

Root filesystem size in MiB.

**boot\_timeout** `float` (default: 90.0)

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

**data\_dir** `Path | None` (default: None)

Local directory for sandbox state. Omit it to use Celesto's default state directory.

**socket\_dir** `Path | None` (default: None)

Local directory for runtime sockets. Omit it to use Celesto's default socket directory.

**ssh\_key\_path** `str | None` (default: None)

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

**on\_progress** `Callable[[str], None] | None` (default: None)

Callback that receives progress messages while the sandbox starts.

### Celesto.desktop

```python theme={null} theme={null}
@classmethod
Celesto.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 `Celesto.browser()`.

## Use Playwright with browser mode

```python playwright_browser.py theme={null}
from celesto import Celesto

with Celesto.browser(headless=True) as sandbox:
    browser = sandbox.connect_playwright()
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()
```

> [!NOTE]
>
> Install Playwright in your local Python environment before using `connect_playwright()`: `pip install playwright`.

## Related

* [Browser and desktop options](https://celesto.ai/docs/celesto/api/browsersessionconfig.md) - Configure viewport, resources, profiles, and recording
* [Display sandbox object](https://celesto.ai/docs/celesto/api/browsersessioninfo.md) - Read returned URLs and lifecycle state
* [Celesto](https://celesto.ai/docs/celesto/api/celesto.md) - General sandbox management
* [AI agent integration](https://celesto.ai/docs/celesto/guides/ai-agent-integration.md) - Use Celesto with agent frameworks


## Related topics

- [Framework Integration](https://celesto.ai/docs/celesto/guides/ai-agent-integration.md)
- [Browser sandboxes](https://celesto.ai/docs/celesto/features/browser-sandboxes.md)
- [Browser and desktop options](https://celesto.ai/docs/celesto/api/browsersessionconfig.md)
- [Display sandbox object](https://celesto.ai/docs/celesto/api/browsersessioninfo.md)
- [Celesto Python class reference](https://celesto.ai/docs/celesto/api/celesto.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.