DESK - Desktop Exposing Server Kit

DESK is a remote desktop environment, originally developed for visualization and processing of medical images. It currently works under Linux or macOS, but patches for other platforms are welcome.

This repository contains desk-base, the shared Node.js library that powers DESK. It is not a standalone server: it provides the action execution engine used by the desk server/clients. The frontend UI source code is available at valette/desk-ui.

Looking for a runnable application? Use the desktop builds: desk-electron (Electron) or desk-nw (NW.js).

Table of contents

• Features
• How it works
• Action Definitions
• Documentation
• Requirements
• Installation
• Usage
• Development
• Goals
• License

Features

• Action Framework: Register command-line tools or JavaScript modules as reusable, parameterized actions via JSON configuration.
• Automatic caching: Action outputs are cached by command-line hash and invalidated when their inputs change.
• Concurrency control: Actions run under CPU-bounded queues; identical concurrent runs are deduplicated.
• Streaming: Stream stdout/stderr and output directories to clients.
• File management: Upload/download files, manage directories, base64 writes.
• Custom RPC: Extend with your own actions in ~/desk/extensions/.
• Live reload: Action definitions are watched and hot-reloaded.

How it works

DESK is a server framework. Custom code execution is defined through action definitions — JSON files that describe executable commands or JavaScript modules along with their typed parameters. Each action becomes a remote procedure call that the UI (or any client) can invoke.

The core flow: a POST object describing an action is queued, its typed parameters are resolved into a shell command line (or a JS module call), the action executes in its output directory, and the result is cached.

See docs/architecture.md for a deep dive into the request lifecycle, queues, event model, and directory layout.

Action Definitions

Actions are defined through JSON configuration files and are loaded from:

• lib/includes/base.json — built-in system actions
• lib/includes/testing/testing.json — test actions
• user files in the ~/desk/extensions/ directory (watched, hot-reloaded)

For a practical example, see the ACVD.json file from the ACVD project, which demonstrates complex mesh-processing actions.

Minimal example

{
  "actions": {
    "greet": {
      "parameters": [
        { "name": "name", "type": "string", "required": true, "prefix": "Hello, " }
      ],
      "command": "echo"
    }
  }
}

Action structure

Each action supports the following fields:

{
  "parameters": [
    {
      "name": "parameter_name",
      "type": "parameter_type",
      "required": true,
      "defaultValue": "default_value",
      "prefix": "--option ",
      "suffix": " postfix",
      "min": 0,
      "max": 100
    }
  ],
  "command": "command_to_execute",
  "executable": "/path/to/executable",
  "js": "module_name",
  "voidAction": true,
  "noCache": true,
  "dependencies": ["dependency1", "dependency2"],
  "permissions": 1
}

Parameter types

| Type | Description | |------|-------------| | string | Simple string parameter | | escapedString | String with shell special characters escaped | | int | Integer value | | float / number | Floating-point number | | file | File path parameter (resolved, escaped) | | fileString | File path string (resolved, escaped) | | directory | Directory path parameter | | fileArray | Array of file paths | | intArray | Array of integers | | floatArray / numberArray | Array of floating-point numbers | | stringArray | Array of strings | | base64data | Base64 encoded binary data | | flag | Boolean flag parameter (injects via prefix) |

Full details — including per-parameter options (prefix, suffix, separator, length, min/max, aliases, defaultValue, text) and shell-escaping rules — are in docs/parameter-types.md.

Documentation

Extensive documentation lives in the docs/ directory:

• Architecture — modules, request lifecycle, queues, events, IPC, directory layout.
• Action Definitions — full JSON schema + inventory of built-in actions.
• Parameter Types — every type, options, and escaping rules.
• Caching — output directories, invalidation, replay, cache cleaner.
• API Reference — the exported module API, events, and environment variables.

Requirements

To install DESK on your computer:

• Git
• Node.js (version 8.1.0 or higher, see engines in package.json)

For 3D data visualization (meshes, volumes):

• VTK with headers
• CMake

Installation

git clone https://github.com/valette/desk-base.git
cd desk-base
npm install

To install binary addons for 3D data visualization (requires VTK and CMake):

npm run buildAddons

Usage

desk-base is a library and does not start a server by itself. Use it in a parent application:

const desk = require('desk-base');

const result = await desk.execute({
  action: 'pwd',
  stdout: true
});

When loaded, lib/index.js also starts a daily cache cleaner and a node-ipc socket server (both skipped if DESK_SINGLE is set) so actions can be invoked across processes.

For a full server with a web UI, use desk-electron or desk-nw. A live demo is available at https://desk.creatis.insa-lyon.fr/demo/.

Development

There is no automated test suite. The testing include ships a testAllParameters action that exercises every parameter type; it can be invoked from a live DESK server to validate the engine (lib/includes/testing/testing.js).

Building the debug UI version (in a desk-server checkout):

cd node_modules/desk-ui
git clone https://github.com/qooxdoo/qooxdoo
npm install
npm run build

The debug version will be available at: http://localhost:8080/ui/source

Goals

The primary goal is to enable efficient visualization tools such as THREE.js and qooxdoo on top of existing server-side command-line programs. Each server-side program is registered as an action using a JSON configuration file. DESK can also generate static content suitable for web deployment; an example served by a classic Apache server is visible here.

More information: http://www.creatis.insa-lyon.fr/~valette/desk.html

License

CeCILL-B (BSD-compatible). For academic use, please cite:

H. Jacinto, R. Kéchichan, M. Desvignes, R. Prost, and S. Valette, "A Web Interface for 3D Visualization and Interactive Segmentation of Medical Images", 17th International Conference on 3D Web Technology (Web 3D 2012), Los Angeles, USA, pp. 51-58, 2012

Acknowledgements

This software benefits from several open-source contributions:

• VTK
• Node.js
• THREE.js
• qooxdoo
• OpenCTM
• ACVD