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(nix): add Nix package and NixOS integration test for cua-driver (#1746)

r33drichardsa145f205b21b
diff --git a/.github/workflows/nix-build.yml b/.github/workflows/nix-build.yml
new file mode 100644
index 0000000000..809d0fa9ff
--- /dev/null
+++ b/.github/workflows/nix-build.yml
@@ -0,0 +1,95 @@
+name: Nix Build & Integration Tests
+
+on:
+ pull_request:
+ paths:
+ - 'nix/**'
+ - 'flake.nix'
+ - 'flake.lock'
+ - 'libs/cua-driver/rust/**'
+ - '.github/workflows/nix-build.yml'
+ push:
+ branches: [main]
+ paths:
+ - 'nix/**'
+ - 'flake.nix'
+ - 'flake.lock'
+ - 'libs/cua-driver/rust/**'
+ - '.github/workflows/nix-build.yml'
+ workflow_dispatch:
+
+permissions:
+ id-token: write
+ contents: read
+
+env:
+ AWS_REGION: us-west-2
+ NIX_CACHE_BUCKET: trycua-nix-cache
+ NIX_CACHE_SECRET: nix-cache/trycua-nix-cache/signing-key
+
+jobs:
+ build-and-test:
+ name: Build cua-driver & run integration tests
+ runs-on: ubuntu-latest
+ timeout-minutes: 60
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+ - name: Configure AWS Credentials via OIDC
+ uses: aws-actions/configure-aws-credentials@ff717079ee2060e4bcee96c4779b553acc87447c # v4
+ with:
+ role-to-assume: arn:aws:iam::296062593712:role/github-actions-nix-cache
+ aws-region: ${{ env.AWS_REGION }}
+
+ - name: Get Nix signing key
+ id: nix-key
+ run: |
+ SECRET=$(aws secretsmanager get-secret-value \
+ --secret-id "${{ env.NIX_CACHE_SECRET }}" \
+ --query 'SecretString' --output text)
+
+ SECRET_KEY=$(echo "$SECRET" | jq -r '.secret_key')
+ echo "::add-mask::$SECRET_KEY"
+ echo "$SECRET_KEY" > "${{ runner.temp }}/signing-key.sec"
+ chmod 600 "${{ runner.temp }}/signing-key.sec"
+
+ PUBLIC_KEY=$(echo "$SECRET" | jq -r '.public_key')
+ echo "public_key=$PUBLIC_KEY" >> "$GITHUB_OUTPUT"
+
+ - name: Setup AWS credentials file for Nix
+ run: |
+ mkdir -p ~/.aws
+ printf '[default]\naws_access_key_id = %s\naws_secret_access_key = %s\naws_session_token = %s\nregion = %s\n' \
+ "$AWS_ACCESS_KEY_ID" "$AWS_SECRET_ACCESS_KEY" "$AWS_SESSION_TOKEN" "$AWS_REGION" > ~/.aws/credentials
+ chmod 600 ~/.aws/credentials
+
+ sudo mkdir -p /root/.aws
+ sudo bash -c "printf '[default]\naws_access_key_id = %s\naws_secret_access_key = %s\naws_session_token = %s\nregion = %s\n' \
+ '$AWS_ACCESS_KEY_ID' '$AWS_SECRET_ACCESS_KEY' '$AWS_SESSION_TOKEN' '$AWS_REGION' > /root/.aws/credentials"
+ sudo chmod 600 /root/.aws/credentials
+
+ - name: Install Nix
+ uses: cachix/install-nix-action@08dcb3a5e62fa31e2da3d490afc4176ef55ecd72 # v30
+ with:
+ extra_nix_config: |
+ experimental-features = nix-command flakes
+ substituters = s3://${{ env.NIX_CACHE_BUCKET }}?region=${{ env.AWS_REGION }} https://cache.nixos.org
+ trusted-substituters = s3://${{ env.NIX_CACHE_BUCKET }}?region=${{ env.AWS_REGION }}
+ trusted-public-keys = ${{ steps.nix-key.outputs.public_key }} cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
+
+ - name: Run NixOS integration test
+ timeout-minutes: 8
+ run: nix build .#checks.x86_64-linux.cua-driver-integration --print-build-logs --show-trace
+
+ - name: Sign and upload to Nix cache
+ if: always()
+ run: |
+ echo "Signing and uploading build artifacts to Nix cache..."
+ nix store sign --key-file "${{ runner.temp }}/signing-key.sec" --all
+ nix copy --to "s3://${{ env.NIX_CACHE_BUCKET }}?region=${{ env.AWS_REGION }}&want-mass-query=true" --all -L
+
+ - name: Cleanup signing key
+ if: always()
+ run: rm -f "${{ runner.temp }}/signing-key.sec"
diff --git a/flake.lock b/flake.lock
new file mode 100644
index 0000000000..c5e45dfd0f
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,61 @@
+{
+ "nodes": {
+ "flake-utils": {
+ "inputs": {
+ "systems": "systems"
+ },
+ "locked": {
+ "lastModified": 1731533236,
+ "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+ "owner": "numtide",
+ "repo": "flake-utils",
+ "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+ "type": "github"
+ },
+ "original": {
+ "owner": "numtide",
+ "repo": "flake-utils",
+ "type": "github"
+ }
+ },
+ "nixpkgs": {
+ "locked": {
+ "lastModified": 1779560665,
+ "narHash": "sha256-tpyBcxPpcQb8ukyNF7DoCwfSY3VPsxHoYwj00Cayv5o=",
+ "owner": "NixOS",
+ "repo": "nixpkgs",
+ "rev": "64c08a7ca051951c8eae34e3e3cb1e202fe36786",
+ "type": "github"
+ },
+ "original": {
+ "owner": "NixOS",
+ "ref": "nixos-unstable",
+ "repo": "nixpkgs",
+ "type": "github"
+ }
+ },
+ "root": {
+ "inputs": {
+ "flake-utils": "flake-utils",
+ "nixpkgs": "nixpkgs"
+ }
+ },
+ "systems": {
+ "locked": {
+ "lastModified": 1681028828,
+ "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+ "owner": "nix-systems",
+ "repo": "default",
+ "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+ "type": "github"
+ },
+ "original": {
+ "owner": "nix-systems",
+ "repo": "default",
+ "type": "github"
+ }
+ }
+ },
+ "root": "root",
+ "version": 7
+}
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 0000000000..3cb97ed19e
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,61 @@
+{
+ description = "CUA - Computer Use Agent";
+
+ inputs = {
+ nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+ flake-utils.url = "github:numtide/flake-utils";
+ };
+
+ outputs =
+ {
+ self,
+ nixpkgs,
+ flake-utils,
+ ...
+ }:
+ flake-utils.lib.eachSystem
+ [
+ "x86_64-linux"
+ "aarch64-linux"
+ ]
+ (
+ system:
+ let
+ pkgs = import nixpkgs { inherit system; };
+
+ rustSrc = ./libs/cua-driver/rust;
+
+ cuaDriverPackage = import ./nix/cua-driver/package.nix {
+ inherit pkgs;
+ src = rustSrc;
+ };
+ in
+ {
+ packages = {
+ cua-driver = cuaDriverPackage;
+ default = cuaDriverPackage;
+ };
+
+ checks =
+ {
+ cua-driver-build = cuaDriverPackage;
+ }
+ // pkgs.lib.optionalAttrs (system == "x86_64-linux") {
+ # NixOS VM integration test (x86_64-linux only)
+ cua-driver-integration = import ./nix/cua-driver/tests/integration.nix {
+ inherit pkgs;
+ inherit (pkgs) lib;
+ cuaDriverModule = {
+ imports = [ ./nix/cua-driver/module.nix ];
+ services.cua-driver.package = cuaDriverPackage;
+ };
+ };
+ };
+ }
+ )
+ // {
+ # NixOS module — consumers must set services.cua-driver.package
+ # (or use the per-system package from self.packages)
+ nixosModules.cua-driver = ./nix/cua-driver/module.nix;
+ };
+}
diff --git a/nix/cua-driver/module.nix b/nix/cua-driver/module.nix
new file mode 100644
index 0000000000..879420d151
--- /dev/null
+++ b/nix/cua-driver/module.nix
@@ -0,0 +1,47 @@
+# CUA Driver NixOS Module
+#
+# Installs the cua-driver binary and its runtime dependencies for
+# Linux computer-use automation (X11, AT-SPI accessibility, ImageMagick).
+#
+# Usage in a NixOS configuration:
+# imports = [ ./nix/cua-driver/module.nix ];
+# services.cua-driver = {
+# enable = true;
+# package = cuaDriverPackage;
+# };
+#
+{
+ config,
+ lib,
+ pkgs,
+ ...
+}:
+
+let
+ cfg = config.services.cua-driver;
+in
+{
+ options.services.cua-driver = {
+ enable = lib.mkEnableOption "CUA Driver MCP server for computer-use automation";
+
+ package = lib.mkOption {
+ type = lib.types.package;
+ description = "The cua-driver package to use.";
+ };
+ };
+
+ config = lib.mkIf cfg.enable {
+ environment.systemPackages = [
+ cfg.package
+ pkgs.imagemagick # `import` command used by capture.rs for window screenshots
+ pkgs.at-spi2-core # AT-SPI bus daemon for accessibility tree queries
+ ];
+
+ # D-Bus is required for AT-SPI communication
+ services.dbus.enable = true;
+
+ environment.variables = {
+ CUA_DRIVER_BIN = "${cfg.package}/bin/cua-driver";
+ };
+ };
+}
diff --git a/nix/cua-driver/package.nix b/nix/cua-driver/package.nix
new file mode 100644
index 0000000000..e73d636a0d
--- /dev/null
+++ b/nix/cua-driver/package.nix
@@ -0,0 +1,53 @@
+# Builds cua-driver (Rust MCP server binary) for Linux.
+#
+# The cua-driver binary speaks MCP JSON-RPC 2.0 over stdio and provides
+# 40+ tools for screen capture, mouse/keyboard input, window management,
+# and accessibility-based element interaction.
+#
+# Usage:
+# cuaDriver = import ./package.nix { inherit pkgs; src = ./../../libs/cua-driver/rust; };
+#
+{
+ pkgs,
+ src,
+ ...
+}:
+
+pkgs.rustPlatform.buildRustPackage {
+ pname = "cua-driver";
+ version = "0.3.2";
+
+ inherit src;
+
+ # Use cargoHash (fetchCargoVendor) rather than cargoLock.lockFile because
+ # the workspace Cargo.lock includes macOS-only crates (apple-metal, apple-cf)
+ # that may be unreachable from crates.io. fetchCargoVendor handles this
+ # gracefully via `cargo vendor`.
+ cargoHash = "sha256-nkVI+O2P/QSTx15dCraNNGDAsEw3m7c/u/V6BXXSTww=";
+
+ # Build only the main binary crate. The workspace also contains
+ # platform-macos, platform-windows, cua-driver-uia, and focus-monitor-win
+ # which are gated behind cfg(target_os) and won't compile on Linux.
+ # Using -p cua-driver ensures Cargo only resolves Linux dependencies.
+ cargoBuildFlags = [ "-p" "cua-driver" ];
+ cargoTestFlags = [ "-p" "cua-driver" ];
+
+ # The entire Linux dependency chain is pure Rust:
+ # x11rb -> RustConnection (no libxcb C binding)
+ # ureq -> rustls (no openssl)
+ # tiny-skia -> pure Rust 2D graphics
+ # ring -> compiles own C/asm via stdenv's cc
+ nativeBuildInputs = [ ];
+ buildInputs = [ ];
+
+ # Skip tests that require a running X11 display or AT-SPI bus
+ doCheck = false;
+
+ meta = with pkgs.lib; {
+ description = "Cross-platform MCP server for computer-use automation";
+ homepage = "https://github.com/trycua/cua";
+ license = licenses.mit;
+ mainProgram = "cua-driver";
+ platforms = platforms.linux;
+ };
+}
diff --git a/nix/cua-driver/tests/integration.nix b/nix/cua-driver/tests/integration.nix
new file mode 100644
index 0000000000..3367123ed0
--- /dev/null
+++ b/nix/cua-driver/tests/integration.nix
@@ -0,0 +1,199 @@
+# CUA Driver Integration Test
+#
+# Tests the cua-driver MCP server end-to-end in a NixOS VM with Xvfb.
+# Verifies CLI subcommands, MCP protocol handshake, and tool invocation.
+#
+# To run: nix build .#checks.x86_64-linux.cua-driver-integration
+#
+{
+ pkgs,
+ lib ? pkgs.lib,
+ cuaDriverModule,
+ ...
+}:
+
+let
+ # Python MCP client that drives cua-driver over stdio.
+ # Sends JSON-RPC requests, reads responses, validates structure.
+ mcpClientTest = pkgs.writeText "mcp-client-test.py" ''
+ import subprocess
+ import json
+ import sys
+ import os
+ import threading
+ import time
+
+ DRIVER_BIN = os.environ.get("CUA_DRIVER_BIN", "cua-driver")
+
+ def main():
+ print("=== CUA Driver MCP Integration Test ===", flush=True)
+
+ proc = subprocess.Popen(
+ [DRIVER_BIN, "mcp", "--no-daemon-relaunch"],
+ stdin=subprocess.PIPE,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE,
+ env={**os.environ},
+ )
+
+ # Drain stderr in background to prevent blocking
+ def drain_stderr():
+ for line in proc.stderr:
+ sys.stderr.buffer.write(line)
+ sys.stderr.buffer.flush()
+ t = threading.Thread(target=drain_stderr, daemon=True)
+ t.start()
+
+ def send_request(method, params=None, req_id=None):
+ msg = {"jsonrpc": "2.0", "method": method}
+ if params is not None:
+ msg["params"] = params
+ if req_id is not None:
+ msg["id"] = req_id
+ line = json.dumps(msg) + "\n"
+ print(f"[send] {line.strip()}", flush=True)
+ proc.stdin.write(line.encode())
+ proc.stdin.flush()
+
+ def read_response(timeout=30):
+ # Simple blocking read with timeout via thread
+ result = [None]
+ def reader():
+ result[0] = proc.stdout.readline()
+ rt = threading.Thread(target=reader)
+ rt.start()
+ rt.join(timeout)
+ if rt.is_alive():
+ raise TimeoutError("No response within timeout")
+ line = result[0].decode().strip()
+ print(f"[recv] {line}", flush=True)
+ return json.loads(line)
+
+ try:
+ # Test 1: Initialize
+ print("\n--- Test 1: Initialize ---", flush=True)
+ send_request("initialize", {
+ "protocolVersion": "2024-11-05",
+ "capabilities": {},
+ "clientInfo": {"name": "nixos-test", "version": "1.0.0"},
+ }, req_id=1)
+ resp = read_response()
+ assert resp.get("id") == 1, f"Expected id=1, got {resp.get('id')}"
+ assert "result" in resp, f"Expected result in response: {resp}"
+ assert "serverInfo" in resp["result"], f"Expected serverInfo: {resp['result']}"
+ print("PASS: initialize", flush=True)
+
+ # Send initialized notification (no response expected)
+ send_request("notifications/initialized", {})
+ time.sleep(0.5)
+
+ # Test 2: List tools
+ print("\n--- Test 2: tools/list ---", flush=True)
+ send_request("tools/list", {}, req_id=2)
+ resp = read_response()
+ assert resp.get("id") == 2, f"Expected id=2, got {resp.get('id')}"
+ tools = resp.get("result", {}).get("tools", [])
+ tool_names = [t["name"] for t in tools]
+ print(f"Found {len(tools)} tools: {tool_names[:10]}...", flush=True)
+ assert "click" in tool_names, f"click not in tools: {tool_names}"
+ assert "type_text" in tool_names, f"type_text not in tools: {tool_names}"
+ assert "get_screen_size" in tool_names, f"get_screen_size not in tools: {tool_names}"
+ assert "get_window_state" in tool_names, f"get_window_state not in tools: {tool_names}"
+ print("PASS: tools/list", flush=True)
+
+ # Test 3: Call get_screen_size (works without any windows)
+ print("\n--- Test 3: tools/call get_screen_size ---", flush=True)
+ send_request("tools/call", {
+ "name": "get_screen_size",
+ "arguments": {},
+ }, req_id=3)
+ resp = read_response(timeout=15)
+ assert resp.get("id") == 3, f"Expected id=3, got {resp.get('id')}"
+ # get_screen_size should return display dimensions from Xvfb
+ if "result" in resp:
+ content = resp["result"].get("content", [])
+ text = content[0].get("text", "") if content else ""
+ print(f"PASS: get_screen_size returned: {text[:200]}", flush=True)
+ elif "error" in resp:
+ err_msg = resp.get("error", {}).get("message", "unknown")
+ print(f"PASS: get_screen_size returned error (acceptable in headless): {err_msg}", flush=True)
+ else:
+ raise AssertionError(f"Unexpected response: {resp}")
+
+ print("\n=== All MCP tests passed! ===", flush=True)
+
+ finally:
+ proc.stdin.close()
+ proc.terminate()
+ proc.wait(timeout=5)
+
+ if __name__ == "__main__":
+ main()
+ '';
+
+in
+
+pkgs.testers.nixosTest {
+ name = "cua-driver-integration-test";
+ meta = {
+ maintainers = [ ];
+ };
+
+ nodes.machine =
+ {
+ config,
+ pkgs,
+ lib,
+ ...
+ }:
+ {
+ imports = [ cuaDriverModule ];
+ virtualisation = {
+ cores = 2;
+ memorySize = 2048;
+ };
+ services.cua-driver.enable = true;
+ environment.systemPackages = with pkgs; [
+ xorg.xorgserver # Xvfb for headless X11
+ python3 # MCP client test script
+ jq
+ procps # pgrep/pkill
+ ];
+ };
+
+ testScript = ''
+ machine.start()
+ machine.wait_for_unit("multi-user.target")
+
+ with subtest("Binary exists and runs"):
+ machine.succeed("cua-driver --help")
+
+ with subtest("list-tools prints available tools"):
+ result = machine.succeed("cua-driver list-tools")
+ assert "click" in result, f"click not in: {result}"
+ assert "type_text" in result, f"type_text not in: {result}"
+ assert "get_screen_size" in result, f"get_screen_size not in: {result}"
+
+ with subtest("describe tool outputs schema"):
+ result = machine.succeed("cua-driver describe get_screen_size")
+ assert "input_schema" in result, f"Unexpected describe output: {result[:200]}"
+
+ with subtest("Start Xvfb"):
+ machine.execute("Xvfb :99 -screen 0 1280x1024x24 >/dev/null 2>&1 &")
+ machine.wait_until_succeeds("test -e /tmp/.X11-unix/X99", timeout=10)
+
+ with subtest("doctor with X11 display"):
+ # Timeout doctor to 15s — AT-SPI/gdbus probes can hang without a session bus
+ result = machine.succeed("timeout 15 env DISPLAY=:99 cua-driver doctor 2>&1 || true")
+ machine.log(result)
+
+ with subtest("MCP protocol handshake and tool listing"):
+ machine.copy_from_host("${mcpClientTest}", "/tmp/mcp-client-test.py")
+ result = machine.succeed(
+ "timeout 60 env DISPLAY=:99 "
+ "python3 /tmp/mcp-client-test.py 2>&1"
+ )
+ machine.log(result)
+ assert "All MCP tests passed" in result, f"MCP tests failed: {result}"
+ '';
+}