Workspace Registry

Installing workspaces in Kasm

The Workspace Registry is a mechanism for allowing users to easily install workspaces. This can be from our own 1st party registry or from 3rd party registries.

The intention was twofold. First to make it as simple as possible for users to add workspaces without needing to fill in lots of fields, and secondly to make it as simple as possible for anyone to create their own registries without us needing to be gatekeepers.

Video Tutorial

1st Party Registry

1st Party Workspace Registry

The 1st party registry comes pre-installed in Kasm Workspaces 1.13.0 or newer and makes it simple to install any of our workspaces that aren’t already installed on your system.

Note

If you remove the 1st party registry and want it back at any point, our registry store front is located at https://registry.kasmweb.com/

3rd Party Registry

3rd Party Workspace Registries

3rd Party repositories allow external developers to create their own workspaces that will work seamlessly with Kasm Workspaces.

Warning

You should only install registries from 3rd parties that you trust, and even then before installing a workspace you should check to see what commands are being executed.

There are a couple of ways this can be done:

1. Click on a workspace tile and instead of clicking install, click on edit.

2. From the Registry page where you got the Workspace Registry Link, clicking on one of the workspaces takes you to a page that displays all the JSON for that workspace (you can also get to this by clicking the registry logo in the list on registries at the top of the page).

Either of these 2 options allows you to see everything that is being set. Pay particular attention to anything in the Docker Run Config Override (JSON) field (run_config in the workspace JSON) or the Docker Exec Config (JSON) field (exec_config in the workspace JSON) as these fields allow arbitrary commands to be run. If either of these fields are populated and you are unsure of what they are doing, ask the 3rd party to clarify before blindly installing.

Installing Workspaces

To install a workspace, click on the workspace you want to install then click on the install button that appears. If the registry has channels then you will be presented with a dropdown of the possible options, with the default pre-selected. If you want to see exactly what is being installed you can click on the edit button instead.

Installing a workspace

Once you click on the install button, the estimated required space will be added to the size widget located at the top of the screen next to the list of stores. As workspaces finish installing the sizes will recalculate based on the actual size taken.

Estimating workspace requirements

The estimated size is the uncompressed size, and so should be a worst case scenario as any duplicate layers will lower the amount of space used up.

The space remaining is based on the remaining space on every agent combined, however by default workspaces are installed on all available agents so potentially it could take up more space then expected.

Configuration Warnings

If a workspace has an orange border and an orange exclamation shield icon to the right of the name, this indicates that the workspace has been flagged as requiring review before installation.

A workspace that requires review

The reason for the workspace being flagged will be that it has defined a configuration that may provide elevated privileges or access. The warning doesn’t mean that there is a problem with the workspace, just that you should review what it is doing prior to installation.

For example, many of the linuxserver.io workspaces are flagged with a warning. By hovering over the exclamation you will receive a tooltip with more information.

This tells you that if you click on the edit button instead of install, you should head to the Docker Run Config Override (JSON) section and look at the value of the security_opt property as that is what triggered the warning.

In this case multiple properties are set. user is set, but it’s set to 1000 so doesn’t cause a flag. entrypoint is set but is on the list of ignored properties so also doesn’t cause a flag. security_opt is not on the ignored list and so does cause a flag. We haven’t included specific information for security_opt so it gets labeled with the generic flag_property identifier (that can be seen as the last item in the tooltip and is the link to this website so you can look up the meaning in the table below).

In this specific case the workspace requires a minimum specific version of libseccomp to run, as a convenience the linuxserver.io workspaces are adding "security_opt":["seccomp=unconfined"] to ensure that users can just click install and get a functioning workspace. On the downside this does mean the workspace will run without the docker seccomp sandbox and will significantly reduce the amount of protection that Kasm Workspaces can provide.

There may be multiple properties that caused a warning and they should all be listed in the tooltip. After the property that caused a flag there is a link to this website with a value to look up on the table below for more information.

Property	Description
user_error	A user has been defined and it’s not set to 1000. This often means the user has been set to root. Some workspaces may need to be run as root to function correctly so it’s not necessarily a major cause for concern, you should just be more cautious and understand that the workspace has elevated privileges.
privilege	This workspace is running in privileged mode which grants the workspace root capabilities to all devices on the host
flag_property	This is a generic flag. What this means is the property that was flagged is not in the list of ignored or safe properties but we haven’t added specific information on it yet. You should look up what the property does and if it’s a cause for concern manually.

Updates

Automatic updates are on by default with the official Kasm registry, and off for 3rd party registries. You can change this by clicking on the ellipsis button on a registry and ticking or unticking Automatic Updates. When automatic updates are on, the registry will be updated when you hit the registrly list page. Whether automatic updates are on or off there is a button to manually update the registry as well.

Updating a registry will pull the latest available workspaces and any updated configuration but wont affect any currently installed workspaces.

If a registry has channels, there will be a dropdown, clicking on the dropdown and making a selection will change the default channel to be used for all workspaces in that registry. This allows you to choose which is the most appropriate channel while still being able to override the choice on an individual workspace.

Update a registry

Search and filter

When on the registry page the same search and category options are available in the top right as when you are on the workspaces page. These allow you to search for specific workspaces or categories.

Searching and selecting a category

When there is more than one registry installed the option to filter by registry will appear. Clicking on a registries name You can also click on the mini workspace icons under a registries name to just show that registries workspaces. Finally, once you are finished, you can click the Clear Filters button next to Available Workspaces to easily bring all the options back.

Searching and selecting a category

Create your own workspace registry

We have worked hard to try and make it as simple as possible for 3rd party developers to build and maintain their own Workspace Registries. With that goal in mind we have a github template repository which can be used as a basis for your own workspace registry. Full instructions on how to create a registry are included in the README there.

Schema

Current version: 1.1

Property	Required	Description
friendly_name	True	The name to show
description	True	A short description of the workspace
image_src	True	The name of the workspace icon used
architecture	True	Json list containing either “amd64”, “arm64” or both
compatability	True	A list of dictionaries each containing version, image, uncompressed_size_in_mb, and available_tags.
categories	False	Json list containing the categories the workspace belongs too. This should be limited to a max of 3.
docker_registry	False	Which docker registry to use
run_config	False	Any additional parameters to add to the run config
exec_config	False	Any additional parameters to add to the exec config
notes	False	Notes about running the workspace, such as if it requires libseccomp.
cores	False	Specify the amount of cores to use for this workspace
memory	False	Specify the amount of memory to use for this workspace
gpu_count	False	Specify the amount of GPUs to use for this workspace
cpu_allocation_method	False	What CPU allocation method to use for this workspace. Can be either “Inherit”, “Quotas” or “Shares”

The compatibility property is an array of objects and needs a bit more explanation

  "compatibility": [
    {
      "version": "1.16.x",
      "image": "kasmweb/chromium:1.16.0-rolling-daily",
      "uncompressed_size_mb": 2643,
      "available_tags": [
        "develop",
        "1.16.0",
        "1.16.0-rolling-weekly",
        "1.16.0-rolling-daily"
      ]
    }
  ]

• version - This is the version of kasm the entry is compatible with

• image - The docker image. The tag is included for things like estimating the size and is used if there are no available_tags.

• uncompressed_size_mb - Integer of the approximate size of the workspace when it’s uncompressed in MB. This doesn’t take into account layers. For example if an image is 2.46GB you would enter 2460

• available_tags - These values are what will determine the available “channels” on the front end. If you don’t want/need channels, remove the available_tags section completely. You shouldn’t mix and match though, if you specify available_tags for 1 workspace, it should be specified for all of them. That doesn’t mean every workspace has to have all the same tags, if a workspace only has develop tags then it will only show when develop is the selected channel.

---

Using workspace registries in Kasm

The idea behind Workspace Registries was to try and make it as simple as possible to add and delete the registries.

Adding a registry

---

1. Find a workspace registry.

2. Click the “Workspace Registry Link” button.

3. In Kasm click on the “Workspaces” navigation link.

4. Click on the “Workspace Registry” button.

5. Click on the “Add new” link at the top, and paste into the text box, then click the “Add” button.