Desktop

A desktop Workspace runs a graphical desktop in the guest. You can view and operate it in a local browser, or script it with screenshots and keyboard and mouse input from kibo workspace desktop.

PrerequisitesCopy Anchor Link

• A kibotos-desktop Workspace.
• For the browser view: the noVNC client on your workstation. See Setting up noVNC.
• For screenshots and keyboard and mouse input: a server with the workspace.desktop capability. See Capability names.

Viewing the desktop in a browserCopy Anchor Link

The kibo workspace desktop view command starts a web page on your machine for viewing and operating the desktop. It prints the address of the page:

kibo workspace desktop view "$workspace_id"
# Page  http://127.0.0.1:41735/

Open the address in a browser. You can keep the page open for as long as you work: after a disconnect, click "Reconnect" instead of running the command again.

Setting up noVNCCopy Anchor Link

The VNC client in the page is upstream noVNC. It is not bundled with kibo, so you need to set it up once on your workstation. The current version needs noVNC v1.6.0.

The command looks for noVNC in these places, in order, and uses the first directory that contains the required files:

1. --novnc-dir
2. KIBO_NOVNC_DIR
3. /usr/share/kibotos/novnc
4. .cache/novnc/<release> under the working directory

If none is found, the command fails, and the error message names the noVNC version it needs.

The following commands download the upstream archive, verify its checksum, extract the needed parts into your user directory, and point kibo at it:

curl -fsSLo novnc.tar.gz https://github.com/novnc/noVNC/archive/refs/tags/v1.6.0.tar.gz
echo '5066103959ef4e9b10f37e5a148627360dd8414e4cf8a7db92bdbd022e728aaa  novnc.tar.gz' | shasum -a 256 -c -
mkdir -p "$HOME/.local/share/kibotos/novnc"
tar -xzf novnc.tar.gz -C "$HOME/.local/share/kibotos/novnc" --strip-components=1 \
  noVNC-1.6.0/core noVNC-1.6.0/vendor noVNC-1.6.0/LICENSE.txt noVNC-1.6.0/AUTHORS
export KIBO_NOVNC_DIR="$HOME/.local/share/kibotos/novnc"

ConnectionsCopy Anchor Link

The view command requests a data-plane credential for the desktop's VNC socket (/run/kibotos/services/desktop/vnc.sock) and turns the RFB traffic into a local WebSocket for the browser.

Starting:

• The desktop is not running when the Workspace boots. The first connection starts it.
• The command connects once and waits for the desktop to become ready within the dial deadline (5 seconds). If the desktop is not ready in time, the command fails; run it again.

Staying connected:

• The command renews the credential automatically before it expires and requests a new one after the Workspace restarts.
• Connections have no limit on duration, idle time, or total traffic. An expired credential does not close an established connection.
• One view command keeps at most 16 connections at the same time, for example 16 browser tabs. Beyond that, new connections are refused.

A connection ends when:

• The Workspace stops or is deleted, or its node restarts. The page shows a notice and lets you reconnect.
• The browser stops reading, and data waiting to be sent to it is not accepted within 5 seconds.

Screenshots and keyboard and mouse inputCopy Anchor Link

The other subcommands of kibo workspace desktop take screenshots of the desktop or send keyboard and mouse input to it directly. They share the same desktop as the browser view page, and neither takes it over from the other.

When the desktop is not running yet, the first call starts it and waits for it to become ready within the call deadline.

Taking a screenshotCopy Anchor Link

screenshot <workspace-id> <local-path|-> saves the current screen to a local file:

kibo workspace desktop screenshot "$workspace_id" screen.png

• It first writes to a temporary file next to the target and replaces the target when the write is complete.
• The target cannot be a symbolic link or a special file. New files get permissions 0600.
• The output includes path, format, width, height, size_bytes, and sha256.
• A newly ready desktop may not have finished drawing yet, so the first screenshot may not show the complete desktop.

When the path is -, the image goes to standard output. In that case, --json is not allowed, and the information above goes to standard error instead:

kibo workspace desktop screenshot "$workspace_id" - > screen.png

Pointer inputCopy Anchor Link

Each input subcommand performs one input action. On success, it prints the pointer position pointer (x, y), shown as x,y in human-readable output.

The following commands move the pointer, click, drag, and scroll:

kibo workspace desktop move "$workspace_id" 640 360
kibo workspace desktop click "$workspace_id"
kibo workspace desktop click "$workspace_id" 640 360 --button right --count 2
kibo workspace desktop drag "$workspace_id" 100 100 400 300 --button left
kibo workspace desktop scroll "$workspace_id" --direction down --amount 3

Keyboard and text inputCopy Anchor Link

The following commands press a key combination, type text, and paste text:

kibo workspace desktop key "$workspace_id" ctrl+l
kibo workspace desktop type "$workspace_id" '在搜索框里输入中文 😀'
kibo workspace desktop paste "$workspace_id" "$(cat notes.md)"
kibo workspace desktop paste "$workspace_id" 'ls -la' --keys ctrl+shift+v

• Key names accepted by key: a single character, or shift ctrl alt super enter tab escape backspace delete insert space home end pageup pagedown up down left right f1..f12.
• When type enters characters that are not in the keyboard layout (Chinese, emoji, and so on), it temporarily borrows free keys in the layout and restores them when the call ends. Each batch of characters has to wait for desktop applications to reload the layout, so paste is faster for long text or text with many different characters.
• paste writes the clipboard and presses the shortcut in one call because any application on the desktop that copies something overwrites the clipboard.
• The clipboard is empty after the desktop process is recreated.
• Terminal applications usually need --keys ctrl+shift+v.

With the APICopy Anchor Link

Programs take screenshots and send input through Screenshot and PerformActions of the data-plane DesktopService. Each kibo workspace desktop subcommand other than view makes one such call.

• The server must have the workspace.desktop capability. See Querying capabilities first.
• Each call needs a data-plane credential with the DESKTOP scope. See Requesting a session credential.
• For every method and message, see DesktopService.

One PerformActions request carries a list of actions. The server checks the whole list before it delivers any action. Each action follows the limits in the tables above, and the request as a whole has these limits:

A request that breaks a limit fails with invalid_argument, and no action is delivered.

NotesCopy Anchor Link

• The server decides whether coordinates are on screen, whether a value is within the limits above, and whether a key name is available. The kibo command checks only the argument format: non-numeric coordinates and unknown buttons and directions are rejected before any request is sent.
• The desktop is unavailable when the default user of the Template is unavailable in the guest. See Default user unavailable.

Next stepsCopy Anchor Link

• Services and ports: open other web services in the guest.
• Commands and terminals: run commands next to the desktop.
• API overview: credentials and conventions for your own program.