Skip to content
Leap0 Leap0 Leap0

DesktopClient

Source: leap0/_sync/desktop.py

Signature

Section titled “Signature”
DesktopClient(transport: Transport, *, sandbox_domain: str | None = None)

Overview

Section titled “Overview”

Control a graphical Linux desktop inside a sandbox.

Requires a sandbox created with the :data:~leap0.constants.DEFAULT_DESKTOP_TEMPLATE_NAME (system/desktop:v0.1.0) template. Provides display info, screenshots, mouse/keyboard input, and screen recording.

Attributes: None.

Methods

Section titled “Methods”

desktop_url

Section titled “desktop_url”
desktop_url(sandbox: SandboxRef) -> str

Build the browser URL for the noVNC desktop viewer.

Args: sandbox: Sandbox ID or object.

Returns: object: Result returned by this operation.

display_info

Section titled “display_info”
display_info(sandbox: SandboxRef, http_timeout: float | None = None) -> DesktopDisplayInfo

Get display information (display name, width, height).

Args: sandbox: Sandbox ID or object.

Returns: object: Result returned by this operation.

screen

Section titled “screen”
screen(sandbox: SandboxRef, http_timeout: float | None = None) -> DesktopDisplayInfo

Get the current screen resolution.

Args: sandbox: Sandbox ID or object.

Returns: object: Result returned by this operation.

resize_screen

Section titled “resize_screen”
resize_screen(sandbox: SandboxRef, *, width: int, height: int, http_timeout: float | None = None) -> DesktopDisplayInfo

Resize the virtual display (width: 320-7680, height: 320-4320).

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

windows

Section titled “windows”
windows(sandbox: SandboxRef, http_timeout: float | None = None) -> list[DesktopWindow]

List all open windows on the desktop.

Args: sandbox: Sandbox ID or object.

Returns: object: Result returned by this operation.

screenshot

Section titled “screenshot”
screenshot(sandbox: SandboxRef, *, image_format: str | None = None, quality: int | None = None, x: int | None = None, y: int | None = None, width: int | None = None, height: int | None = None, http_timeout: float | None = None) -> bytes

Take a screenshot and return the image as bytes.

Args: sandbox: Sandbox ID or object. image_format: "png", "jpg", or "jpeg" (default "png"). quality: JPEG quality (1-100). x: Left edge of capture region. y: Top edge of capture region. width: Region width in pixels. height: Region height in pixels. http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

screenshot_region

Section titled “screenshot_region”
screenshot_region(sandbox: SandboxRef, *, x: int, y: int, width: int, height: int, image_format: str | None = None, quality: int | None = None, http_timeout: float | None = None) -> bytes

Take a screenshot of a specific region and return the image as bytes.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

pointer_position

Section titled “pointer_position”
pointer_position(sandbox: SandboxRef, http_timeout: float | None = None) -> DesktopPointerPosition

Get the current mouse pointer position.

Args: sandbox: Sandbox ID or object.

Returns: object: Result returned by this operation.

move_pointer

Section titled “move_pointer”
move_pointer(sandbox: SandboxRef, *, x: int, y: int, http_timeout: float | None = None) -> DesktopPointerPosition

Move the mouse pointer to the given coordinates.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

click

Section titled “click”
click(sandbox: SandboxRef, *, x: int | None = None, y: int | None = None, button: int | None = None, http_timeout: float | None = None) -> DesktopPointerPosition

Click the mouse. Clicks at the current position if coordinates are omitted.

Args: sandbox: Sandbox ID or object. x: X coordinate. y: Y coordinate. button: 1=left, 2=middle, 3=right (default 1). http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

drag

Section titled “drag”
drag(sandbox: SandboxRef, *, from_x: int, from_y: int, to_x: int, to_y: int, button: int | None = None, http_timeout: float | None = None) -> DesktopPointerPosition

Drag from one position to another.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

scroll

Section titled “scroll”
scroll(sandbox: SandboxRef, *, direction: str, amount: int | None = None, http_timeout: float | None = None) -> DesktopPointerPosition

Scroll the mouse wheel.

Args: sandbox: Sandbox ID or object. direction: "up", "down", "left", or "right". amount: Number of scroll steps (1-100, default 1). http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

type_text

Section titled “type_text”
type_text(sandbox: SandboxRef, *, text: str, http_timeout: float | None = None) -> bool

Type text using simulated keyboard input (max 50,000 characters).

Args: sandbox: Sandbox ID or object. text: Parameter for this operation.

Returns: object: Result returned by this operation.

press_key

Section titled “press_key”
press_key(sandbox: SandboxRef, *, key: str, http_timeout: float | None = None) -> bool

Press a single key by X11 keysym name (e.g. "Return", "Escape").

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

hotkey

Section titled “hotkey”
hotkey(sandbox: SandboxRef, *, keys: list[str], http_timeout: float | None = None) -> bool

Press multiple keys simultaneously (e.g. ["Control_L", "c"]).

Args: sandbox: Sandbox ID or object. keys: Parameter for this operation.

Returns: object: Result returned by this operation.

recording_status

Section titled “recording_status”
recording_status(sandbox: SandboxRef, http_timeout: float | None = None) -> DesktopRecordingStatus

Get the current screen recording status.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

start_recording

Section titled “start_recording”
start_recording(sandbox: SandboxRef, http_timeout: float | None = None) -> DesktopRecordingStatus

Start recording the screen. Returns 409 if a recording is already active.

Args: sandbox: Sandbox ID or object.

Returns: object: Result returned by this operation.

stop_recording

Section titled “stop_recording”
stop_recording(sandbox: SandboxRef, http_timeout: float | None = None) -> DesktopRecordingStatus

Stop the active screen recording.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

recordings

Section titled “recordings”
recordings(sandbox: SandboxRef, http_timeout: float | None = None) -> list[DesktopRecordingSummary]

List all screen recordings.

Args: sandbox: Sandbox ID or object.

Returns: object: Result returned by this operation.

get_recording

Section titled “get_recording”
get_recording(sandbox: SandboxRef, recording_id: str, http_timeout: float | None = None) -> DesktopRecordingSummary

Get details for a single recording.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

download_recording

Section titled “download_recording”
download_recording(sandbox: SandboxRef, recording_id: str, http_timeout: float | None = None) -> bytes

Download a recording as MP4 bytes.

Args: sandbox: Sandbox ID or object. recording_id: Recording identifier.

Returns: object: Result returned by this operation.

delete_recording

Section titled “delete_recording”
delete_recording(sandbox: SandboxRef, recording_id: str, http_timeout: float | None = None) -> None

Delete a recording. Cannot delete an active recording.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

health

Section titled “health”
health(sandbox: SandboxRef, http_timeout: float | None = None) -> DesktopHealth

Check the health of the desktop environment.

Args: sandbox: Sandbox ID or object.

Returns: object: Result returned by this operation.

process_status

Section titled “process_status”
process_status(sandbox: SandboxRef, http_timeout: float | None = None) -> DesktopProcessStatusList

Get the status of all desktop processes (xvfb, xfce4, x11vnc, novnc).

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

get_process

Section titled “get_process”
get_process(sandbox: SandboxRef, process_name: str, http_timeout: float | None = None) -> DesktopProcessStatus

Get the status of a single desktop process by name.

Args: sandbox: Sandbox ID or object. process_name: Desktop process name.

Returns: object: Result returned by this operation.

restart_process

Section titled “restart_process”
restart_process(sandbox: SandboxRef, process_name: str, http_timeout: float | None = None) -> DesktopProcessRestart

Restart a desktop process.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

process_logs

Section titled “process_logs”
process_logs(sandbox: SandboxRef, process_name: str, http_timeout: float | None = None) -> DesktopProcessLogs

Get stdout logs for a desktop process.

Args: sandbox: Sandbox ID or object. process_name: Desktop process name.

Returns: object: Result returned by this operation.

process_errors

Section titled “process_errors”
process_errors(sandbox: SandboxRef, process_name: str, http_timeout: float | None = None) -> DesktopProcessErrors

Get stderr logs for a desktop process.

Args: http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Returns: object: Result returned by this operation.

status_stream

Section titled “status_stream”
status_stream(sandbox: SandboxRef, *, deadline: float | None = None, http_timeout: float | None = None) -> Iterator[DesktopProcessStatusList]

Subscribe to a live SSE stream of process status updates.

Args: sandbox: Sandbox ID or object. deadline: Absolute time.monotonic() deadline. When set, a :class:Leap0TimeoutError is raised once the deadline is exceeded. None means no deadline. http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Yields: object: Items yielded by this operation.

wait_until_ready

Section titled “wait_until_ready”
wait_until_ready(sandbox: SandboxRef, *, timeout: float = 60.0, http_timeout: float | None = None) -> None

Block until all desktop processes are running.

Connects to the SSE status stream and waits for the aggregate status to become "running" (all four desktop processes alive). Automatically retries the stream connection on transient errors using exponential back-off, bounded by timeout seconds total.

Args: sandbox: Sandbox ID or object. timeout: Maximum seconds to wait (default 60).

http_timeout: Optional HTTP request timeout in seconds for this SDK call.

Throws

Section titled “Throws”
  • Leap0TimeoutError: If the desktop does not become ready within timeout seconds.