Custom Chrome extensions

Overview

Distributing an internal or unsigned Chrome extension to users one machine at a time does not scale. This guide configures a Kasm Workspaces container-based workspace to load a custom Chrome extension automatically on every launch. You upload the extension with file mapping, extract it during workspace startup, and pass it to Chrome through a Docker Run Config override. As a result, users open a workspace that already has the extension installed, with no manual setup and no reliance on the Chrome Web Store.

Prerequisites

Before you begin, confirm the following:

• Administrator access to the Kasm Workspaces deployment, with permission to edit Workspaces.
• A container-based Chrome or Chromium workspace to customize.
• The source directory of the extension you want to load, packaged as a .zip archive.
• Familiarity with file mapping. For background, see the file mappings guide.

Solution approach

This guide progresses through the following phases:

1. Package the extension source directory.
2. Upload the package with a file mapping.
3. Pass the extension to Chrome with a Docker Run Config override.
4. Extract the package on launch with a Docker Exec Config.
5. Verify that the extension loads.

Detailed steps

Package the extension source directory

Chrome loads an unpacked extension from a directory, so the upload must contain the directory rather than the loose source files.

1. Compress the extension source directory into a .zip archive. Zip the directory itself, not the individual source files inside it.

Zip source code files with zip command

Upload the package with a file mapping

A file mapping delivers the archive into the workspace filesystem each time a session starts.

1. In the Kasm Workspaces UI, go to Admin > Workspaces, then Edit the target workspace.
2. Open the File Mapping tab and click Add File Mapping.
3. Set the type to File Upload and give it a descriptive name and description.
4. Set the Destination Path to a location such as /tmp/extension/your-extension.zip.
5. Set both Writable and Executable to Disabled, then save the changes.

Workspace-level file mapping settings

note

File mapping can be set at both the workspace level and the group level.

Pass the extension to Chrome with a Docker Run Config override

The Docker Run Config override sets the application arguments that tell Chrome where to find the unpacked extension.

1. In the workspace editor, open the Docker Run Config Override field.
2. Enter the following configuration. Replace the extension name and path with your own values.

{
  "hostname": "kasm",
  "environment": {
    "APP_ARGS": "--load-extension=/tmp/extension/your-extension"
  }
}

Docker run config override

caution

Chrome removed --load-extension in Chrome 137. The argument still works on Chromium. On Chrome it works for now with --disable-features=DisableLoadExtensionCommandLineSwitch, but that workaround will be removed in a future Chrome version.

To keep loading the extension on a current Chrome version, add the --disable-features argument as shown below.

{
  "hostname": "kasm",
  "environment": {
    "APP_ARGS": "--disable-features=DisableLoadExtensionCommandLineSwitch --load-extension=/tmp/extension/your-extension"
  }
}

Docker run config override with --disable-features

Extract the package on launch with a Docker Exec Config

The uploaded archive must be unpacked before Chrome can load it. A Docker Exec Config runs the extraction command at first launch.

1. In the workspace editor, open the Docker Exec Config field.
2. Enter the following configuration. Replace the archive name and path with your own values.

{
  "first_launch": {
    "user": "root",
    "cmd": "bash -c 'unzip /tmp/extension/simple-chrome-extension-master.zip -d /tmp/extension/'"
  }
}

Docker exec config

Verify that the extension loads

1. Launch a new session of the workspace.
2. Confirm that Google Chrome opens with the custom extension already loaded.

Custom chrome extension in action

Common troubleshooting steps

• The extension does not appear in Chrome. Confirm that the --load-extension path matches the extracted directory, not the .zip archive. The path passed to Chrome must point to the unpacked extension folder.
• The extension loads on Chromium but not on Chrome 137 or later. Chrome removed --load-extension in version 137. Add --disable-features=DisableLoadExtensionCommandLineSwitch to APP_ARGS, and plan to migrate before that workaround is removed.
• The Docker Exec Config command fails to extract the archive. Confirm that the archive name and destination path in the unzip command match the Destination Path set in the file mapping.
• The archive uploads but Chrome finds no extension files. Confirm that the .zip contains the extension directory rather than the loose source files. Repackage the directory if needed.