Support

Set up

1. Install Sidekey on your Mac. Download Sidekey.dmg, open it and drag Sidekey to Applications. Open Sidekey; it appears in the menu bar. To start it when you log in, tick Launch at Login in the Sidekey menu (Mac 1.4.0 or later).
2. Allow Accessibility. macOS asks the first time. Switch Sidekey on in System Settings › Privacy & Security › Accessibility.
3. Open Sidekey on your iPad or iPhone and allow it to find devices on your local network.
4. Connect the two. Put both on the same Wi-Fi network. An iPad can also plug into the Mac with a USB cable.
5. Pair once. On the Mac, choose Pair Device... in the Sidekey menu. A window shows a 6-digit code for two minutes. Type it on the iPad or iPhone and tap Pair. From then on it connects to that Mac by itself, and the top of the screen shows the Mac's name and whether the link is USB or Wi-Fi.

Pairing

• Until a device is paired, the Mac sends it only its name and a pairing request, and runs none of its taps.
• If Sidekey says the code is wrong, check the code in the Mac's Pair Device window. The window says iPad, but the same code works on iPhone. After five wrong codes, or two minutes, choose Pair Device again for a new code.
• To pair with a different Mac, press and hold the connection label in Sidekey while it is connected and choose Forget This Mac. If the old Mac is no longer available, delete and reinstall Sidekey on the device.
• To revoke access, choose Forget Paired Devices in the Mac's Sidekey menu. This removes every paired device from that Mac; Forget This Mac on the device only removes its own copy.
• Traffic between the device and the Mac is not encrypted yet. Someone who can watch or tamper with your network could read what Sidekey sends and, by capturing the pairing exchange, press keys in your Mac's layouts, including ones you made, until you choose Forget Paired Devices. Use Sidekey over USB (iPad) or on a network you trust.

Sidekey keeps looking for your Mac

• Check that Sidekey is running on the Mac: its icon should be in the menu bar.
• A paired device looks only for the Mac it paired with. If that Mac is off or Sidekey is not running there, it keeps looking.
• Check both devices are on the same Wi-Fi network, or connect an iPad with a USB cable. Some guest and office networks block devices from seeing each other.
• On the iPad or iPhone, open Settings › Privacy & Security › Local Network and make sure Sidekey is on. On macOS 15 or later, check the same setting on the Mac.
• If you just restarted Sidekey on the Mac, give the iPad or iPhone a few seconds to reconnect.

Keys light up red or say a permission is missing

• Open System Settings › Privacy & Security › Accessibility on the Mac and switch Sidekey on. If it is already on, switch it off and on again; if that does not help, remove it with the minus button and add it back with the plus button.
• If Sidekey is not in the list, click +, choose Sidekey from Applications and switch it on.
• Keys that run AppleScript, such as Play/Pause, also need Automation: check System Settings › Privacy & Security › Automation.

A key says "Layout changed. Tap again."

The app in front of the Mac changed between you looking at the key and tapping it. Sidekey refuses to send a shortcut meant for one app to another. Tap the key again on the new layout, or pin a layout with the pin button so it stays put while you switch apps.

Custom layouts

Custom layouts need Sidekey for Mac 1.4.0 or later. Choose Edit Layouts... in the Sidekey menu on the Mac to change, move, remove and reset keys, or to add a layout for another app with the + button under the list of apps (choosing an app that already has a layout selects it instead). The − (minus) button removes an app you added after you confirm, and the iPad or iPhone then shows the System layout for that app; it is greyed out for built-in apps, where Reset Layout... undoes your changes. Changes take effect at once and show on the iPad or iPhone when that app is in front. On a pinned layout, a key you changed, moved, removed or reset is refused until you unpin, bring the app to the front and pin again; keys you have not changed since pinning keep working. If you reset or remove a layout you added for an app, unpin it.

A custom key can send a keyboard or Windows shortcut, run one of your Apple Shortcuts, or switch Citrix modes. It cannot run shell commands or AppleScript itself; an Apple Shortcut you choose runs whatever steps it contains. Built-in keys that run scripts can be replaced or removed but not edited or moved. A key that lights with the app's state, such as Zoom's mute key or a Citrix mode key, stops lighting once you edit or move it.

Each customised layout is a file called <layoutId>.json in ~/Library/Application Support/Sidekey/Layouts/. You can edit these by hand; then choose Reload Layouts in the menu.

"N layout files have errors"

Sidekey checks every layout file each time it loads. A file that is not valid, has the wrong name, or uses an action custom keys cannot have (such as a shell command or AppleScript) is refused whole. The app it belongs to uses its built-in layout instead, or the System layout if you added the app. The menu shows "1 layout file has errors..." or "N layout files have errors..."; click it to see each file and the reason. To fix it, edit the file in the folder above and choose Reload Layouts. To discard it, open Edit Layouts, find it under Files with errors and choose Delete File...; your changes in that file are lost. The editor will not save over a broken file until you fix or delete it.

Some keys need a press and hold

Keys that interrupt what you are doing, such as Lock Mac, Interrupt, End Call, Telegram Lock, Xcode Clean, and Citrix Viewer's Lock, Close App and Teams Leave, fire only after you hold them for just over half a second. A short tap shows a reminder instead.

Citrix Viewer

With a Citrix session in front, Sidekey shows Windows keys such as Start, File Explorer, Switch App and Alt+F4 and sends them into the session. Citrix turns Mac keys into Windows keys according to its own settings, so the layout needs these in Citrix Viewer › Settings › Keyboard:

• Send Control character using: Command (left) or Control.
• Send Alt character using: Command (left)-Option.
• Send Windows logo key using Command (right): on.
• Send F1 - F12 keys with Option: on.

With other settings the Alt, Windows and function keys send the wrong shortcut. Sidekey cannot see which Windows app is in front inside the session, so you choose a mode with the bottom row: Windows, Outlook, Browser or VS Code, or More for Word, Excel and Teams. The lit key and the top of the screen show the current mode, and Sidekey remembers it when you switch away and back. The Citrix layout needs Sidekey for Mac 1.3.0 or later.

Do Not Disturb does nothing

The Do Not Disturb key runs a shortcut named Toggle Focus. Create a shortcut with that name in the Shortcuts app on your Mac, for example one that turns a Focus on or off.

Zoom meeting state

Sidekey shows Zoom meeting state, such as whether your mic is muted, by reading Zoom's menus. This is built from Zoom's documented menu wording and has not yet been tested in a live meeting. If it shows the wrong state, please let us know.

Requirements

• iPad with iPadOS 16 or later, or iPhone with iOS 16 or later.
• Mac with macOS 13 or later.
• Both on the same Wi-Fi network, or a USB cable between an iPad and the Mac.

Contact

Email m.hoque@gmail.com, or open an issue on GitHub.