> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# VNC Server

> Start and manage VNC server for remote desktop access in HopX sandboxes. Set up VNC servers for graphical desktop environments, connect via VNC clients, and manage remote desktop sessions. Learn how to configure VNC settings, access desktop environments, and use VNC for desktop automation. Includes Python and JavaScript SDK examples.

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](/core-concepts/sandboxes/creating))
* **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

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

## Starting VNC Server

Start a VNC server to enable remote desktop access:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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}`);
    ```
  </Tab>
</Tabs>

## VNC Server with Password

Start VNC server with a password for security:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Start VNC with password
    vnc_info = sandbox.desktop.start_vnc(display=1, password="my-secure-password")
    print(f"Connect to: {vnc_info.url}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Note: JavaScript SDK may have different password parameter
    const vncInfo = await sandbox.desktop.startVnc();
    console.log(`Connect to: ${vncInfo.url}`);
    ```
  </Tab>
</Tabs>

## Getting VNC Status

Check if VNC server is running and get connection details:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # 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")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // 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');
    }
    ```
  </Tab>
</Tabs>

## Getting VNC URL

Get just the VNC URL string (convenience method):

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Get VNC URL
    url = sandbox.desktop.get_vnc_url()
    print(f"Connect to: {url}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Get VNC URL
    const url = await sandbox.desktop.getVncUrl();
    console.log(`Connect to: ${url}`);
    ```
  </Tab>
</Tabs>

## Stopping VNC Server

Stop the VNC server:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Stop VNC server
    sandbox.desktop.stop_vnc()
    print("VNC server stopped")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Stop VNC server
    await sandbox.desktop.stopVnc();
    console.log('VNC server stopped');
    ```
  </Tab>
</Tabs>

## 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`)

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

## VNC Display Numbers

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

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Start VNC on display 2
    vnc_info = sandbox.desktop.start_vnc(display=2)
    print(f"Display: {vnc_info.display}")  # :2
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Note: JavaScript SDK may use different parameter
    const vncInfo = await sandbox.desktop.startVnc();
    console.log(`Display: ${vncInfo.display}`);
    ```
  </Tab>
</Tabs>

## Complete Example

Complete workflow for VNC access:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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();
    }
    ```
  </Tab>
</Tabs>

## Troubleshooting

### VNC Not Available

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

<Warning>
  Desktop automation requires specific dependencies. Ensure your template includes:

  * `tigervnc-standalone-server`
  * `xvfb`
  * `xdotool`
  * `wmctrl`
</Warning>

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

## Related

* [Mouse Control](/core-concepts/desktop/mouse-control) - Control mouse input
* [CLI Reference](/cli/introduction) - Command-line interface for HopX
* [Keyboard Control](/core-concepts/desktop/keyboard-control) - Control keyboard input
* [Screenshots](/core-concepts/desktop/screenshots) - Capture screenshots
* [Display Management](/core-concepts/desktop/display-management) - Configure display settings
* **SDK**: [sandbox.desktop.start\_vnc()](/sdk/python/desktop#start_vnc) - Python SDK method

## Next Steps

* Learn about [Mouse Control](/core-concepts/desktop/mouse-control) to interact with GUI
* Explore [Keyboard Control](/core-concepts/desktop/keyboard-control) for text input
* Review [Screenshots](/core-concepts/desktop/screenshots) for visual verification