Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(computer-server): add --vnc-force-caps for servers that drop Shift (#3509)

umutcagand18217d0f03f3
diff --git a/.github/workflows/ci-test-python.yml b/.github/workflows/ci-test-python.yml
index 839d3a961f..8070affe65 100644
--- a/.github/workflows/ci-test-python.yml
+++ b/.github/workflows/ci-test-python.yml
@@ -23,6 +23,11 @@ jobs:
- mcp-server
- som
- cua-auto
+ include:
+ # computer-server's VNC backend tests assert what vncdotool puts on
+ # the wire, so the job needs the package's own `vnc` extra.
+ - package: computer-server
+ extras: "[vnc]"
steps:
- name: Checkout code
@@ -42,10 +47,14 @@ jobs:
cd libs/python/${{ matrix.package }}
# Install the package in editable mode with dev dependencies
if [ -f pyproject.toml ]; then
- uv pip install --system -e .
+ uv pip install --system -e ".${{ matrix.extras }}"
fi
shell: bash
+ - name: Install Computer SDK for server integration tests
+ if: matrix.package == 'computer-server'
+ run: uv pip install --system -e ./libs/python/computer
+
- name: Install test dependencies
run: |
# Install test dependencies from root pyproject.toml if tests directory exists
diff --git a/libs/python/computer-server/README.md b/libs/python/computer-server/README.md
index 7259cca3f7..cac85d1124 100644
--- a/libs/python/computer-server/README.md
+++ b/libs/python/computer-server/README.md
@@ -24,6 +24,9 @@ pip install cua-computer-server[mcp]
# With the generated native Cua Driver SDK backend
pip install cua-computer-server[driver]
+
+# With the VNC backend
+pip install cua-computer-server[vnc]
```
## Usage
@@ -58,6 +61,46 @@ This provides:
MCP clients can connect via streamable HTTP at `http://localhost:8000/mcp`.
+### VNC backend
+
+`--backend vnc` drives a remote target over RFB instead of the local OS, so it
+covers screen, pointer, scroll, and keyboard only. Host-scoped surfaces (shell,
+files, PTY, browser, windows) are refused rather than silently executed against
+the server's own machine.
+
+```bash
+python -m computer_server --backend vnc \
+ --vnc-host 127.0.0.1 --vnc-port 5900 --vnc-password secret
+```
+
+The equivalent environment variables are `CUA_VNC_HOST`, `CUA_VNC_PORT`,
+`CUA_VNC_PASSWORD`, and `CUA_VNC_FORCE_CAPS`.
+
+#### Shift and non-compliant servers
+
+RFB sends a keysym and leaves it to the server to work out which physical key
+and modifiers produce it, so a compliant server presses Shift itself when it
+receives `underscore`. QEMU only does that for uppercase letters: shifted
+punctuation arrives unshifted, and `Hello_World (a>b)` is typed as
+`Hello-World 9a.b0`.
+
+Pass `--vnc-force-caps` (or set `CUA_VNC_FORCE_CAPS=1`) to send `shift-<key>`
+from the client instead. It stays off by default: vncdotool documents it as a
+workaround for non-compliant servers, and it changes what every uppercase and
+shifted-punctuation keystroke puts on the wire.
+
+When the server is started for you by the Python SDK, pass it through
+`Computer(...)` instead — it is forwarded to the VM alongside the other VNC
+settings:
+
+```python
+computer = Computer(
+ backend="vnc",
+ vnc_host="127.0.0.1",
+ vnc_force_caps=True,
+)
+```
+
### Cua Driver backend
`--backend cua-driver` keeps computer-server's HTTP/WebSocket, MCP, shell,
diff --git a/libs/python/computer-server/computer_server/backend_policy.py b/libs/python/computer-server/computer_server/backend_policy.py
index fad8085483..8833e0b92c 100644
--- a/libs/python/computer-server/computer_server/backend_policy.py
+++ b/libs/python/computer-server/computer_server/backend_policy.py
@@ -58,6 +58,15 @@ VNC_REMOTE_MCP_TOOLS = frozenset(
)
+_TRUTHY_ENV_VALUES = frozenset({"1", "true", "yes", "on"})
+
+
+def env_flag(name: str) -> bool:
+ """Return True when an environment variable holds a truthy value."""
+
+ return os.environ.get(name, "").strip().lower() in _TRUTHY_ENV_VALUES
+
+
def configured_backend() -> str:
"""Return the effective backend using the same selection rule as the factory."""
@@ -71,6 +80,19 @@ def is_vnc_backend() -> bool:
return configured_backend() == "vnc"
+def vnc_force_caps() -> bool:
+ """Return True when the VNC client must send Shift itself.
+
+ RFB expects the server to derive the physical key and modifiers from the
+ keysym, so a compliant server types ``_`` when it receives the ``underscore``
+ keysym. QEMU only synthesises Shift for uppercase letters, so shifted
+ punctuation arrives unshifted (``_`` becomes ``-``). This opt-in makes the
+ client send ``shift-<key>`` instead of relying on the server.
+ """
+
+ return env_flag("CUA_VNC_FORCE_CAPS")
+
+
def vnc_unsupported_result() -> Dict[str, Any]:
"""Return the stable refusal shared by defensive handler fallbacks."""
diff --git a/libs/python/computer-server/computer_server/cli.py b/libs/python/computer-server/computer_server/cli.py
index 5ef1dbf222..5a33996d0f 100644
--- a/libs/python/computer-server/computer_server/cli.py
+++ b/libs/python/computer-server/computer_server/cli.py
@@ -8,6 +8,8 @@ import os
import sys
from typing import List, Optional
+from .backend_policy import env_flag
+
logger = logging.getLogger(__name__)
@@ -97,6 +99,16 @@ def parse_args(args: Optional[List[str]] = None) -> argparse.Namespace:
default="",
help="VNC server password",
)
+ parser.add_argument(
+ "--vnc-force-caps",
+ action="store_true",
+ default=env_flag("CUA_VNC_FORCE_CAPS"),
+ help=(
+ "Send Shift from the client for uppercase letters and US-layout "
+ "shifted punctuation, for servers such as QEMU that do not "
+ "synthesise it from the keysym (default: CUA_VNC_FORCE_CAPS)"
+ ),
+ )
return parser.parse_args(args)
@@ -126,8 +138,13 @@ def main() -> None:
os.environ["CUA_VNC_PORT"] = str(args.vnc_port)
if args.vnc_password:
os.environ["CUA_VNC_PASSWORD"] = args.vnc_password
+ if args.vnc_force_caps:
+ os.environ["CUA_VNC_FORCE_CAPS"] = "true"
vnc_host = args.vnc_host or os.environ.get("CUA_VNC_HOST")
- logger.info(f"VNC backend enabled → {vnc_host}:{args.vnc_port}")
+ logger.info(
+ f"VNC backend enabled → {vnc_host}:{args.vnc_port} "
+ f"(force_caps={args.vnc_force_caps})"
+ )
elif args.backend == "cua-driver":
os.environ["CUA_BACKEND"] = "cua-driver"
if args.driver_mode:
diff --git a/libs/python/computer-server/computer_server/handlers/factory.py b/libs/python/computer-server/computer_server/handlers/factory.py
index 25a2eaa27d..41a7d1efba 100644
--- a/libs/python/computer-server/computer_server/handlers/factory.py
+++ b/libs/python/computer-server/computer_server/handlers/factory.py
@@ -5,7 +5,7 @@ from typing import Optional, Tuple
from computer_server.diorama.base import BaseDioramaHandler
-from ..backend_policy import VNCUnavailableHandler, configured_backend
+from ..backend_policy import VNCUnavailableHandler, configured_backend, vnc_force_caps
from ..utils.helpers import get_current_os
from .base import (
BaseAccessibilityHandler,
@@ -60,11 +60,17 @@ class HandlerFactory:
vnc_port = int(os.environ.get("CUA_VNC_PORT", "5900"))
vnc_password = os.environ.get("CUA_VNC_PASSWORD", "")
+ force_caps = vnc_force_caps()
unavailable = VNCUnavailableHandler()
- logger.info(f"Using VNC backend → {vnc_host}:{vnc_port}")
+ logger.info(f"Using VNC backend → {vnc_host}:{vnc_port} (force_caps={force_caps})")
return (
VNCAccessibilityHandler(),
- VNCAutomationHandler(host=vnc_host, port=vnc_port, password=vnc_password),
+ VNCAutomationHandler(
+ host=vnc_host,
+ port=vnc_port,
+ password=vnc_password,
+ force_caps=force_caps,
+ ),
BaseDioramaHandler(),
unavailable,
unavailable,
diff --git a/libs/python/computer-server/computer_server/handlers/vnc.py b/libs/python/computer-server/computer_server/handlers/vnc.py
index 9b0de5da99..3f37da83ba 100644
--- a/libs/python/computer-server/computer_server/handlers/vnc.py
+++ b/libs/python/computer-server/computer_server/handlers/vnc.py
@@ -16,6 +16,9 @@ Usage:
# Via env vars
CUA_VNC_HOST=192.168.64.1 CUA_VNC_PORT=5900 CUA_VNC_PASSWORD=secret python -m computer_server
+
+ # Against a server that does not synthesise Shift for shifted punctuation
+ python -m computer_server --vnc-host 127.0.0.1 --vnc-force-caps
"""
import asyncio
@@ -92,14 +95,27 @@ class _VNCConnection:
asyncio.to_thread to avoid blocking the event loop.
"""
- def __init__(self, host: str, port: int, password: str = ""):
+ def __init__(self, host: str, port: int, password: str = "", force_caps: bool = False):
self._host = host
self._port = port
self._password = password
+ self._force_caps = force_caps
# Track cursor position locally
self._cursor_x: int = 0
self._cursor_y: int = 0
+ def _build_factory(self):
+ """Build the vncdotool factory that configures every connection."""
+
+ from vncdotool.client import VNCDoToolFactory
+
+ factory = VNCDoToolFactory()
+ factory.password = self._password or None
+ # Non-compliant servers (notably QEMU) do not synthesise Shift for
+ # shifted keysyms, so ask vncdotool to send `shift-<key>` instead.
+ factory.force_caps = self._force_caps
+ return factory
+
def _with_client(self, fn):
"""Execute fn(client) with a fresh VNC connection via the global Twisted reactor.
@@ -110,15 +126,13 @@ class _VNCConnection:
import threading
from twisted.internet import defer, reactor
- from vncdotool.client import VNCDoToolFactory
result_holder: list = [None]
error_holder: list = [None]
done_event = threading.Event()
def _work():
- factory = VNCDoToolFactory()
- factory.password = self._password or None
+ factory = self._build_factory()
@defer.inlineCallbacks
def _do():
@@ -320,7 +334,12 @@ class _VNCConnection:
self._with_client(lambda c: c.keyUp(_translate_key(key)))
def type_text(self, text: str):
- """Type text character by character, handling shift for uppercase/symbols."""
+ """Type text character by character.
+
+ Each character is sent as its own keysym, which is what RFB prescribes:
+ the server is responsible for pressing Shift when the keysym needs it.
+ Servers that only do this for letters (QEMU) need ``force_caps``.
+ """
from twisted.internet import defer
@defer.inlineCallbacks
@@ -385,8 +404,9 @@ class VNCAutomationHandler(BaseAutomationHandler):
host: str = "127.0.0.1",
port: int = 5900,
password: str = "",
+ force_caps: bool = False,
):
- self._conn = _VNCConnection(host, port, password)
+ self._conn = _VNCConnection(host, port, password, force_caps=force_caps)
def _resolve_coords(self, x: Optional[int], y: Optional[int]) -> Tuple[int, int]:
if x is not None and y is not None:
diff --git a/libs/python/computer-server/pyproject.toml b/libs/python/computer-server/pyproject.toml
index 4191fb365a..d82e32dedf 100644
--- a/libs/python/computer-server/pyproject.toml
+++ b/libs/python/computer-server/pyproject.toml
@@ -52,7 +52,9 @@ windows = [
"pywin32>=310"
]
vnc = [
- "vncdotool>=1.2.0"
+ # 1.3.0 is the first release that supports Python 3.12 and that releases
+ # force_caps keys in reverse order, so Shift outlives the key it modifies.
+ "vncdotool>=1.3.0"
]
driver = [
"cua-driver>=0.22.2,<0.23.0"
diff --git a/libs/python/computer-server/tests/test_vnc_force_caps.py b/libs/python/computer-server/tests/test_vnc_force_caps.py
new file mode 100644
index 0000000000..2e7c295729
--- /dev/null
+++ b/libs/python/computer-server/tests/test_vnc_force_caps.py
@@ -0,0 +1,322 @@
+"""Shift delivery for the VNC backend.
+
+RFB leaves keysym-to-key translation to the server, so a compliant server
+presses Shift itself when it receives the ``underscore`` keysym. QEMU only does
+that for uppercase letters, so shifted punctuation arrives unshifted and
+``Hello_World`` is typed as ``Hello-World``. ``--vnc-force-caps`` moves the
+modifier to the client.
+"""
+
+import os
+import sys
+from types import ModuleType, SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from computer_server.backend_policy import env_flag, vnc_force_caps
+from computer_server.cli import parse_args
+from computer_server.handlers.vnc import VNCAutomationHandler, _VNCConnection
+
+# The exact characters from the bug report that QEMU types unshifted.
+SHIFTED_PUNCTUATION = "_(>)&{|}#~$"
+
+
+def _require_vncdotool() -> None:
+ """Require the `vnc` extra, except when running outside CI without it.
+
+ CI installs `cua-computer-server[vnc]` for this package, so a missing import
+ there is a packaging regression and must fail rather than quietly skip.
+ """
+
+ if os.environ.get("CI"):
+ import vncdotool # noqa: F401
+ else:
+ pytest.importorskip("vncdotool", reason="requires cua-computer-server[vnc]")
+
+
+def vnc_client_factory():
+ """Return a builder for a real vncdotool client bound to a cua-built factory."""
+
+ _require_vncdotool()
+ from vncdotool.client import VNCDoToolClient
+
+ def build(force_caps: bool):
+ connection = _VNCConnection("127.0.0.1", 5900, "secret", force_caps=force_caps)
+ client = VNCDoToolClient.__new__(VNCDoToolClient)
+ client.factory = connection._build_factory()
+ return client
+
+ return build
+
+
+def _record_key_events(client, key: str):
+ """Return the (keysym, down) events ``keyPress`` would put on the wire."""
+
+ events: list = []
+ client.keyEvent = lambda keysym, down: events.append((keysym, down))
+ client.keyPress(key)
+ return events
+
+
+def test_shifted_punctuation_reaches_the_wire_without_shift_by_default(vnc_client_factory):
+ client = vnc_client_factory(force_caps=False)
+
+ for character in SHIFTED_PUNCTUATION:
+ assert _record_key_events(client, character) == [
+ (ord(character), True),
+ (ord(character), False),
+ ]
+
+
+def test_force_caps_sends_shift_around_every_shifted_character(vnc_client_factory):
+ from vncdotool.client import KEYMAP
+
+ client = vnc_client_factory(force_caps=True)
+ shift = KEYMAP["shift"]
+
+ for character in SHIFTED_PUNCTUATION + "A":
+ assert _record_key_events(client, character) == [
+ (shift, True),
+ (ord(character), True),
+ (ord(character), False),
+ (shift, False),
+ ]
+
+
+def test_force_caps_leaves_unshifted_characters_alone(vnc_client_factory):
+ client = vnc_client_factory(force_caps=True)
+
+ for character in "a4-=[]`":
+ assert _record_key_events(client, character) == [
+ (ord(character), True),
+ (ord(character), False),
+ ]
+
+
+def test_force_caps_preserves_the_password(vnc_client_factory):
+ assert vnc_client_factory(force_caps=True).factory.password == "secret"
+
+
+def test_handler_defaults_to_server_side_shift():
+ _require_vncdotool()
+
+ assert VNCAutomationHandler(host="127.0.0.1")._conn._build_factory().force_caps is False
+
+
+def test_handler_forwards_force_caps_to_every_connection():
+ _require_vncdotool()
+
+ handler = VNCAutomationHandler(host="127.0.0.1", force_caps=True)
+
+ assert handler._conn._build_factory().force_caps is True
+
+
+def test_factory_builds_a_force_caps_handler_from_the_environment(monkeypatch):
+ _require_vncdotool()
+ monkeypatch.setenv("CUA_BACKEND", "vnc")
+ monkeypatch.setenv("CUA_VNC_HOST", "127.0.0.1")
+ monkeypatch.setenv("CUA_VNC_FORCE_CAPS", "true")
+ from computer_server.handlers.factory import HandlerFactory
+
+ automation = HandlerFactory.create_handlers()[1]
+
+ assert automation._conn._build_factory().force_caps is True
+
+
+def test_cli_flag_is_off_unless_requested():
+ assert parse_args(["--backend", "vnc", "--vnc-host", "127.0.0.1"]).vnc_force_caps is False
+
+
+def test_cli_flag_selects_client_side_shift():
+ args = parse_args(["--backend", "vnc", "--vnc-host", "127.0.0.1", "--vnc-force-caps"])
+
+ assert args.vnc_force_caps is True
+
+
+def test_cli_flag_defaults_to_the_environment_variable(monkeypatch):
+ monkeypatch.setenv("CUA_VNC_FORCE_CAPS", "1")
+
+ assert parse_args(["--backend", "vnc", "--vnc-host", "127.0.0.1"]).vnc_force_caps is True
+
+
[email protected]("value", ["1", "true", "TRUE", "yes", "on", " true "])
+def test_env_flag_accepts_common_truthy_spellings(monkeypatch, value):
+ monkeypatch.setenv("CUA_VNC_FORCE_CAPS", value)
+
+ assert vnc_force_caps() is True
+
+
[email protected]("value", ["", "0", "false", "no", "off", "maybe"])
+def test_env_flag_rejects_everything_else(monkeypatch, value):
+ monkeypatch.setenv("CUA_VNC_FORCE_CAPS", value)
+
+ assert vnc_force_caps() is False
+
+
+def test_env_flag_is_false_when_unset(monkeypatch):
+ monkeypatch.delenv("CUA_VNC_FORCE_CAPS", raising=False)
+
+ assert env_flag("CUA_VNC_FORCE_CAPS") is False
+
+
+def test_computer_forwards_force_caps_to_the_server_env():
+ """The SDK has to hand the flag down, or --vnc-force-caps only helps people
+ who start computer-server by hand."""
+ from computer.computer import Computer
+
+ computer = Computer(
+ use_host_computer_server=True,
+ backend="vnc",
+ vnc_host="127.0.0.1",
+ vnc_password="secret",
+ vnc_force_caps=True,
+ )
+
+ assert computer._backend_env() == {
+ "CUA_BACKEND": "vnc",
+ "CUA_VNC_HOST": "127.0.0.1",
+ "CUA_VNC_PORT": "5900",
+ "CUA_VNC_PASSWORD": "secret",
+ "CUA_VNC_FORCE_CAPS": "true",
+ }
+
+
+def test_computer_leaves_force_caps_unset_by_default():
+ from computer.computer import Computer
+
+ computer = Computer(use_host_computer_server=True, backend="vnc", vnc_host="127.0.0.1")
+
+ assert "CUA_VNC_FORCE_CAPS" not in computer._backend_env()
+
+
+def test_computer_sends_no_backend_env_for_the_native_backend():
+ from computer.computer import Computer
+
+ assert Computer(use_host_computer_server=True)._backend_env() == {}
+
+
+def test_computer_preserves_positional_run_opts():
+ from computer.computer import Computer
+
+ run_opts = {"env": {"CUSTOM_OPTION": "preserved"}}
+ computer = Computer(
+ "1024x768",
+ "8GB",
+ "4",
+ "macos",
+ "",
+ None,
+ None,
+ True,
+ 20,
+ False,
+ "lume",
+ 7777,
+ 8006,
+ None,
+ "localhost",
+ None,
+ None,
+ False,
+ None,
+ None,
+ None,
+ None,
+ 100,
+ "vnc",
+ "127.0.0.1",
+ 5900,
+ "",
+ run_opts,
+ )
+
+ assert computer.custom_run_opts == run_opts
+ assert computer.vnc_force_caps is False
+ assert "CUA_VNC_FORCE_CAPS" not in computer._backend_env()
+
+
+def test_cli_startup_passes_force_caps_to_server(monkeypatch):
+ from computer_server.cli import main
+
+ # Restore every environment variable CLI startup can change.
+ for name in ("CUA_BACKEND", "CUA_VNC_HOST", "CUA_VNC_PORT", "CUA_VNC_FORCE_CAPS"):
+ monkeypatch.delenv(name, raising=False)
+ monkeypatch.setattr(
+ sys, "argv", ["computer-server", "--vnc-host", "127.0.0.1", "--vnc-force-caps"]
+ )
+ startup_env = {}
+ server = Mock()
+ server.start.side_effect = lambda: startup_env.update(os.environ)
+ server_module = ModuleType("computer_server.server")
+ server_module.Server = Mock(return_value=server)
+ monkeypatch.setitem(sys.modules, "computer_server.server", server_module)
+
+ main()
+
+ server.start.assert_called_once_with()
+ assert startup_env["CUA_BACKEND"] == "vnc"
+ assert startup_env["CUA_VNC_FORCE_CAPS"] == "true"
+
+
+async def test_computer_run_passes_force_caps_to_provider(monkeypatch):
+ from computer.computer import Computer, InterfaceFactory, VMProviderFactory, helpers
+
+ provider = AsyncMock()
+ provider.get_vm.return_value = {"status": "stopped"}
+ monkeypatch.setattr(VMProviderFactory, "create_provider", Mock(return_value=provider))
+ interface = AsyncMock()
+ monkeypatch.setattr(InterfaceFactory, "create_interface_for_os", Mock(return_value=interface))
+ monkeypatch.setattr(helpers, "set_default_computer", Mock())
+ computer = Computer(
+ name="force-caps-test",
+ provider_type="lume",
+ telemetry_enabled=False,
+ backend="vnc",
+ vnc_host="127.0.0.1",
+ vnc_force_caps=True,
+ )
+ monkeypatch.setattr(computer, "get_ip", AsyncMock(return_value="127.0.0.1"))
+
+ try:
+ await computer.run()
+
+ provider.run_vm.assert_awaited_once()
+ options = provider.run_vm.call_args.kwargs["run_opts"]
+ assert options["env"]["CUA_BACKEND"] == "vnc"
+ assert options["env"]["CUA_VNC_FORCE_CAPS"] == "true"
+ interface.wait_for_ready.assert_awaited_once()
+ finally:
+ if hasattr(computer, "_keep_alive_task"):
+ computer._stop_event.set()
+ await computer._keep_alive_task
+
+
+def test_connection_uses_force_caps_factory(monkeypatch):
+ _require_vncdotool()
+ import twisted.internet
+
+ client = SimpleNamespace(transport=Mock(), keyPress=Mock())
+ factories = []
+
+ def connect(host, port, factory):
+ assert (host, port) == ("127.0.0.1", 5900)
+ factories.append(factory)
+ factory.deferred.callback(client)
+
+ reactor = SimpleNamespace(
+ running=True,
+ connectTCP=Mock(side_effect=connect),
+ callFromThread=lambda work: work(),
+ )
+ monkeypatch.setattr(twisted.internet, "reactor", reactor)
+ connection = _VNCConnection("127.0.0.1", 5900, "secret", force_caps=True)
+
+ connection.key_press("_")
+
+ reactor.connectTCP.assert_called_once()
+ assert factories[0].force_caps is True
+ assert factories[0].password == "secret"
+ client.keyPress.assert_called_once_with("_")
+ client.transport.loseConnection.assert_called_once_with()
diff --git a/libs/python/computer/computer/computer.py b/libs/python/computer/computer/computer.py
index fb07c4db9f..519a378a06 100644
--- a/libs/python/computer/computer/computer.py
+++ b/libs/python/computer/computer/computer.py
@@ -119,6 +119,7 @@ class Computer:
vnc_port: int = 5900,
vnc_password: str = "",
run_opts: Optional[Dict[str, Any]] = None,
+ vnc_force_caps: bool = False,
):
"""Initialize a new Computer instance.
@@ -164,6 +165,10 @@ class Computer:
vnc_port: VNC server port (default: 5900)
vnc_password: VNC server password
run_opts: Optional dictionary of provider-specific run options.
+ vnc_force_caps: Synthesise Shift around shifted characters when typing over
+ VNC. Some servers (notably QEMU's) only apply the shift level implied by
+ a keysym to letters, so symbols like '@' arrive as '2'. Only used when
+ backend='vnc'.
"""
self.logger = Logger("computer", verbosity)
@@ -224,6 +229,7 @@ class Computer:
self.vnc_host = vnc_host
self.vnc_port = vnc_port
self.vnc_password = vnc_password
+ self.vnc_force_caps = vnc_force_caps
if "app-use" in self.experiments:
assert self.os_type == "macos", "App use experiment is only supported on macOS"
@@ -359,6 +365,25 @@ class Computer:
loop = asyncio.get_event_loop()
loop.run_until_complete(self.__aexit__(exc_type, exc_val, exc_tb))
+ def _backend_env(self) -> Dict[str, str]:
+ """Environment the computer-server needs to select and configure its backend.
+
+ Every VNC setting has to travel this way: the server reads its backend
+ configuration from the environment, and a setting that is not forwarded here
+ silently falls back to its default inside the VM.
+ """
+ if self.backend != "vnc":
+ return {}
+ env: Dict[str, str] = {"CUA_BACKEND": "vnc"}
+ if self.vnc_host:
+ env["CUA_VNC_HOST"] = self.vnc_host
+ env["CUA_VNC_PORT"] = str(self.vnc_port)
+ if self.vnc_password:
+ env["CUA_VNC_PASSWORD"] = self.vnc_password
+ if self.vnc_force_caps:
+ env["CUA_VNC_FORCE_CAPS"] = "true"
+ return env
+
async def run(self) -> Optional[str]:
"""Initialize the VM and computer interface."""
if TYPE_CHECKING:
@@ -551,14 +576,9 @@ class Computer:
run_opts["shared_directories"] = shared_dirs.copy()
# Pass backend configuration as env vars for the computer-server
- if self.backend == "vnc":
- run_opts.setdefault("env", {})
- run_opts["env"]["CUA_BACKEND"] = "vnc"
- if self.vnc_host:
- run_opts["env"]["CUA_VNC_HOST"] = self.vnc_host
- run_opts["env"]["CUA_VNC_PORT"] = str(self.vnc_port)
- if self.vnc_password:
- run_opts["env"]["CUA_VNC_PASSWORD"] = self.vnc_password
+ backend_env = self._backend_env()
+ if backend_env:
+ run_opts.setdefault("env", {}).update(backend_env)
# Merge custom run_opts
run_opts.update(self.custom_run_opts)