Customize Tailscale using system policies

System policies are currently in private alpha. Therefore, this topic is currently hidden.

This page contains a list of policies observed by the Tailscale client. You might find these policies useful if you are a system administrator deploying Tailscale in a corporate environment, using a solution like MDM.

Setting these policies can improve the user experience for your users. For instance, you can hide UI items that might be confusing to less tech-savvy individuals in your organization. You can also enforce settings to improve your security posture.

If you need help using any of the settings listed in this document, or would like to suggest any new policies, contact our support or sales teams.

How to apply system policies

While many of the configuration keys listed on this page are shared between platforms, different steps are required to configure these policies on each.

Windows

The Tailscale client for Windows reads and applies system policies stored in the Windows registry.

For more information, refer to the platform-specific documentation for Windows.

macOS / iOS / tvOS

The Tailscale clients for macOS, iOS, and tvOS read and apply system policies stored in the user defaults. You can impose these policies by deploying a configuration profile using MDM solutions like Jamf or Kandji. If you are not using server-based MDM, you can also use install a configuration profile using Apple Configurator.

For more information, refer to the platform-specific documentation for macOS/iOS/tvOS.

Available system policies

The following is a list of the system policies observed by the Tailscale clients.

Change the visibility of UI items

The AdminConsole policy can be used to show or hide the Admin Console item in the Tailscale menu.

Supported platforms: Windows
Possible values: show, hide
Added in Tailscale: 1.50

Hide the exit node picker

The ExitNodesPicker policy can be used to show or hide all UI items to choose an exit node in the Tailscale client.

Supported platforms: Windows, macOS, iOS
Possible values: show, hide
Added in Tailscale: 1.50

Hide network devices

The HiddenNetworkDevices policy can be used to hides one or more categories of network devices normally displayed in the Tailscale client. Administrators can choose to hide:

devices owned by the current user
devices owned by other users
tagged devices

If all three options are chosen, the Network Devices menu item disappears entirely and users aren’t able to see any device on the tailnet.

Supported platforms: macOS, iOS
Possible values: String Array. Use one or more of: current-user, other-users, tagged-devices.
Added in Tailscale: 1.52

Hide the tailnet lock settings

The ManageTailnetLock policy can be used to show or hide the Manage Tailnet lock menu item.

Supported platforms: macOS, iOS
Possible values: show, hide
Added in Tailscale: 1.50

The NetworkDevices policy can be used to show or hide the Network Devices menu item from the Tailscale client.

Deprecated: prefer using “HiddenNetworkDevices” instead, which works on other platforms too.
Supported platforms: Windows
Possible values: show, hide
Added in Tailscale: 1.50

The PreferencesMenu policy can be used to show or hide the Preferences menu item from the Tailscale client.

Supported platforms: Windows
Possible values: show, hide
Added in Tailscale: 1.50

The ResetToDefaults policy can be used to show or hide the Reset to Defaults menu item in the Tailscale client.

Supported platforms: macOS
Possible values: show, hide
Added in Tailscale: 1.50

The RunExitNode policy can be used to show or hide the Run as Exit Node menu item.

Supported platforms: macOS, tvOS, Windows
Possible values: show, hide
Added in Tailscale: 1.50

The StartOnLoginMenuItem policy can be used to show or hide the Start on Login menu item.

Supported platforms: macOS
Possible values: show, hide
Added in Tailscale: 1.50

The TestMenu policy can be used to show or hide the debug menu in the Tailscale client. On macOS, this system policy will also hide any information displayed when holding down the Option key while clicking on the Tailscale menubar item.

Supported platforms: Windows, macOS
Possible values: show, hide
Added in Tailscale: 1.50

The UpdateMenu policy can be used to show or hide the Update Tailscale menu option.

Supported platforms: Windows
Possible values: show, hide
Added in Tailscale: 1.50

The VPNOnDemandSettings policy can be used to show or hide the VPN On-Demand menu item. You might want to use this setting if you’re deploying your own VPN configuration profile for Tailscale, and you don’t want your users to interact with the on-demand VPN configuration you set up for them.

Supported platforms: iOS
Possible values: show, hide
Added in Tailscale: 1.52

Show contact information for your organization

Set your organization name

Use the ManagedByOrganizationName policy to specify the name of the organization managing Tailscale, for instance “XYZ Corp, Inc.”.

The value will be displayed in the Tailscale client, so that users can easily reach your internal support resources.

Supported platforms: macOS, iOS
Possible values: any String
Added in Tailscale: 1.52

Set an info message

Use the ManagedByCaption policy to specify a caption to be displayed in the Managed By view in the Tailscale client. Use this string value to provide your users with information on how to reach support resources for Tailscale in your organization.

Supported platforms: macOS, iOS
Possible values: any String
Added in Tailscale: 1.52

Set a support URL

Use the ManagedByURL policy to specify a URL pointing to a help desk webpage, or other helpful resources for users in the organization. Clicking the Support button in the Tailscale UI will open this webpage.

Supported platforms: macOS, iOS
Possible values: a valid URL
Added in Tailscale: 1.52

Configure the auto-update settings

Check for updates automatically

This system policy exclusively applies to the Standalone variant of Tailscale for macOS. When you download Tailscale from the Mac App Store, the system automatically updates it for you, provided that automatic app updates are enabled.

If you are using the Standalone version of Tailscale for macOS, the client will periodically check for updates automatically and notify the user that a new version is available, using the Sparkle framework. We recommend that you leave this feature on, in order to ensure your users receive any security updates in a timely manner.

However, you might prefer to manually deploy updates and disable notifications of new available versions. To do so, use the boolean policy with key SUEnableAutomaticChecks. When it is set to true, the standalone variant of Tailscale for macOS will automatically check for updates. Set this value to false to disable automatically checking for updates.

Supported platforms: macOS (Standalone variant only)
Possible values: Boolean
Added in Tailscale: 1.46

Install updates automatically

If you are using the Standalone version of Tailscale for macOS, the client can also install updates automatically. This feature also relies on the Sparkle framework. We recommend that you always turn this feature on, in order to ensure your users receive any security updates in a timely manner.

However, if you manually manage updates, or prefer your users to be notified but to manually update, you can disable the automatic installation. To do so, use the boolean policy with key SUAutomaticallyUpdate. When it is set to false, the standalone variant of Tailscale for macOS will require user input before updates are installed.

Supported platforms: macOS (Standalone variant only)
Possible values: Boolean
Added in Tailscale: 1.52

Hide the auto-update settings

If you do not want to allow the user to turn the automatic installation of updates on or off, you can use the ApplyUpdates policy. When this setting is set to hide, the Automatically install updates menu item won’t be shown to the user, and the user won’t be able to configure automatic updates.

Supported platforms: macOS (Standalone variant only)
Possible values: show, hide
Added in Tailscale: 1.52

Other settings

Automatically start Tailscale when the user logs in

The first time the application is opened on a Mac, Tailscale installs a macOS login helper. This allows Tailscale to start automatically when the user logs into their account. The TailscaleStartOnLogin boolean policy controls whether the login helper should start Tailscale at login time.

Supported platforms: macOS
Possible values: Boolean
Added in Tailscale: 1.46

Force Tailscale to always be running

When set to true, the ForceEnabled boolean policy instructs Tailscale to always be connected and actively monitor the tunnel state for disconnections. The Disconnect toggle will be disabled, to prevent users from disabling the VPN themselves. An attempt to disconnect will present a banner informing the user the organization’s policy prevents Tailscale from being disconnected. If the client detects the VPN tunnel is down because the Tailscale VPN process was terminated, Tailscale will automatically restart it and reconnect.

This policy should always be used together with an always-on VPN configuration profile (available on supervised iOS devices). You might also want to set VPNOnDemandSettings to hide, to prevent the user from interacting with your on-demand VPN configuration.

Supported platforms: macOS, iOS
Possible values: Boolean
Added in Tailscale: 1.52

Set a custom control server URL

The LoginURL policy can be used to specify a custom control server URL. This should not be changed unless you are not using the standard Tailscale server. Use this policy if you’re deploying your own server, such as Headscale.

Supported platforms: Windows, macOS, iOS, tvOS
Possible values: https://controlplane.tailscale.com or another Tailscale server instance
Added in Tailscale: 1.4 (Windows), 1.38.1 (macOS, iOS)
The now-deprecated key ControlURL was used in early versions of Tailscale for macOS and iOS

Set a machine certificate subject

The MachineCertificateSubject policy enables signed registration requests with an externally-provisioned machine certificate. This policy is only applicable to particular enterprise customers and they receive further documentation on how to correctly configure this option.

Supported platforms: Windows
Possible values: consult customer-specific documentation
Added in Tailscale: 1.52

Set a suggested or required tailnet

The Tailnet policy allows the organization to specify a tailnet, its identity provider will be used on the login page. If the policy value is prefixed with required:, Tailscale will force that identity provider to be used and won’t allow logging in with anything else.

Supported platforms: Windows, macOS, iOS, tvOS
Possible values: a tailnet name, for example: example.com or required:example.com
Added in Tailscale: 1.52

Set the key expiration notice period

The KeyExpirationNotice policy controls how long before key expiry should a notice be displayed. The default is 24 hours.

Supported platforms: Windows
Possible values: Go-style Duration, for example 24h or 5h25m30s
Added in Tailscale: 1.50

Set unattended mode

The UnattendedMode policy sets the Unattended Mode option.

Supported platforms: Windows
Possible values: always, never, user-decides
Added in Tailscale: 1.52

Suppress IP Address Copied notifications

When you use the Tailscale menu bar item to copy to the Clipboard the IP address of a device, a notification displaying the IP address is presented. The IPAddressCopiedAlertSuppressed policy can be used to suppress this Copied IP address to clipboard notification.

Supported platforms: macOS
Possible values: Boolean
Added in Tailscale: 1.50

Suppress the first launch onboarding flow

When you start Tailscale on your Mac for the first time, an onboarding flow is presented. It explains the Tailscale privacy policy, and guides the user in setting up the VPN configuration on their Mac. You might want to disable this onboarding flow if you are going to automatically set up the VPN configuration on the system by using a configuration profile. In order to do so, the TailscaleOnboardingSeen boolean policy suppresses the onboarding flow when Tailscale launches for the first time and the value is set to true.

Supported platforms: macOS
Possible values: Boolean
Added in Tailscale: 1.46