OpenLogi

Configuration

Reference for the schema 11 TOML configuration: file recovery, settings, devices, bindings, profiles, Actions Ring layouts, and Flow.

OpenLogi stores its shared settings in one TOML file. The GUI and the background agent read the same file. The GUI writes supported changes, but you can also author the file directly.

File and safe editing

PlatformPath
macOS / Linux$XDG_CONFIG_HOME/openlogi/config.toml (default: ~/.config/openlogi/config.toml)
Windows%USERPROFILE%\.config\openlogi\config.toml

The schema is strict. Unknown, obsolete, malformed, and out-of-range values stop the file from loading. The GUI opens a read-only error screen with the TOML error until you fix the file and relaunch OpenLogi.

SituationOpenLogi behavior
GUI saveWrites the file atomically. Existing comments and formatting remain for fields that still exist.
BackupBefore its first save, a process rotates five backups: config.toml.backup.1 through config.toml.backup.5.
Schema migrationThe first successful save also copies the old file to config.toml.v<version>.bak.
Symbolic linkWrites the resolved target and preserves the link. Missing target directories are created.
Symbolic-link lockThe persistent .lock sidecar stays beside the target. Different links to one target share the lock.
External editThe next GUI save is refused rather than overwriting the edit. Relaunch OpenLogi to load it.
Open GUIThe GUI asks the resident agent to reload the current file.

On Unix, OpenLogi creates written files with 0600 permissions. Keep a manual copy before a large hand edit. A strict parse error prevents OpenLogi from silently replacing your file with defaults.

Document shape and migrations

schema_version is required. This release writes schema 11. A version of 0 or a version newer than the running build is rejected before other fields are parsed.

schema_version = 11
selected_device = "unit:6be9d300"

[app_settings]
# App-wide preferences.

[flow]
# Cross-computer Flow handoff.

[devices."unit:6be9d300"]
# One physical device.

[keyboard.bindings]
# Function-key remaps for any keyboard.

[apps.chrome]
# An optional cross-platform application alias.
Top-level keyTypeMeaning
schema_versionintegerRequired schema version. Use 11.
selected_devicephysical device key or omitThe last device selected in the GUI.
app_settingstableApp-wide preferences.
flowtableFlow peers, screen edges, and devices. Omitted while it is at its default.
devicestable of tablesSettings by physical device key.
keyboardtableGlobal function-key bindings.
appstable of tablesOptional application aliases for profiles.

The loader accepts versions 1 through 11. It migrates supported layouts when it loads them.

VersionChange and migration
v1Used separate button_bindings and gesture_bindings maps.
v2Merged those maps into bindings. A v1 file rewrites to this shape on save.
v3Moved device entries from model keys to physical device keys. Copy a v2 model-key entry manually when identical devices exist.
v4Removed the device-wide gesture_owner. Gesture mode became a per-button binding shape.
v5Moved direct-device settings to a device identity, retained routes in links, and added ui_scale.
v6Added { short = ..., long = ... } button bindings.
v7Normalized thumb-wheel directions. Explicit old default pairs migrate in device and per-app bindings.
v8Added wheel-hold bindings and the per-device smooth_wheel switch.
v9Added [apps] aliases and app:<alias> profile keys. v8 files otherwise load unchanged.
v10Added the per-device disabled_keys policy. Older builds reject a v10 file before parsing its fields. v9 files load unchanged.
v11Added the [flow] section. A v10 build rejects a v11 file at the version check. v10 files load unchanged, with Flow off.

App settings

[app_settings] is omitted when every value is at its default. The values below are the schema defaults, not GUI state inferred from a connected device.

KeyTypeDefaultMeaning
launch_at_loginbooltrueStarts the background agent after login.
check_for_updatesboolfalseChecks the latest GitHub release once per app launch.
auto_install_updatesboolfalseDownloads and stages an update after an enabled update check. It applies on restart.
update_prompt_seenboolfalseRecords that the first-run update prompt received an answer.
show_in_menu_barbooltrueShows the macOS menu-bar item and Windows notification-area icon. Linux ignores it.
capture_mouse_eventsbooltrueInstalls the OS mouse hook for mouse remapping. Restart the agent after changing it.
smooth_scrollboolfalseSmooths eligible traditional mouse-wheel input. Native trackpad input stays native.
vertical_scroll_sensitivityinteger14Traditional vertical-wheel distance, from 1 through 100. 14 is 1×.
auto_download_assetsbooltrueDownloads device assets when a device appears. A manual asset refresh still downloads.
asset_sourceenumautomaticAsset source: automatic, openlogi, cloudflare, or fastly.
languagestring or omitsystem localeBundled UI locale, such as en or zh-CN.
thumbwheel_sensitivityinteger14Thumb-wheel sensitivity from 1 through 100. 14 is 1×.
momentum_scrollingtableoffMomentum scrolling for every mouse whose smooth_wheel is on. Keys: enabled, pixels_per_notch, glide_shape, max_glide_speed, glide_ms, and repeat_boost. See Momentum scrolling.
appearanceenumsystemInterface appearance: system, light, or dark.
ui_scaleenumnormalInterface scale: small (90%), normal (100%), large (110%), or extra_large (125%).
device_view_modeenumgridHome layout: grid, list, or carousel.
app_iconenumopenlogimacOS app icon: openlogi or prism. Other platforms ignore it.
theme_lightstring or omitbrand light themeTheme name for light mode.
theme_darkstring or omitbrand dark themeTheme name for dark mode.
ui_radiusinteger or omittheme radiusCorner-radius override in pixels. The UI offers 0, 6, and 12.
mouse_profile_targetenumpointerTarget for mouse profiles: pointer or focused.
low_battery_notificationsbooltrueShows one low-battery notice per discharge.
lock_key_notificationsbooltrueShows lock-key state notices from compatible keyboards.

With capture_mouse_events = false, button remapping stops and OpenLogi does not grab input devices. HID++ features, such as DPI and SmartShift, continue to work. A smooth_wheel device setting needs mouse capture as well.

mouse_profile_target = "pointer" follows the window under the pointer on macOS, Windows, and X11. Wayland and unidentified surfaces use the focused application. The desktop uses global mouse bindings.

OpenLogi never focuses a background window to send a shortcut. A mouse binding that emits keys or runs a workflow goes to the focused application when that application binds the button the same way. A binding that a per-app profile makes different is skipped until the hovered window has focus. Keyboard profiles and Actions Ring layouts always follow the focused application.

Low battery means 20% or less while not charging, or a device-reported low or critical level without a percentage. A notice closes after 8 seconds or when clicked. Lock-key notices require HID++ 0x4220; macOS does not show Num Lock or Scroll Lock notices.

Device identities and routes

[devices.<key>] uses a physical identity, not a model id. Two identical mice therefore keep independent settings. Let OpenLogi create the key, then copy it from config.toml.

Key formUse
unit:6be9d300A non-zero four-byte HID++ unit id.
serial:abc123A non-empty device serial, stored in lower case.
receiver:aabbccdd:slot:1A receiver UID and pairing slot. It identifies a receiver-paired device.
direct:046d:c08d:serial:abc123A direct HID++ device before its settings move to the bare serial: or unit: identity.
raw:046d:c900:ff43:0202:serial:your-serialA standalone raw-HID device with a serial, such as a Litra light. stable:<id> is also valid when its driver provides it.
camera:046d:0893:serial:abc123A camera with a USB serial.
camera:046d:0893A camera without a USB serial. Same-model cameras then share this settings key.

A device may have several routes. links records each route beneath its physical entry. capabilities records features measured on that route, while overrides deliberately changes a supported route's settings.

[devices."unit:6be9d300".links."receiver:aabbccdd:slot:1"]

[devices."unit:6be9d300".links."direct:046d:c08d".capabilities]
buttons = true
pointer = true

[devices."unit:6be9d300".links."direct:046d:c08d".overrides]
dpi = 800
Link tableFields
capabilitiesApp-measured capability table. Do not author it by hand.
overridesOptional dpi, invert_scroll, scroll_resolution, lighting, and smartshift.

A serial-less camera cannot distinguish same-model units across USB ports. Its GUI card still uses the OS capture id, but its settings key remains model-scoped. A direct device with only unit:00000000 has no persistent identity.

Per-device fields

Each [devices.<key>] table stores settings for one physical device. Optional values are omitted until you set them.

KeyTypeDefaultMeaning
enabledbooltruefalse leaves the device native. OpenLogi stops capture and reconnect re-application.
custom_namestring or omitomitUser-assigned device name.
identitytableomitApp-managed snapshot of model name, type, and capabilities.
linkstableemptyApp-managed route index, route capabilities, and route overrides.
bindingstableemptyLogical control to binding map.
disabled_gesturestableemptyApp-managed saved gesture maps for controls not currently in gesture mode.
per_app_bindingstable of tablesemptySparse app-specific button-action overlays.
action_ringtabledefaultActions Ring enablement, haptics, size, default layout, and complete per-app layouts.
dpi_presetsinteger arrayemptyDPI list used by CycleDpiPresets and zero-based SetDpiPreset.
dpiinteger or omitomitSensor DPI that the agent reapplies after a reconnect.
lightingtable or omitomitStatic HID++ keyboard RGB settings.
lighttable or omitomitStandalone light settings.
smartshifttable or omitomitSmartShift wheel settings.
camera_controlsstring-to-integer table or omitomitRaw UVC values, for example brightness, focus, or focus_auto.
camera_profilestable of tablesemptyNamed saved camera-control snapshots.
camera_profilestring or omitomitLast camera profile applied in the GUI.
thumbwheel_sensitivityinteger or omitapp settingPer-device override from 1 through 100.
invert_scrollboolfalseReverses this device's vertical wheel without changing trackpad direction.
scroll_resolutionenum or omitomitHID++ 0x2121 resolution: low or high. Omit it for the device setting.
smooth_wheelboolfalseSmooths this mouse's main wheel in software.
momentum_scrollingtable or omitapp settingThis mouse's own momentum scrolling, with the app setting's keys. Keys it omits take their defaults.
host_switch_targetsphysical device key arrayemptyPointing devices switched before this keyboard leaves an Easy-Switch host.
fn_lockbool or omitomittrue makes the F row send F1–F12 without Fn.
keep_os_layoutbool or omittrueKeeps a compatible keyboard on the host operating-system layout.
report_rateinteger or omitomitMouse report rate in Hz. The agent applies it only on a route that offers it.
force_sensinginteger or omitomitPress force of a force-sensing button that software can change (HID++ 0x19c0, the MX Master 4's Haptic Sense panel). It is a raw device value with no unit; lower is a lighter press. The agent clamps it into the range the device reports and writes it when the device connects. Omit it to keep the device's own force.

There is no backlight configuration field. Backlight state is stored by the keyboard. lighting is the static RGB table for supported HID++ keyboards.

Disabled keys

The Device tab offers Disabled keys only when the keyboard advertises HID++ 0x4521 for end-user configuration. Hidden and engineering features are excluded. It shows only firmware-supported keys from the following set:

  • Caps Lock
  • Num Lock
  • Scroll Lock
  • Insert
  • Windows, labelled Command on macOS

A switch on disables the key. This changes keyboard firmware behavior, not key remapping. Disabling Caps Lock can also suppress a host action assigned to that key, such as changing the input language.

Add the field beneath an existing physical-device entry:

disabled_keys = ["caps_lock", "windows_command"]

The other accepted names are num_lock, scroll_lock, and insert. Omit the field to stop managing the setting. An explicit disabled_keys = [] enables all supported known keys. It does not clear firmware-advertised unknown bits.

Controls require an online keyboard, a persistent identity, writable configuration, and a successful device read. The agent writes the full mask and reads it back. The app saves only confirmed known keys.

An error or timeout does not prove that the keyboard stayed unchanged. The app discards the old snapshot and keeps controls unavailable until a fresh read succeeds. Click the read-failure status to restart an exhausted read. Save Retry retries saving confirmed state; Reload Retry retries loading saved state into the agent. These retries do not resend the manual write request.

Each saved change requires acceptance of its own file revision, even when changes share one agent reload. Acceptance of a newer save does not confirm an older one. After an external edit, the app refreshes the file without overwriting it. This also applies when Save Retry or a save of another setting finds the edit. Each keyboard requires acceptance of that exact revision, then a new device read, before editing resumes. A failed refresh or agent reload keeps editing blocked. Reload Retry resumes reconciliation. A device read alone cannot confirm the file revision.

Recovery stays inside the device card and uses shared status and retry controls. Messages resolve from the selected language catalog when the card renders. Every interface language translates these messages. Technical errors are recorded in app logs, not displayed as ordinary recovery text. Switches and recovery actions keep separate identities for each physical device. Each switch's screen-reader name states the disable action and the key.

The agent reapplies configured policy after discovery, reconnect, and wake. After an uncertain manual write, it schedules the latest confirmed choice, including confirmed state that the app has not saved. A newer pending request retains priority. When the restoring write starts, the app reads the keyboard again and shows the restored keys. Removing the policy or disabling device management retires obsolete queued work; it does not promise to undo an existing firmware value.

The agent retains ownership until each submitted native report completes. This includes discovery and readback. Cancellation stops subsequent reports, not reports already submitted. A completed write becomes the recovery baseline only when the requester consumes its successful result. An unread result remains unconfirmed. Reads queue behind already scheduled policy writes. A native driver operation that never completes can keep later writes waiting. A request cancelled before its first report leaves the queue at once.

Different known unit IDs or serials identify a replacement. This applies to receiver slots and directly connected keyboards. The agent retires old requests and starts a fresh discovery retry budget. Learning previously missing identity preserves active work and the remaining budget. The slot alone cannot identify replacement when both snapshots lack those identifiers. A directly connected keyboard without a nonzero unit ID counts as new when its identity changes.

Confirmation retries are delayed and bounded. Failed inventory scans do not count as successful confirmation. Pending confirmation survives exhausted fast retries for ordinary recovery. An unreachable keyboard might not accept a write. Disabled keys support arrived in schema 10. A schema 9 file still loads. Builds older than schema 10 reject a saved file before parsing its fields. Keep a compatible backup before downgrading.

lighting, light, and smartshift

TableKeyDefaultMeaning
lightingenabledtrueApplies the static color.
lightingcolor"ffffff"Six hexadecimal RRGGBB digits. A leading # also loads.
lightingbrightness100Brightness from 0 through 100.
lightenabledtrueTurns a standalone light on or off.
lightauto_camerafalseMakes a standalone light follow aggregate camera use.
lightbrightness_percent100Brightness from 0 through 100.
lighttemperature_kelvinomitRequested color temperature when the device supports it.
lightcoloromitRequested RGB color when the driver supports it.
smartshiftmoderequiredratchet or free.
smartshiftauto_disengagerequired8 through 254 in 0.25-turn-per-second steps, or 255 for permanent ratchet.
smartshifttunable_torqueomit1 through 100 percent, or 0 when the hardware reports no torque level.

A smooth_wheel mouse diverts HID++ 0x2121 reports and posts eased scrolling. It applies inversion and vertical sensitivity. It needs input capture and, on macOS, Accessibility access. Turning it off, disabling the device, or stopping the agent returns the wheel to native reporting.

Binding controls

bindings and per_app_bindings use a logical control name as the key. The mouse controls are always spelled as follows:

Mouse controls
LeftClick, RightClick, MiddleClick, Back, Forward, DpiToggle, Thumbwheel, ThumbwheelScrollUp, ThumbwheelScrollDown, GestureButton, HapticPanel, WheelTiltLeft, WheelTiltRight

Thumbwheel is a capacitive tap report, not a mechanical click. It stays inert unless you bind it. It can report an incidental thumb contact.

Keyboard controls are HID++ 0x1b04 controls. A known control uses its catalog name. Any divertable unlisted control uses control:0x<cid>.

Known keyboard control names
KeyBrightnessDown, KeyBrightnessUp, KeyBacklightDown, KeyBacklightUp, KeyMissionControl, KeyLaunchpad, KeyShowDesktop, KeySearch, KeyDictation, KeyEmoji, KeyScreenCapture, KeyPrintScreen, KeyMicMute, KeyPreviousTrack, KeyPlayPause, KeyPlayPauseTrack, KeyNextTrack, KeyMute, KeyVolumeDown, KeyVolumeUp, KeyCalculator, KeyLock, KeyDoNotDisturb, KeyEmojiHeartEyes, KeyEmojiCrying, KeyEmojiSmiley, KeyEmojiTears, KeyLookUp, KeyAppSwitch, KeyAppSwitchLaunchpad, KeyHome, KeyEnd, KeyPageUp, KeyPageDown, KeyMultiPlatformAppSwitch, KeyMultiPlatformHome, KeyMultiPlatformMenu, KeyMultiPlatformInsert, KeyLanguageSwitch, KeyCircle, KeyTriangle, KeyDiamond, KeyStar

A keyboard key remains on its firmware function until you bind it. An explicit None binding diverts a bound keyboard control and does nothing. This differs from removing the entry, which returns the key to its firmware function.

Actions

Binding values use serialized Rust action names. The table lists every action in schema 11. Payload actions use a one-key TOML table rather than a string.

GroupActions
SuppressNone
MouseLeftClick, RightClick, MiddleClick, MouseBack, MouseForward
EditingCopy, Paste, Cut, Undo, Redo, SelectAll, Find, Save
BrowserBrowserBack, BrowserForward, NewTab, CloseTab, ReopenTab, NextTab, PrevTab, ReloadPage
NavigationMissionControl, AppExpose, PreviousDesktop, NextDesktop, ShowDesktop, LaunchpadShow
SystemLockScreen, Screenshot, CaptureRegion, Sleep, ShowActionsRing, OpenApplication
MediaPlayPause, NextTrack, PrevTrack, VolumeUp, VolumeDown, MuteVolume
DPICycleDpiPresets, SetDpiPreset, ToggleSmartShift
ScrollScrollUp, ScrollDown, HorizontalScrollLeft, HorizontalScrollRight
Payload and automationCustomShortcut, HoldShortcut, TapKeyHoldingModifiers, TypeText, RunAppleScript, RunShellCommand, Workflow
Back = "BrowserBack"
DpiToggle = { SetDpiPreset = 2 }
Forward = { CustomShortcut = "Cmd+Shift+P" }
MiddleClick = { HoldShortcut = "Ctrl+Space" }
GestureButton = { TapKeyHoldingModifiers = "Cmd+Tab" }
HapticPanel = { OpenApplication = { path = "~/Downloads", display_name = "Downloads" } }

SetDpiPreset uses a zero-based index. OpenApplication accepts an application, folder, file-system path, or URL. A leading ~ expands when the action runs.

CustomShortcut, HoldShortcut, and TapKeyHoldingModifiers accept a chord with one ordinary key. Modifiers are Cmd, Ctrl, Alt, Shift, and Super. Command aliases Cmd; Control aliases Ctrl; Option aliases Alt; and Win or Meta aliases Super.

Cmd is the cross-platform primary modifier. It is Command on macOS and Control on Linux and Windows. Super always presses the logo key: Command on macOS, the Windows key on Windows, and KEY_LEFTMETA on Linux.

Press shapes

A global device binding can be a single action, a short/long pair, a wheel hold, or a gesture map. Per-app and [keyboard.bindings] entries always use one action.

# Release before 500 ms for `short`. Reach 500 ms for `long`.
DpiToggle = { short = "ShowDesktop", long = "MissionControl" }

# The action holds until the physical button releases.
MiddleClick = { HoldShortcut = "Ctrl+Space" }

# Hold modifiers, then tap Tab once. This leaves the app switcher open.
Forward = { TapKeyHoldingModifiers = "Cmd+Tab" }

# Back or Forward can turn the main wheel into a virtual thumb wheel while held.
Back = { click = "BrowserBack", wheel = "HorizontalScroll" }

A short/long pair waits for a release. Releasing before 500 ms fires short. Reaching 500 ms fires long once, and the later release does not fire short. If capture ends, the binding changes, or the agent stops first, neither action fires.

CustomShortcut presses and releases its chord immediately. HoldShortcut holds the whole chord until release. TapKeyHoldingModifiers holds only the modifiers and taps the ordinary key once. Use the latter for Cmd+Tab, Alt+Tab, or another application switcher.

Wheel hold is available only on Back and Forward, and only when the hardware reports raw-wheel support. A release without wheel motion runs click. A press that scrolls runs no click action. The wheel direction reverses when invert_scroll is on.

Gesture maps

A gesture map is a device-global binding table keyed by Up, Down, Left, Right, and Click. Click is the plain press without a swipe.

[devices."unit:6be9d300".bindings.GestureButton]
Up = "MissionControl"
Down = "ShowDesktop"
Left = "PrevTab"
Right = "NextTab"
Click = "AppExpose"

Gesture mode is independent for every supported control. MiddleClick, Back, and Forward use the OS hook. DpiToggle, GestureButton, and HapticPanel need a device route with raw-XY support.

Middle-click gesture maps are valid in schema 11. You can author or retain one in TOML. A per-app single action temporarily replaces the complete gesture map for that application.

Keyboard, profiles, and Actions Ring

Global function-key bindings

[keyboard.bindings] maps function-key triggers for any keyboard. A trigger is [modifier+]…key. Valid modifiers are shift, control (ctrl), option (alt), and command (cmd). Valid keys are esc and f1 through f19.

[keyboard.bindings]
f1 = "MissionControl"
"shift+f2" = "ShowDesktop"
"cmd+f5" = { CustomShortcut = "Cmd+Shift+P" }

This map is separate from a Logitech keyboard's HID++ control bindings under [devices.<key>.bindings]. keyboard.bindings does not accept short/long pairs, gesture maps, or wheel holds.

Application aliases and profiles

per_app_bindings is a sparse overlay. Its unlisted controls continue to use the device-global bindings value. action_ring.per_app instead selects a complete layout.

Use a platform identifier directly, or define [apps.<alias>] and use app:<alias>. Alias names may contain only ASCII letters, digits, -, and _. Each platform field accepts one identifier or an array.

[apps.chrome]
name = "Google Chrome"
macos = "com.google.Chrome"
linux = ["google-chrome", "Google-chrome"]
windows = "exe:chrome.exe"

[devices."unit:6be9d300".per_app_bindings."app:chrome"]
Back = "PrevTab"
Identifier sourceAccepted form
macOSBundle id, or exact executable path without a bundle id.
LinuxX11 WM_CLASS or Wayland xdg app_id.
WindowsExact lower-case executable path, or exe:<filename>.exe.

The most specific matching profile wins in this order:

  1. Exact platform identifier.
  2. Windows exe:<filename>.exe fallback.
  3. An alias that lists the exact identifier.
  4. An alias that lists the exe:<filename>.exe fallback.

The file fails to load when an app: key names an undefined alias. It also fails when two aliases list the same platform identifier, an identifier is empty, an identifier begins with app:, or a Windows identifier has uppercase letters.

Actions Ring layouts

The ring uses eight slots: Top, TopRight, Right, BottomRight, Bottom, BottomLeft, Left, and TopLeft. Each populated slot has action, plus optional icon and label. Omit a slot to leave it empty.

KeyDefaultMeaning
enabledtrueLets ShowActionsRing open this device's ring.
hapticstruePlays device haptics on hover and activation.
sizemediumRing size: small, medium, or large. It applies to every layout of the device.
defaultdefault layoutLayout used when the foreground application has no layout.
per_appemptyComplete layouts keyed by application selector.

None and ShowActionsRing are invalid slot actions. An Actions Ring cannot contain an empty action or recursively open another ring.

[devices."unit:6be9d300".action_ring]
enabled = true
haptics = true
size = "large"

[devices."unit:6be9d300".action_ring.default.slots]
Top = { action = "Copy" }
Right = { action = { OpenApplication = { path = "/Applications/Safari.app", display_name = "Safari" } }, icon = "Applications" }
Bottom = { action = "ShowDesktop", label = "Desktop" }

[devices."unit:6be9d300".action_ring.per_app."app:chrome".slots]
Top = { action = "Cut" }
TopRight = { action = "Copy" }
Right = { action = "Paste" }
BottomRight = { action = "BrowserForward" }
Bottom = { action = "PlayPause" }
BottomLeft = { action = "BrowserBack" }
Left = { action = "Undo" }
TopLeft = { action = "Redo" }

The default ring contains Cut, Copy, Paste, Browser Forward, Play/Pause, Browser Back, Undo, and Redo in slot order. A per-app layout replaces that entire layout. It is not a sparse overlay.

Flow

[flow] holds Flow settings: the paired computers, the screen edge that leads to each, and the devices that switch with the pointer. Pairing in the Flow window writes peers. The window writes edges and channels. The section is omitted while it is at its default.

[flow]
enabled = true
require_modifier = false

[[flow.peers]]
name = "work-laptop"
public_key = "ed25519:0f1e2d3c4b5a69780f1e2d3c4b5a69780f1e2d3c4b5a69780f1e2d3c4b5a6978"
addresses = ["work-laptop.tailnet.example", "10.0.0.7"]

[[flow.layout]]
edge = "right"
peer = "work-laptop"

[[flow.devices]]
key = "unit:0f1e2d3c"
peer_channels = { self = 0, "work-laptop" = 1 }
KeyTypeDefaultMeaning
enabledboolfalseTurns Flow on.
require_modifierboolfalseRequires Control while the pointer crosses an edge, on every platform.
peersarray of tablesemptyPaired computers: name, public_key, and optional addresses.
peers[].namestringrequiredNon-empty, without surrounding whitespace or control characters, and not self.
peers[].public_keystringrequireded25519: followed by 64 lowercase hex digits.
peers[].addressesstring arrayemptyHost names or IP addresses tried when mDNS cannot reach the peer. A value without a port uses UDP 42424.
layoutarray of tablesemptyScreen edges: edge (left, right, top, or bottom) and peer.
devicesarray of tablesemptyDevices that switch: key and peer_channels.
devices[].keyphysical device keyrequiredA serial: or unit: identity key. Route keys are rejected.
devices[].peer_channelsstring-to-integer tablerequiredZero-based Easy-Switch channels from 0 through 2. self names this computer and is required.

The file fails to load when two peers share a name or public key, an edge appears twice, or a layout or device entry names an unknown peer. It also fails when a device lists one channel twice. The machine's private key is not in this file.

Valid schema 11 example

This complete example uses only physical keys. Copy the structure, then replace the keys and paths with values OpenLogi generated for your devices.

schema_version = 11
selected_device = "receiver:aabbccdd:slot:1"

[app_settings]
launch_at_login = true
check_for_updates = false
auto_install_updates = false
show_in_menu_bar = true
capture_mouse_events = true
mouse_profile_target = "pointer"
smooth_scroll = false
vertical_scroll_sensitivity = 14
auto_download_assets = true
asset_source = "automatic"
language = "en"
thumbwheel_sensitivity = 14
appearance = "system"
ui_scale = "normal"
device_view_mode = "grid"
app_icon = "openlogi"
low_battery_notifications = true
lock_key_notifications = true

[devices."receiver:aabbccdd:slot:1"]
custom_name = "Office mouse"
dpi = 1600
dpi_presets = [800, 1600, 3200]
thumbwheel_sensitivity = 20
invert_scroll = false
scroll_resolution = "high"
smooth_wheel = true

[devices."receiver:aabbccdd:slot:1".bindings]
Back = { click = "BrowserBack", wheel = "HorizontalScroll" }
Forward = { TapKeyHoldingModifiers = "Cmd+Tab" }
MiddleClick = { HoldShortcut = "Ctrl+Space" }
DpiToggle = { short = "ShowDesktop", long = "MissionControl" }
Thumbwheel = "AppExpose"

[devices."receiver:aabbccdd:slot:1".bindings.GestureButton]
Click = "MissionControl"
Up = "MissionControl"
Down = "AppExpose"
Left = "PreviousDesktop"
Right = "NextDesktop"

[devices."receiver:aabbccdd:slot:1".per_app_bindings."app:chrome"]
Back = "PrevTab"
Forward = "NextTab"

[devices."receiver:aabbccdd:slot:1".action_ring]
enabled = true
haptics = true
size = "medium"

[devices."receiver:aabbccdd:slot:1".action_ring.default.slots]
Top = { action = "Copy", icon = "Keyboard" }
Right = { action = { OpenApplication = { path = "/Applications/Safari.app", display_name = "Safari" } }, icon = "Applications" }
Bottom = { action = "ShowDesktop", label = "Desktop" }

[devices."receiver:aabbccdd:slot:1".lighting]
enabled = true
color = "ff0000"
brightness = 80

[devices."receiver:aabbccdd:slot:1".smartshift]
mode = "ratchet"
auto_disengage = 16
tunable_torque = 50

[devices."receiver:aabbccdd:slot:2"]
host_switch_targets = ["receiver:aabbccdd:slot:1"]
fn_lock = false
keep_os_layout = true

[devices."receiver:aabbccdd:slot:2".bindings]
KeySearch = "MissionControl"
KeyScreenCapture = "Sleep"
KeyCalculator = { OpenApplication = { path = "/System/Applications/Calculator.app", display_name = "Calculator" } }
"control:0x01f3" = { CustomShortcut = "Cmd+Shift+4" }

[devices."raw:046d:c900:ff43:0202:serial:your-serial".light]
enabled = true
auto_camera = false
brightness_percent = 65
temperature_kelvin = 4600
color = "ffffff"

[keyboard.bindings]
f1 = "MissionControl"
"shift+command+f5" = "ShowDesktop"

[apps.chrome]
name = "Google Chrome"
macos = "com.google.Chrome"
linux = ["google-chrome", "Google-chrome"]
windows = "exe:chrome.exe"

[flow]
enabled = true
require_modifier = false

[[flow.peers]]
name = "work-laptop"
public_key = "ed25519:0f1e2d3c4b5a69780f1e2d3c4b5a69780f1e2d3c4b5a69780f1e2d3c4b5a6978"

[[flow.layout]]
edge = "right"
peer = "work-laptop"

[[flow.devices]]
key = "unit:6be9d300"
peer_channels = { self = 0, "work-laptop" = 1 }

On this page