Workspace Registry
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
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 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:
Click on a workspace tile and instead of clicking install, click on edit.
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.
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.
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.
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.
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.
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.
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.
Find a workspace registry.
Click the “Workspace Registry Link” button.
In Kasm click on the “Workspaces” navigation link.
Click on the “Workspace Registry” button.
Click on the “Add new” link at the top, and paste into the text box, then click the “Add” button.