Tampermonkey® by Jan Biniok

Table of Contents

Overview

This document describes how to deploy Tampermonkey in a managed environment. It covers both installing the extension and centrally provisioning scripts and settings using managed browser policies.

The deployment approach is supported by:

  • Chromium-based browsers (Chrome, Chromium, Edge, Brave, etc.)
  • Firefox (desktop, non-mobile)

The configuration itself is provided as a JSON export from a preconfigured Tampermonkey installation and fetched by managed Tampermonkey instances at startup. This requires version 5.5+ or 5.5.6235+ (BETA).

Deployment consists of three steps:

  1. Install Tampermonkey via browser policy (force-installed)
  2. Host a provisioning JSON file (exported from Tampermonkey)
  3. Configure browser policies so Tampermonkey imports that JSON via managed storage

The provisioning file can include:

  • Userscripts
  • Script storage
  • Tampermonkey settings
  • External script resources

Creating the Provisioning JSON

Tampermonkey provides a built-in export mechanism.

Export Steps

  1. Open Tampermonkey
  2. Dashboard → Utilities
  3. Enable:
    • Include script storage
    • Include Tampermonkey settings
    • Include external script resources
  4. In the File section, click Export

The resulting file (for example tm.json) is the provisioning source used by the browsers.

Example tm.json

{
  "version": "1",
  "scripts": [
    {
      "name": "Log location",
      "enabled": true,
      "position": 1,
      "uuid": "4190fc63-64c8-4c68-9a7c-96f41f85729a",
      "source": "Ly8gPT1Vc2VyU2NyaXB0PT0KLy8gQG5[...]sb2cobG9jYXRpb24uaHJlZik7"
    }
  ],
  "settings": {
    "configMode": 100,
    "logLevel": 80
  }
}

Host this file on an internal web server, for example:

php -S localhost:12121 -t .

In production mode – Use a real web server (Apache, Nginx, IIS, …) that serves the file over HTTPS with a valid certificate.

Hash Handling

Each provisioning entry requires a content hash to guarantee integrity. If the hash does not match, Tampermonkey logs an error similar to:

Error: Hash mismatch for provisioning jsonImport from http://localhost:12121/tm.json:
    expected 1:abcd... !== calculated 1:ef01...

The correct hash is shown in the error output (calculated …). Copy that value into the policy configuration. A dedicated hash helper tool is planned.

Managed Storage Schema

Tampermonkey reads its managed configuration from the browser. Relevant schema excerpt:

{
  "jsonImport": [
    {
      "hash": "1:…",
      "url": "https://example.com/tm.json",
      "haltOnError": true,
      "installAsSystemScripts": false
    }
  ]
}

Fields

  • hash (required): integrity hash of the JSON file
  • url (required): HTTPS or HTTP URL to the JSON file
  • haltOnError: abort provisioning on error (Tampermonkey will not start at all in case of an error)
  • installAsSystemScripts: install scripts as system scripts (default: true)

Extension IDs

See Q406 in the FAQ for Tampermonkey's extension IDs.

Firefox Deployment

Firefox supports managed extension configuration via policies.json.

Policies can be inspected at:

  • about:policies

Linux (system-wide)

/etc/firefox/policies/policies.json

{
  "policies": {
    "Extensions": {
      "Install": [
        "https://www.tampermonkey.net/xpi/firefox-current-beta.xpi"
      ]
    },
    "3rdparty": {
      "Extensions": {
        "firefoxbeta@tampermonkey.net": {
          "jsonImport": [
            {
              "hash": "1:66849534c66c5bd384f39f7fb5c7c5bdbc8611bfedab082762cb943f853637d0",
              "url": "http://localhost:12121/tm.json",
              "haltOnError": true,
              "installAsSystemScripts": false
            }
          ]
        }
      }
    }
  }
}

Windows

  • Place policies.json in the distribution directory next to firefox.exe

    Find the Firefox install directory (commonly):

    C:\Program Files\Mozilla Firefox\

    Create:

    C:\Program Files\Mozilla Firefox\distribution\

    Put this file here:

    C:\Program Files\Mozilla Firefox\distribution\policies.json

  • Alternatively deploy via GPO or Intune

macOS

  • Place policies.json in the distribution directory

    Find and edit:

    Firefox.app/Contents/Resources/distribution/policies.json

  • Or deploy via configuration profiles / MDM

Mozilla policy documentation:

Chromium-Based Browsers

Policies can be inspected at:

  • chrome://policy/
  • edge://policy/

Linux

/etc/opt/chrome/policies/managed/tampermonkey.json

{
  "ExtensionInstallForcelist": [
    "gcalenpjmijncebpfijmoaglllgpjagf"
  ],
  "3rdparty": {
    "extensions": {
      "gcalenpjmijncebpfijmoaglllgpjagf": {
        "jsonImport": [
          {
            "hash": "1:66849534c66c5bd384f39f7fb5c7c5bdbc8611bfedab082762cb943f853637d0",
            "url": "http://localhost:12121/tm.json",
            "haltOnError": true,
            "installAsSystemScripts": false
          }
        ]
      }
    }
  }
}

Windows

Create a .reg file (e.g. tampermonkey_provision.reg) and import it with reg import as an administrator:

Windows Registry Editor Version 5.00

; Force‑install Tampermonkey (if not already installed)
[HKEY_LOCAL_MACHINE\Software\Policies\Google\Chrome\ExtensionInstallForcelist]
"1"="gcalenpjmijncebpfijmoaglllgpjagf"

; 3rd‑party policy for the extension
[HKEY_LOCAL_MACHINE\Software\Policies\Google\Chrome\3rdparty\extensions\gcalenpjmijncebpfijmoaglllgpjagf\jsonImport\1]
"hash"="1:66849534c66c5bd384f39f7fb5c7c5bdbc8611bfedab082762cb943f853637d0"
"url"="http://localhost:12121/tm.json"
"haltOnError"=dword:00000001
"installAsSystemScripts"=dword:00000000
  • Deploy via Group Policy or MDM

macOS

  • Deploy via MCX using .mobileconfig or .plist

Chromium documentation:

Imprint Privacy Policy
▲