Conceptual Guide

Understanding the core concepts of Cyberdesk will help you build more effective applications.

Architecture Overview

Cyberdesk is built on a microservices architecture that provides scalable, reliable access to virtual desktop environments. The system consists of:

• API Service: The backend service accessed via the SDK.
• Desktop Pool: Managed virtual desktop instances.
• Stream Service: Real-time visual streaming of desktop environments.
• Database: Persistent storage for desktop metadata and user information.

Desktop Instances

A desktop instance is a virtual desktop environment running in the cloud. Each instance:

• Has a unique identifier (UUID format).
• Runs in an isolated environment for security.
• Can be controlled programmatically through the SDK methods.
• Provides a stream_url (obtained via SDK methods) for visual feedback.
• Persists until explicitly stopped (via terminateDesktop) or times out.
• Has configurable resources (CPU, memory, storage) - future feature.

When creating a desktop instance using launchDesktop, you can specify a custom timeout in milliseconds using the body.timeout_ms parameter. This allows you to control how long the desktop instance will remain active before being automatically terminated. If not specified, a default timeout is applied. Check your plan for maximum allowed timeout values.

Computer Actions

Cyberdesk supports various computer actions to interact with the desktop via the executeComputerAction SDK method. Actions are specified using a body object containing a type field and associated parameters:

Mouse Actions

• type: 'click_mouse': Perform a mouse action (click, press down, or release up).
  • x, y (optional): Coordinates for the click.
  • button (optional): left, right, or middle (defaults to left).
  • num_of_clicks (optional): Number of clicks (defaults to 1, for click_type: 'click').
  • click_type (optional): click (down and up), down (press), or up (release) (defaults to click).
• type: 'scroll': Scroll the mouse wheel.
  • direction: up, down, left, or right.
  • amount: Amount to scroll in pixels.
• type: 'move_mouse': Move the mouse cursor to specific coordinates.
  • x, y: Target coordinates.
• type: 'drag_mouse': Drag the mouse from a start point to an end point.
  • start: { x, y } starting coordinates.
  • end: { x, y } ending coordinates.

Keyboard Actions

• type: 'type': Type text at the current cursor position.
  • text: The string to type.
• type: 'press_keys': Press, hold down, or release keyboard keys.
  • keys: A single key string (e.g., 'Enter') or an array of keys to press simultaneously (e.g., ['Control', 'c']).
  • key_action_type (optional): press (down and up), down (hold), or up (release) (defaults to press).

Other Actions

• type: 'wait': Pause execution for a specified duration.
  • ms: Time to wait in milliseconds.
• type: 'screenshot': Capture the current state of the desktop.
  • Returns a base64_image field in the successful response object.
• type: 'get_cursor_position': Get the current mouse cursor coordinates.
  • Returns x, y coordinates in the successful response object.

Bash Actions

Bash actions allow you to execute shell commands on the desktop instance via the executeBashAction SDK method. This is useful for:

• Installing software
• Running applications
• Manipulating files
• Executing scripts
• System configuration

The method accepts a body.command parameter containing the shell command to execute and returns the command output (stdout/stderr) as a string in the successful response object.

Desktop Streaming

Cyberdesk provides real-time streaming of desktop visuals. The stream_url obtained from the launchDesktop or getDesktop SDK methods can be used for:

1. Web-based Viewer: Opening the URL in a browser.
2. VNC Protocol: Connecting with a VNC client (if the stream URL supports it).
3. Embedded Iframe: Embedding the desktop view directly in your web applications.

The streaming service aims for low-latency transmission suitable for real-time interaction.

Authentication and Security

Cyberdesk uses API keys for authentication. The SDK client is initialized with your API key, which is then automatically included in all requests.

• API keys are associated with a specific user account.
• Rate limits apply to prevent abuse.
• Keys can be revoked or regenerated from your dashboard.
• Keep your API key secure.

Communication with the API is encrypted using TLS/SSL.

Resource Management

Cyberdesk automatically manages resources:

• Desktop instances are cleaned up when stopped via the terminateDesktop SDK method or when they reach their timeout.
• Users are responsible for stopping instances when no longer needed to manage costs and resources.
• Resource quotas and limits may apply depending on your subscription plan.

Error Handling

The Cyberdesk SDK methods simplify error handling. Each method returns a promise that resolves to an object. You should check if this object contains an error property:

const result = await cyberdesk.someMethod(...);
 
if ('error' in result) {
  // Handle the error
  console.error('Cyberdesk SDK Error:', result.error);
  // The 'error' property contains the descriptive error message from the API
} else {
  // Process the successful result
  console.log('Success:', result);
}

Common error scenarios include:

• Invalid parameters in the request body (body property of the method call).
• Missing or invalid API key (during client initialization or if the key is revoked).
• Attempting an action not allowed by your plan.
• Referencing a non-existent desktop instance ID (path.id).
• Rate limit exceeded.
• Server-side issues on the Cyberdesk platform.

Check the specific error message returned in the error property for details.

Performance Considerations

When building applications with the Cyberdesk SDK, consider:

• API Call Latency: Network latency affects the time it takes for SDK methods to complete.
• Action Duration: Some actions (like wait or long bash commands) naturally take time.
• Streaming Latency: There will be some delay in the visual stream.
• Error Retries: For transient issues (like network errors or potential server-side hiccups), consider implementing retry logic around your SDK calls, possibly with exponential backoff.

Billing and Usage

Cyberdesk billing is typically based on factors like:

• Active Desktop Time: The duration desktop instances are running (often billed per second or minute).

Monitor your usage and understand the pricing model via the Cyberdesk dashboard (coming soon!).