kvm desk

The kvm desk command manages desk configurations for MultiDevice KVM. A desk configuration is a named source→destination routing map: each entry (a "monitor") pairs a source (the TX/encoder carrying a PC's video) with a destination RX (the decoder driving a physical monitor at the desk), and places that monitor at a position in a shared canvas. Entries are added in display order (left-to-right is typical), and insertion order becomes the navigation index the cursor uses when it crosses between monitors.

A monitor can also be control-only (no video route, destination -) or view-only (routed onto the desk but never grabs the mouse, controllable false).

Once a desk is configured, apply its routing and start a MultiDevice KVM session on it with kvm desk connect.


Command Type	DisplayNet
Minimum Version	5.0

Usage

kvm desk create <name>
kvm desk rename <oldName> <newName>
kvm desk add-monitor <name> <source> <destination|-> <x> <y> [<width> <height>] [<controllable>]
kvm desk remove-monitor <name> <source>
kvm desk delete <name>
kvm desk list
kvm desk show <name>
kvm desk connect <name> <remoteId>

<source> is the TX device ID of the PC whose video feeds that monitor. <destination> is the RX device ID of the decoder driving the physical monitor, or - for a control-only pair with no video route. <x> <y> is the monitor's top-left position in the shared canvas, in pixels. <width> <height> is its resolution and is optional: provide both or neither. When omitted, the system queries the source device's current output resolution at connect time and falls back to 1920×1080 if that is unavailable; kvm desk show reports auto for monitors without stored dimensions. <controllable> is an optional true/false override. Omit it to leave the monitor controllable.

Subcommands

Subcommand	Description
`create`	Creates a new, empty desk configuration.
`rename`	Renames an existing desk configuration. A case-only rename (for example `ops` → `Ops`) is allowed.
`add-monitor`	Adds a monitor to a desk. See `add-monitor`.
`remove-monitor`	Removes a monitor from a desk by its source ID. The remaining monitors are re-indexed to close the gap.
`delete`	Deletes a desk configuration and all of its monitors.
`list`	Returns the names of all desk configurations.
`show`	Returns one desk configuration with its monitors in navigation-index order.
`connect`	Applies the desk's routing map and starts a MultiDevice KVM session. See `connect`.

`add-monitor`

Adds a monitor to a desk. The monitor is appended after any existing monitors and takes the next navigation index. A monitor is keyed by its source, so a desk cannot hold two entries with the same source. Width and height are optional: provide both or neither. Pass - as the destination for a control-only pair (no video is routed), and an optional trailing true/false to override controllability.

`connect`

Applies the desk's routing map, routing each monitor's source to its destination RX, and starts a MultiDevice KVM session: one keyboard and mouse drive several PCs, each shown on a separate physical monitor at the same desk. <remoteId> is the HID Remote extender at the desk where the keyboard and mouse are plugged in; it must be unlocked. The cursor moves between monitors using the same virtual-desktop edge-crossing geometry as MultiView. End the session with kvm disconnect.

See the kvm page for the shared focus/lock model that MultiView and Desk sessions use.

Arguments

Argument	Description
`name`	The desk configuration name (case-insensitive). Names contain no spaces: a name passed to `create` or `rename` with spaces is stored as its underscore form (`Front Lobby` → `Front_Lobby`), trimmed of surrounding whitespace. A name that already contains spaces can be addressed by wrapping it in double quotes: `kvm desk show "old desk name"`.
`source`	The TX device ID (or name) of the PC whose video feeds this monitor. A monitor is keyed by its source, so a desk cannot contain two monitors with the same source.
`destination`	The RX device ID (or name) of the decoder driving the physical monitor this source is shown on. Pass `-` for a control-only pair, where the source is navigable for KVM control but no video is routed (the pre-routing desk behavior).
`x` / `y`	The monitor's top-left position in the shared canvas, in pixels. Integers.
`width` / `height`	The monitor's resolution in pixels. Optional: provide both or neither. When omitted, the resolution is resolved from the source device at `connect` time (falling back to 1920×1080).
`controllable`	Optional `true`/`false` override for whether the cursor may enter this monitor. Omit (or `true`) to leave it controllable; `false` makes it a view-only tile, routed onto the desk but never grabbing the mouse. It may follow the size, or for an auto-sized monitor come directly after `x y` (`… <x> <y> <true\|false>`), since a `true`/`false` in the width position is read as this flag.
`remoteId`	The HID Remote extender at the desk where the keyboard and mouse are plugged in (`connect` only). Must be in HID Remote mode and unlocked.

Examples

Build a four-monitor desk, inspect it, and connect it
kvm desk create ops-desk
kvm desk add-monitor ops-desk 6cdffb01f5c3 6cdffb00f0a1 0    0
kvm desk add-monitor ops-desk 6cdffb01f5bd 6cdffb00f0a2 1920 0 2560 1440
kvm desk add-monitor ops-desk 6cdffb01f5c6 6cdffb00f0a3 4480 0 1920 1080 false
kvm desk add-monitor ops-desk 6cdffb01f5c9 6cdffb00f0a4 6400 0 true
kvm desk show ops-desk
kvm desk connect ops-desk ControlRoom

Return value

`kvm desk list`

Returns the names of all desk configurations.

kvm desk list
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "desk_list": ["ops-desk", "theater"]
  },
  "error": null
}

`kvm desk show`

Returns one desk configuration with its monitors in navigation-index order. DestinationRxId is null for a control-only pair; Controllable is null when no override is set (the default, controllable). Size is "<width>x<height>", or "auto" when no resolution is stored (it is resolved from the source device at connect time).

kvm desk show ops-desk
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "desk_show": [
      {
        "Name": "ops-desk",
        "Monitors": [
          { "Index": 0, "SourceId": "6cdffb01f5c3", "DestinationRxId": "6cdffb00f0a1", "Controllable": null,  "X": 0,    "Y": 0, "Size": "auto" },
          { "Index": 1, "SourceId": "6cdffb01f5bd", "DestinationRxId": "6cdffb00f0a2", "Controllable": false, "X": 1920, "Y": 0, "Size": "2560x1440" }
        ]
      }
    ]
  },
  "error": null
}

Management subcommands

create, rename, add-monitor, remove-monitor, delete and connect all return the same envelope.

kvm desk create ops-desk
{
  "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:

Desk configuration not found, or a name collision on create / rename
A monitor with the same source already exists in the desk (add-monitor)
add-monitor given a width without a height, or a height without a width; a non-positive width/height; a non-integer x/y; or a controllable value that isn't true/false
Monitor not found in the desk (remove-monitor)
Desk configuration not found, or the remote is not an unlocked HID Remote extender (connect)

Notifications

`desk_config_update`

Sent whenever a desk configuration changes: create, rename, add-monitor, remove-monitor, delete, and connect/disconnect (which change the connected-devices list). It carries the desk's Name, its Monitors (same shape as kvm desk show), and connectedDevices, the remote extenders currently in a MultiDevice session on this desk. This mirrors the mtvconfig_update shape so a UI can track desks the same way it tracks MultiView configs.

desk_config_update notification
{
  "status": "DN_NOTIFICATION",
  "request_id": null,
  "error": null,
  "result": {
    "desk_config_update": [
      {
        "Name": "ops-desk",
        "Monitors": [ "..." ],
        "connectedDevices": ["ControlRoom"]
      }
    ]
  }
}

A deleted desk is signaled with a positive removal shape instead:

desk_config_update (deleted)
{
  "status": "DN_NOTIFICATION",
  "request_id": null,
  "error": null,
  "result": {
    "desk_config_update": [
      { "Name": "ops-desk", "Deleted": true }
    ]
  }
}

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
`desk`	`kvm_desk`	`action` `[args]*`
`desk_add_monitor`	`kvm_desk_add_monitor`	`name` `source` `x` `y` `[destination]` `[width]` `[height]` `[controllable]`
`desk_connect`	`kvm_desk_connect`	`name` `remote_id`
`desk_create`	`kvm_desk_create`	`name`
`desk_delete`	`kvm_desk_delete`	`name`
`desk_list`	`kvm_desk_list`	—
`desk_remove_monitor`	`kvm_desk_remove_monitor`	`name` `source`
`desk_rename`	`kvm_desk_rename`	`old_name` `new_name`
`desk_show`	`kvm_desk_show`	`name`

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.

Every action has a typed operation taking named fields. A desk name containing spaces needs no quoting, a control-only pair omits destination rather than passing -, and a missing or unknown field is rejected before the command runs.

kvm_desk takes a raw grammar line instead: action and args, spelled as under Usage above.

Usage​

Subcommands​

add-monitor​

connect​

Arguments​

Examples​

Return value​

kvm desk list​

kvm desk show​

Management subcommands​

Errors​

Notifications​

desk_config_update​

REST API​

See also​