Skip to main content
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}")

​
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}")

​
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")

​
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}")

​
Stopping VNC Server

Stop the VNC server:
  • Python
  • JavaScript
# Stop VNC server
sandbox.desktop.stop_vnc()
print("VNC server stopped")

​
Connecting to VNC

Once VNC is started, connect using a VNC client:
  1. Get the VNC URL from vnc_info.url or get_vnc_url()
  2. Use a VNC client such as:
    • TigerVNC Viewer (Windows, macOS, Linux)
    • RealVNC Viewer (Windows, macOS, Linux)
    • Remmina (Linux)
    • Built-in Screen Sharing (macOS)
  3. 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

​
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()

​
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)

​
Next Steps