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:

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:

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

beam vm screenshot desktop-dev ./desktop.png

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

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:

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:

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 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:

beam vm logs desktop-dev --unit beam-desktop.service
beam vm exec desktop-dev -- systemctl status beam-desktop.service