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

# Desktop

> Use a Linux desktop in your browser and automate it through the Python SDK

## Open a desktop

Create a desktop VM using the default Ubuntu 22.04 image:

```bash theme={null}
beam vm new desktop-dev --desktop --protected-port 8080 --protected-port 7681
beam vm desktop desktop-dev
```

The desktop has a browser and Terminal launcher. On x86-64, the browser is Chrome; on ARM64 it is Firefox. Applications and user files live on the durable root.

Desktop access uses port **8080**. The CLI opens a fresh entry session for a protected desktop. To print the entry URL:

```bash theme={null}
beam vm desktop desktop-dev --url
beam vm terminal desktop-dev --url
```

You can also open the desktop from the VM's dashboard detail page. Keep its browser session private: desktop and terminal access run programs as root inside the VM.

A desktop requires at least **2048 MiB RAM**. The browser viewer resizes the guest display to its viewport. A larger display or video workload needs more CPU and bandwidth; VMs do not provide GPU acceleration.

## Screenshot and resolution

```bash theme={null}
beam vm screenshot desktop-dev ./desktop.png
```

```python theme={null}
from beam import VM

with VM.connect("desktop-dev") as vm:
    vm.wait(services=True)
    print(vm.desktop.screen_size())
    vm.desktop.resize(1920, 1080)
    png = vm.desktop.screenshot("desktop.png")
    print(len(png))
```

`screenshot()` returns PNG bytes and optionally saves a file on your local machine. `resize(width, height)` accepts integer widths from **320 to 4096** and heights from **200 to 2160**. The active browser viewer can resize the display again to match its window.

`vm.desktop_url` and `vm.desktop.url` return the stable desktop URL, not an authenticated entry session. Use `vm.access_url(8080)` when the port is protected.

## Mouse and keyboard control

```python theme={null}
from beam import VM

with VM.connect("desktop-dev") as vm:
    vm.desktop.move_mouse(200, 150)
    vm.desktop.click(200, 150, button="left", count=2)
    vm.desktop.press("ctrl+l")
    vm.desktop.write("https://www.beam.cloud")
    vm.desktop.press("Return")
    vm.desktop.scroll("down", amount=3)
    vm.desktop.drag((200, 150), (400, 300))
```

Coordinates refer to guest display pixels. `press()` uses X11 key names such as `Return`, `ctrl+l`, and `alt+Tab`. `write()` pastes literal UTF-8 text. `click()` supports left, middle, and right buttons and counts from 1 to 3; `scroll()` supports up, down, left, and right with 1–100 steps.

Launch a GUI program and keep its managed process handle:

```python theme={null}
from beam import VM

with VM.connect("desktop-dev") as vm:
    terminal = vm.desktop.launch("xterm")
    print(terminal.pid)
```

## Record the guest screen

Record to an absolute path **inside the VM**, stop the recording cleanly, then download it:

```python theme={null}
import time
from beam import VM

with VM.connect("desktop-dev") as vm:
    with vm.keep_alive():
        recording = vm.desktop.record("/workspace/session.mp4", fps=30)
        try:
            time.sleep(5)
        finally:
            vm.desktop.stop_recording(recording)
        vm.fs.download_file("/workspace/session.mp4", "session.mp4")
```

Recording uses CPU encoding, with an FPS setting from **1 to 60**. It is independent of the browser viewer's frame rate. Use a new output path for each recording; existing files are not overwritten. Finish or stop the recording before stopping, pausing, or restarting the VM.

## Desktop lifecycle

Use [pause/resume](/v2/vm/lifecycle#pause-and-resume) to retain open applications in RAM. Stop/start boots a new desktop session while keeping installed software, launcher files, and user data. Reopen the desktop after a lifecycle operation, and generate a new entry URL if the protected session has expired.

For service diagnostics:

```bash theme={null}
beam vm logs desktop-dev --unit beam-desktop.service
beam vm exec desktop-dev -- systemctl status beam-desktop.service
```


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