Launcher - Admin Notes

Last updated 5 months ago

Overview

The desktop application, AYON launcher, is the entry point for artists to work within the AYON system. It should be installed locally on the artist's workstation. This self-contained (frozen) software includes all the necessary dependencies to run.

The AYON launcher connects to the AYON server and distributes addons, dependency packages, third-party binaries like ffmpeg and OIIO and different versions of the AYON Launcher.

Distribution is based on your bundles. For more info, check Bundles & Addons.

Launcher Distribution

Installation

The AYON server distributes the AYON launcher. Artists can log in to the AYON web UI to download the available launcher versions that have been uploaded by administrators, as outlined in the Lanucher Installation section.

Launcher binaries are named as follows:

  • Windows: AYON-1.0.0-win-setup.exe

  • Linux: AYON-1.0.0-linux.tar.gz

  • Mac: AYON-1.0.0-Installer.dmg

The AYON Launcher updates automatically based on your bundles configuration in Bundles & Addons. Every time it is started, it compares the currently launched version against the version in your bundle. If the versions do not match, the launcher will first attempt to launch the correct version. If that version is not found, it will download and install it to ensure consistency.

Upload Launcher Binaries to AYON Server

On the Bundles & Addons Tab, you can upload a new launcher by clicking the Upload Launcher button.

You can find all official launcher builds on the GitHub ayon-launcher releases page, available for direct download. On this page, you can also find the version of the latest released launcher.

Running AYON​

Users can find information about running AYON launcher in Getting Started with AYON Pipeline and Launcher.

AYON Executables​

After installing the AYON Launcher, you’ll find different executables available depending on your operating system.

  • On Windows use ayon.exe or ayon_console.exe .

  • On Linux and Mac OS use ayon .

Example
cd <ayon-launcher-installation-location>
./ayon.exe

OR

cd <ayon-launcher-installation-location>
./ayon_console.exe

Windows:
The executable ayon_console.exe creates a console with output, which is useful for debugging. ayon.exe does not create a console and has no stdout or stderr output.

AYON Executable Arguments

The AYON launcher supports executable arguments, allowing you to work in different pipeline modes or specify which bundle to use.

⬤ Run AYON Launcher in Production Mode

By default, the AYON Launcher runs in Production mode. There’s no need to take any special action. simply run the launcher as usual.

Example
cd <ayon-launcher-installation-location>
./ayon.exe

OR

cd <ayon-launcher-installation-location>
./ayon_console.exe

⬤ Run AYON Launcher in Staging Mode

To run the AYON Launcher in Staging mode, add the --use-staging argument to the AYON executable.

Example
cd <ayon-launcher-installation-location>
./ayon.exe --use-staging

OR

cd <ayon-launcher-installation-location>
./ayon_console.exe --use-staging

⬤ Run AYON Launcher in Development Mode

To run the AYON Launcher in Development mode, add the --use-dev argument to the executable.
For more information about Development mode, see AYON Developer Mode.

Example
cd <ayon-launcher-installation-location>
./ayon.exe --use-dev

OR

cd <ayon-launcher-installation-location>
./ayon_console.exe --use-dev

📦 Override Bundle

To use a different bundle than the one associated with the current pipeline mode, pass the bundle name to the AYON Launcher executable using the --bundle argument. For more details, see How to Use Different Bundles with Different Projects? | Ynput Forums.

Example
cd <ayon-launcher-installation-location>
./ayon.exe --bundle <Bundle Name>

OR

cd <ayon-launcher-installation-location>
./ayon_console.exe --bundle <Bundle Name>

Runtime Environment Variables​

See Launcher Environment Variables for information about environment variables set during startup.

Additional Information​

Site ID​

After installing the AYON launcher, a unique ID is assigned to the machine, usually a funny name like military-mouse-of-jest.

Some addons provides settings per machine (site_id), For more info about settings categories in AYON, see Addon Settings Categories.

Where Site ID is Saved

It's saved in a file called site_id located in the path saved in AYON_LAUNCHER_LOCAL_DIR. By default, based on OS:

  • Windows: %LOCALAPPDATA%\Ynput\AYON

  • Linux: ~/.local/share/AYON

  • macOS: ~/Library/Application Support/AYON

Customize Site ID

You can set site IDs to sensible names, making navigation in site settings easier.
To set a custom site ID, there are two possible solutions:

  • Set an environment variable on the machine, e.g., AYON_SITE_ID=my-cool-machine.

  • Modify the value in the Site ID file.

Giving your farm machines a single site can optimise AYON publish jobs significantly.

However, be cautious not to do this on machines that are not dedicated farm machines, such as artist machines. Also, ensure these machines have the same operating system.

Shims​

Shims are used to register the path to the AYON launcher. Currently, you can only point to a single version, which will stop working if that specific launcher version is uninstalled.

Shims are deployed upon installing the AYON launcher, but you can also deploy them manually using the init-ayon-launcher executable argument. For further information, please see Executable Arguments.

Shims deployment includes the custom ayon-launcher:// protocol scheme, which is required for running actions that can be launched from the Web UI.

Shims are installed in the AYON_LAUNCHER_LOCAL_DIR directory (per user).

FAQ​

Use Shared Location for AYON Launcher and Add-ons​

This is done by leveraging the AYON_LAUNCHER_STORAGE_DIR environment variable.
For a step-by-step guide, see this community guide Use Shared Location for AYON Launcher and Add-ons | Ynput Forums.

For further information about launcher environment variables, see Launcher Environment Variables.

AYON Launcher Versioning Convention​

AYON uses semantic versioning for add-ons and desktop applications, For more details check semvar.org.

For studios customizing the AYON source code, it's practical to build by adding a name and number after the PATCH, rather than deploying with the same version from the original AYON repository. For example, 1.0.0 should become 1.0.0+yourstudio.1.