Cyberdesk Docs

Quickstart

Get up and running with Cyberdesk in minutes.

Fastest Start: Cyberdesk Starter Assistant UI

The quickest way to get started with Cyberdesk is to use our AI SDK Starter template. This ready-to-use Next.js application demonstrates how to build an AI assistant with virtual desktop control capabilities using the Cyberdesk API and Anthropic's Claude AI model.

Features

  • Interactive virtual desktop with streaming capabilities
  • AI assistant chat interface powered by Claude 3.7 Sonnet
  • Desktop control via AI (mouse clicks, keyboard input, screenshots)
  • Bash command execution in the virtual environment

Quick Setup

  1. Clone the repository (alternatively, click "Use this template" on GitHub):
git clone https://github.com/cyberdesk-hq/cyberdesk-ai-sdk-starter.git
cd cyberdesk-ai-sdk-starter
  1. Install dependencies:
npm install
  1. Create a .env.local file with your API keys:
CYBERDESK_API_KEY=your_cyberdesk_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
  1. Start the development server:
npm run dev
  1. Open http://localhost:3000 in your browser

This template provides a complete working example that you can customize for your specific use case. For more details, check out the repository README.

Building a Custom Integration

If you want to build your own integration, you can use either the official TypeScript SDK or the official Python SDK. See the code tabs below for both options.

Prerequisites

Installation

npm install cyberdesk
# or
yarn add cyberdesk
# or
pnpm add cyberdesk

1. Initialize the Client

import { createCyberdeskClient } from 'cyberdesk';
 
const cyberdesk = createCyberdeskClient({
  apiKey: 'YOUR_API_KEY',
  // Optionally, you can override the baseUrl or provide a custom fetch implementation
});

2. Launch a Desktop Instance

const launchResult = await cyberdesk.launchDesktop({
  body: { timeout_ms: 600000 } // Optional: 10-minute timeout
});
 
if ('error' in launchResult) {
  throw new Error('Failed to launch desktop: ' + launchResult.error);
}
 
const desktopId = launchResult.id;

3. Get Desktop Information (Including Stream URL)

const info = await cyberdesk.getDesktop({ path: { id: desktopId } });
 
if ('error' in info) {
  throw new Error('Failed to get desktop info: ' + info.error);
}
 
console.log('Desktop info:', info);
console.log('Stream URL:', info.stream_url);

4. Control the Desktop

Perform a Mouse Click

const actionResult = await cyberdesk.executeComputerAction({
  path: { id: desktopId },
  body: {
    type: 'click_mouse',
    x: 100,
    y: 150,
    button: 'left'
  }
});
 
if ('error' in actionResult) {
  throw new Error('Mouse click failed: ' + actionResult.error);
}

Run a Bash Command

const bashResult = await cyberdesk.executeBashAction({
  path: { id: desktopId },
  body: {
    command: 'ls -la /tmp'
  }
});
 
if ('error' in bashResult) {
  throw new Error('Bash command failed: ' + bashResult.error);
}
 
console.log('Bash command output:', bashResult.output);

5. Stop the Desktop Instance

const terminateResult = await cyberdesk.terminateDesktop({
  path: { id: desktopId }
});
 
if ('error' in terminateResult) {
  // You might still want to proceed even if termination fails
}

6. Async Usage

// All methods are available as async functions (see above)

7. Type Hints and Models

// All request/response types are available from the generated models

8. Available Computer Actions

ActionFactory Function (Python Only)Description
Click Mouseclick_mouseMouse click at (x, y)
Drag Mousedrag_mouseMouse drag from/to (x, y)
Move Mousemove_mouseMove mouse to (x, y)
ScrollscrollScroll by dx, dy
Type Texttype_textType text
Press Keyspress_keysPress keyboard keys
ScreenshotscreenshotTake a screenshot
WaitwaitWait for ms milliseconds
Get Cursor Posget_cursor_positionGet mouse cursor position

Next Steps

On this page