ComputerUse

class ComputerUse()

Computer Use functionality for interacting with the desktop environment.

Provides access to mouse, keyboard, screenshot, display, recording, and accessibility operations for automating desktop interactions within a sandbox.

Attributes:

mouse Mouse - Mouse operations interface.
keyboard Keyboard - Keyboard operations interface.
screenshot Screenshot - Screenshot operations interface.
display Display - Display operations interface.
recording RecordingService - Screen recording operations interface.
accessibility Accessibility - Accessibility operations interface.

ComputerUse.start

@intercept_errors(message_prefix="Failed to start computer use: ")
@with_instrumentation()
def start(request_timeout: float | None = None) -> ComputerUseStartResponse

Starts all computer use processes (Xvfb, xfce4, x11vnc, novnc).

Arguments:

request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

ComputerUseStartResponse - Computer use start response.

Example:

result = sandbox.computer_use.start()
print("Computer use processes started:", result.message)

ComputerUse.stop

@intercept_errors(message_prefix="Failed to stop computer use: ")
@with_instrumentation()
def stop(request_timeout: float | None = None) -> ComputerUseStopResponse

Stops all computer use processes.

Arguments:

request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

ComputerUseStopResponse - Computer use stop response.

Example:

result = sandbox.computer_use.stop()
print("Computer use processes stopped:", result.message)

ComputerUse.get_status

@intercept_errors(message_prefix="Failed to get computer use status: ")
@with_instrumentation()
def get_status(
        request_timeout: float | None = None) -> ComputerUseStatusResponse

Gets the status of all computer use processes.

Arguments:

request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

ComputerUseStatusResponse - Status information about all VNC desktop processes.

Example:

response = sandbox.computer_use.get_status()
print("Computer use status:", response.status)

ComputerUse.get_process_status

@intercept_errors(message_prefix="Failed to get process status: ")
@with_instrumentation()
def get_process_status(
        process_name: str,
        request_timeout: float | None = None) -> ProcessStatusResponse

Gets the status of a specific VNC process.

Arguments:

process_name str - Name of the process to check.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

ProcessStatusResponse - Status information about the specific process.

Example:

xvfb_status = sandbox.computer_use.get_process_status("xvfb")
no_vnc_status = sandbox.computer_use.get_process_status("novnc")

ComputerUse.restart_process

@intercept_errors(message_prefix="Failed to restart process: ")
@with_instrumentation()
def restart_process(
        process_name: str,
        request_timeout: float | None = None) -> ProcessRestartResponse

Restarts a specific VNC process.

Arguments:

process_name str - Name of the process to restart.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

ProcessRestartResponse - Process restart response.

Example:

result = sandbox.computer_use.restart_process("xfce4")
print("XFCE4 process restarted:", result.message)

ComputerUse.get_process_logs

@intercept_errors(message_prefix="Failed to get process logs: ")
@with_instrumentation()
def get_process_logs(
        process_name: str,
        request_timeout: float | None = None) -> ProcessLogsResponse

Gets logs for a specific VNC process.

Arguments:

process_name str - Name of the process to get logs for.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

ProcessLogsResponse - Process logs.

Example:

logs = sandbox.computer_use.get_process_logs("novnc")
print("NoVNC logs:", logs)

ComputerUse.get_process_errors

@intercept_errors(message_prefix="Failed to get process errors: ")
@with_instrumentation()
def get_process_errors(
        process_name: str,
        request_timeout: float | None = None) -> ProcessErrorsResponse

Gets error logs for a specific VNC process.

Arguments:

process_name str - Name of the process to get error logs for.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

ProcessErrorsResponse - Process error logs.

Example:

errors = sandbox.computer_use.get_process_errors("x11vnc")
print("X11VNC errors:", errors)

Mouse

class Mouse()

Mouse operations for computer use functionality.

Mouse.get_position

@intercept_errors(message_prefix="Failed to get mouse position: ")
@with_instrumentation()
def get_position(
        request_timeout: float | None = None) -> MousePositionResponse

Gets the current mouse cursor position.

Arguments:

request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

MousePositionResponse - Current mouse position with x and y coordinates.

Example:

position = sandbox.computer_use.mouse.get_position()
print(f"Mouse is at: {position.x}, {position.y}")

Mouse.move

@intercept_errors(message_prefix="Failed to move mouse: ")
@with_instrumentation()
def move(x: int,
         y: int,
         request_timeout: float | None = None) -> MousePositionResponse

Moves the mouse cursor to the specified coordinates.

Arguments:

x int - The x coordinate to move to.
y int - The y coordinate to move to.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

MousePositionResponse - Position after move.

Example:

result = sandbox.computer_use.mouse.move(100, 200)
print(f"Mouse moved to: {result.x}, {result.y}")

Mouse.down

@intercept_errors(message_prefix="Failed to press mouse button: ")
@with_instrumentation()
def down(x: int | None = None,
         y: int | None = None,
         button: str = "left",
         request_timeout: float | None = None) -> MousePositionResponse

Presses and holds a mouse button until a matching up() call.

Coordinates are optional. When both are provided the cursor moves there before the button is pressed; when omitted the button is pressed wherever the cursor already is.

Arguments:

x int | None - Optional x coordinate to move to before pressing.
y int | None - Optional y coordinate to move to before pressing.
button str - The mouse button to press ('left', 'right', 'middle').
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

MousePositionResponse - Mouse position after the button press.

Example:

# Press at the current cursor position
sandbox.computer_use.mouse.down()

# Move to a point and press the left button, then release it there
sandbox.computer_use.mouse.down(100, 200)
sandbox.computer_use.mouse.up(100, 200)

# Hold modifiers around a drag by using the keyboard endpoints. Release in
# `finally` so a failed press cannot leave Shift stuck down.
sandbox.computer_use.keyboard.down("shift")
try:
    sandbox.computer_use.mouse.down(100, 200)
    sandbox.computer_use.mouse.up(300, 400)
finally:
    sandbox.computer_use.keyboard.up("shift")

Mouse.up

@intercept_errors(message_prefix="Failed to release mouse button: ")
@with_instrumentation()
def up(x: int | None = None,
       y: int | None = None,
       button: str = "left",
       request_timeout: float | None = None) -> MousePositionResponse

Releases a mouse button that is currently held down.

Coordinates are optional. When both are provided the cursor moves there before the button is released, which is how a press-move-release drag is composed manually.

Arguments:

x int | None - Optional x coordinate to move to before releasing.
y int | None - Optional y coordinate to move to before releasing.
button str - The mouse button to release ('left', 'right', 'middle').
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

MousePositionResponse - Mouse position after the button release.

Example:

# Release at the current cursor position
sandbox.computer_use.mouse.up()

# Release the right button at a specific point
result = sandbox.computer_use.mouse.up(300, 400, "right")
print(f"Released at: {result.x}, {result.y}")

Mouse.click

@intercept_errors(message_prefix="Failed to click mouse: ")
@with_instrumentation()
def click(x: int,
          y: int,
          button: str = "left",
          double: bool = False,
          request_timeout: float | None = None,
          *,
          clicks: int | None = None,
          modifiers: list[str] | None = None) -> MouseClickResponse

Clicks the mouse at the specified coordinates.

Arguments:

x int - The x coordinate to click at.
y int - The y coordinate to click at.
button str - The mouse button to click ('left', 'right', 'middle').
double bool - Whether to perform a double-click.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.
clicks int | None - Explicit number of clicks to perform, from 1 to 10. When both clicks and double are given, clicks wins over double, mirroring the API. Omit it to keep the double behavior.
modifiers list[str] | None - Modifier keys to hold for the duration of the click. Canonical modifier names are 'ctrl', 'alt', 'shift', and 'cmd'. Common aliases such as 'control', 'option', 'meta', and 'win' are normalized.

Returns:

MouseClickResponse - Click operation result.

Example:

# Single left click
result = sandbox.computer_use.mouse.click(100, 200)

# Double click
double_click = sandbox.computer_use.mouse.click(100, 200, "left", True)

# Right click
right_click = sandbox.computer_use.mouse.click(100, 200, "right")

# Triple click
triple_click = sandbox.computer_use.mouse.click(100, 200, clicks=3)

# Ctrl+click
ctrl_click = sandbox.computer_use.mouse.click(100, 200, modifiers=["ctrl"])

Mouse.drag

@intercept_errors(message_prefix="Failed to drag mouse: ")
@with_instrumentation()
def drag(start_x: int,
         start_y: int,
         end_x: int,
         end_y: int,
         button: str = "left",
         request_timeout: float | None = None,
         *,
         modifiers: list[str] | None = None) -> MouseDragResponse

Drags the mouse from start coordinates to end coordinates.

Arguments:

start_x int - The starting x coordinate.
start_y int - The starting y coordinate.
end_x int - The ending x coordinate.
end_y int - The ending y coordinate.
button str - The mouse button to use for dragging.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.
modifiers list[str] | None - Modifier keys to hold for the duration of the drag. Canonical modifier names are 'ctrl', 'alt', 'shift', and 'cmd'. Common aliases such as 'control', 'option', 'meta', and 'win' are normalized.

Returns:

MouseDragResponse - Drag operation result.

Example:

result = sandbox.computer_use.mouse.drag(50, 50, 150, 150)
print(f"Drag ended at {result.x}, {result.y}")

# Shift-constrained drag
constrained = sandbox.computer_use.mouse.drag(50, 50, 150, 150, modifiers=["shift"])

Mouse.scroll

@intercept_errors(message_prefix="Failed to scroll mouse: ")
@with_instrumentation()
def scroll(x: int,
           y: int,
           direction: str,
           amount: int = 1,
           request_timeout: float | None = None,
           *,
           modifiers: list[str] | None = None) -> bool

Scrolls the mouse wheel at the specified coordinates.

Arguments:

x int - The x coordinate to scroll at.
y int - The y coordinate to scroll at.
direction str - The direction to scroll ('up', 'down', 'left', or 'right').
amount int - The amount to scroll.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.
modifiers list[str] | None - Modifier keys to hold for the duration of the scroll. Canonical modifier names are 'ctrl', 'alt', 'shift', and 'cmd'. Common aliases such as 'control', 'option', 'meta', and 'win' are normalized.

Returns:

bool - Whether the scroll operation was successful.

Example:

# Scroll up
scroll_up = sandbox.computer_use.mouse.scroll(100, 200, "up", 3)

# Scroll down
scroll_down = sandbox.computer_use.mouse.scroll(100, 200, "down", 5)

# Scroll horizontally
scroll_left = sandbox.computer_use.mouse.scroll(100, 200, "left", 2)

# Ctrl+scroll to zoom
zoom_in = sandbox.computer_use.mouse.scroll(100, 200, "up", 1, modifiers=["ctrl"])

Keyboard

class Keyboard()

Keyboard operations for computer use functionality.

Keyboard.type

@intercept_errors(message_prefix="Failed to type text: ")
@with_instrumentation()
def type(text: str,
         delay: int | None = None,
         request_timeout: float | None = None) -> None

Types the specified text.

Arguments:

text str - The text to type.
delay int - Delay between characters in milliseconds.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Raises:

DaytonaError - If the type operation fails.

Example:

try:
    sandbox.computer_use.keyboard.type("Hello, World!")
    print(f"Operation success")
except Exception as e:
    print(f"Operation failed: {e}")

# With delay between characters
try:
    sandbox.computer_use.keyboard.type("Slow typing", 100)
    print(f"Operation success")
except Exception as e:
    print(f"Operation failed: {e}")

Keyboard.press

@intercept_errors(message_prefix="Failed to press key: ")
@with_instrumentation()
def press(key: str,
          modifiers: list[str] | None = None,
          request_timeout: float | None = None) -> None

Presses a key with optional modifiers.

Arguments:

key str - The key to press. Canonical names include 'enter', 'escape', 'tab', letters, digits, unshifted punctuation, function keys, and grammar-safe numpad names such as 'num_plus'. Named keys are case-insensitive, and common aliases such as 'Return' and 'Escape' are normalized.
modifiers list[str] - Canonical modifier names are 'ctrl', 'alt', 'shift', and 'cmd'. Common aliases such as 'control', 'option', 'meta', and 'win' are normalized.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Raises:

DaytonaError - If the press operation fails.

Example:

# Press Enter
try:
    sandbox.computer_use.keyboard.press("enter")
    print(f"Operation success")
except Exception as e:
    print(f"Operation failed: {e}")

# Press Ctrl+C
try:
    sandbox.computer_use.keyboard.press("c", ["ctrl"])
    print(f"Operation success")

# Press Ctrl+Shift+T
try:
    sandbox.computer_use.keyboard.press("t", ["ctrl", "shift"])
    print(f"Operation success")
except Exception as e:
    print(f"Operation failed: {e}")

Keyboard.hotkey

@intercept_errors(message_prefix="Failed to press hotkey: ")
@with_instrumentation()
def hotkey(keys: str, request_timeout: float | None = None) -> None

Presses a hotkey combination.

Arguments:

keys str - A single atomic hotkey chord (e.g., 'ctrl+c', 'alt+tab', 'cmd+shift+t', 'ctrl + c', 'shift'). Uses the same normalized key contract as press().
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Raises:

DaytonaError - If the hotkey operation fails.

Example:

# Copy
try:
    sandbox.computer_use.keyboard.hotkey("ctrl+c")
    print(f"Operation success")
except Exception as e:
    print(f"Operation failed: {e}")

# Paste
try:
    sandbox.computer_use.keyboard.hotkey("ctrl+v")
    print(f"Operation success")
except Exception as e:
    print(f"Operation failed: {e}")

# Alt+Tab
try:
    sandbox.computer_use.keyboard.hotkey("alt+tab")
    print(f"Operation success")
except Exception as e:
    print(f"Operation failed: {e}")

Keyboard.down

@intercept_errors(message_prefix="Failed to press key down: ")
@with_instrumentation()
def down(key: str, request_timeout: float | None = None) -> None

Presses a key and holds it down until a matching up() call.

This is the building block for held modifiers: press the modifier with down(), perform the mouse or keyboard work, then release it with up().

Arguments:

key str - The key or modifier to hold. Uses the same normalized key contract as press(), so 'ctrl', 'shift', 'alt', 'cmd', letters, digits, and named keys are all accepted and case-insensitive.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Raises:

DaytonaError - If the key down operation fails.

Example:

# Hold Shift across several clicks, then release it
try:
    sandbox.computer_use.keyboard.down("shift")
    sandbox.computer_use.mouse.click(100, 200)
    sandbox.computer_use.mouse.click(100, 300)
finally:
    sandbox.computer_use.keyboard.up("shift")

Keyboard.up

@intercept_errors(message_prefix="Failed to release key: ")
@with_instrumentation()
def up(key: str, request_timeout: float | None = None) -> None

Releases a key that is currently held down.

Arguments:

key str - The key or modifier to release. Uses the same normalized key contract as press().
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Raises:

DaytonaError - If the key up operation fails.

Example:

try:
    sandbox.computer_use.keyboard.up("shift")
    print(f"Operation success")
except Exception as e:
    print(f"Operation failed: {e}")

Screenshot

class Screenshot()

Screenshot operations for computer use functionality.

Screenshot.take_full_screen

@intercept_errors(message_prefix="Failed to take screenshot: ")
@with_instrumentation()
def take_full_screen(
        show_cursor: bool = False,
        request_timeout: float | None = None) -> ScreenshotResponse

Takes a screenshot of the entire screen.

Arguments:

show_cursor bool - Whether to show the cursor in the screenshot.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

ScreenshotResponse - Screenshot data with base64 encoded image.

Example:

screenshot = sandbox.computer_use.screenshot.take_full_screen()
print(f"Screenshot size: {screenshot.width}x{screenshot.height}")

# With cursor visible
with_cursor = sandbox.computer_use.screenshot.take_full_screen(True)

Screenshot.take_region

@intercept_errors(message_prefix="Failed to take region screenshot: ")
@with_instrumentation()
def take_region(region: ScreenshotRegion,
                show_cursor: bool = False,
                request_timeout: float | None = None) -> ScreenshotResponse

Takes a screenshot of a specific region.

Arguments:

region ScreenshotRegion - The region to capture.
show_cursor bool - Whether to show the cursor in the screenshot.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

ScreenshotResponse - Screenshot data with base64 encoded image.

Example:

region = ScreenshotRegion(x=100, y=100, width=300, height=200)
screenshot = sandbox.computer_use.screenshot.take_region(region)
print(f"Captured region: {screenshot.region.width}x{screenshot.region.height}")

Screenshot.take_compressed

@intercept_errors(message_prefix="Failed to take compressed screenshot: ")
@with_instrumentation()
def take_compressed(
        options: ScreenshotOptions | None = None,
        request_timeout: float | None = None) -> ScreenshotResponse

Takes a compressed screenshot of the entire screen.

Arguments:

options ScreenshotOptions | None - Compression and display options.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

ScreenshotResponse - Compressed screenshot data.

Example:

# Default compression
screenshot = sandbox.computer_use.screenshot.take_compressed()

# High quality JPEG
jpeg = sandbox.computer_use.screenshot.take_compressed(
    ScreenshotOptions(format="jpeg", quality=95, show_cursor=True)
)

# Scaled down PNG
scaled = sandbox.computer_use.screenshot.take_compressed(
    ScreenshotOptions(format="png", scale=0.5)
)

Screenshot.take_compressed_region

@intercept_errors(
    message_prefix="Failed to take compressed region screenshot: ")
@with_instrumentation()
def take_compressed_region(
        region: ScreenshotRegion,
        options: ScreenshotOptions | None = None,
        request_timeout: float | None = None) -> ScreenshotResponse

Takes a compressed screenshot of a specific region.

Arguments:

region ScreenshotRegion - The region to capture.
options ScreenshotOptions | None - Compression and display options.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

ScreenshotResponse - Compressed screenshot data.

Example:

region = ScreenshotRegion(x=0, y=0, width=800, height=600)
screenshot = sandbox.computer_use.screenshot.take_compressed_region(
    region,
    ScreenshotOptions(format="webp", quality=80, show_cursor=True)
)
print(f"Compressed size: {screenshot.size_bytes} bytes")

Display

class Display()

Display operations for computer use functionality.

Display.get_info

@intercept_errors(message_prefix="Failed to get display info: ")
@with_instrumentation()
def get_info(request_timeout: float | None = None) -> DisplayInfoResponse

Gets information about the displays.

Arguments:

request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

DisplayInfoResponse - Display information including primary display and all available displays.

Example:

info = sandbox.computer_use.display.get_info()
print(f"Primary display: {info.primary_display.width}x{info.primary_display.height}")
print(f"Total displays: {info.total_displays}")
for i, display in enumerate(info.displays):
    print(f"Display {i}: {display.width}x{display.height} at {display.x},{display.y}")

Display.get_windows

@intercept_errors(message_prefix="Failed to get windows: ")
@with_instrumentation()
def get_windows(request_timeout: float | None = None) -> WindowsResponse

Gets the list of open windows.

Arguments:

request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

WindowsResponse - List of open windows with their IDs and titles.

Example:

windows = sandbox.computer_use.display.get_windows()
print(f"Found {windows.count} open windows:")
for window in windows.windows:
    print(f"- {window.title} (ID: {window.id})")

RecordingService

class RecordingService()

Recording operations for computer use functionality.

RecordingService.start

@intercept_errors(message_prefix="Failed to start recording: ")
@with_instrumentation()
def start(label: str | None = None,
          request_timeout: float | None = None) -> Recording

Starts a new screen recording session.

Arguments:

label str | None - Optional custom label for the recording.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

Recording - Recording start response.

Example:

# Start a recording with a label
recording = sandbox.computer_use.recording.start("my-test-recording")
print(f"Recording started: {recording.id}")
print(f"File: {recording.file_path}")

RecordingService.stop

@intercept_errors(message_prefix="Failed to stop recording: ")
@with_instrumentation()
def stop(recording_id: str, request_timeout: float | None = None) -> Recording

Stops an active screen recording session.

Arguments:

recording_id str - The ID of the recording to stop.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

Recording - Recording stop response.

Example:

result = sandbox.computer_use.recording.stop(recording.id)
print(f"Recording stopped: {result.duration_seconds} seconds")
print(f"Saved to: {result.file_path}")

RecordingService.list

@intercept_errors(message_prefix="Failed to list recordings: ")
@with_instrumentation()
def list(request_timeout: float | None = None) -> ListRecordingsResponse

Lists all recordings (active and completed).

Arguments:

request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

ListRecordingsResponse - List of all recordings.

Example:

recordings = sandbox.computer_use.recording.list()
print(f"Found {len(recordings.recordings)} recordings")
for rec in recordings.recordings:
    print(f"- {rec.file_name}: {rec.status}")

RecordingService.get

@intercept_errors(message_prefix="Failed to get recording: ")
@with_instrumentation()
def get(recording_id: str, request_timeout: float | None = None) -> Recording

Gets details of a specific recording by ID.

Arguments:

recording_id str - The ID of the recording to retrieve.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

Recording - Recording details.

Example:

recording = sandbox.computer_use.recording.get(recording_id)
print(f"Recording: {recording.file_name}")
print(f"Status: {recording.status}")
print(f"Duration: {recording.duration_seconds} seconds")

RecordingService.delete

@intercept_errors(message_prefix="Failed to delete recording: ")
@with_instrumentation()
def delete(recording_id: str, request_timeout: float | None = None) -> None

Deletes a recording by ID.

Arguments:

recording_id str - The ID of the recording to delete.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Example:

sandbox.computer_use.recording.delete(recording_id)
print("Recording deleted")

RecordingService.download

@intercept_errors(message_prefix="Failed to download recording: ")
@with_instrumentation()
def download(recording_id: str, local_path: str) -> None

Downloads a recording file from the Sandbox and saves it to a local file.

The file is streamed directly to disk without loading the entire content into memory.

Arguments:

recording_id str - The ID of the recording to download.
local_path str - Path to save the recording file locally.

Example:

# Download recording to file
sandbox.computer_use.recording.download(recording_id, "local_recording.mp4")
print("Recording downloaded")

Accessibility

class Accessibility()

Accessibility operations for computer use functionality.

This service exposes thin wrappers over the toolbox AT-SPI accessibility API. Start computer use before calling these methods.

Accessibility.get_tree

@intercept_errors(message_prefix="Failed to get accessibility tree: ")
@with_instrumentation()
def get_tree(
        scope: str | None = None,
        pid: int | None = None,
        max_depth: int | None = None,
        request_timeout: float | None = None) -> AccessibilityTreeResponse

Fetches the AT-SPI accessibility tree.

Arguments:

scope str | None - Tree scope to inspect: focused, pid, or all.
pid int | None - Process ID when scope is pid.
max_depth int | None - Maximum depth to descend. Use 0 for the root only.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

AccessibilityTreeResponse - Accessibility tree rooted at the requested scope.

Example:

tree = sandbox.computer_use.accessibility.get_tree(scope="all", max_depth=3)
print(tree.root.name)

Accessibility.find_nodes

@intercept_errors(message_prefix="Failed to find accessibility nodes: ")
@with_instrumentation()
def find_nodes(
        scope: str | None = None,
        pid: int | None = None,
        role: str | None = None,
        name: str | None = None,
        name_match: str | None = None,
        states: list[str] | None = None,
        limit: int | None = None,
        request_timeout: float | None = None) -> AccessibilityNodesResponse

Finds AT-SPI accessibility nodes matching the provided filters.

Arguments:

scope str | None - Search scope: focused, pid, or all.
pid int | None - Process ID when scope is pid.
role str | None - Accessibility role to match, such as button.
name str | None - Accessible name to match.
name_match str | None - Name match mode, such as exact or substring.
states list[str] | None - Required accessibility states.
limit int | None - Maximum number of matches. Use 0 to let the API apply its default.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

AccessibilityNodesResponse - Matching accessibility nodes.

Example:

buttons = sandbox.computer_use.accessibility.find_nodes(
    scope="all",
    role="button",
    name="Submit",
    name_match="substring",
)
print(len(buttons.matches))

Accessibility.focus_node

@intercept_errors(message_prefix="Failed to focus accessibility node: ")
@with_instrumentation()
def focus_node(node_id: str, request_timeout: float | None = None) -> None

Focuses an AT-SPI accessibility node.

Arguments:

node_id str - Accessibility node ID returned by get_tree or find_nodes.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Raises:

DaytonaError - If the focus operation fails. API failures may use a more specific subclass.

Example:

sandbox.computer_use.accessibility.focus_node(node.id)

Accessibility.invoke_node

@intercept_errors(message_prefix="Failed to invoke accessibility node: ")
@with_instrumentation()
def invoke_node(node_id: str,
                action: str | None = None,
                request_timeout: float | None = None) -> None

Invokes an AT-SPI accessibility node action.

Arguments:

node_id str - Accessibility node ID returned by get_tree or find_nodes.
action str | None - Action name to invoke. If omitted, the API invokes the primary action.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Raises:

DaytonaError - If the invoke operation fails. API failures may use a more specific subclass.

Example:

sandbox.computer_use.accessibility.invoke_node(node.id, action="click")

Accessibility.set_node_value

@intercept_errors(message_prefix="Failed to set accessibility node value: ")
@with_instrumentation()
def set_node_value(node_id: str,
                   value: str,
                   request_timeout: float | None = None) -> None

Sets an AT-SPI accessibility node value.

Arguments:

node_id str - Accessibility node ID returned by get_tree or find_nodes.
value str - Value to write to the node.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Raises:

DaytonaError - If the value update fails. API failures may use a more specific subclass.

Example:

sandbox.computer_use.accessibility.set_node_value(node.id, "hello")

ScreenshotRegion

class ScreenshotRegion(BaseModel)

Region coordinates for screenshot operations.

Attributes:

x int - X coordinate of the region.
y int - Y coordinate of the region.
width int - Width of the region.
height int - Height of the region.

ScreenshotOptions

class ScreenshotOptions(BaseModel)

Options for screenshot compression and display.

Attributes:

show_cursor bool | None - Whether to show the cursor in the screenshot.
fmt str | None - Image format (e.g., 'png', 'jpeg', 'webp').
quality int | None - Compression quality (0-100).
scale float | None - Scale factor for the screenshot.

On this page

Computersfor Agents