vnc-computer-use 0.1.0__tar.gz

vnc_computer_use-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

vnc_computer_use-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+*.egg

vnc_computer_use-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 EYHN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vnc_computer_use-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: vnc-computer-use
+Version: 0.1.0
+Summary: VNC Computer-Use CLI - control a remote desktop via VNC for AI computer-use agents
+Project-URL: Homepage, https://github.com/EYHN/vnc-computer-use
+Project-URL: Repository, https://github.com/EYHN/vnc-computer-use
+Project-URL: Issues, https://github.com/EYHN/vnc-computer-use/issues
+Author: EYHN
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,automation,computer-use,remote-desktop,vnc
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: vncdotool>=1.0.0
+Description-Content-Type: text/markdown
+
+# vnc-computer-use
+
+VNC Computer-Use CLI - control a remote desktop via VNC for AI computer-use agents.
+
+## Installation
+
+```bash
+pip install vnc-computer-use
+```
+
+## Usage
+
+### Connect to a VNC server
+
+```bash
+vnc connect localhost::5900
+vnc connect myhost:0 --password secret
+vnc connect myhost:0 --username user --password pass  # macOS Screen Sharing
+```
+
+### Interact with the remote desktop
+
+```bash
+# Screenshots
+vnc get_screenshot -o screen.png
+vnc get_screenshot  # returns base64 JSON
+
+# Keyboard
+vnc key enter
+vnc key ctrl-c
+vnc type "hello world"
+
+# Mouse
+vnc left_click 100 200
+vnc right_click 300 400
+vnc double_click 100 200
+vnc mouse_move 500 500
+vnc left_click_drag 100 200
+vnc scroll down 100 200
+
+# Info
+vnc get_cursor_position
+vnc get_screen_size
+vnc status
+```
+
+### Multi-session support
+
+```bash
+vnc connect host1::5900 --session work
+vnc connect host2::5900 --session personal
+vnc -s work get_screenshot -o work.png
+vnc -s personal left_click 100 200
+```
+
+### Disconnect
+
+```bash
+vnc disconnect
+vnc disconnect --session work
+```
+
+## How it works
+
+`vnc` launches a background daemon process that maintains a persistent VNC connection via [vncdotool](https://github.com/sibson/vncdotool). The CLI communicates with the daemon over a Unix domain socket, making each action fast without reconnection overhead.

vnc_computer_use-0.1.0/README.md

@@ -0,0 +1,65 @@
+# vnc-computer-use
+
+VNC Computer-Use CLI - control a remote desktop via VNC for AI computer-use agents.
+
+## Installation
+
+```bash
+pip install vnc-computer-use
+```
+
+## Usage
+
+### Connect to a VNC server
+
+```bash
+vnc connect localhost::5900
+vnc connect myhost:0 --password secret
+vnc connect myhost:0 --username user --password pass  # macOS Screen Sharing
+```
+
+### Interact with the remote desktop
+
+```bash
+# Screenshots
+vnc get_screenshot -o screen.png
+vnc get_screenshot  # returns base64 JSON
+
+# Keyboard
+vnc key enter
+vnc key ctrl-c
+vnc type "hello world"
+
+# Mouse
+vnc left_click 100 200
+vnc right_click 300 400
+vnc double_click 100 200
+vnc mouse_move 500 500
+vnc left_click_drag 100 200
+vnc scroll down 100 200
+
+# Info
+vnc get_cursor_position
+vnc get_screen_size
+vnc status
+```
+
+### Multi-session support
+
+```bash
+vnc connect host1::5900 --session work
+vnc connect host2::5900 --session personal
+vnc -s work get_screenshot -o work.png
+vnc -s personal left_click 100 200
+```
+
+### Disconnect
+
+```bash
+vnc disconnect
+vnc disconnect --session work
+```
+
+## How it works
+
+`vnc` launches a background daemon process that maintains a persistent VNC connection via [vncdotool](https://github.com/sibson/vncdotool). The CLI communicates with the daemon over a Unix domain socket, making each action fast without reconnection overhead.

vnc_computer_use-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vnc-computer-use"
+version = "0.1.0"
+description = "VNC Computer-Use CLI - control a remote desktop via VNC for AI computer-use agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "EYHN" },
+]
+keywords = ["vnc", "computer-use", "remote-desktop", "automation", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Networking",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "vncdotool>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/EYHN/vnc-computer-use"
+Repository = "https://github.com/EYHN/vnc-computer-use"
+Issues = "https://github.com/EYHN/vnc-computer-use/issues"
+
+[project.scripts]
+vnc = "vnc_computer_use.cli:main"

vnc_computer_use-0.1.0/src/vnc_computer_use/__init__.py

@@ -0,0 +1,3 @@
+"""VNC Computer-Use CLI - control a remote desktop via VNC."""
+
+__version__ = "0.1.0"

vnc_computer_use-0.1.0/src/vnc_computer_use/cli.py

@@ -0,0 +1,417 @@
+#!/usr/bin/env python3
+"""VNC Computer-Use CLI - control a remote desktop via VNC.
+
+Use a mouse and keyboard to interact with a computer, and take screenshots.
+
+* This is an interface to a desktop GUI. You do not have access to a terminal
+  or applications menu. You must click on desktop icons to start applications.
+* Always prefer using keyboard shortcuts rather than clicking, where possible.
+* Some applications may take time to start or process actions, so you may need
+  to wait and take successive screenshots to see the results of your actions.
+  E.g. if you click on Firefox and a window doesn't open, try taking another
+  screenshot.
+* Whenever you intend to move the cursor to click on an element like an icon,
+  you should consult a screenshot to determine the coordinates of the element
+  before moving the cursor.
+* If you tried clicking on a program or link but it failed to load, even after
+  waiting, try adjusting your cursor position so that the tip of the cursor
+  visually falls on the element that you want to click.
+* Make sure to click any buttons, links, icons, etc with the cursor tip in the
+  center of the element. Don't click boxes on their edges unless asked.
+"""
+
+import argparse
+import base64
+import json
+import os
+import signal
+import socket
+import subprocess
+import sys
+import time
+
+DEFAULT_SESSION = "default"
+SOCKET_TIMEOUT = 60  # seconds
+
+ACTION_DESCRIPTIONS = """\
+Available actions:
+  key              Press a key or key-combination on the keyboard.
+                   Examples: "enter", "tab", "ctrl-c", "alt-f4", "shift-a"
+  type             Type a string of text on the keyboard. Short text is typed
+                   character by character; long text uses clipboard paste.
+  mouse_move       Move the cursor to a specified (x, y) coordinate.
+  left_click       Click the left mouse button. Optionally move to (x, y) first.
+  left_click_drag  Click and drag the cursor to a specified (x, y) coordinate.
+  right_click      Click the right mouse button. Optionally move to (x, y) first.
+  middle_click     Click the middle mouse button. Optionally move to (x, y) first.
+  double_click     Double-click the left mouse button. Optionally move to (x, y) first.
+  scroll           Scroll the screen in a direction. Requires a coordinate.
+                   Text param specifies direction and optional pixel amount:
+                   "up", "down", "left", "right", or "down:500" for 500 pixels.
+  get_screenshot   Take a screenshot of the screen.
+  get_cursor_position  Get the current (x, y) coordinate of the cursor.
+  get_screen_size  Get the screen dimensions (width x height).
+  status           Show daemon connection status.
+"""
+
+
+def session_socket_path(session):
+    return f"/tmp/vnc-cli-{session}.sock"
+
+
+def session_pid_file(session):
+    return f"/tmp/vnc-cli-{session}.pid"
+
+
+def session_log_file(session):
+    return f"/tmp/vnc-cli-{session}.log"
+
+
+def send_command(session, request):
+    """Send a JSON command to the daemon and return the response."""
+    socket_path = session_socket_path(session)
+    if not os.path.exists(socket_path):
+        result = {"error": f"VNC session '{session}' not running. Run 'vnc connect <host> --session {session}' first."}
+        print(json.dumps(result))
+        sys.exit(1)
+
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    sock.settimeout(SOCKET_TIMEOUT)
+    try:
+        sock.connect(socket_path)
+        sock.sendall(json.dumps(request).encode() + b"\n")
+
+        chunks = []
+        while True:
+            chunk = sock.recv(1 << 20)  # 1MB buffer
+            if not chunk:
+                break
+            chunks.append(chunk)
+            if b"\n" in chunk:
+                break
+        data = b"".join(chunks)
+        return json.loads(data.strip())
+    except socket.timeout:
+        result = {"error": f"VNC session '{session}' timed out."}
+        print(json.dumps(result))
+        sys.exit(1)
+    except ConnectionRefusedError:
+        result = {"error": f"VNC session '{session}' not responding. Try 'vnc disconnect --session {session}' then reconnect."}
+        print(json.dumps(result))
+        sys.exit(1)
+    finally:
+        sock.close()
+
+
+def cmd_connect(args):
+    session = args.session
+    pid_file = session_pid_file(session)
+    socket_path = session_socket_path(session)
+    log_file = session_log_file(session)
+
+    if os.path.exists(pid_file):
+        with open(pid_file) as f:
+            pid = int(f.read().strip())
+        try:
+            os.kill(pid, 0)
+            print(json.dumps({"error": f"VNC session '{session}' already running (PID {pid}). Use 'vnc disconnect --session {session}' first."}))
+            sys.exit(1)
+        except ProcessLookupError:
+            os.unlink(pid_file)
+            if os.path.exists(socket_path):
+                os.unlink(socket_path)
+
+    daemon_script = os.path.join(os.path.dirname(os.path.abspath(__file__)), "daemon.py")
+    cmd = [sys.executable, daemon_script, args.host, "--session", session]
+    if args.password:
+        cmd += ["--password", args.password]
+    if args.username:
+        cmd += ["--username", args.username]
+
+    with open(log_file, "w") as log:
+        proc = subprocess.Popen(cmd, stdout=log, stderr=log, start_new_session=True)
+
+    for _ in range(30):
+        if os.path.exists(socket_path):
+            print(json.dumps({"ok": True, "session": session, "host": args.host, "pid": proc.pid}))
+            return
+        ret = proc.poll()
+        if ret is not None:
+            err = ""
+            try:
+                with open(log_file) as f:
+                    err = f.read()
+            except Exception:
+                pass
+            print(json.dumps({"error": f"Daemon exited with code {ret}.", "log": err}))
+            sys.exit(1)
+        time.sleep(0.5)
+
+    proc.terminate()
+    print(json.dumps({"error": f"Timeout waiting for daemon to start. Check {log_file}"}))
+    sys.exit(1)
+
+
+def cmd_disconnect(args):
+    session = args.session
+    pid_file = session_pid_file(session)
+    socket_path = session_socket_path(session)
+
+    if not os.path.exists(pid_file):
+        print(json.dumps({"ok": True, "message": f"VNC session '{session}' was not running."}))
+        return
+
+    with open(pid_file) as f:
+        pid = int(f.read().strip())
+
+    try:
+        os.kill(pid, signal.SIGTERM)
+        for _ in range(10):
+            try:
+                os.kill(pid, 0)
+                time.sleep(0.2)
+            except ProcessLookupError:
+                break
+    except ProcessLookupError:
+        pass
+
+    for path in [pid_file, socket_path]:
+        try:
+            os.unlink(path)
+        except OSError:
+            pass
+
+    print(json.dumps({"ok": True, "session": session, "message": "disconnected"}))
+
+
+def cmd_action(args):
+    """Unified action handler -- mirrors the computer-use tool interface."""
+    action = args.action
+    req = {"action": action}
+
+    # Parse coordinate
+    if args.coordinate is not None:
+        if len(args.coordinate) != 2:
+            print(json.dumps({"error": "coordinate requires exactly 2 values: x y"}))
+            sys.exit(1)
+        req["x"] = args.coordinate[0]
+        req["y"] = args.coordinate[1]
+
+    # Parse text
+    if args.text is not None:
+        req["text"] = args.text
+
+    # Parse output (screenshot)
+    if hasattr(args, "output") and args.output:
+        req["output"] = os.path.abspath(args.output)
+
+    # Validate required params per action
+    needs_coord = {"mouse_move", "left_click_drag", "scroll"}
+    needs_text = {"key", "type", "scroll"}
+    optional_coord = {"left_click", "right_click", "middle_click", "double_click"}
+
+    if action in needs_coord and "x" not in req:
+        print(json.dumps({"error": f"coordinate required for {action}"}))
+        sys.exit(1)
+    if action in needs_text and "text" not in req:
+        print(json.dumps({"error": f"text required for {action}"}))
+        sys.exit(1)
+    if action not in needs_coord and action not in optional_coord and "x" in req:
+        # Ignore stray coordinates for actions that don't use them
+        del req["x"]
+        del req["y"]
+
+    resp = send_command(args.session, req)
+
+    # Handle screenshot output
+    if action == "get_screenshot" and resp.get("ok"):
+        if "path" in resp:
+            print(json.dumps({"ok": True, "path": resp["path"]}))
+        elif "data" in resp:
+            if args.output:
+                png_data = base64.b64decode(resp["data"])
+                output = os.path.abspath(args.output)
+                with open(output, "wb") as f:
+                    f.write(png_data)
+                print(json.dumps({"ok": True, "path": output}))
+            else:
+                print(json.dumps({"ok": True, "format": "png", "data": resp["data"]}))
+        return
+
+    print(json.dumps(resp))
+
+
+def _rewrite_argv():
+    """Rewrite sys.argv to map positional shorthand to --text / --coordinate flags."""
+    argv = sys.argv[1:]
+    if len(argv) < 1:
+        return
+
+    # Find session flag and skip it
+    clean = []
+    i = 0
+    while i < len(argv):
+        if argv[i] in ("--session", "-s") and i + 1 < len(argv):
+            clean.append(argv[i])
+            clean.append(argv[i + 1])
+            i += 2
+        else:
+            clean.append(argv[i])
+            i += 1
+
+    # Separate global flags from subcommand
+    global_flags = []
+    rest = []
+    i = 0
+    while i < len(clean):
+        if clean[i] in ("--session", "-s"):
+            global_flags += [clean[i], clean[i + 1]]
+            i += 2
+        elif clean[i].startswith("-") and not rest:
+            global_flags.append(clean[i])
+            i += 1
+        else:
+            rest = clean[i:]
+            break
+
+    if not rest:
+        return
+
+    action = rest[0]
+    action_args = rest[1:]
+
+    text_actions = {"key", "type"}
+    coord_actions = {"mouse_move", "left_click_drag"}
+    optional_coord_actions = {"left_click", "right_click", "middle_click", "double_click"}
+    scroll_action = {"scroll"}
+
+    # Already has flags -- don't rewrite
+    if any(a.startswith("-") for a in action_args if a not in ("-o", "--output")):
+        return
+
+    new_args = global_flags + [action]
+
+    if action in text_actions and action_args:
+        # vnc key enter  /  vnc type "hello"
+        # Find -o flag if present
+        text_parts = []
+        j = 0
+        while j < len(action_args):
+            if action_args[j] in ("-o", "--output") and j + 1 < len(action_args):
+                new_args += [action_args[j], action_args[j + 1]]
+                j += 2
+            else:
+                text_parts.append(action_args[j])
+                j += 1
+        if text_parts:
+            new_args += ["--text", " ".join(text_parts)]
+
+    elif action in scroll_action and action_args:
+        # vnc scroll down:5 100 200
+        parts = []
+        j = 0
+        while j < len(action_args):
+            if action_args[j] in ("-o", "--output") and j + 1 < len(action_args):
+                new_args += [action_args[j], action_args[j + 1]]
+                j += 2
+            else:
+                parts.append(action_args[j])
+                j += 1
+        if parts:
+            new_args += ["--text", parts[0]]
+        if len(parts) >= 3:
+            new_args += ["--coordinate", parts[1], parts[2]]
+
+    elif action in coord_actions and action_args:
+        # vnc mouse_move 100 200
+        parts = []
+        j = 0
+        while j < len(action_args):
+            if action_args[j] in ("-o", "--output") and j + 1 < len(action_args):
+                new_args += [action_args[j], action_args[j + 1]]
+                j += 2
+            else:
+                parts.append(action_args[j])
+                j += 1
+        if len(parts) >= 2:
+            new_args += ["--coordinate", parts[0], parts[1]]
+
+    elif action in optional_coord_actions and action_args:
+        # vnc left_click 100 200
+        parts = []
+        j = 0
+        while j < len(action_args):
+            if action_args[j] in ("-o", "--output") and j + 1 < len(action_args):
+                new_args += [action_args[j], action_args[j + 1]]
+                j += 2
+            else:
+                parts.append(action_args[j])
+                j += 1
+        if len(parts) >= 2:
+            new_args += ["--coordinate", parts[0], parts[1]]
+
+    elif action == "get_screenshot":
+        new_args += action_args
+
+    else:
+        new_args += action_args
+
+    sys.argv = [sys.argv[0]] + new_args
+
+
+def main():
+    _rewrite_argv()
+
+    parser = argparse.ArgumentParser(
+        prog="vnc",
+        description=__doc__,
+        epilog=ACTION_DESCRIPTIONS,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--session", "-s", default=DEFAULT_SESSION,
+                        help=f"Session name for multi-connection support (default: {DEFAULT_SESSION})")
+    sub = parser.add_subparsers(dest="command")
+
+    # connect
+    p = sub.add_parser("connect", help="Connect to VNC server and start daemon")
+    p.add_argument("host", help="VNC host (e.g. localhost::5900 or localhost:0)")
+    p.add_argument("--password", "-p", help="VNC password")
+    p.add_argument("--username", "-u", help="VNC/ARD username (required for macOS Screen Sharing)")
+
+    # disconnect
+    sub.add_parser("disconnect", help="Stop VNC daemon")
+
+    # All computer-use actions share the same interface
+    actions = [
+        "key", "type", "mouse_move",
+        "left_click", "left_click_drag", "right_click",
+        "middle_click", "double_click", "scroll",
+        "get_screenshot", "get_cursor_position",
+        "get_screen_size", "status",
+    ]
+
+    for action in actions:
+        p = sub.add_parser(action)
+        p.add_argument("--coordinate", "-c", type=int, nargs=2, metavar=("X", "Y"),
+                        help="(x, y) pixel coordinate on the screen")
+        p.add_argument("--text", "-t", help="Text to type, key name, or scroll direction")
+        if action == "get_screenshot":
+            p.add_argument("--output", "-o", help="Output file path (default: base64 JSON to stdout)")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.command == "connect":
+        cmd_connect(args)
+    elif args.command == "disconnect":
+        cmd_disconnect(args)
+    else:
+        args.action = args.command
+        cmd_action(args)
+
+
+if __name__ == "__main__":
+    main()

vnc_computer_use-0.1.0/src/vnc_computer_use/daemon.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+"""VNC CLI Daemon - maintains VNC connection and serves commands over Unix socket."""
+
+import json
+import os
+import signal
+import socketserver
+import sys
+import tempfile
+import time
+import base64
+import threading
+import traceback
+
+DEFAULT_SESSION = "default"
+
+
+def session_socket_path(session):
+    return f"/tmp/vnc-cli-{session}.sock"
+
+
+def session_pid_file(session):
+    return f"/tmp/vnc-cli-{session}.pid"
+
+
+def session_log_file(session):
+    return f"/tmp/vnc-cli-{session}.log"
+
+# Threshold: texts shorter than this use keyPress; longer use paste()
+PASTE_THRESHOLD = 32
+
+
+class VNCController:
+    """Wraps vncdotool client with local cursor tracking."""
+
+    def __init__(self, host, password=None, username=None, session=DEFAULT_SESSION):
+        import vncdotool.api
+        self._api = vncdotool.api
+        self.client = self._api.connect(host, password=password, username=username)
+        self.cursor_x = 0
+        self.cursor_y = 0
+        self.host = host
+        self.session = session
+        self._lock = threading.Lock()
+
+    def shutdown(self):
+        try:
+            self.client.disconnect()
+        except Exception:
+            pass
+        try:
+            self._api.shutdown()
+        except Exception:
+            pass
+
+    def handle(self, request):
+        action = request.get("action")
+        with self._lock:
+            handler = getattr(self, f"_do_{action}", None)
+            if handler is None:
+                return {"error": f"Unknown action: {action}"}
+            try:
+                return handler(request)
+            except Exception as e:
+                traceback.print_exc(file=sys.stderr)
+                return {"error": str(e)}
+
+    def _do_key(self, req):
+        text = req.get("text")
+        if not text:
+            return {"error": "text required for key"}
+        self.client.keyPress(text)
+        return {"ok": True}
+
+    def _do_type(self, req):
+        text = req.get("text")
+        if not text:
+            return {"error": "text required for type"}
+        if len(text) >= PASTE_THRESHOLD:
+            self.client.paste(text)
+        else:
+            for char in text:
+                self.client.keyPress(char)
+        return {"ok": True}
+
+    def _do_mouse_move(self, req):
+        x, y = self._require_coords(req)
+        self.client.mouseMove(x, y)
+        self.cursor_x, self.cursor_y = x, y
+        return {"ok": True}
+
+    def _do_left_click(self, req):
+        x, y = self._optional_coords(req)
+        if x is not None:
+            self.client.mouseMove(x, y)
+            self.cursor_x, self.cursor_y = x, y
+        self.client.mousePress(1)
+        return {"ok": True}
+
+    def _do_right_click(self, req):
+        x, y = self._optional_coords(req)
+        if x is not None:
+            self.client.mouseMove(x, y)
+            self.cursor_x, self.cursor_y = x, y
+        self.client.mousePress(3)
+        return {"ok": True}
+
+    def _do_middle_click(self, req):
+        x, y = self._optional_coords(req)
+        if x is not None:
+            self.client.mouseMove(x, y)
+            self.cursor_x, self.cursor_y = x, y
+        self.client.mousePress(2)
+        return {"ok": True}
+
+    def _do_double_click(self, req):
+        x, y = self._optional_coords(req)
+        if x is not None:
+            self.client.mouseMove(x, y)
+            self.cursor_x, self.cursor_y = x, y
+        self.client.mousePress(1)
+        self.client.pause(0.1)
+        self.client.mousePress(1)
+        return {"ok": True}
+
+    def _do_left_click_drag(self, req):
+        x, y = self._require_coords(req)
+        step = int(req.get("step", 10))
+        self.client.mouseDrag(x, y, step=step)
+        self.cursor_x, self.cursor_y = x, y
+        return {"ok": True}
+
+    def _do_scroll(self, req):
+        text = req.get("text")
+        if not text:
+            return {"error": "text required for scroll. Use 'up', 'down', 'left', 'right', or 'down:500'"}
+
+        # Parse direction and optional amount from text (e.g. "down" or "down:5")
+        parts = text.split(":")
+        direction = parts[0].lower()
+        amount = int(parts[1]) if len(parts) > 1 else 3
+
+        x, y = self._optional_coords(req)
+        if x is not None:
+            self.client.mouseMove(x, y)
+            self.cursor_x, self.cursor_y = x, y
+
+        # VNC scroll uses mouse buttons 4/5 (up/down) and 6/7 (left/right)
+        button_map = {"up": 4, "down": 5, "left": 6, "right": 7}
+        button = button_map.get(direction)
+        if button is None:
+            return {"error": f"Invalid scroll direction: '{direction}'. Use 'up', 'down', 'left', or 'right'"}
+        for _ in range(amount):
+            self.client.mousePress(button)
+        return {"ok": True}
+
+    def _do_get_screenshot(self, req):
+        output = req.get("output")
+        if output:
+            # Write directly to the requested file path
+            self.client.captureScreen(output)
+            return {"ok": True, "path": output}
+        else:
+            # Fallback: return base64 via socket
+            tmpfile = os.path.join(tempfile.gettempdir(), f"vnc-screenshot-{os.getpid()}.png")
+            try:
+                self.client.captureScreen(tmpfile)
+                with open(tmpfile, "rb") as f:
+                    data = base64.b64encode(f.read()).decode("ascii")
+                return {"ok": True, "data": data, "format": "png"}
+            finally:
+                try:
+                    os.unlink(tmpfile)
+                except OSError:
+                    pass
+
+    def _do_get_cursor_position(self, req):
+        return {"ok": True, "x": self.cursor_x, "y": self.cursor_y}
+
+    def _do_get_screen_size(self, req):
+        self.client.refreshScreen()
+        screen = self.client.screen
+        return {"ok": True, "width": screen.size[0], "height": screen.size[1]}
+
+    def _do_status(self, req):
+        return {
+            "ok": True,
+            "host": self.host,
+            "session": self.session,
+            "pid": os.getpid(),
+            "cursor_x": self.cursor_x,
+            "cursor_y": self.cursor_y,
+        }
+
+    def _require_coords(self, req):
+        x = req.get("x")
+        y = req.get("y")
+        if x is None or y is None:
+            raise ValueError("x and y coordinates required")
+        return int(x), int(y)
+
+    def _optional_coords(self, req):
+        x = req.get("x")
+        y = req.get("y")
+        if x is not None and y is not None:
+            return int(x), int(y)
+        return None, None
+
+
+class RequestHandler(socketserver.StreamRequestHandler):
+    def handle(self):
+        for line in self.rfile:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                request = json.loads(line)
+            except json.JSONDecodeError as e:
+                response = {"error": f"Invalid JSON: {e}"}
+            else:
+                response = self.server.vnc_controller.handle(request)
+            self.wfile.write(json.dumps(response).encode() + b"\n")
+            self.wfile.flush()
+
+
+class VNCDaemonServer(socketserver.ThreadingUnixStreamServer):
+    def __init__(self, socket_path, handler, vnc_controller):
+        self.vnc_controller = vnc_controller
+        super().__init__(socket_path, handler)
+
+
+def cleanup(socket_path, pid_file):
+    try:
+        os.unlink(socket_path)
+    except OSError:
+        pass
+    try:
+        os.unlink(pid_file)
+    except OSError:
+        pass
+
+
+def parse_arg(argv, flag):
+    if flag in argv:
+        idx = argv.index(flag)
+        return argv[idx + 1]
+    return None
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: vnc_daemon.py <host[:display]> [--password <pw>] [--username <user>] [--session <name>]", file=sys.stderr)
+        sys.exit(1)
+
+    host = sys.argv[1]
+    password = parse_arg(sys.argv, "--password")
+    username = parse_arg(sys.argv, "--username")
+    session = parse_arg(sys.argv, "--session") or DEFAULT_SESSION
+
+    socket_path = session_socket_path(session)
+    pid_file = session_pid_file(session)
+
+    # Clean up stale socket
+    if os.path.exists(socket_path):
+        os.unlink(socket_path)
+
+    # Connect to VNC
+    print(f"[{session}] Connecting to VNC at {host}...", file=sys.stderr)
+    try:
+        controller = VNCController(host, password=password, username=username, session=session)
+    except Exception as e:
+        print(f"[{session}] Failed to connect to VNC: {e}", file=sys.stderr)
+        sys.exit(1)
+    print(f"[{session}] VNC connected.", file=sys.stderr)
+
+    # Write PID file
+    with open(pid_file, "w") as f:
+        f.write(str(os.getpid()))
+
+    # Set up signal handlers for clean shutdown
+    def handle_signal(signum, frame):
+        print(f"\n[{session}] Shutting down...", file=sys.stderr)
+        controller.shutdown()
+        cleanup(socket_path, pid_file)
+        sys.exit(0)
+
+    signal.signal(signal.SIGTERM, handle_signal)
+    signal.signal(signal.SIGINT, handle_signal)
+
+    # Start socket server
+    server = VNCDaemonServer(socket_path, RequestHandler, controller)
+    print(f"[{session}] Listening on {socket_path}", file=sys.stderr)
+
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.shutdown()
+        controller.shutdown()
+        cleanup(socket_path, pid_file)
+
+
+if __name__ == "__main__":
+    main()