{"id":13831516,"url":"https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice","last_synced_at":"2025-07-09T15:32:20.441Z","repository":{"id":40637464,"uuid":"262576736","full_name":"pqrs-org/Karabiner-DriverKit-VirtualHIDDevice","owner":"pqrs-org","description":null,"archived":false,"fork":false,"pushed_at":"2024-08-28T22:57:24.000Z","size":112106,"stargazers_count":222,"open_issues_count":14,"forks_count":26,"subscribers_count":20,"default_branch":"main","last_synced_at":"2024-08-28T23:52:36.938Z","etag":null,"topics":["dext","driverkit","hid","keyboard","macos"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pqrs-org.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-09T13:27:08.000Z","updated_at":"2024-08-19T12:56:03.000Z","dependencies_parsed_at":"2024-08-28T23:49:39.054Z","dependency_job_id":"5bf9f51a-875f-4129-a015-8e02061ec131","html_url":"https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice","commit_stats":null,"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pqrs-org%2FKarabiner-DriverKit-VirtualHIDDevice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pqrs-org%2FKarabiner-DriverKit-VirtualHIDDevice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pqrs-org%2FKarabiner-DriverKit-VirtualHIDDevice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pqrs-org%2FKarabiner-DriverKit-VirtualHIDDevice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pqrs-org","download_url":"https://codeload.github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225565822,"owners_count":17489272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dext","driverkit","hid","keyboard","macos"],"created_at":"2024-08-04T10:01:29.963Z","updated_at":"2025-07-09T15:32:20.410Z","avatar_url":"https://github.com/pqrs-org.png","language":"C++","funding_links":[],"categories":["Keyboard","C++"],"sub_categories":[],"readme":"[![Build Status](https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice/workflows/CI/badge.svg)](https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice/actions)\n[![License](https://img.shields.io/badge/license-Public%20Domain-blue.svg)](https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice/blob/main/LICENSE.md)\n\n# Karabiner-DriverKit-VirtualHIDDevice\n\nThis project implements a virtual keyboard and virtual mouse using DriverKit on macOS.\nThese virtual devices are recognized by macOS as same as physical hardware, allowing you to control macOS with keystrokes and mouse inputs from the virtual devices.\n\nThe client for controlling the virtual devices is provided as a header-only C++ library.\nBy integrating this library, your software can control the virtual devices.\n\n**Note:**\nThe ability to send keystrokes and mouse inputs means having full control over macOS.\nTherefore, to prevent malicious software from manipulating the virtual devices, the virtual devices will only accept commands from processes running with root privileges.\nThis means that the software incorporating the client library must be run with root privileges.\n\n## Supported systems\n\n-   macOS 26 Tahoe\n    -   Apple Silicon Macs\n    -   It will probably work on Intel Macs as well, but we haven't tested it.\n-   macOS 15 Sequoia\n    -   Both Intel-based Macs and Apple Silicon Macs\n-   macOS 14 Sonoma\n    -   Both Intel-based Macs and Apple Silicon Macs\n-   macOS 13 Ventura\n    -   Both Intel-based Macs and Apple Silicon Macs\n\n## Screenshots\n\n-   macOS Settings (macOS detects the virtual keyboard)\u003cbr/\u003e\u003cbr /\u003e\n    \u003cimg src=\"docs/images/macos-settings@2x.png\" width=\"668\" alt=\"System Preferences\" /\u003e\u003cbr /\u003e\u003cbr /\u003e\n\n---\n\n## Usage\n\n1.  Open `dist/Karabiner-DriverKit-VirtualHIDDevice-x.x.x.pkg`.\n2.  Install files via installer.\n3.  Execute the following command in Terminal.\n\n    ```shell\n    /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate\n    ```\n\n4.  Run Karabiner-VirtualHIDDevice-Daemon:\n\n    ```shell\n    sudo '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-VirtualHIDDevice-Daemon.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Daemon'\n    ```\n\n5.  Run a client program to test the driver extension.\n\n    ```shell\n    git clone --depth 1 https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice.git\n    cd Karabiner-DriverKit-VirtualHIDDevice/examples/virtual-hid-device-service-client\n    brew install xcodegen\n    make\n    make run\n    ```\n\n## Uninstallation\n\n1.  Run uninstaller in Terminal.\n\n    ```shell\n    bash '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/scripts/uninstall/deactivate_driver.sh'\n    sudo bash '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/scripts/uninstall/remove_files.sh'\n    sudo killall Karabiner-VirtualHIDDevice-Daemon\n    ```\n\n### Installed files\n\n-   `/Applications/.Karabiner-VirtualHIDDevice-Manager.app`\n-   `/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice`\n-   `/Library/Application Support/org.pqrs/tmp`\n-   `/var/log/karabiner`\n\n---\n\n## How to build a package from source code\n\nTo run DriverKit drivers, simply building from the code is not sufficient; proper signing is also necessary.\nIn particular, a general developer account lacks the necessary permissions for DriverKit signing, so you need to apply to Apple for higher privileges.\nThe primary focus of this document is on signing.\n\n### System requirements\n\n-   macOS 14+\n-   Xcode 15+\n-   Command Line Tools for Xcode\n-   [XcodeGen](https://github.com/yonaskolb/XcodeGen)\n\n### Obtain DriverKit entitlements\n\nTo create an App ID that supports the `com.apple.developer.driverkit` entitlement required for distributing DriverKit drivers, you need to apply to Apple with your developer account to obtain the necessary permissions.\n\nSpecifically, follow the instructions on [Requesting Entitlements for DriverKit Development](https://developer.apple.com/documentation/driverkit/requesting_entitlements_for_driverkit_development)\n\nNote: This process may take some time to be completed on Apple's side.\n\n### Create App IDs\n\nCreate the following App IDs on the [Apple Developer](https://developer.apple.com/account/resources/identifiers/list) site.\n\n\u003ctable\u003e\n    \u003cthead\u003e\n        \u003ctr\u003e\n            \u003cth\u003eBundle ID\u003c/th\u003e\n            \u003cth\u003eCapabilities\u003c/th\u003e\n            \u003cth\u003eApp Services\u003c/th\u003e\n            \u003cth\u003eAdditional Capabilities\u003c/th\u003e\n        \u003c/tr\u003e\n    \u003c/thead\u003e\n    \u003ctbody\u003e\n        \u003ctr\u003e\n            \u003ctd\u003eorg.pqrs.Karabiner-DriverKit-VirtualHIDDevice\u003c/td\u003e\n            \u003ctd\u003e---\u003c/td\u003e\n            \u003ctd\u003e---\u003c/td\u003e\n            \u003ctd\u003e\n                com.apple.developer.driverkit\u003cbr/\u003e\n                com.apple.developer.driverkit.family.hid.device\u003cbr/\u003e\n                com.apple.developer.driverkit.family.hid.eventservice\u003cbr/\u003e\n                com.apple.developer.driverkit.transport.hid\u003cbr/\u003e\n                com.apple.developer.hid.virtual.device\u003cbr/\u003e\n            \u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n            \u003ctd\u003eorg.pqrs.Karabiner-VirtualHIDDevice-Daemon\u003c/td\u003e\n            \u003ctd\u003e---\u003c/td\u003e\n            \u003ctd\u003e---\u003c/td\u003e\n            \u003ctd\u003e---\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n            \u003ctd\u003eorg.pqrs.Karabiner-VirtualHIDDevice-Manager\u003c/td\u003e\n            \u003ctd\u003e\n                System Extension\u003cbr/\u003e\n            \u003c/td\u003e\n            \u003ctd\u003e---\u003c/td\u003e\n            \u003ctd\u003e---\u003c/td\u003e\n        \u003c/tr\u003e\n    \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003ctable\u003e\u003ctr\u003e\u003ctd\u003e\u003c!-- border hack --\u003e\n\u003cimg src=\"docs/images/additional-capabilities@2x.png\" alt=\"Additional Capabilities\" style=\"border: 1px solid gray\" /\u003e\n\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n\n### Grant permission for com.apple.developer.driverkit.userclient-access from Apple\n\nThe entitlement of `com.apple.developer.driverkit.userclient-access` must be applied for from Apple, and unless individually authorized, it cannot be granted to your application.\nYou can apply through the request form: \u003chttps://developer.apple.com/contact/request/system-extension/\u003e\n\n### Create a profile corresponding to the App IDs on the Apple Developer site\n\n| Profile      | App ID                                        | Entitlements                                                        |\n| ------------ | --------------------------------------------- | ------------------------------------------------------------------- |\n| Developer ID | org.pqrs.Karabiner-DriverKit-VirtualHIDDevice | DriverKit and System Extension Template for XXXXXXXX (Developer ID) |\n| Developer ID | org.pqrs.Karabiner-VirtualHIDDevice-Daemon    | DriverKit and System Extension Template for XXXXXXXX (Developer ID) |\n| Developer ID | org.pqrs.Karabiner-VirtualHIDDevice-Manager   | Default                                                             |\n\nPlease ensure that `com.apple.developer.driverkit.userclient-access` appears under Extended Entitlements when you select `DriverKit and System Extension Template` in Entitlements.\n\n\u003ctable\u003e\u003ctr\u003e\u003ctd\u003e\u003c!-- border hack --\u003e\n\u003cimg src=\"docs/images/entitlements@2x.png\" alt=\"entitlements\" /\u003e\u003cbr /\u003e\u003cbr /\u003e\n\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n\n### Replace the `*.provisionprofile` files in the repository with your own provision profile files\n\n-   src/Daemon/Developer_ID_KarabinerVirtualHIDDeviceDaemon.provisionprofile\n-   src/DriverKit/Developer_ID_KarabinerDriverKitVirtualHIDDevice.provisionprofile\n-   src/Manager/Developer_ID_KarabinerVirtualHIDDeviceManager.provisionprofile\n\n### Replace team identifier, domain and embedded.provisionprofile\n\nSearch `G43BCU2T37` and replace them with your team identifier.\n\n```shell\ngit grep G43BCU2T37 src/\n```\n\n### Open Terminal.app to create a package\n\nThe rest of the operations will be performed in the terminal.\n\n### Set environment variables for signing\n\nSet the following environment variables for application signing and package signing.​\n\n-   `PQRS_ORG_CODE_SIGN_IDENTITY`\n-   `PQRS_ORG_INSTALLER_CODE_SIGN_IDENTITY`\n\nYou can determine the values using the following methods:\n\nFind the value for `PQRS_ORG_CODE_SIGN_IDENTITY`:\n\n```shell\nsecurity find-identity -p codesigning -v | grep 'Developer ID Application'\n```\n\n```text\n    2) BD3B995B69EBA8FC153B167F063079D19CCC2834 \"Developer ID Application: Fumihiko Takayama (G43BCU2T37)\"\n```\n\nThen, set `PQRS_ORG_CODE_SIGN_IDENTITY`\n\n```shell\nexport PQRS_ORG_CODE_SIGN_IDENTITY=BD3B995B69EBA8FC153B167F063079D19CCC2834\n```\n\nFind the value for `PQRS_ORG_INSTALLER_CODE_SIGN_IDENTITY`:\n\n```shell\nsecurity find-identity -p basic -v | grep 'Developer ID Installer'\n```\n\n```text\n  1) C3107C61DB3605DA2D4549054B225DAFB1D6FA2D \"Developer ID Installer: Fumihiko Takayama (G43BCU2T37)\"\n```\n\nThen, set `PQRS_ORG_INSTALLER_CODE_SIGN_IDENTITY`\n\n```shell\nexport PQRS_ORG_INSTALLER_CODE_SIGN_IDENTITY=C3107C61DB3605DA2D4549054B225DAFB1D6FA2D\n```\n\n### Build a package\n\n```shell\nmake package\n```\n\n`dist/Karabiner-DriverKit-VirtualHIDDevice-X.X.X.pkg` will be generated.\n\n### Notarize the package\n\nCreate App-Specific Passwords on \u003chttps://appleid.apple.com\u003e.\n\n-   name: `pqrs.org notarization`\n\nExecute `store-credentials`\n\n```shell\nxcrun notarytool store-credentials --apple-id tekezo@pqrs.org --team-id G43BCU2T37\n\nProfile name:\n\u003e pqrs.org notarization\n\nApp-specific password for tekezo@pqrs.org:\n\u003e The password you created earlier\n```\n\nThen, notarize the package:\n\n```shell\nmake notarize\n```\n\n---\n\n## More detailed information\n\n### Components\n\nKarabiner-DriverKit-VirtualHIDDevice consists the following components.\n\n-   Extension Manager (including DriverKit driver)\n    -   `/Applications/.Karabiner-VirtualHIDDevice-Manager.app`\n    -   It provides a command line interface to activate or deactivate DriverKit driver.\n-   Karabiner-VirtualHIDDevice-Daemon\n    -   `/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-VirtualHIDDevice-Daemon.app`\n    -   It mediates between the client app and the driver.\n    -   It allows apps to communicate with the virtual device even if the app is not signed with pqrs.org's code signing identity.\n        (The client app must be running with root privileges.)\n-   Client apps\n    -   Client apps are not included in the distributed package.\n    -   For example, you can build the client app from `examples/virtual-hid-device-service-client` in this repository.\n    -   Client apps can send input events by communicating with Karabiner-VirtualHIDDevice-Daemon via UNIX domain socket.\n        (`/Library/Application Support/org.pqrs/tmp/rootonly/vhidd_server/*.sock`)\n\n![components.svg](./docs/plantuml/output/components.svg)\n\n### Versions\n\nVersion is defined in `version.json`.\n\n-   `package_version`:\n    -   Karabiner-DriverKit-VirtualHIDDevice package version.\n    -   Increment this when any components are updated.\n-   `driver_version`:\n    -   DriverKit driver internal version.\n    -   Increment this when the driver source code is updated.\n-   `client_protocol_version`:\n    -   The version for communication between Karabiner-VirtualHIDDevice-Daemon and the DriverKit driver.\n    -   Increment this when the communication specifications are changed.\n\n### Run Karabiner-VirtualHIDDevice-Daemon via launchd\n\nKarabiner-VirtualHIDDevice-Daemon requires high responsiveness, so it is recommended to run it via launchd with the `ProcessType: Interactive` specified.\nThere is an example application for registration with launchd in `examples/SMAppServiceExample`, which you can refer to for registering with launchd.\n\n### Extra documents\n\n-   [How to be close to DriverKit](DEVELOPMENT.md)\n-   [Extracts from xnu](XNU.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpqrs-org%2FKarabiner-DriverKit-VirtualHIDDevice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpqrs-org%2FKarabiner-DriverKit-VirtualHIDDevice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpqrs-org%2FKarabiner-DriverKit-VirtualHIDDevice/lists"}