Desktop

JavaScript examples use @beamcloud/beam-js 1.1.0 or later. Configure the SDK before running them.

Open a desktop

Create a desktop VM using the default Ubuntu 24.04 image:

beam vm new desktop-dev
beam vm desktop desktop-dev

CLI creation includes a desktop for fresh images; use --no-desktop to skip it. In Python or JavaScript, set desktop=True or desktop: true at creation. Custom desktop images support Ubuntu 24.04 (Noble) and 22.04 (Jammy). 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, protected by default on new VMs. The CLI opens a fresh entry session. See networking for protection toggles. 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 1024 MiB RAM (1 GiB). 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

Python
JavaScript

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

const vm = await VM.connect("desktop-dev");
await vm.wait({ services: true });
console.log(await vm.desktop.screenSize());
await vm.desktop.resize(1920, 1080);
const png = await vm.desktop.screenshot("desktop.png");
console.log(png.length);

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 in Python and vm.desktopUrl in JavaScript return the stable desktop URL. Use vm.access_url(8080) in Python or await vm.accessUrl(8080) in JavaScript for an authenticated entry session when the port is protected.

Mouse and keyboard control

Python
JavaScript

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

const vm = await VM.connect("desktop-dev");
await vm.desktop.moveMouse(200, 150);
await vm.desktop.click({ x: 200, y: 150, button: "left", count: 2 });
await vm.desktop.press("ctrl+l");
await vm.desktop.write("https://www.beam.cloud");
await vm.desktop.press("Return");
await vm.desktop.scroll({ direction: "down", amount: 3 });
await vm.desktop.drag({ x: 200, y: 150 }, { x: 400, y: 300 });

Coordinates refer to guest display pixels. press() uses X11 key names such as Return, ctrl+l, and alt+Tab. write() pastes text with Ctrl+V, so focus a field that supports that shortcut. Use the process API to run terminal commands. 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 get its process handle:

Python
JavaScript

from beam import VM

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

const vm = await VM.connect("desktop-dev");
const terminal = await vm.desktop.launch(["xterm"]);
console.log(terminal.pid);

Record the guest screen

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

Python
JavaScript

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")

const vm = await VM.connect("desktop-dev");
await vm.keepAlive(async () => {
  const recording = await vm.desktop.record("/workspace/session.mp4", {
    fps: 30,
  });
  try {
    await new Promise((resolve) => setTimeout(resolve, 5000));
  } finally {
    await vm.desktop.stopRecording(recording);
  }
  await vm.fs.downloadFile("/workspace/session.mp4", "session.mp4");
});
await vm.close();

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 stop/start or pause/resume; request 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

Start Here

Virtual Machines

Sandboxes

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Open a desktop

Screenshot and resolution

Mouse and keyboard control

Record the guest screen

Desktop lifecycle

​Open a desktop

​Screenshot and resolution

​Mouse and keyboard control

​Record the guest screen

​Desktop lifecycle

Open a desktop

Screenshot and resolution

Mouse and keyboard control

Record the guest screen

Desktop lifecycle