All guides
QMK / RMK: remap with Vial
Live remapping in the Vial app or browser, with combos, tap dance and macros. Works with QMK and RMK keyboards.
Last updated 2026-10-15
Vial is an open-source remapping tool that writes changes to the keyboard instantly. Compared with VIA it adds graphical combos, tap dance and key overrides, and the keyboard definition lives in the firmware — nothing extra to load.
Vial works with two firmwares:
- QMK — the keyboard needs Vial's QMK fork (vial-qmk).
- RMK — RMK speaks the Vial protocol natively once enabled.
You'll need
- ✅ Vial desktop (Windows / macOS / Linux), or vial.rocks in Chrome / Edge
- ✅ A data-capable USB cable
- ✅ Vial-compatible firmware on the keyboard
Step 1: connect
- Plug in the keyboard and open Vial.
- The desktop app detects it automatically; on the web, follow the prompt and pick the keyboard in the browser dialog.
- When the layout appears at the top, you're connected.
Step 2: change keys
- Open the Keymap tab and choose a layer with the numbers above the layout.
- Click the position to change.
- Pick the new key in the panel below. It saves automatically and works immediately.
Useful panel categories:
| Category | Contains |
|---|---|
| Basic | Letters, numbers, symbols, function keys |
| Layers | MO, TG, TO, LT and other layer keys |
| Quantum | Tap-hold, modifier combinations and other advanced keys |
| Tap Dance / Macro | References to tap dances and macros defined in their tabs |
| User | Maker-defined keys; RMK's Bluetooth keys (BT0 …) live here |
Advanced features
| Tab | Use it for |
|---|---|
| Macros | Record a sequence, e.g. type your email in one press |
| Combos | Press two keys together for a third, e.g. J+K = Esc |
| Tap Dance | Different actions for tap, double tap and hold |
| Key Overrides | e.g. Shift+Backspace = Delete |
| QMK Settings | Tapping term and other parameters (QMK only) |
| Matrix tester | Check every switch works (requires unlocking) |
Unlocking
To protect against malicious software, some actions (matrix tester, bootloader keys) need the keyboard unlocked:
- Click Security → Unlock.
- Vial highlights a few keys; hold them together on the keyboard until the progress bar fills.
Back up and restore
- File → Save current layout exports a
.vilbackup. - File → Load saved layout restores it.
Notes for RMK keyboards
- Vial must be enabled in the firmware (
vial_enabled = trueunder[host]inkeyboard.toml). - Bluetooth keys are in the User category:
BT0,BT1… switch profiles; hold one for 5 seconds to clear it. See Bluetooth pairing. - To discard Vial edits and return to the firmware's default keymap, use a build with
clear_layout(clears keys, keeps Bluetooth pairings).
Common problems
- Linux doesn't see the keyboard: add a udev rule — see the Vial guide.
- "Not a Vial keyboard": it runs plain QMK or VIA firmware — use VIA or ask the maker for Vial firmware.
More → Troubleshooting