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
| Platform | Path |
|---|---|
| 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.
| Situation | OpenLogi behavior |
|---|---|
| GUI save | Writes the file atomically. Existing comments and formatting remain for fields that still exist. |
| Backup | Before its first save, a process rotates five backups: config.toml.backup.1 through config.toml.backup.5. |
| Schema migration | The first successful save also copies the old file to config.toml.v<version>.bak. |
| Symbolic link | Writes the resolved target and preserves the link. Missing target directories are created. |
| Symbolic-link lock | The persistent .lock sidecar stays beside the target. Different links to one target share the lock. |
| External edit | The next GUI save is refused rather than overwriting the edit. Relaunch OpenLogi to load it. |
| Open GUI | The 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 key | Type | Meaning |
|---|---|---|
schema_version | integer | Required schema version. Use 11. |
selected_device | physical device key or omit | The last device selected in the GUI. |
app_settings | table | App-wide preferences. |
flow | table | Flow peers, screen edges, and devices. Omitted while it is at its default. |
devices | table of tables | Settings by physical device key. |
keyboard | table | Global function-key bindings. |
apps | table of tables | Optional application aliases for profiles. |
The loader accepts versions 1 through 11. It migrates supported layouts when
it loads them.
| Version | Change and migration |
|---|---|
| v1 | Used separate button_bindings and gesture_bindings maps. |
| v2 | Merged those maps into bindings. A v1 file rewrites to this shape on save. |
| v3 | Moved device entries from model keys to physical device keys. Copy a v2 model-key entry manually when identical devices exist. |
| v4 | Removed the device-wide gesture_owner. Gesture mode became a per-button binding shape. |
| v5 | Moved direct-device settings to a device identity, retained routes in links, and added ui_scale. |
| v6 | Added { short = ..., long = ... } button bindings. |
| v7 | Normalized thumb-wheel directions. Explicit old default pairs migrate in device and per-app bindings. |
| v8 | Added wheel-hold bindings and the per-device smooth_wheel switch. |
| v9 | Added [apps] aliases and app:<alias> profile keys. v8 files otherwise load unchanged. |
| v10 | Added the per-device disabled_keys policy. Older builds reject a v10 file before parsing its fields. v9 files load unchanged. |
| v11 | Added 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.
| Key | Type | Default | Meaning |
|---|---|---|---|
launch_at_login | bool | true | Starts the background agent after login. |
check_for_updates | bool | false | Checks the latest GitHub release once per app launch. |
auto_install_updates | bool | false | Downloads and stages an update after an enabled update check. It applies on restart. |
update_prompt_seen | bool | false | Records that the first-run update prompt received an answer. |
show_in_menu_bar | bool | true | Shows the macOS menu-bar item and Windows notification-area icon. Linux ignores it. |
capture_mouse_events | bool | true | Installs the OS mouse hook for mouse remapping. Restart the agent after changing it. |
smooth_scroll | bool | false | Smooths eligible traditional mouse-wheel input. Native trackpad input stays native. |
vertical_scroll_sensitivity | integer | 14 | Traditional vertical-wheel distance, from 1 through 100. 14 is 1×. |
auto_download_assets | bool | true | Downloads device assets when a device appears. A manual asset refresh still downloads. |
asset_source | enum | automatic | Asset source: automatic, openlogi, cloudflare, or fastly. |
language | string or omit | system locale | Bundled UI locale, such as en or zh-CN. |
thumbwheel_sensitivity | integer | 14 | Thumb-wheel sensitivity from 1 through 100. 14 is 1×. |
momentum_scrolling | table | off | Momentum 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. |
appearance | enum | system | Interface appearance: system, light, or dark. |
ui_scale | enum | normal | Interface scale: small (90%), normal (100%), large (110%), or extra_large (125%). |
device_view_mode | enum | grid | Home layout: grid, list, or carousel. |
app_icon | enum | openlogi | macOS app icon: openlogi or prism. Other platforms ignore it. |
theme_light | string or omit | brand light theme | Theme name for light mode. |
theme_dark | string or omit | brand dark theme | Theme name for dark mode. |
ui_radius | integer or omit | theme radius | Corner-radius override in pixels. The UI offers 0, 6, and 12. |
mouse_profile_target | enum | pointer | Target for mouse profiles: pointer or focused. |
low_battery_notifications | bool | true | Shows one low-battery notice per discharge. |
lock_key_notifications | bool | true | Shows 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 form | Use |
|---|---|
unit:6be9d300 | A non-zero four-byte HID++ unit id. |
serial:abc123 | A non-empty device serial, stored in lower case. |
receiver:aabbccdd:slot:1 | A receiver UID and pairing slot. It identifies a receiver-paired device. |
direct:046d:c08d:serial:abc123 | A direct HID++ device before its settings move to the bare serial: or unit: identity. |
raw:046d:c900:ff43:0202:serial:your-serial | A 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:abc123 | A camera with a USB serial. |
camera:046d:0893 | A 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 table | Fields |
|---|---|
capabilities | App-measured capability table. Do not author it by hand. |
overrides | Optional 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.
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled | bool | true | false leaves the device native. OpenLogi stops capture and reconnect re-application. |
custom_name | string or omit | omit | User-assigned device name. |
identity | table | omit | App-managed snapshot of model name, type, and capabilities. |
links | table | empty | App-managed route index, route capabilities, and route overrides. |
bindings | table | empty | Logical control to binding map. |
disabled_gestures | table | empty | App-managed saved gesture maps for controls not currently in gesture mode. |
per_app_bindings | table of tables | empty | Sparse app-specific button-action overlays. |
action_ring | table | default | Actions Ring enablement, haptics, size, default layout, and complete per-app layouts. |
dpi_presets | integer array | empty | DPI list used by CycleDpiPresets and zero-based SetDpiPreset. |
dpi | integer or omit | omit | Sensor DPI that the agent reapplies after a reconnect. |
lighting | table or omit | omit | Static HID++ keyboard RGB settings. |
light | table or omit | omit | Standalone light settings. |
smartshift | table or omit | omit | SmartShift wheel settings. |
camera_controls | string-to-integer table or omit | omit | Raw UVC values, for example brightness, focus, or focus_auto. |
camera_profiles | table of tables | empty | Named saved camera-control snapshots. |
camera_profile | string or omit | omit | Last camera profile applied in the GUI. |
thumbwheel_sensitivity | integer or omit | app setting | Per-device override from 1 through 100. |
invert_scroll | bool | false | Reverses this device's vertical wheel without changing trackpad direction. |
scroll_resolution | enum or omit | omit | HID++ 0x2121 resolution: low or high. Omit it for the device setting. |
smooth_wheel | bool | false | Smooths this mouse's main wheel in software. |
momentum_scrolling | table or omit | app setting | This mouse's own momentum scrolling, with the app setting's keys. Keys it omits take their defaults. |
host_switch_targets | physical device key array | empty | Pointing devices switched before this keyboard leaves an Easy-Switch host. |
fn_lock | bool or omit | omit | true makes the F row send F1–F12 without Fn. |
keep_os_layout | bool or omit | true | Keeps a compatible keyboard on the host operating-system layout. |
report_rate | integer or omit | omit | Mouse report rate in Hz. The agent applies it only on a route that offers it. |
force_sensing | integer or omit | omit | Press 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
| Table | Key | Default | Meaning |
|---|---|---|---|
lighting | enabled | true | Applies the static color. |
lighting | color | "ffffff" | Six hexadecimal RRGGBB digits. A leading # also loads. |
lighting | brightness | 100 | Brightness from 0 through 100. |
light | enabled | true | Turns a standalone light on or off. |
light | auto_camera | false | Makes a standalone light follow aggregate camera use. |
light | brightness_percent | 100 | Brightness from 0 through 100. |
light | temperature_kelvin | omit | Requested color temperature when the device supports it. |
light | color | omit | Requested RGB color when the driver supports it. |
smartshift | mode | required | ratchet or free. |
smartshift | auto_disengage | required | 8 through 254 in 0.25-turn-per-second steps, or 255 for permanent ratchet. |
smartshift | tunable_torque | omit | 1 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.
| Group | Actions |
|---|---|
| Suppress | None |
| Mouse | LeftClick, RightClick, MiddleClick, MouseBack, MouseForward |
| Editing | Copy, Paste, Cut, Undo, Redo, SelectAll, Find, Save |
| Browser | BrowserBack, BrowserForward, NewTab, CloseTab, ReopenTab, NextTab, PrevTab, ReloadPage |
| Navigation | MissionControl, AppExpose, PreviousDesktop, NextDesktop, ShowDesktop, LaunchpadShow |
| System | LockScreen, Screenshot, CaptureRegion, Sleep, ShowActionsRing, OpenApplication |
| Media | PlayPause, NextTrack, PrevTrack, VolumeUp, VolumeDown, MuteVolume |
| DPI | CycleDpiPresets, SetDpiPreset, ToggleSmartShift |
| Scroll | ScrollUp, ScrollDown, HorizontalScrollLeft, HorizontalScrollRight |
| Payload and automation | CustomShortcut, 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 source | Accepted form |
|---|---|
| macOS | Bundle id, or exact executable path without a bundle id. |
| Linux | X11 WM_CLASS or Wayland xdg app_id. |
| Windows | Exact lower-case executable path, or exe:<filename>.exe. |
The most specific matching profile wins in this order:
- Exact platform identifier.
- Windows
exe:<filename>.exefallback. - An alias that lists the exact identifier.
- An alias that lists the
exe:<filename>.exefallback.
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.
| Key | Default | Meaning |
|---|---|---|
enabled | true | Lets ShowActionsRing open this device's ring. |
haptics | true | Plays device haptics on hover and activation. |
size | medium | Ring size: small, medium, or large. It applies to every layout of the device. |
default | default layout | Layout used when the foreground application has no layout. |
per_app | empty | Complete 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 }| Key | Type | Default | Meaning |
|---|---|---|---|
enabled | bool | false | Turns Flow on. |
require_modifier | bool | false | Requires Control while the pointer crosses an edge, on every platform. |
peers | array of tables | empty | Paired computers: name, public_key, and optional addresses. |
peers[].name | string | required | Non-empty, without surrounding whitespace or control characters, and not self. |
peers[].public_key | string | required | ed25519: followed by 64 lowercase hex digits. |
peers[].addresses | string array | empty | Host names or IP addresses tried when mDNS cannot reach the peer. A value without a port uses UDP 42424. |
layout | array of tables | empty | Screen edges: edge (left, right, top, or bottom) and peer. |
devices | array of tables | empty | Devices that switch: key and peer_channels. |
devices[].key | physical device key | required | A serial: or unit: identity key. Route keys are rejected. |
devices[].peer_channels | string-to-integer table | required | Zero-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 }