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:
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:
# 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:
# 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):
# 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:
# 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:
# 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:
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-serverxvfbxdotoolwmctrl
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
