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

> ## Agent Instructions
> Install the Beam CLI, sign in, and connect coding agents to the Beam MCP server with `curl -fsSL https://www.beam.cloud/install | sh`. To also create a VM, run `curl -fsSL https://www.beam.cloud/install | sh -s -- --vm`.
> VMs are persistent Linux machines without GPUs. Defaults: 4 CPUs, 8 GiB of RAM, a 50 GiB disk, Ubuntu 24.04, and a browser desktop. A running VM accrues usage until you stop, pause, or remove it, or until an idle timeout puts it to sleep.
> Stopping a VM keeps its disk and discards RAM and processes. Pausing keeps both, and resuming restores them. To pause after 5 idle minutes and wake on access, run `beam vm update NAME --ttl 300 --idle-action pause --auto-resume`.
> Core VM commands: `beam vm new NAME`, `beam vm ssh NAME`, `beam vm sync NAME ./dir`, `beam vm exec NAME -- CMD`, `beam vm expose NAME PORT --protected`, `beam vm fork NAME NEW_NAME`, `beam vm pause NAME`, `beam vm stop NAME`, `beam vm rm NAME`.
> For GPUs, use a sandbox or a deployed endpoint. Sandboxes are disposable environments that boot in seconds and fork from snapshots.
> Current rates are at https://www.beam.cloud/pricing.

# Desktop

> Use a Linux desktop in your browser and automate it through Python or JavaScript

JavaScript examples use `@beamcloud/beam-js` 1.1.0 or later. [Configure the SDK](https://docs.beam.cloud/v2/vm/sdk.md#installation-and-configuration) before running them.

## Open a desktop

Create a desktop VM using the default Ubuntu 24.04 image:

```bash theme={null}
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](https://docs.beam.cloud/v2/vm/networking.md#protect-a-published-port) for protection toggles. 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 **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

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

> [tab] Python
>
> ```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))
> ```

> [tab] JavaScript
>
> ```javascript theme={null}
> 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

> [tab] Python
>
> ```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))
> ```

> [tab] JavaScript
>
> ```javascript theme={null}
> 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](https://docs.beam.cloud/v2/vm/processes.md) 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:

> [tab] Python
>
> ```python theme={null}
> from beam import VM
>
> with VM.connect("desktop-dev") as vm:
>     terminal = vm.desktop.launch("xterm")
>     print(terminal.pid)
> ```

> [tab] JavaScript
>
> ```javascript theme={null}
> 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:

> [tab] Python
>
> ```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")
> ```

> [tab] JavaScript
>
> ```javascript theme={null}
> 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](https://docs.beam.cloud/v2/vm/lifecycle.md#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 stop/start or pause/resume; request 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.