VNC Remote Control #

A pure Python VNC client and remote control service. It provides a interactive browser interface for remote desktop control and a comprehensive REST API for programmatic automation using raw RFB sockets.

🚀 Features #

• Raw RFB Implementation: Direct socket communication using RFB 003.008 for maximum compatibility with servers like wayvnc.
• Adaptive Web UI:
  • Real-time JPEG streaming via WebSockets.
  • Automatic upscaling/downscaling to fit any browser window size while preserving aspect ratio.
  • Full interactive mouse and keyboard support (including touchpad scrolling).
• Remote Control API: Full REST API for programmatic interaction, making it ideal for automation, testing, or integration into other tools.

🛠️ Installation & Setup #

This project uses uv for fast Python package and environment management.

Prerequisites #

• uv installed on your system.

Running the Server #

# Set your VNC server address (host:port or host::port)
export VNC_SERVER="127.0.0.1::5902"
export VNC_PASSWORD="your_password" # Optional

uv run python main.py

The web interface will be available at http://localhost:8000.

🔌 REST API Reference #

Mouse Control #

Endpoint	Method	Payload	Description
/api/mouse/move	POST	{"x": int, "y": int}	Move cursor to absolute position
/api/mouse/down	POST	{"x": int, "y": int, "button": int}	Press and hold button (1:L, 2:M, 4:R)
/api/mouse/up	POST	{"x": int, "y": int}	Release all mouse buttons
/api/mouse/click	POST	{"x": int, "y": int, "button": int}	Click button at position (1:L, 2:M, 4:R, 8:Up, 16:Down)
/api/mouse/drag	POST	{"x1": int, "y1": int, "x2": int, "y2": int, "button": int, "steps": int}	Drag from (x1,y1) to (x2,y2)

Keyboard Control #

Endpoint	Method	Payload	Description
/api/keyboard/key	POST	{"key": "string"}	Send a key or combo (e.g., "Enter", "F5", "Ctrl+C")
/api/keyboard/type	POST	{"text": "string"}	Types a full string of text (handles Shift automatically)

Screen Capture #

Endpoint	Method	Description
/api/screenshot	GET	Returns the current screen as a JPEG image

⌨️ Supported Key Mappings #

Use these strings in the key field of the /api/keyboard/key endpoint.

Special Keys #

Enter, Backspace, Tab, Escape, Insert, Delete, Home, End, PageUp, PageDown

Navigation Keys #

ArrowUp, ArrowDown, ArrowLeft, ArrowRight

Function Keys #

F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12

Modifiers & Combinations #

Use the + symbol to combine modifiers with target keys.

• Modifiers: Ctrl, Alt, Shift, Meta (or Win)
• Examples:
  • Ctrl+C
  • Alt+Tab
  • Ctrl+Alt+Delete
  • Shift+S

📝 Usage Examples (curl) #

Mouse Control #

# Move mouse to x=500, y=500
curl -X POST http://localhost:8000/api/mouse/move -H "Content-Type: application/json" -d '{"x": 500, "y": 500}'

# Left click at x=500, y=500
curl -X POST http://localhost:8000/api/mouse/click -H "Content-Type: application/json" -d '{"x": 500, "y": 500, "button": 1}'

# Drag window from (100,100) to (300,300)
curl -X POST http://localhost:8000/api/mouse/drag -H "Content-Type: application/json" -d '{"x1": 100, "y1": 100, "x2": 300, "y2": 300, "button": 1}'

Keyboard Control #

# Type a string of text
curl -X POST http://localhost:8000/api/keyboard/type -H "Content-Type: application/json" -d '{"text": "Hello World!"}'

# Send a specific key (Enter)
curl -X POST http://localhost:8000/api/keyboard/key -H "Content-Type: application/json" -d '{"key": "Enter"}'

# Send a combination (Ctrl+C)
curl -X POST http://localhost:8000/api/keyboard/key -H "Content-Type: application/json" -d '{"key": "Ctrl+C"}'

Screenshot #

# Save current VNC screen to a file
curl http://localhost:8000/api/screenshot --output screenshot.jpg

⚙️ Configuration #

Environment variables:

• VNC_SERVER: The target VNC server (default: 127.0.0.1::5902).
• VNC_PASSWORD: Password for authentication (if required).
• FRAME_RATE: Target frames per second (default: 10).