Skip to content

Building from source ​

KeyLayers is a Swift 6 app built with Tuist and The Composable Architecture. The source is on GitHub, MIT licensed.

Requires mise, which installs Tuist and the other tools.

Without an Apple Developer account the project builds ad hoc: you can build and run the configurator and run the unit and snapshot tests. Remapping does not work.

Remapping requires a paid Apple Developer Program membership. The helper creates its virtual keyboard with the restricted com.apple.developer.hid.virtual.device entitlement, which needs a provisioning profile. The root input service exits at startup without a team ID, because it can only verify its XPC peer with a team signature and it streams keystrokes as root. As far as we know, a free Personal Team can't add the HID Virtual Device capability. The bundle IDs under com.plunien.keylayers belong to the author's team, so use your own prefix.

Setup (Xcode 27.2; Tuist.swift pins it):

  1. mise install, then git lfs install && git lfs pull (snapshot references are in Git LFS).
  2. cp mise.local.toml.example mise.local.toml and set TUIST_TEAM_ID and TUIST_BUNDLE_ID_PREFIX (mise loads it for every task; the file is git-ignored).
  3. In the developer portal, register the App IDs <prefix>.dev.configurator (no capabilities) and <prefix>.dev.helper with the "HID Virtual Device (development)" capability. <prefix>.dev.inputservice needs no App ID. Debug builds use <prefix>.dev for every identifier (App Group <TEAMID>.<prefix>.dev, so their own configuration file) and show as "KeyLayers Dev", so they never collide with an installed release; release builds use <prefix> itself.
  4. Sign in to that team in Xcode (Settings, Accounts).
  5. mise run build. It passes -allowProvisioningUpdates, so Xcode creates the development profile. After each Debug build the helper restarts and the input service replaces itself on the helper's next connection (a gap of about 2 s).
  6. Launch the app and grant the permissions as in the setup guide.
  7. mise run test runs the unit and snapshot tests.
VariableNeeded forDefault
TUIST_TEAM_IDRemapping, signed builds, releasenone (ad hoc build)
TUIST_BUNDLE_ID_PREFIXUsing your own App IDscom.plunien.keylayers
HELPER_PROVISIONING_PROFILERelease only: Developer ID profile name for the helpernone
ASC_API_KEY, ASC_API_KEY_ID, ASC_API_ISSUER_IDRelease only: notarizationnone
DEVELOPER_ID_CERTIFICATERelease only, optional: base64 .p12 instead of a login keychain identitynone

fnox.toml holds the maintainer's age-encrypted secrets, which only the author and CI can decrypt.

No Tuist account is needed. The project is connected to the Tuist server for a shared binary cache of the external packages (TCA and its dependencies); without a login Tuist simply builds them from source. Maintainers get the cache locally with tuist auth login. Everyone else uses mise.local.toml or plain environment variables.

The website ​

This site is built with VitePress from docs/. Node and the package manager aube come from mise.

TaskDoes
mise run site:devServes the site with live reload at http://localhost:5173/KeyLayers/
mise run site:buildBuilds it into docs/.vitepress/dist and checks it (screenshots, base paths)
mise run site:previewBuilds and serves the build
mise run site:imagesCopies the app screenshots from the snapshot test references, and the app icon from an installed KeyLayers
mise run site:screenshotsCaptures the System Settings screenshots in a throwaway tart VM, guided

site:screenshots needs tart. The first run prepares a base VM, keylayers-screenshots-base, from ghcr.io/cirruslabs/macos-tahoe-xcode:27, and asks you once to allow the guest agent to control System Events (to switch between light and dark). Each run clones the base, installs the latest release, opens the clone in Screen Sharing and walks you through the shots; the clone is deleted afterwards. --only <name> redoes one shot, --reset-base rebuilds the base.

A pull request that touches the site builds it; a push to main deploys it to GitHub Pages.

More ​

Released under the MIT License.