computers.md

Run a computer with a desktop

A computer with a desktop gives an agent a visible Linux screen with Chromium, a terminal, a file manager, and a text editor. Use it when the work spans more than one desktop application or when a person needs to watch and take control.

Choose the right resource

Use the smallest option that fits the job:

Need	Use
Run commands or code	A minimal computer
Automate websites through Chromium	A browser session
Work across a visible desktop and its applications	A computer with a desktop

A computer with a desktop includes Chromium, but a browser session is the simpler choice for web-only work.

Celesto downloads the Linux desktop image on first use and verifies its checksum. Later starts reuse the cached image, so applications do not need Docker to create a computer.

Start and view a computer

Start the built-in Linux desktop template:

celesto computer create --desktop --name assistant

The command prints the computer's viewer URL. Open it later by name:

celesto computer open assistant

List available templates and your computers with a desktop:

celesto computer templates
celesto computer list --desktop

Delete the computer when the work is finished:

celesto computer delete assistant --desktop

Deletion removes the computer and its temporary files.

Use it from Python

The returned object groups each capability by what it controls. display is for people or visual-control tools. browser is for Chromium automation. files and run() operate as the same unprivileged user who owns the desktop.

from celesto import Celesto

with Celesto.computer() as computer:
    print(computer.display.viewer_url)
    print(computer.browser.cdp_url)
    computer.files.write("/workspace/task.txt", "Review this file")
    result = computer.run("ls -la /workspace")
    print(result.stdout)

CDP is Chrome DevTools Protocol, the local address automation libraries use to control Chromium. It can be absent if a person closes Chromium without closing the computer. Start it again with:

computer.browser.launch()

Use it from TypeScript

import { Celesto } from "@celestoai/celesto";

const celesto = new Celesto({ runtimePath: "celesto" });
const computer = await celesto.computers.create();

try {
  console.log(computer.display.viewerUrl);
  console.log(computer.browser.cdpUrl);
  await computer.files.write("/workspace/task.txt", "Review this file");
  const result = await computer.exec("ls -la /workspace");
  console.log(result.stdout);
} finally {
  await celesto.close();
}

If Chromium was closed, open it again without replacing the computer:

await computer.browser.launch();
console.log(computer.browser.cdpUrl);

What is included

The linux-desktop template includes Chromium, LXTerminal, PCManFM, Mousepad, Tint2, Openbox, Git, Wget, SSH tools, jq, Zip, and Unzip. It is intentionally small rather than a full GNOME or KDE installation.

Viewer and CDP addresses listen only on your machine and include secret access tokens. Keep the complete URLs in trusted application code. Raw VNC addresses are unavailable; use the authenticated viewer. See secure local access for connection and upgrade requirements.