Persistent Profiles

Administrators may desire to give each user a personal persistent profile that is restored during each session. This can be achieved in one of two ways: volume mounted profiles and S3 based profiles.

Volume Mount Profiles

This is achieved by mounting in a host level directory into the container meaning the top level folders used for this setting should exist on the host beforehand. When configured, the user’s home directory will be stored at the specified location and mapped in each time the user loads that Workspace. Administrators must use the {username} or {user_id} variables in the mapping to ensure they are unique per user. {image_id} may also be used as a variable. Persistent profiles are configured on a per Workspace basis and should be isolated in their pathing IE if you have a Chrome and Firefox image on your Workspaces deployment and the users are user@kasm.local and admin@kasm.local the directory structure would look like:

├── chrome
│   ├── admin@kasm.local
│   └── user@kasm.local
└── firefox
    ├── admin@kasm.local
    └── user@kasm.local

The only folder the administrator needs to create is /mnt/kasm_profiles/ and the rest will be generated on Workspace launch.

S3 Based Profiles

AWS S3 object storage can be used for persistent profiles. The advantages of using S3 for persistent profiles are:

  • Redundancy

  • Data management policies in S3

  • Globally distributed

  • Security

The user’s session container does not have direct authenticated access to S3. When the container starts, it makes an API call to the Kasm API service to request the profile manifest. The Kasm API returns a manifest that contains presigned URLs for each layer of the profile. The S3 presigned URLs are only authorized for each object they are signed for and only for a limited amount of time. This architecture ensures that a single S3 bucket can be securely used for all users in the system.

The administrator needs to define the AWS Access Key ID and Access Secret in the Server Settings. The access key should be defined on a user that only has access to the specific bucket in question, with no other permissions. The user should be able to read and write to the bucket, and create pre-signed URLs. Kasm API services need to be restarted after changing/setting the AWS Access Key ID or Access Key Secret.

Finally, the administrator will need to specify the S3 URL path in the Workspace settings, in the format of s3://bucket-name/folder/{username}/. Replace bucket-name with the target S3 bucket name. Each Workspace in Kasm should have its own folder, if the folder does not exist, it will be created. Use the {username} or {user_id} token in the path, to ensure each user has their own directory. Administrators can use different buckets for different Workspaces, as long as the AWS Access Key used in the global settings has the required access to all configured buckets.


Container based images must support S3 persistent profiles. All Kasm maintained images support S3 persistent profiles with the exception of the following images.


S3 Endpoints

By default, the endpoint used for S3 access is Administrators may desire to specify a custom endpoint in order to support the following use cases.

  • A private VPC Endpoint

  • AWS Gov Cloud end-points

  • Region specific end-points

  • AWS S3 Accelerated Endpoints

  • S3 Compatible Solutions

To specify a custom endpoint, in the Workspaces settings, format the Persistent Profile path in the following format:


The following example configures Kasm to use Wasabi (an S3 compliant cloud storage provider) for a persistent profile, where kasm is the bucket name, is the endpoint name, and the remaining is the path with {username} replaced by the Kasm username.


Adding a persistent profile to a Workspace

To add a persistent profile path to a Workspace from the administrator menu first click on Workspaces -> Workspaces and edit your desired Workspace:


Edit a Workspace

How to configure a persistent profile in a workspace

  • Configure the persistent profile path on the Workspace.

Variables can be used for the Image ID and User ID so that the persistent profile path is uniform across all images:


Configuring persistent profile path with Image ID and User ID

Alternatively, if the paths should be human-readable the image name can be specified in the path and the Username as a variable:



Configuring persistent profile path with image name


If Kasm is installed in a multi-server deployment path should reference a shared data storage solution (e.g NFS, HDFS, GFS, SMB, SSHFS) to ensure data continuity. Administrators must ensure this path is accessible from the hosts of all Agent services. Kasm will create the directory if it does not exist.

Limiting group access to persistent profiles

It may be necessary to limit which users can access the persistent profile feature, this can be achieved with a group setting. See Group Setting for more details.

From the administrator menu first click on Access Management -> Groups and click Edit on your desired group:


Edit a Group

Under Settings find the allow_persistent_profile group setting and click edit:


Select Persistent Profile Group Setting

This is a Boolean value, set it to true to enable access and false to disable access for this particular group.


Enabling Persistent Profiles at the Group Level

Utilize a persistent profile with creating a Kasm


Using a persistent profile

When creating a Kasm, the user will now be presented with a Persistent Profile Option. Multiple Settings are available.

  • Enabled

    • The persistent profile path defined on the workspace will be loaded during creation.

  • Disabled

    • The persistent profile will NOT be loaded on creation.

  • Reset

    • The existing persistent profile will be deleted and re-created. The is useful if the user desires to clear old profile data and start fresh.

Size Limits

Administrators can place a size limit on S3-based persistent profiles and a size warning for volume mapped profiles. When a user’s home profile exceeds the limit, the user will get a warning message within the Workspace desktop session. For S3-based profiles, the user’s changes will not be saved between sessions until they reduce the size of their profile. The size limit can be set using the environmental variable KASM_PROFILE_SIZE_LIMIT, specified in KB. To specify a persistent profile size limit of 2GB, you would set a value of 2000000. To set the environmental variable, use the Docker Run Override setting in the Workspace definition. By default, there is no limit.


S3-based persistent profiles support filters that will ignore files and/or directories. The filter is a comma separated list of file or directory names, relative from the user’s home profile path.

The default filter is.


This default filter ignores the .cache, .vnc, Downloads, and Uploads directories within the user’s home profile. This default filter can be overridden by setting the KASM_PROFILE_FILTER environmental variable. To set the environmental variable, use the Docker Run Override setting in the Workspace definition.

Globing is supported, such as Documents/*.docx, to mean any file ending in ‘.docx’ or Documents/**.docx, meaning any file ending in ‘.docx’ in the Documents directory or any child directory within.

Video Example

This video shows an example of configuring persistent profiles.