Apply License in an Air-Gapped Workspace

Air-gapped workspaces require an offline license to unlock premium features in Rocket.Chat. This guide walks you through obtaining a premium plan license and applying it to your workspace.

Key considerations
Version compatibility: Offline licenses are valid for Rocket.Chat versions within the standard support window covered by the license. If your organization requires extended support for a specific version, contact the Sales team for an updated license.
Starter workspace limits: Workspaces running on a Starter license in air-gapped environments enter read-only mode after 90 days without online validation. To avoid service disruption, manually renew the license every 90 days or upgrade to a premium plan to continue offline.
Community Workspaces (v7.0+): Air-gapped Community workspaces operate in read-only mode by default. You must upgrade to Starter or higher to enable air-gapped functionality.

Hash your workspace URL for privacy (optional)

If you cannot share your actual workspace URL with Rocket.Chat Sales for privacy reasons, you can provide a SHA-256 hash instead. This hash is non-reversible, meaning Rocket.Chat cannot recover or view your original domain.

Tip: Since Rocket.Chat 8.6, your workspace calculates this hash for you. Go to Manage > Workspace and check the Hashed Site URL field. Copy that value and share it with Sales instead of generating the hash manually. If you're on an earlier version, or prefer to generate the hash yourself, follow the steps below.

To generate the hash value for your workspace URL,

Copy the exact URL used to access your workspace.
Remove http:// or https:// from the workspace URL.
Follow the instructions for your operating system below.

Mac/Linux

Windows

Other OS

If you are using a Linux or Mac terminal, run the following command:

Linux: echo -n "your-workspace-url" | sha256sum
Mac: echo -n "your-workspace-url" | shasum -a 256

You should see an output like this: 176523d046360a9180a9a3ca0af17d30e1edebc0148440e921af184166ad4c8b.

If you are using Windows, open Powershell and run the following command:

$domain = "your-workspace-url"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($domain)
$sha256 = [System.Security.Cryptography.SHA256]::Create()
$hashBytes = $sha256.ComputeHash($bytes)
$hashString = [BitConverter]::ToString($hashBytes) -replace "-", ""
$hashString.ToLower()

If you are using other OS:

Use an external tool to generate the hash value of the workspace URL, such as SHA256.
Enter your workspace URL in the input section.
The hash value is displayed in the output section. For example, 82671fa26911cdd7b6855ccdcbdf3392bbf1c554c9a0d5fffdb5ff7cde6e49b6.

Always hash the exact URL used to access your workspace in the browser. For example, if you access it via example.rocket.chat:3000, hash that exact address.
Run the command more than once to confirm the same hash output each time.

Step 1: Get premium license for your workspace

Once you have your domain or hashed identifier:

Paid plans: Contact Rocket.Chat Sales with your raw or hashed workspace URL to get your license token.
Community to Starter upgrade:
- Log in to the Rocket.Chat Cloud portal and select the Workspaces tab.
- Click the kebab menu against the Community workspace that you want to upgrade.
- Select Upgrade to Starter.
- Select the upgraded workspace. The workspace details page opens.
- Click the Get License button from the Rocket.Chat License section.
- An Apply Offline License pop-up opens. Copy the License Code.

Step 2: Apply the license in an air-gapped workspace

After you receive the offline license token, apply it using one of the following methods.

Rocket.Chat 8.7 or later: Apply the license from the workspace administration UI.
Below Rocket.Chat 8.7 or using a hashed workspace URL: Use the deployment environmental variable.

Option 1: Apply license via the workspace admin UI

Navigate to Manage > Workspace > Subscription.
Click Manage license from the plan details card.
Apply your license using one of the following methods:
1. Paste key: Paste your raw license key directly into the License key field.
2. Upload file: Drag and drop your .txt license file, or click Upload license file to select it. Rocket.Chat checks whether the file name matches your workspace's raw or hashed URL and flags a mismatch before you apply the key.
Wait for real-time validation. Rocket.Chat automatically verifies the license key against your workspace instance.
Once the license passes validation, click Apply license.
Click Sync license update at the top right of the page to refresh your workspace capabilities immediately.
To remove an applied license key, go to Manage > Workspace > Subscription, click Manage license, and select Remove license. Your workspace reverts to community plan once the key is removed.

Note: An invalid license key is rejected during validation and never applied. Your workspace keeps its current plan and an invalid key no longer downgrades or disrupts your existing subscription.

Option 2: Apply license via deployment environmental variable

In your .env file, add the license key:
```
ROCKETCHAT_LICENSE=<license-key>
```
Replace <license-key> with the token provided by the Sales team.

Restart your Rocket.Chat container to apply the license:

docker compose stop rocketchat
docker compose rm rocketchat
docker compose up -d rocketchat

Refresh your workspace URL and verify the new plan upgrade in Manage > Workspace > Subscription .

Now that you've upgraded your workspace plan, you can explore the additional benefits Rocket.Chat offers on your workspace. In the next section, you’ll explore additional configuration options your air-gapped workspace.