VNC Server

Access and control the graphical desktop environment through VNC (Virtual Network Computing). VNC provides remote desktop access to your sandbox, allowing you to see and interact with GUI applications.

Prerequisites

Before you begin, make sure you have:

Desktop template - A sandbox created from a template with desktop support (e.g., desktop template)
Active sandbox - A running sandbox (see Creating Sandboxes)
VNC client - A VNC viewer application (optional, for manual access)

Overview

VNC server enables:

Remote desktop access to sandbox GUI
Visual debugging of GUI applications
Interactive testing of desktop software
Screen sharing and collaboration

Desktop automation requires a template with desktop support. Templates like desktop or custom templates with X11/VNC dependencies are required.

Starting VNC Server

Start a VNC server to enable remote desktop access:

Python
JavaScript

from hopx_ai import Sandbox

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

# Start VNC server
vnc_info = sandbox.desktop.start_vnc()
print(f"VNC URL: {vnc_info.url}")
print(f"Display: {vnc_info.display}")
print(f"Port: {vnc_info.port}")

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

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

// Start VNC server
const vncInfo = await sandbox.desktop.startVnc();
console.log(`VNC URL: ${vncInfo.url}`);
console.log(`Display: ${vncInfo.display}`);
console.log(`Port: ${vncInfo.port}`);

VNC Server with Password

Start VNC server with a password for security:

Python
JavaScript

# Start VNC with password
vnc_info = sandbox.desktop.start_vnc(display=1, password="my-secure-password")
print(f"Connect to: {vnc_info.url}")

// Note: JavaScript SDK may have different password parameter
const vncInfo = await sandbox.desktop.startVnc();
console.log(`Connect to: ${vncInfo.url}`);

Getting VNC Status

Check if VNC server is running and get connection details:

Python
JavaScript

# Get VNC status
vnc_info = sandbox.desktop.get_vnc_status()

if vnc_info.running:
    print(f"VNC is running at {vnc_info.url}")
    print(f"Display: {vnc_info.display}")
else:
    print("VNC server is not running")

// Get VNC info
const vncInfo = await sandbox.desktop.getVncInfo();

if (vncInfo.running) {
  console.log(`VNC is running at ${vncInfo.url}`);
  console.log(`Display: ${vncInfo.display}`);
} else {
  console.log('VNC server is not running');
}

Getting VNC URL

Get just the VNC URL string (convenience method):

Python
JavaScript

# Get VNC URL
url = sandbox.desktop.get_vnc_url()
print(f"Connect to: {url}")

// Get VNC URL
const url = await sandbox.desktop.getVncUrl();
console.log(`Connect to: ${url}`);

Stopping VNC Server

Stop the VNC server:

Python
JavaScript

# Stop VNC server
sandbox.desktop.stop_vnc()
print("VNC server stopped")

// Stop VNC server
await sandbox.desktop.stopVnc();
console.log('VNC server stopped');

Connecting to VNC

Once VNC is started, connect using a VNC client:

Get the VNC URL from vnc_info.url or get_vnc_url()
Use a VNC client such as:
- TigerVNC Viewer (Windows, macOS, Linux)
- RealVNC Viewer (Windows, macOS, Linux)
- Remmina (Linux)
- Built-in Screen Sharing (macOS)
Connect using the URL (e.g., vnc://sandbox-id.region.hopx.dev:5901)

For web-based access, some VNC clients support WebSocket connections. Check your VNC client documentation for WebSocket support.

VNC Display Numbers

VNC servers use display numbers (e.g., :1, :2). The default is display 1:

Python
JavaScript

# Start VNC on display 2
vnc_info = sandbox.desktop.start_vnc(display=2)
print(f"Display: {vnc_info.display}")  # :2

// Note: JavaScript SDK may use different parameter
const vncInfo = await sandbox.desktop.startVnc();
console.log(`Display: ${vncInfo.display}`);

Complete Example

Complete workflow for VNC access:

Python
JavaScript

from hopx_ai import Sandbox

# Create sandbox with desktop support
sandbox = Sandbox.create(template="desktop")

try:
    # Start VNC
    vnc_info = sandbox.desktop.start_vnc(password="secure-password")
    print(f"✅ VNC started: {vnc_info.url}")
    print(f"   Display: {vnc_info.display}")
    print(f"   Port: {vnc_info.port}")
    
    # Check status
    status = sandbox.desktop.get_vnc_status()
    if status.running:
        print("✅ VNC is running")
    
    # Use VNC URL to connect with VNC client
    print(f"\nConnect using: {vnc_info.url}")
    
finally:
    # Cleanup
    sandbox.desktop.stop_vnc()
    sandbox.kill()

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

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

try {
  // Start VNC
  const vncInfo = await sandbox.desktop.startVnc();
  console.log(`✅ VNC started: ${vncInfo.url}`);
  console.log(`   Display: ${vncInfo.display}`);
  console.log(`   Port: ${vncInfo.port}`);
  
  // Check status
  const status = await sandbox.desktop.getVncInfo();
  if (status.running) {
    console.log('✅ VNC is running');
  }
  
  // Use VNC URL to connect with VNC client
  console.log(`\nConnect using: ${vncInfo.url}`);
  
} finally {
  // Cleanup
  await sandbox.desktop.stopVnc();
  await sandbox.kill();
}

Troubleshooting

VNC Not Available

If VNC methods raise DesktopNotAvailableError, your template may be missing required dependencies:

Desktop automation requires specific dependencies. Ensure your template includes:

tigervnc-standalone-server
xvfb
xdotool
wmctrl

Connection Issues

Check VNC status: Verify server is running with get_vnc_status()
Verify URL: Ensure you’re using the correct VNC URL
Firewall: Check if ports are accessible
Password: If using password, ensure it’s correct

Display Issues

Multiple displays: Use different display numbers for multiple VNC sessions
Resolution: Set display resolution before starting VNC (see Display Management)

Mouse Control - Control mouse input
CLI Reference - Command-line interface for HopX
Keyboard Control - Control keyboard input
Screenshots - Capture screenshots
Display Management - Configure display settings
SDK: sandbox.desktop.start_vnc() - Python SDK method

Next Steps

Learn about Mouse Control to interact with GUI
Explore Keyboard Control for text input
Review Screenshots for visual verification

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Prerequisites

Overview

Starting VNC Server

VNC Server with Password

Getting VNC Status

Getting VNC URL

Stopping VNC Server

Connecting to VNC

VNC Display Numbers

Complete Example

Troubleshooting

VNC Not Available

Connection Issues

Display Issues

Next Steps

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Documentation Index

​Prerequisites

​Overview

​Starting VNC Server

​VNC Server with Password

​Getting VNC Status

​Getting VNC URL

​Stopping VNC Server

​Connecting to VNC

​VNC Display Numbers

​Complete Example

​Troubleshooting

​VNC Not Available

​Connection Issues

​Display Issues

​Related

​Next Steps

Prerequisites

Overview

Starting VNC Server

VNC Server with Password

Getting VNC Status

Getting VNC URL

Stopping VNC Server

Connecting to VNC

VNC Display Numbers

Complete Example

Troubleshooting

VNC Not Available

Connection Issues

Display Issues

Related

Next Steps