Skip to main content
The Desktop resource provides desktop automation capabilities for controlling GUI applications, taking screenshots, and managing windows. Note: Desktop automation requires a template with desktop dependencies installed.

Accessing Desktop Resource

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

const sandbox = await Sandbox.create({ template: 'desktop' });
await sandbox.init();
const desktop = sandbox.desktop;  // Lazy-loaded resource

VNC Server

startVnc()

Start VNC server for remote desktop access.
const vncInfo = await sandbox.desktop.startVnc();
console.log(`VNC URL: ${vncInfo.url}`);

getVncInfo()

Get VNC server information.
const vnc = await sandbox.desktop.getVncInfo();
if (vnc.running) {
  console.log(`VNC running at ${vnc.url}`);
}

Mouse Control

mouseClick()

Click at coordinates.
await sandbox.desktop.mouseClick(100, 200);
await sandbox.desktop.mouseClick(500, 300, { button: 'right', clicks: 2 });

mouseMove()

Move mouse to coordinates.
await sandbox.desktop.mouseMove(500, 300);

mouseDrag()

Drag mouse from one point to another.
await sandbox.desktop.mouseDrag(100, 100, 300, 300);

mouseScroll()

Scroll at coordinates.
await sandbox.desktop.mouseScroll(500, 300, 3);  // Scroll down
await sandbox.desktop.mouseScroll(500, 300, -3); // Scroll up

Keyboard Control

keyboardType()

Type text.
await sandbox.desktop.keyboardType('Hello, World!');

keyboardPress()

Press a key.
await sandbox.desktop.keyboardPress('Return');
await sandbox.desktop.keyboardPress('Control_L+c');  // Ctrl+C

keyboardCombination()

Press key combination.
await sandbox.desktop.keyboardCombination(['Control_L', 'c']);  // Ctrl+C
await sandbox.desktop.keyboardCombination(['Alt', 'Tab']);      // Alt+Tab

Clipboard

getClipboard()

Get clipboard contents.
const content = await sandbox.desktop.getClipboard();
console.log(content);

setClipboard()

Set clipboard contents.
await sandbox.desktop.setClipboard('Text to copy');

Screenshots

screenshot()

Capture full screen screenshot.
const screenshot = await sandbox.desktop.screenshot();
await fs.promises.writeFile('screen.png', screenshot);

screenshotRegion()

Capture screenshot of specific region.
const img = await sandbox.desktop.screenshotRegion(100, 100, 800, 600);

Screen Recording

startRecording()

Start screen recording.
await sandbox.desktop.startRecording('/workspace/recording.mp4');

stopRecording()

Stop screen recording.
await sandbox.desktop.stopRecording();

Window Management

listWindows()

List all windows.
const windows = await sandbox.desktop.listWindows();
for (const win of windows) {
  console.log(`${win.title} (${win.window_id})`);
}

focusWindow()

Focus a window.
await sandbox.desktop.focusWindow('window_id_123');