Skip to content

Installation

Jump to bottom
argenkiwi edited this page Aug 11, 2026 · 1 revision

Installation

This guide walks you through installing keydo on Linux, macOS, and Windows.

Note

keydo runs as a system daemon and requires low-level access to input devices. Make sure you meet the prerequisites for your platform before proceeding.

Prerequisites

Platform Requirements
Linux Root / sudo access; uinput kernel module available
macOS macOS 13.0 or later; Accessibility permissions granted to the binary
Windows Windows 10/11; Visual Studio Build Tools 2019+ with the "Desktop development with C++" workload (build from source only)

A Rust toolchain (2024 edition) is required to build from source.

Step 1 — Build the Binary

Clone the repository and compile a release build with Cargo:

git clone https://github.com/argenkiwi/keydo.git
cd keydo
cargo build --release

Then install the binary into your Cargo bin directory:

cargo install --path .

Make sure the Cargo bin directory is on your PATH:

Platform Default Cargo bin path
Linux / macOS ~/.cargo/bin
Windows %USERPROFILE%\.cargo\bin

Step 2 — Register the Service

keydo needs to run as a background daemon. Use the built-in install subcommand to register it with your platform's service manager.

Linux

# Copy the binary to the system path
sudo cp ~/.cargo/bin/keydo /usr/local/bin/

# Register and start the daemon (supports systemd and runit)
sudo /usr/local/bin/keydo install

Important

The installer automatically creates a keydo system group and configures the IPC socket at /run/keydo/socket with 0660 permissions. Add your user to this group so you can use the CLI without root:

sudo usermod -aG keydo $USER

Log out and back in for the group change to take effect.

Verify the service is running

# systemd
systemctl status keydo

# runit
sv status keydo

macOS

keydo install

This registers keydo as a user-level launchd service that starts automatically at login.

Important

Accessibility permissions are required. After running the installer, go to:

System Settings → Privacy & Security → Accessibility

Add the keydo binary (~/.cargo/bin/keydo) to the list and enable it. Without this, keydo cannot capture or inject key events.

Verify the service is running

launchctl list | grep keydo

Windows

Open an elevated Command Prompt (Run as Administrator) and run:

keydo install

This registers keydo to start automatically at logon via the Windows Task Scheduler / startup mechanism.

Warning

To remap keys inside elevated (admin) windows, the daemon itself must also run elevated. Start the registered task from an elevated prompt or adjust the task settings in Task Scheduler.

Step 3 — Create a Configuration File

keydo uses the same configuration syntax as keyd. Place a .conf file in the appropriate directory for your platform:

Platform Configuration directory
Linux /etc/keyd/
macOS ~/.config/keydo/
Windows %APPDATA%\keydo\ (user) or C:\ProgramData\keyd\ (system-wide)

Minimal example (default.conf):

[ids]
*

[main]
# Caps Lock → Escape when tapped, Control when held
capslock = overload(nav, esc)

[nav]
h = left
j = down
k = up
l = right

After saving the file, reload keydo to apply changes:

keydo reload

For a full reference of the configuration syntax, see the keyd documentation.

Troubleshooting

keydo doesn't start

  • Linux: Check the service logs with journalctl -u keydo (systemd) or inspect runit's log directory.
  • macOS: Run keydo daemon in the foreground to see error output directly. Ensure Accessibility permissions are granted.
  • Windows: Run keydo daemon in an elevated command prompt to see error output.

Key events are not being captured

  • Linux: Verify your user is in the keydo group and that you have logged out and back in.
  • macOS: Re-check Privacy & Security → Accessibility. If you moved or replaced the binary, you may need to re-add it.
  • Windows: The daemon must run elevated to capture input inside elevated windows.

Emergency recovery (Windows)

If input locks up, press and hold Backspace + Enter + Escape simultaneously to instantly terminate the daemon and restore default keyboard behaviour.

Uninstalling

To remove the service registration:

# Linux / macOS / Windows
keydo uninstall

Then remove the binary from your PATH and delete any configuration files you no longer need.

Clone this wiki locally