How to Get Started Using Vial with Your Keyboard

Updated

To use Vial, your keyboard must be running Vial-compatible firmware—either preloaded by the manufacturer or installed by you—after which the Vial GUI should detect it automatically. From there, you can configure the keyboard in real time using either the downloadable Vial app (Windows, Linux, Mac) or Vial Web. The steps below cover the full path from checking compatibility to making your first configuration change.

Before you start: confirm firmware compatibility

Vial is not a standalone remapping tool that works with any keyboard. It is a GUI paired with a QMK fork, and it only works with keyboards running firmware built from that fork.

  • If your keyboard shipped with Vial firmware, you can skip firmware installation entirely—the site states such keyboards are automatically detected by the Vial GUI.
  • If it did not, you need to install a Vial-compatible firmware on the keyboard first. The site's guidance is explicit on this point: install Vial-compatible firmware "if it did not come preloaded with one," and the GUI will then detect the device automatically.
  • If your keyboard has no Vial port at all, the site's manual includes a porting guide (Create JSON, then Port to Vial), which is a separate, more involved path than simply configuring a supported board.

A practical check: look for your keyboard model in Vial's supported-keyboard resources or ask in the project's Discord server before assuming it will work.

Step-by-step: connect and configure

1. Get the Vial GUI

The site offers two entry points:

Option What it is When to choose it
Download Vial Desktop app for Windows, Linux, and Mac You want a locally installed tool
Vial Web Browser-based version You prefer not to install software

Both are presented on the homepage as starting points alongside the user manual.

2. Connect your keyboard

Plug in the keyboard with Vial-compatible firmware installed. According to the site, the Vial GUI detects it automatically—you should not need to manually pair or select a device.

Expected result: the GUI opens your keyboard's layout and is ready for live configuration.

Linux note: the manual includes a dedicated entry on configuring udev. If the GUI does not detect the keyboard on Linux, permissions for the device are the usual place to look—this is a documented setup step, not a fault in the keyboard.

3. Make your first configuration change

Vial is described as a real-time configurator, so changes apply as you make them rather than requiring a rebuild. The manual's sidebar lists the feature areas you can work in, including:

  • Layers — organize multiple keymap layers
  • Quantum — QMK's extended key behaviors
  • Macros — record or define sequences
  • Tap Dance — different actions on tap versus hold
  • Combos — multiple keys pressed together triggering one action
  • Alt Repeat Key — alternate behavior on repeated keypresses
  • QMK Settings — firmware-level options exposed in the GUI
  • Any key — assign a keycode directly

Start with a single, easily reversible change—for example, remapping one key on your base layer—then test it on the keyboard before moving on to macros or combos.

4. Verify the change

Type with the keyboard after each edit. Because configuration is live, the effect should be immediate. If nothing changes, re-check that the firmware is the Vial build and that the GUI is connected to the intended device.

Common sticking points

  • Keyboard not detected. The most common cause is firmware that is not Vial-compatible. Confirm the board is running a Vial build, not stock QMK or a vendor's proprietary firmware.
  • Linux permissions. Follow the manual's udev configuration entry if detection fails on Linux.
  • Feature overload. The manual covers many advanced areas (rotary encoders, backlight and RGB, MIDI, custom keycodes). These are optional; get basic keymap editing working first.
  • Firmware size limits. The manual includes a section on selecting GUI features for size, which matters if you are building firmware for a board with limited storage.

Where to go next

The user manual is the authoritative reference for every feature listed above, and the project is fully open source with all components on GitHub. For questions or feature suggestions, the site points to its Discord server and a dedicated feedback site. If you are porting a new keyboard rather than configuring an existing one, begin with the porting guide's JSON creation step.