Window Management

Manage windows on the desktop: list, focus, resize, minimize, and close windows.

Overview

Window management enables:

Listing all windows
Focusing (activating) windows
Resizing windows
Minimizing windows
Closing windows

Desktop automation requires a template with desktop support. Ensure your sandbox has desktop capabilities enabled.

Listing Windows

Get list of all windows:

Python
JavaScript

from hopx_ai import Sandbox

sandbox = Sandbox.create(template="desktop")

# Get all windows
windows = sandbox.desktop.get_windows()

for window in windows:
    print(f"Window: {window.title}")
    print(f"  ID: {window.id}")
    print(f"  Position: ({window.x}, {window.y})")
    print(f"  Size: {window.width}x{window.height}")
    print(f"  PID: {window.pid}")

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({ template: 'desktop' });

// Get all windows
const windows = await sandbox.desktop.listWindows();

windows.forEach(window => {
  console.log(`Window: ${window.title}`);
  console.log(`  ID: ${window.id}`);
  console.log(`  Position: (${window.x}, ${window.y})`);
  console.log(`  Size: ${window.width}x${window.height}`);
  console.log(`  PID: ${window.pid}`);
});

Focusing Windows

Focus (activate) a window:

Python
JavaScript

# Get windows
windows = sandbox.desktop.get_windows()

# Focus first window
if windows:
    sandbox.desktop.focus_window(windows[0].id)

# Find and focus window by title
for window in windows:
    if "Firefox" in window.title:
        sandbox.desktop.focus_window(window.id)
        break

// Get windows
const windows = await sandbox.desktop.listWindows();

// Focus first window
if (windows.length > 0) {
  await sandbox.desktop.focusWindow(windows[0].id);
}

// Find and focus window by title
for (const window of windows) {
  if (window.title.includes('Firefox')) {
    await sandbox.desktop.focusWindow(window.id);
    break;
  }
}

Resizing Windows

Resize a window:

Python
JavaScript

# Get windows
windows = sandbox.desktop.get_windows()

# Resize first window to 800x600
if windows:
    sandbox.desktop.resize_window(windows[0].id, 800, 600)

# Resize window by title
for window in windows:
    if "My App" in window.title:
        sandbox.desktop.resize_window(window.id, 1024, 768)
        break

// Get windows
const windows = await sandbox.desktop.listWindows();

// Resize first window to 800x600
if (windows.length > 0) {
  await sandbox.desktop.resizeWindow(windows[0].id, 800, 600);
}

// Resize window by title
for (const window of windows) {
  if (window.title.includes('My App')) {
    await sandbox.desktop.resizeWindow(window.id, 1024, 768);
    break;
  }
}

Minimizing Windows

Minimize a window:

Python
JavaScript

# Minimize first window
windows = sandbox.desktop.get_windows()
if windows:
    sandbox.desktop.minimize_window(windows[0].id)

// Minimize first window
const windows = await sandbox.desktop.listWindows();
if (windows.length > 0) {
  await sandbox.desktop.minimizeWindow(windows[0].id);
}

Closing Windows

Close a window:

Python
JavaScript

# Close window by title
windows = sandbox.desktop.get_windows()
for window in windows:
    if "Firefox" in window.title:
        sandbox.desktop.close_window(window.id)
        break

// Close window by title
const windows = await sandbox.desktop.listWindows();
for (const window of windows) {
  if (window.title.includes('Firefox')) {
    await sandbox.desktop.closeWindow(window.id);
    break;
  }
}

Window Information

Window objects contain:

id: Unique window identifier
title: Window title/name
x, y: Window position (top-left corner)
width, height: Window size
desktop: Desktop number (for multi-desktop)
pid: Process ID of the window

Complete Example

Complete window management workflow:

Python
JavaScript

from hopx_ai import Sandbox

sandbox = Sandbox.create(template="desktop")

try:
    # List all windows
    windows = sandbox.desktop.get_windows()
    print(f"Found {len(windows)} windows")
    
    # Find specific window
    target_window = None
    for window in windows:
        if "My Application" in window.title:
            target_window = window
            break
    
    if target_window:
        # Focus window
        sandbox.desktop.focus_window(target_window.id)
        print(f"Focused: {target_window.title}")
        
        # Resize window
        sandbox.desktop.resize_window(target_window.id, 1024, 768)
        print("Resized to 1024x768")
        
        # Minimize
        sandbox.desktop.minimize_window(target_window.id)
        print("Minimized")
        
        # Close
        sandbox.desktop.close_window(target_window.id)
        print("Closed")
    
finally:
    sandbox.kill()

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({ template: 'desktop' });

try {
  // List all windows
  const windows = await sandbox.desktop.listWindows();
  console.log(`Found ${windows.length} windows`);
  
  // Find specific window
  const targetWindow = windows.find(w => w.title.includes('My Application'));
  
  if (targetWindow) {
    // Focus window
    await sandbox.desktop.focusWindow(targetWindow.id);
    console.log(`Focused: ${targetWindow.title}`);
    
    // Resize window
    await sandbox.desktop.resizeWindow(targetWindow.id, 1024, 768);
    console.log('Resized to 1024x768');
    
    // Minimize
    await sandbox.desktop.minimizeWindow(targetWindow.id);
    console.log('Minimized');
    
    // Close
    await sandbox.desktop.closeWindow(targetWindow.id);
    console.log('Closed');
  }
  
} finally {
  await sandbox.kill();
}

Display Management - Configure display settings
VNC Server - Remote desktop access
SDK: sandbox.desktop.get_windows() - Python SDK method

Next Steps

Learn about Display Management to configure display
Explore VNC Server for remote desktop access
Review Screenshots for visual verification
Display Management - Configure display settings
Screenshots - Capture window screenshots
CLI System Commands - System operations from CLI

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Overview

Listing Windows

Focusing Windows

Resizing Windows

Minimizing Windows

Closing Windows

Window Information

Complete Example

Next Steps

​Overview

​Listing Windows

​Focusing Windows

​Resizing Windows

​Minimizing Windows

​Closing Windows

​Window Information

​Complete Example

​Related

​Next Steps

Overview

Listing Windows

Focusing Windows

Resizing Windows

Minimizing Windows

Closing Windows

Window Information

Complete Example

Related

Next Steps