KVM

The kvm command manages keyboard, video, and mouse (KVM) control between DisplayNet extenders, enabling keyboard and mouse input from a local station to be forwarded to one or more remote stations. It also manages MultiView and MultiDevice KVM sessions, including window focus, input locking, and fullscreen toggling, along with user-defined hotkey macros, Stream Deck control surfaces, and per-seat configurations that bundle a station's macros and buttons together. A receiver's HID auto-connect keeps it paired so those customizations work the moment an operator sits down.

Command Type	DisplayNet
Minimum Version	4.6

Command Families

The core session commands, hub routing and the MultiView / MultiDevice session controls, are below. The larger kvm sub-command families each have their own page:

• kvm workstation: the seat as a whole, its reach and KVM-follows-video policy
• kvm desk: desk configurations for MultiDevice KVM (multi-monitor seats)
• kvm macro: keyboard hotkey macros
• kvm streamdeck: Elgato Stream Deck control surface bindings
• kvm config: per-seat configurations bundling macros and buttons
• kvm hid: HID auto-connect policy

MultiView and Desk sessions

Two kinds of KVM session let one keyboard and mouse span multiple sources. Both use the same edge-crossing cursor model: the cursor is confined to the union of controllable windows and crosses where their edges are adjacent. They differ in whether the server composites the video:

• MultiView (kvm mtvconnect). Several sources composited into tiles on one display. The layout and source mapping are a MultiView configuration, owned by the mtv command and usable for display on its own. KVM references it by name and layers cursor control over its surfaces.
• Desk / MultiDevice (kvm desk connect). Several sources each driving their own physical monitor at one desk, with no compositing. The desk layout is a KVM-native configuration managed by kvm desk.

Both present the cursor with the same thing, a spatial arrangement of controllable sources, so they share the focus and lock controls, and disconnect ends either kind.

The surface a session navigates (a MultiView or Desk config) is distinct from a seat configuration (kvm config), which bundles a seat's macros and Stream Deck buttons. A seat can have both at once.

Usage

kvm list
kvm seats
kvm status <device>
kvm connect <local_device> <remote_device_list>
kvm disconnect <device>
kvm stop <device>
kvm mtvconnect <config_name> <remote_device>
kvm focus <remote_device> next|prev|<window>
kvm lock <remote_device> [toggle|on|off]
kvm fullscreen <remote_device> [toggle|on|off]
kvm sensitivity <remote_device> [<factor>|default]
kvm sendkeys seat <remote_device> "<sequence>"
kvm sendkeys tx <local_device> "<sequence>"

Subcommands

Subcommand	Description
list	Returns the full KVM state for every active session: the remote/local extender pairs currently managed by the KVM service, including pairing state, routing mode, input-lock and fullscreen flags, and (for MultiView sessions) the window topology.
seats	5.0 Returns one row per workstation seat (id, name, presence, the mounted control surface, and the active session) in a single call. A runtime directory for a dashboard; see seats.
status	Returns the KVM state for a single device. The response object has the same shape as one entry of kvm list.
connect	Connects a local HID extender (the keyboard and mouse source) to one or more remote HID extenders (the destination displays). Both the source and destination devices must be HID-capable and unlocked.
disconnect	Ends the KVM session on a device, whatever kind it is. See disconnect.
stop	Stops USB HID streaming on a device. This is a no-op if the stream is already stopped.
mtvconnect	Connects a MultiView configuration to a remote HID extender. See mtvconnect.
focus	Moves the input focus of a MultiView KVM session to another window without moving the mouse. See focus.
lock	Locks or unlocks the input of a MultiView KVM session to the currently focused window. See lock.
fullscreen	Toggles the focused window of a MultiView KVM session to fullscreen. See fullscreen.
sensitivity	Gets or sets the mouse sensitivity multiplier for a remote HID extender. See sensitivity.
sendkeys	4.7 Synthesizes keyboard input on the server and delivers it to a host. See sendkeys.

disconnect

Ends the KVM session on a device, whatever kind it is, whether a collaborative hub, a MultiView session, or a Desk (MultiDevice) session, stopping keyboard and mouse forwarding. For a MultiView or Desk session it also broadcasts the matching mtvconfig_update / desk_config_update so the config's connected-devices list stays current. This is the single teardown command for every session kind.

mtvconnect

Connects a MultiView configuration to a remote HID extender. This enables the remote station's keyboard and mouse to control across all surfaces in the MultiView layout. The active window follows the cursor as it crosses display boundaries.

focus

Moves the input focus of a MultiView KVM session to another window without moving the mouse. next and prev cycle through the controllable windows in layout order (top-to-bottom, left-to-right); a window index jumps directly. On a focus change the cursor warps to the center of the new window, and keyboard indicator state (Caps Lock, Num Lock, Scroll Lock) is synchronized to the newly focused source.

Focus works while the session is locked, and moving focus moves the lock with it.

lock

Locks or unlocks the input of a MultiView KVM session to the currently focused window. While locked, mouse movement no longer crosses window boundaries, and the cursor is confined to the focused window. Unlocking restores cursor-position-based focus switching.

With no third argument, the lock state is toggled.

fullscreen

Toggles the focused window of a MultiView KVM session to fullscreen. When engaged, the display is switched directly to the focused source (native resolution and latency, because the MultiView processing path is bypassed), and keyboard/mouse input is locked to that source. Toggling off re-applies the original MultiView configuration and restores focus to the same window.

The fullscreen state survives a server restart: toggling off after a restart still restores the original MultiView configuration. With no third argument, the state is toggled. Only one fullscreen transition runs at a time per session. A re-trigger arriving mid-transition is coalesced, and the latest request is applied once the current transition finishes.

The kvm.FullscreenRestoreSettleMs configuration item sets the delay between the two passes of the restore, per RX.

sensitivity

Gets or sets the mouse sensitivity multiplier for a remote HID extender. The value persists across KVM disconnect and reconnect cycles and is applied live to any active session.

Omit the factor argument to query the current value. Pass default to remove the stored value so the seat falls back to the shipped default.

default versus an explicit 1.0

Setting 1.0 pins the seat to that value. default removes the stored value, so the seat inherits any future change to the default. The has_override field in the response tells you which state a seat is in. A seat set to exactly 1.0 otherwise reads identically to one that was never touched.

Because the value is stored rather than applied to hardware, the command accepts a seat that is not present, including one that has been decommissioned. See Configuring a seat before it exists.

sendkeys

4.7

Synthesizes keyboard input on the server and delivers it to a host without a physical keyboard, to fire a hotkey or macro the host recognizes. Two target modes:

Target mode	Sends to
seat <remote_device>	Whichever host the seat is currently controlling (its active KVM focus). Errors if the seat is not connected to a host.
tx <local_device>	Directly to a specific host (transmitter), independent of KVM state.

The <sequence> is a comma-separated list of steps: chords (ctrl+alt+f1, with modifiers ctrl, shift, alt, gui; win/cmd/meta alias gui), literal text (type:<text>), and pauses (delay:<ms>, up to 5000). Quote the sequence if it contains spaces.

The same sendkeys action is also bindable to a Stream Deck button or a keyboard macro (... sendkeys "<sequence>"), where it always targets the seat's currently-controlled host.

type: text assumes a US keyboard layout

Chords are layout-independent, but type: text maps characters as if the host uses a US-QWERTY layout. type: payloads are stored and displayed masked (type:••••) and are not intended for secrets.

Arguments

Argument	Description
local_device	The device name or ID of the local HID extender, the station where the keyboard and mouse are physically connected. The device must be configured in HID Local mode.
remote_device	The device name or ID of the remote HID extender, the station being controlled. The device must be configured in HID Remote mode.
remote_device_list	A comma-separated list of remote HID extender names or IDs. Each device must be configured in HID Remote mode.
device	Any HID-capable extender, regardless of mode. Device names are case-insensitive; spaces may be replaced with underscores.
config_name	The name of an existing MultiView configuration. See multiview for configuration management.
window	A 1-based window index over the controllable windows. See window.
factor	A floating-point mouse sensitivity multiplier. See factor.
sequence	A quoted, comma-separated keystroke sequence for sendkeys. See sequence.

window

A 1-based window index in layout order (top-to-bottom, left-to-right) over the controllable windows of the MultiView configuration. In a 2×2 layout, 1 is the top-left window and 4 is the bottom-right. Out-of-range indices leave the focus unchanged.

factor

A floating-point mouse sensitivity multiplier in the range 0.1 to 4.0. Values outside this range are clamped to the nearest boundary. The default is 1.0 (no scaling).

Value	Effect
< 1.0	Slower mouse movement
1.0	No change (default)
> 1.0	Faster mouse movement

sequence

A quoted, comma-separated keystroke sequence for sendkeys. Steps are chords (ctrl+alt+f1), literal text (type:<text>), or pauses (delay:<ms>, ≤ 5000). Modifiers are ctrl, shift, alt, and gui (aliases win/cmd/meta). type: text is interpreted for a US-QWERTY host layout.

Examples

Move a MultiView session's focus to the next window
kvm focus ControlRoom next

Jump a MultiView session's focus to window 3
kvm focus ControlRoom 3

Query the current mouse sensitivity
kvm sensitivity ControlRoom

Set the mouse sensitivity to 1.5x
kvm sensitivity ControlRoom 1.5

Send a hotkey chord to the host the seat is controlling
kvm sendkeys seat ControlRoom "ctrl+alt+f1"

Open the Run dialog and launch Notepad on the controlled host
kvm sendkeys seat ControlRoom "gui+r, type:notepad, enter"

Send a chord directly to a specific host
kvm sendkeys tx HostPC "ctrl+shift+esc"

Return value

kvm list

Each entry describes one KVM session. Mode is one of NotAssigned, Exclusive, Collaborative, MultiView, MultiDevice. PairingState is one of unknown, unpaired, pairing, paired, or linked; linked is the steady state of a working session. Windows is null for non-MultiView sessions. The RemoteExtender/LocalExtender keys are retained for backward compatibility and mirror RemoteExtenderId/ActiveLocalExtenderId.

kvm list
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "kvm_connections": [
      {
        "RemoteExtender": "6cdffb00387f",
        "LocalExtender": "6cdffb003a12",
        "RemoteExtenderId": "6cdffb00387f",
        "ActiveLocalExtenderId": "6cdffb003a12",
        "PairingState": "linked",
        "Mode": "MultiView",
        "MtvConfigName": "Wall",
        "Locked": false,
        "Fullscreen": false,
        "Windows": [
          {
            "LocalExtenderId": "6cdffb003a12",
            "HorizontalOffset": 0,
            "VerticalOffset": 0,
            "Width": 1920,
            "Height": 1080,
            "IsControllable": true,
            "IsActive": true
          }
        ]
      }
    ]
  },
  "error": null
}

kvm seats

5.0

One row per workstation seat, in a single call. Where kvm workstation show is the configuration view of a seat, kvm seats is the runtime view: what deck is physically mounted and what session is live. Every seat appears, including a present one with no deck ("Deck": null) and a configured-but-powered-off one ("Present": false, "Session": null).

• RemoteId is always present (the canonical device id). Name is the device name, or null when the hardware is not in the device catalog: never discovered, or not seen since the server started.
• Deck is the mounted control surface (Model, the model= binding key; Name; the key grid as Keys/Cols/Rows; and Dials, omitted for a deck without encoders), or null when none is attached.
• Session is the active KVM session (SourceId/Source, the host being controlled; Mode, one of Collaborative/MultiView/MultiDevice; Mtv, the MultiView config name or null; and Locked), or null when the seat is idle.

kvm seats
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "kvm_seats": [
      {
        "RemoteId": "6cdffb00f077",
        "Name": null,
        "Present": false,
        "Deck": null,
        "Session": null
      },
      {
        "RemoteId": "6cdffb01f5ba",
        "Name": "RokuTV",
        "Present": true,
        "Deck": { "Model": "plusxl", "Name": "Stream Deck + XL", "Keys": 36, "Cols": 9, "Rows": 4, "Dials": 6 },
        "Session": { "SourceId": "6cdffb00f1cb", "Source": "Laptop-LT", "Mode": "Collaborative", "Mtv": null, "Locked": false }
      }
    ]
  },
  "error": null
}

getinitdata workstations 5.0 returns the whole Workstations subsystem in one object: Seats (the array above), Configs (as kvm config list) and Desks (as kvm desk list).

kvm status

kvm status RemoteStation
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "kvm_status": [
      {
        "RemoteExtenderId": "6cdffb00387f",
        "ActiveLocalExtenderId": "6cdffb003a12",
        "PairingState": "linked",
        "Mode": "Collaborative",
        "MtvConfigName": null,
        "Locked": false,
        "Fullscreen": false,
        "Windows": null
      }
    ]
  },
  "error": null
}

kvm focus

Moved is false when the focus did not change (already on the target window, out-of-range index, or no other controllable window).

kvm focus ControlRoom next
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "kvm_focus": [
      { "Moved": true }
    ]
  },
  "error": null
}

kvm sensitivity

kvm sensitivity ControlRoom 1.5
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "kvm_sensitivity": [
      { "device_id": "6cdffb00387f", "mouse_sensitivity": 1.5, "has_override": true }
    ]
  },
  "error": null
}

kvm sendkeys

kvm sendkeys seat ControlRoom 
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "sendkeys": [
      { "Status": "ok", "Target": "6cdffb003a12" }
    ]
  },
  "error": null
}

Session commands

kvm connect, kvm disconnect, kvm stop, kvm mtvconnect, kvm lock and kvm fullscreen all return the same envelope.

kvm connect LocalStation RemoteDisplay
{
  "status": "SUCCESS",
  "request_id": null,
  "result": null,
  "error": null
}

Errors

Error response
{
  "status": "ERROR",
  "request_id": null,
  "result": null,
  "error": {
    "message": "<description>",
    "reason": "KVM API ERROR"
  }
}

Common error conditions for the core session commands:

• Device not found by the given name or ID
• Device is not HID-capable
• Device is in the wrong HID mode (local_device must be HID Local; remote_device must be HID Remote)
• Device is locked. See lock and unlock
• No active KVM session for the device (status, focus, lock, fullscreen)
• Invalid focus selector or window index (focus)
• Fullscreen requires an active MultiView session (fullscreen)
• fullscreen attempted on a MultiDevice session, which is not applicable. Use lock instead
• Invalid sensitivity value (non-numeric)
• MultiView configuration not found (mtvconnect)
• Unknown sendkeys target mode (expected seat or tx), the seat controls no host, or an invalid keystroke sequence (sendkeys)

Errors specific to the kvm macro, kvm streamdeck, kvm config, kvm hid, and kvm desk families are documented on their respective pages.

Notifications

Connected API clients receive push notifications when KVM state changes.

kvm_update

Sent whenever a session's state changes: connect, disconnect, focus change, lock change, or fullscreen transition. Carries the same object shape as a kvm list entry. A clean disconnect is signaled with "PairingState": "disconnected".

kvm_update notification
{
  "status": "DN_NOTIFICATION",
  "request_id": null,
  "error": null,
  "result": {
    "kvm_update": [
      {
        "RemoteExtenderId": "6cdffb00387f",
        "ActiveLocalExtenderId": "6cdffb003a12",
        "PairingState": "linked",
        "Mode": "MultiView",
        "MtvConfigName": "Wall",
        "Locked": true,
        "Fullscreen": false,
        "Windows": [ "..." ]
      }
    ]
  }
}

The kvm macro, kvm streamdeck, and kvm desk families emit their own notifications (macro_update, macro_error, streamdeck_update, desk_config_update). See their respective pages.

REST API

Endpoint type	DisplayNet API command
Address	POST /api/displaynet/<operation>, or name the operation in the body of a POST /api/displaynet. See Sending commands.
Role	User

Subcommand	Operation	Parameters
connect	kvm_connect	source destinations
disconnect	kvm_disconnect	source
focus	kvm_focus	remote selector
fullscreen	kvm_fullscreen	remote [mode]
list	kvm_list	—
lock	kvm_lock	remote [mode]
mtvconnect	kvm_mtvconnect	config remote
seats	kvm_seats	—
sendkeys	kvm_sendkeys	mode target sequence*
sensitivity	kvm_sensitivity	remote [factor]
status	kvm_status	device
stop	kvm_stop	source

A parameter in brackets is optional. A parameter marked * takes the remainder of the command line as one string. Pass the text exactly as you would type it on the TCI interface.

See also

• kvm workstation: the seat as a whole
• kvm desk: desk configurations for MultiDevice KVM
• kvm macro: keyboard hotkey macros
• kvm streamdeck: Stream Deck control surface bindings
• kvm config: per-seat configurations
• kvm hid: HID auto-connect policy
• mtv: MultiView configuration management