LogoCua Documentation

Computer

Reference for the current version of the Computer library.

The Computer library provides a Computer class that can be used to control and automate a container running the Computer Server.

Reference

Basic Usage

Connect to a cua cloud container:

from computer import Computer

computer = Computer(
    os_type="linux",
    provider_type="cloud",
    name="your-container-name",
    api_key="your-api-key"
)

computer = await computer.run() # Connect to a cua cloud container
import { Computer, OSType } from '@trycua/computer';

const computer = new Computer({
  osType: OSType.LINUX,
  name: "your-container-name",
  apiKey: "your-api-key"
});

await computer.run(); // Connect to a cua cloud container

Connect to a cua local container:

from computer import Computer

computer = Computer(
    os_type="macos"
)

computer = await computer.run() # Connect to the container

Interface Actions

# Shell Actions
result = await computer.interface.run_command(cmd)       # Run shell command
# result.stdout, result.stderr, result.returncode

# Mouse Actions
await computer.interface.left_click(x, y)       # Left click at coordinates
await computer.interface.right_click(x, y)      # Right click at coordinates
await computer.interface.double_click(x, y)     # Double click at coordinates
await computer.interface.move_cursor(x, y)      # Move cursor to coordinates
await computer.interface.drag_to(x, y, duration)  # Drag to coordinates
await computer.interface.get_cursor_position()  # Get current cursor position
await computer.interface.mouse_down(x, y, button="left")  # Press and hold a mouse button
await computer.interface.mouse_up(x, y, button="left")    # Release a mouse button

# Keyboard Actions
await computer.interface.type_text("Hello")     # Type text
await computer.interface.press_key("enter")     # Press a single key
await computer.interface.hotkey("command", "c") # Press key combination
await computer.interface.key_down("command")    # Press and hold a key
await computer.interface.key_up("command")      # Release a key

# Scrolling Actions
await computer.interface.scroll(x, y)           # Scroll the mouse wheel
await computer.interface.scroll_down(clicks)    # Scroll down
await computer.interface.scroll_up(clicks)      # Scroll up

# Screen Actions
await computer.interface.screenshot()           # Take a screenshot
await computer.interface.get_screen_size()      # Get screen dimensions

# Clipboard Actions
await computer.interface.set_clipboard(text)    # Set clipboard content
await computer.interface.copy_to_clipboard()    # Get clipboard content

# File System Operations
await computer.interface.file_exists(path)      # Check if file exists
await computer.interface.directory_exists(path) # Check if directory exists
await computer.interface.read_text(path, encoding="utf-8")        # Read file content
await computer.interface.write_text(path, content, encoding="utf-8") # Write file content
await computer.interface.read_bytes(path)       # Read file content as bytes
await computer.interface.write_bytes(path, content) # Write file content as bytes
await computer.interface.delete_file(path)      # Delete file
await computer.interface.create_dir(path)       # Create directory
await computer.interface.delete_dir(path)       # Delete directory
await computer.interface.list_dir(path)         # List directory contents

# Accessibility
await computer.interface.get_accessibility_tree() # Get accessibility tree

# Delay Configuration
# Set default delay between all actions (in seconds)
computer.interface.delay = 0.5  # 500ms delay between actions

# Or specify delay for individual actions
await computer.interface.left_click(x, y, delay=1.0)     # 1 second delay after click
await computer.interface.type_text("Hello", delay=0.2)   # 200ms delay after typing
await computer.interface.press_key("enter", delay=0.5)   # 500ms delay after key press

# Python Virtual Environment Operations
await computer.venv_install("demo_venv", ["requests", "macos-pyxa"]) # Install packages in a virtual environment
await computer.venv_cmd("demo_venv", "python -c 'import requests; print(requests.get(`https://httpbin.org/ip`).json())'') # Run a shell command in a virtual environment
await computer.venv_exec("demo_venv", python_function_or_code, *args, **kwargs) # Run a Python function in a virtual environment and return the result / raise an exception

# Example: Use sandboxed functions to execute code in a Cua Container
from computer.helpers import sandboxed

@sandboxed("demo_venv")
def greet_and_print(name):
    """Get the HTML of the current Safari tab"""
    import PyXA
    safari = PyXA.Application("Safari")
    html = safari.current_document.source()
    print(f"Hello from inside the container, {name}!")
    return {"greeted": name, "safari_html": html}

# When a @sandboxed function is called, it will execute in the container
result = await greet_and_print("Cua")
# Result: {"greeted": "Cua", "safari_html": "<html>...</html>"}
# stdout and stderr are also captured and printed / raised
print("Result from sandboxed function:", result)
// Shell Actions
const result = await computer.interface.runCommand(cmd);       // Run shell command
// result.stdout, result.stderr, result.returncode

// Mouse Actions
await computer.interface.leftClick(x, y);       // Left click at coordinates
await computer.interface.rightClick(x, y);      // Right click at coordinates
await computer.interface.doubleClick(x, y);     // Double click at coordinates
await computer.interface.moveCursor(x, y);      // Move cursor to coordinates
await computer.interface.dragTo(x, y, duration);  // Drag to coordinates
await computer.interface.getCursorPosition();  // Get current cursor position
await computer.interface.mouseDown(x, y, "left");  // Press and hold a mouse button
await computer.interface.mouseUp(x, y, "left");    // Release a mouse button

// Keyboard Actions
await computer.interface.typeText("Hello");     // Type text
await computer.interface.pressKey("enter");     // Press a single key
await computer.interface.hotkey("command", "c"); // Press key combination
await computer.interface.keyDown("command");    // Press and hold a key
await computer.interface.keyUp("command");      // Release a key

// Scrolling Actions
await computer.interface.scroll(x, y);           // Scroll the mouse wheel
await computer.interface.scrollDown(clicks);    // Scroll down
await computer.interface.scrollUp(clicks);      // Scroll up

// Screen Actions
await computer.interface.screenshot();           // Take a screenshot
await computer.interface.getScreenSize();      // Get screen dimensions

// Clipboard Actions
await computer.interface.setClipboard(text);    // Set clipboard content
await computer.interface.copyToClipboard();    // Get clipboard content

// File System Operations
await computer.interface.fileExists(path);      // Check if file exists
await computer.interface.directoryExists(path); // Check if directory exists
await computer.interface.readText(path, "utf-8");        // Read file content
await computer.interface.writeText(path, content, "utf-8"); // Write file content
await computer.interface.readBytes(path);       // Read file content as bytes
await computer.interface.writeBytes(path, content); // Write file content as bytes
await computer.interface.deleteFile(path);      // Delete file
await computer.interface.createDir(path);       // Create directory
await computer.interface.deleteDir(path);       // Delete directory
await computer.interface.listDir(path);         // List directory contents

// Accessibility
await computer.interface.getAccessibilityTree(); // Get accessibility tree