本文へスキップ

Docs Administration

Deploy with MDM

If you manage Macs with a device management (MDM) tool, such as Jamf Pro, Kandji or Microsoft Intune, you can activate VMPal on them with a license key file. VMPal reads the file when it starts or the file changes, and activates the key on its own. You can also require your organization's key, so that VMPal can't be used without it. And in the License Manager, you can turn off features and choose the version the Macs update to.

License key files and the restrictions below need a version of VMPal for macOS that supports them. Older versions ignore them.

Create the key file

The key file is a plain text file named .vmpallicensekey. Put your license key on the first line:

VP-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
require: true

The require line is optional:

  • require: true: VMPal can't be used until the key is activated, and users can't activate a different key.
  • require: false, or no require line, activates the key, but lets users keep or activate their own license while yours can't be activated.

A few details:

  • You can also write the key as key: VP-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
  • require also accepts yes and no, 1 and 0, or on and off, and require = true works too. Any other value counts as true.
  • Lines that start with # are comments. VMPal ignores fields it doesn't know.
  • A file with only blank lines and comments counts as no file. A file with fields but no key is ignored. The exception is require: true in /Users/Shared: with no key, it still requires one, so VMPal can't be used until the file has a key.
  • Save it as UTF-8 text.

Install the key file

Install the file at /Users/Shared/.vmpallicensekey, owned by root and writable only by root (owner root:wheel, mode 0644). VMPal then activates the key for every user of the Mac, using one seat for the Mac.

Run this script as root, for example as a script in your MDM policy. To activate the key without requiring it, leave out "require: true".

#!/bin/sh
set -eu
KEY="VP-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
KEY_FILE="/Users/Shared/.vmpallicensekey"

# Any user can create files in /Users/Shared: write the file under a new name
# only root can change, then move it over whatever is at KEY_FILE. -h replaces
# a link there instead of following it
TMP_FILE=$(mktemp /Users/Shared/.vmpallicensekey.XXXXXX)
printf '%s\n' "$KEY" "require: true" > "$TMP_FILE"
chown root:wheel "$TMP_FILE"
chmod 0644 "$TMP_FILE"
rm -rf "$KEY_FILE"
mv -fh "$TMP_FILE" "$KEY_FILE"
# Fails if a user made a folder there meanwhile: run the script again
[ -f "$KEY_FILE" ] && [ ! -L "$KEY_FILE" ]

Keep the file owned by root and writable only by root, as the script does. VMPal applies any key file in /Users/Shared, whoever owns it. A user who owns the file can change it or delete it, so a file a user can change lets them get around require. Install the file itself, not a symbolic link: VMPal ignores a symbolic link at /Users/Shared/.vmpallicensekey. A hard link is read like the file itself: another name for the file, anywhere on the Mac, changes nothing.

VMPal saves the activated license next to the key file, in /Users/Shared/.vmpallicense, so every user of the Mac shares it, and no user takes another seat. If you create that file in advance, make it writable by every user (mode 0666). If it exists and a user can't write to it, activation fails with "VMPal couldn't save the license in /Users/Shared." Beside it, VMPal keeps the license owner's last policy, in .vmpallicensepolicy.

You can also install a key file for a single user, at ~/Library/Application Support/com.tableplus.VMPal/.vmpallicensekey. VMPal then keeps that user's license in the same folder. Users can delete files in their own folder, so VMPal ignores require there. A key file in /Users/Shared wins over one in a user's folder.

What users see

VMPal reads the key file at launch, and while it's open, it notices a new or changed key file within about a minute.

With the key file in /Users/Shared What VMPal does
No license Activates your key without asking.
A license the user entered Says "Your organization manages VMPal on this Mac", then activates your key in place of theirs. Their license is removed from the Mac, and its seat is freed.
Already activated with your key Nothing. Settings › License says "VMPal is activated with the license key your admin set up on this Mac" and shows Activated for: All users on this Mac. Deactivate This Mac is hidden.

If your key can't be activated, VMPal says why in "Activate license key ****1234", with the last 4 characters of your key. It offers:

  • Try Again, when VMPal couldn't reach the license server, or the server had a problem.
  • Email License Owner, when all seats are in use or the license's updates have ended. It opens an email to the license's secondary license manager, or to its owner when there's none, with the key's last 4 characters, the reason, the Mac's name, and the macOS and VMPal versions.
  • Download the Old Build, when this version of VMPal was released after the license's updates ended, or Download VMPal, when this build was withdrawn. Both download the newest version the license covers, or the version you chose in Updates.
  • Try Another Key and Use Free Version on a Mac without a license, unless the key is required. OK otherwise.

VMPal shows this alert at most once a launch, and tries your key again later. A user who keeps their own license, without require, keeps it until VMPal activates your key on a later try.

With require: true

  • Until your key is activated, VMPal shows "Activating license key ****1234" before it loads your VMs and the Hub, opens a window, restores its terminal tabs, starts the VMs that start at login, or answers coding agents and vmpal. When VMPal opens at login, it comes into the Dock and bounces until someone looks.
  • If the activation fails, VMPal says why, and offers Try Again, Email License Owner when all seats are in use or updates have ended, Download the Old Build when the version is too new for the license, Download VMPal when this build was withdrawn, and Quit. Quit keeps the terminal tabs VMPal restores for the next launch.
  • VMPal also tries again on its own: every minute after a network or server error, and every 15 minutes otherwise. It reads the key file again every minute, so a fixed key file takes effect within a minute.
  • Users can't activate a different key. Settings › License shows yours, masked, with Activate. A key typed there, or from a vmpal://license/activate link, gets "This Mac can only be activated with your organization's license key ****1234. Contact your admin to change it."
  • VMPal never closes in the middle of a session. If the Mac loses its license while VMPal is open, VMPal tries to activate your key again, and if it can't, says "VMPal can't be opened again until this key is activated." Until the key is activated, running VMs keep running, but no VM starts, vmpal can't use VMPal, and VMPal is blocked from its next launch.
  • If you install or change the key file while VMPal is open, VMPal activates your key within about a minute. Until then, a license VMPal activated from a key file keeps working, VMs included, but on a license a user entered, no VM starts and vmpal can't use VMPal.
  • The first launch needs to reach vmpal.com.

VMs and the command line

Each VM runs in a process of its own, which can start without VMPal's window: from the VM's icon in the Dock, at login for a VM set to Start when you log in, or from vmpal. These processes, and vmpal, read the license files themselves, so they follow the same rules:

  • With require: true, while the Mac doesn't have your key's license, a VM doesn't start. It says "The virtual machine can't start", with Open VMPal, which opens VMPal to activate the key.
  • In the same case, vmpal commands that need VMPal fail at once with "VMPal can't be used until it's activated with your organization's license key ****1234, as device management requires. Open VMPal to activate it."
  • A license VMPal activated from a key file is the exception: while VMPal activates your key in its place, such as after you change the key, VMs still start and vmpal still works on it.
  • The restrictions below apply in each VM too.

Restrict features and updates

In the License Manager, the VMPal for macOS policy section of a license key applies to every Mac activated with that key, with a key file or by hand. The license's owner and its secondary license manager can change it. Open the License Manager with an access link.

Setting What it does on the Macs
Disable coding agents (MCP and agent control) Turns off VMPal's MCP servers, adding VMPal to coding agents, and agent control of every VM. vmpal refuses its commands. Hub scripts that run in VMs are skipped too, because they need agent control
Disable Hub scripts on the Mac Skips the runs of scripts that run on the Mac itself, whether from Run Now or vmpal. Agents and vmpal can't make a script run there. Scripts in VMs still run
Disable crash reports Turns off crash reports from VMPal and from VMs
Disable shared folders and clipboard Turns off shared folders, the shared clipboard, and dragging files into VMs, in every VM
Updates Auto updates the Macs to the newest version the license allows. Choose a version to keep them on it until you change it here

On the Macs, the settings of what you turn off are dimmed, with "Disabled by the license owner. Contact your admin to unlock it." Settings › License lists them under Restrictions. Coding agents and vmpal are told "The license owner turned off coding agents for VMPal on this Mac. Contact your admin to unlock it." Each VM keeps its own settings, and they come back when you turn a feature on again.

Updates lists the version that was current when the license was bought, and the ones after it that the license covers. With a version chosen, VMPal doesn't install a newer one, and doesn't go back to an older one: a Mac already on a newer version stays on it. The update screens and Settings › About say "Updates are approved by the license owner up to build 88." An update VMPal downloaded before you chose a version still installs when VMPal quits. If we withdraw the version you chose, the Macs update as with Auto.

VMPal picks up a change at launch, when it comes to the front (at most once an hour) and, on Macs with a key file, every 6 hours. The change applies at once, in VMPal and in running VMs, except that:

  • Crash reports turned back on start at the next launch of VMPal, or of each VM.
  • Shared folders in a VM with macOS 13 change when the VM starts again.
  • Hub runs already in progress go on. Runs still waiting are skipped.

A Mac that loses its license keeps the last policy for as long as the key file is installed. If you don't see the policy section, ask us to turn it on for your license key.

If your MDM tool installs VMPal updates itself, install only versions your license covers, or the version you chose in Updates. A version released after the license's updates ended can't be activated, and with require: true VMPal is then blocked until an older build is installed.

Change or remove the key

  • Change the key: replace the file, for example with the script above. VMPal activates the new key within about a minute, or at its next launch when it isn't open. The old license keeps working until the new key is activated, VMs included. With require: true, though, the new key is the one required: until it's activated, VMPal's next launch waits for it.
  • Rotate the key in the License Manager: update the key file with the new key too. Macs that are already activated keep working, but a Mac that needs to activate can't use the old key, and with require: true it's blocked.
  • Release a Mac: delete the key file (rm -f /Users/Shared/.vmpallicensekey as root), or empty it. Within about a minute, or at its next launch when it isn't open, VMPal unregisters the Mac, which frees the seat, removes the license and lifts the restrictions. If the Mac can't reach vmpal.com then, the seat stays taken: remove the Mac in the License Manager.

A key file VMPal can't read, such as one with fields but no key, changes nothing.

Troubleshooting

Message What to do
All seats on this license are in use. Remove Macs you no longer use in the License Manager, or add seats.
This license key isn't valid. Check the key in the file, especially after you rotate the key.
This version of VMPal was released after the license's updates ended. Install an older build with Download the Old Build, or renew the license.
This build was removed from the registry. Update VMPal and try again. Install another version with Download VMPal, in the same alert: it downloads the newest version the license covers, or the version you chose in Updates.
VMPal couldn't reach the license server. Check your network connection and try again. Make sure the Mac can reach vmpal.com over HTTPS. VMPal doesn't follow redirects from it.
VMPal couldn't save the license in /Users/Shared. Remove /Users/Shared/.vmpallicense, or make it a file every user can write to (mode 0666), not a link.
VMPal couldn't save the license on this Mac. For a key file in a user's folder, make sure the user can write to ~/Library/Application Support/com.tableplus.VMPal.
VMPal couldn't activate this license key. Try again later, and contact us if it keeps happening.
The virtual machine can't start Open VMPal, which activates your key.

VMPal logs what it ignores in a key file, such as a field it doesn't know or a require value it reads as true. To see it:

log show --last 1d --predicate 'eventMessage CONTAINS "License key file"'

A local administrator can still remove the key file. To keep every Mac on a version that reads key files, manage VMPal updates with your MDM tool.