Desktop Startup

Desktop Startup Framework

Startup logic for the Shotgun Desktop
Latest Version: v1.8.4 (prod)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-framework-desktopstartup

Please Note: This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations User Guide for more details.
Overview Summary
                  Locking-down the startup logic
                        Download a specific release from GitHub
                        Configure the Shotgun Desktop to use a specific copy
                        Reverting to the old behaviour
Installation, Updates and Development
Configuration Options
Release Notes History

Upgradable startup logic for the Shotgun Desktop. This is a system framework that is being auto-downloaded by the Shotgun desktop at startup, containing all the bootstrap logic that it needs in order to initialize itself.


The Desktop Startup framework implements the startup logic of the Shotgun Desktop. Its main function is to:

  1. initialize the browser integration
  2. log the user in
  3. download Toolkit
  4. configure the site configuration
  5. auto update itself and the site configuration when necessary
  6. launch the tk-desktop engine.

This is an internal Toolkit framework and therefore the interface it implements is subject to change. We advise that you do not use this framework in your projects.

Locking-down the startup logic

Note, this requires the Shotgun Desktop app version 1.3.4. If you are unsure of your application version, launch the Shotgun Desktop. Once you are logged in, click on the user icon at the bottom right and click About.... The App Version should be 1.3.4 or greater.

By default, Shotgun Desktop downloads tk-framework-desktopstartup updates locally on the user's machine and uses it during the launch sequence of the application. When you launch the application, Toolkit automatically checks for updates to the framework. If an update is available, it will also download and install it automatically.

Alternately, you can configure the Shotgun Desktop to use a specific copy of the framework instead of using the local copy. This will disable the auto-update function and you will now be responsible for updating your the startup logic. In order to be kept up to date with updates, we suggest you subscribe to this page.

Download a specific release from GitHub

You will need to download updates from GitHub manually. The bundles can easily be downloaded from the Releases page and you can find more information about each official release here.

Configure the Shotgun Desktop to use a specific copy

The only way to lock down the startup logic is to use an environment variable. By setting SGTK_DESKTOP_STARTUP_LOCATION to the root folder of a copy of the framework, you will tell the Shotgun Desktop to use this copy of the code when starting up. Once the variable is set, you can launch the Shotgun Desktop and it will use this specific copy of the startup logic.

Note that as of this writing the Startup Version field in the About... box will be Undefined when locking the startup logic due to a technical limitation.

Reverting to the old behaviour

To revert back your changes, simply unset the environment variable and launch the Shotgun Desktop.

Installation and Updates

Updating to the latest version

If you already have this item installed in a project and you want to get the latest version, you can run the update command. You can either navigate to the tank command that comes with that specific project, and run it there:

> cd /my_tank_configs/project_xyz
> ./tank updates

Alternatively, you can run your studio tank command and specify the project name to tell it which project to run the update check for:

> tank Project XYZ updates

Collaboration and Evolution

If you have access to the Shotgun Pipeline Toolkit, you also have access to the source code for all apps, engines and frameworks in Github where we store and manage them. Feel free to evolve these items; use them as a base for further independent development, make changes (and submit pull requests back to us!) or simply tinker with them to see how they have been built and how the toolkit works. You can access this code repository at

Special Requirements

  • You need Shotgun Pipeline Toolkit Core API version v0.16.0 or higher to use this.


No Configuration Needed!

This item does not have any options to configure!

Release Notes

Welcome to the release notes for this Framework. Below you will find an overview of all the changes we did for each release. We try to be as detailed as possible and include all bugs we have fixed, features we have added and things that may have changed. If you have questions about a particular release, don't hesitate to contact our support team!



Zipped configurations will now pull their core from the zip file, if included.



This fixes an issue with file name length when using uploaded configurations on Windows.



Fixes an issue that prevents Shotgun Desktop from launching a site configuration using a core released between v0.16.0 and v0.18.0



Login dialog now shows the most recent users and sites.



Introduces support for single-sign on with Shotgun.



Global debug logging is now restored prior to core swap.


This is resolving an issue that arises when the tk-core version in the site config is older than v0.18.117. In that case, when the global debug is toggled on in desktopstartup, TK_DEBUG is set in the environment. If it is toggled off after the core swap, that environment variable isn't purged since the older tk-core doesn't know to do that. We end up in a situation where TK_DEBUG persists, resulting in any subprocesses spawned running in debug logging active when it wasn't asked for.

Instead, we now restore the global debug setting prior to core swap, which ensures that the same version of tk-core is used both to set and restore global debug.



Updates embedded core version to 0.18.120



Bumps core version to v0.18.117



Better URL filtering and cleanup on login screen.



Better URL filtering and cleanup on login screen.



Fixes an issue when reporting errors when Shotgun Desktop starts.



Bundles v0.18.98 of tk-core, which makes the bootstrap process resilient to bundle download errors.



Toolkit now detects cached configuration that weren't written completely on disk and fixes them.



This fix prevents a crash when trying to update the Shotgun Desktop when the app store credentials are invalid.



This fixes an issue where the incorrect path to the Shotgun Desktop's python interpreter would be written to the interpreter_*.yml files if it is not installed at the default location.



This release introduces support for Shotgun Integrations.


Click here to learn more about Shotgun Integrations.



Fixes AppStore connectivity issues when updating the Shotgun Desktop.



This release fixes a certificate issue with Chrome 58+ on all platforms.


Please visit our support page to learn more about this issue and how to update your Shotgun Desktop installation.



Fixes an issue on startup with CentOS if QT_PLUGIN_PATH is set.



Toolkit App Store credentials issues are better handled.



Fixes a crashing bug in Linux on startup when the ~/.pki/nssdb folder doesn't exist or that location has no database.



Placeholder text is displayed when the text box is selected in the login dialog.



Fixes an issue where unexpected errors during startup are not reported correctly to the user.



Updates Shotgun Desktop to support the new toolkit.ini file.


Toolkit.ini is a new global file that can be read not only by the Shotgun Desktop but also by any Toolkit based applications. You can read more about this configuration file here.



Fixes a crash introduced by trailing whitespaces in user login.



Fixed error reporting when the Shotgun Desktop failed at configuring Toolkit.



App Store specific proxy setting.


Following release v0.17.14 of core, this integrates App Store specific proxy setting for the Shotgun Desktop. It also adds a new setting called app_store_http_proxy to config.ini. This setting is used when creating the site configuration to instruct the new configuration how to connect to the App Store.



handle Toolkit App Store connection timeout exception


Better handling for when the Shotgun API connection times out while connecting to the Toolkit App Store. For cases where internet access is blocked, this ensures that SG Desktop will abort the auto-update of the startup framework within a reasonable amount of time and continue loading without error.



handle Toolkit App Store connection timeout exception


Better handling for when the Shotgun API connection times out while connecting to the Toolkit App Store.



Upgrades to core v0.17.6 which adds case insensitive username comparison.



Support @ in proxy authentication passwords.



Browser integration now supports OSX 10.7.



Startup does not log proxy settings anymore.


Due to security concerns, the framework is not logging out the proxy settings anymore during startup.



An expired session on startup is now considered as not logged in.


Having TANK_PRESERVE_YAML set does not prevent the Desktop from upgrading anymore.


Better support for network paths in the file dialog.


For MacOS, we've added a link to the /Volumes folder in the dialog's sidebar so mounted shares can be accessed. For all platforms, you can now edit the box at the top of the dialog to specify any path, including UNC paths on Windows.


Logging actions from the browser integration in a secure way.


Debug option

The browser integration had a flag named debug which has been renamed to low_level_debug. The documentation for this flag has been updated to make it clear that Twisted might log sensitive information like passwords and such to disk. Therefore, it shouldn't be used in a production environment.

Logging command line parameters

Command line parameters are no longer logged to disk when an application fails. This is done in order to avoid logging sensitive information.


Fixes an issue where hitting Command-Q on MacOSX on the login screen makes the app unresponsive.


Fixes a connection error and certificate generation issues.


  • Better handling of errors when generating certificates.
  • Better handling of errors when connecting to the app store to download the update to the Desktop Startup framework.


Change tray icon to fit in OSX Dark mode.


Enhanced tray-based workflow for people not using Toolkit and simpler configuration.


Tray-based workflow

The Shotgun Desktop now always starts by running in the tray if there is no currently logged in user. Tray messages inform the user that the browser integration is running in the background and the user can sign in at anytime by clicking on the Shotgun icon.


The Shotgun Desktop's configuration file (config.ini) can now reside in the user folder at

Windows: %APPDATA%\Shotgun\desktop\config\config.ini
MacOSX: ~/Library/Caches/Shotgun/desktop/config/config.ini
Linux: .shotgun/desktop/config/config.ini

This avoids having to update the installation directory. You can also use an environment variable, SGTK_DESKTOP_CONFIG_LOCATION to point to a config.ini file anywhere on your computer or your network. The Shotgun Desktop will evaluate these in the following order:

  1. Look in the user directory.
  2. Look if the environment variable exists.
  3. Look if the file is present in the installation folder.


Fixes TK_SITE_CONFIG_ROOT behavior.


Adds support for TK_SITE_CONFIG_ROOT environment variable.


Cleaner error handling when connecting to during the tk-framework-desktopstartup update.


Fixes an issue on Windows where port 9000 might still be in use after closing the Shotgun Desktop.


Fixes an issue on Windows with paths that are too long in the roaming directory.


Fixes issues with the Shotgun Desktop and proxy servers.


Updated to launch commands from the websocket server in a cleaner environment.


This fixes the issue where applications like Maya or Nuke that were launched from Toolkit would report errors about the wrong path to the pipeline configuration being used.


Update the startup to continue even if there was an error during websocket startup.


Adds support for answering websocket queries from the Shotgun web interface.


Fixes an issue with old versions of the desktop engine and the newer Shotgun Desktop application (v1.1+).


The new Shotgun Desktop application (v1.1+) and the new login based authentication module are not supported by the old desktop engine. This new version of the startup logic validates that the right version of the engine is found.

This issue can only be encountered when the site configuration is locked to a pre-2.0.0 version of the tk-desktop engine and is not upgraded after installing the Shotgun Desktop application v1.1+. Users of the Shotgun Desktop who are running in auto-update mode will never encounter this issue.


Supports Shotgun Desktop migration away from the Template Project.


This release allows the Shotgun Desktop to update a site configuration so that it doesn't depend on the Template Project anymore. In order to migrate away from the Template Project, type tank migrate_desktop (introduced in core v0.16.8) to remove Shotgun Desktop dependency on the Template Project. Then, all users who launch the Shotgun Desktop will migrate their local site configuration automatically. If the site configuration was shared on the network, then the migration will already have been taken care of by the migrate_desktopcommand.


This releases adds Two-Factor authentication support.


Two-Factor authentication needs to be activated on your site first.


Removes dependency on the Template Project for the site configuration.


This release removes the need to have the Template Project to launch Shotgun Desktop. It is backwards compatible with existing site configurations. New site configurations will however be configured using a Pipeline Configuration not associated to a Shotgun project. Note: Due to the recent permissions changes on Shotgun, if you wish to keep using the Template Project configuration with artists users, you will need to assign them to the Template Project.


Better backward compatibility with script based authentication.


  • The app now runs as a script user whenever possible.
  • Bundles core v0.16.3


Initial release of the framework.


This framework allows to initialize the site configuration and launch the tk-desktop engine.



Please sign in to leave a comment.