Skip to main content

Running AYON desktop launcher


To use AYON on a workstation, simply run the ayon executable that was installed.


Make sure to use the AYON executable and not OpenPype's.

On the first run, the user will be prompted for the AYON Server URL and credentials. This information needs to be provided by the admin who set up AYON in the studio.


Once the artist logs in, they will receive an API token, which AYON will remember for the next launch until the token expires. From that moment, AYON will do its best to always keep up-to-date with the latest updates.

If the launch is successful, the artist should see a green AYON logo in their tray menu.


On Windows, this icon might be hidden by default. In this case, the artist can simply drag the icon down to the tray.

Launch checks

When you run the AYON executable, a few checks are made.

Check for AYON Server URL

The server URL should start with https:// or http://.

When you start AYON for the first time, the login UI will show up to ask you for the server URL and credentials. It will then save it securely to your system's keyring - on Windows, it is Credential Manager, on macOS, it will use its Keychain, on Linux, it can be GNOME Keyring or other software, depending on your distribution.

This can also be set beforehand with the environment variable AYON_SERVER_URL. If set, it takes precedence over the one set in the keyring.

Check for AYON Add-ons Updates

When a connection to the server is made, AYON will get various information from the server - one among them is updates of add-ons. If add-ons are missing or outdated, the right versions are downloaded, validated, and extracted to the artist workstation.

Runtime provided environment variables

AYON provides the following environment variables for its subprocesses that can be used in various places, like scripting, etc.


Some of OpenPype environment variables don't have an AYON variant yet. They will be replaced and removed over time.

  • USE_AYON_SERVER - AYON mode is enabled.
  • AYON_VERSION - String of the current desktop application version, like 1.0.0.
  • AYON_ROOT - Path to the root of the desktop application.
  • AYON_EXECUTABLE - Path to the executable used to run AYON subprocesses - points to the python executable in the virtual environment when run from sources. If run from frozen code, it will point to either ayon (or ayon_console on windows).
  • AYON_HEADLESS_MODE - Headless mode is enabled ("1").
  • AYON_LOG_LEVEL - Logging level for AYON logger.
  • AYON_DEBUG - Debug mode enabled (affecting logs).
  • AYON_USE_STAGING - Staging mode is enabled ("1").
  • AYON_BUNDLE_NAME - Bundle name that is used.
  • OPENPYPE_HEADLESS_MODE - Variable leading to same value as AYON_HEADLESS_MODE.
  • OPENPYPE_USE_STAGING - Variable leading to same value as AYON_USE_STAGING.
  • OPENPYPE_LOG_LEVEL - Variable leading to same value as AYON_LOG_LEVEL.
  • OPENPYPE_DEBUG - Variable leading to same value as AYON_DEBUG.
  • OPENPYPE_VERSION - Variable leading to same value as AYON_VERSION.
  • OPENPYPE_EXECUTABLE - Variable leading to same value as AYON_EXECUTABLE.
  • OPENPYPE_ROOT - Variable leading to same path as AYON_ROOT.
  • OPENPYPE_REPOS_ROOT - Variable leading to same path as AYON_ROOT.


Desktop can be launched with various arguments to change how behaves or what is launched. The command arguments are defined by addons. The source of main command line handling is, ATM, openpype addon.

It is possible to run python scripts when passed as positional argument ayon

Common Arguments

These arguments apply to whole AYON process.

--headless - to run AYON without graphical UI (useful on server or on automated tasks, etc.).

--use-staging - to use staging versions of AYON.

--verbose <level> - change the log verbose level of AYON loggers.

--skip-bootstrap - bootstrap is skipped (no updates and addons/dependency packages are not available).

Level value can be integer in range 0-50 or one of enum strings "notset" (0), "debug" (10), "info" (20), "warning" (30), "error" (40), "critical" (50). Value is stored to AYON_LOG_LEVEL environment variable for next processes.

ayon --verbose debug

--debug - set the debug flag, which affects logging.

Enable debug flag for AYON process. Change value of environment variable AYON_DEBUG to "1". At this moment affects only AYON loggers. Argument --verbose or environment variable AYON_LOG_LEVEL are used in preference to affect log level.

ayon --debug

--use-staging - to specify you prefer staging version. In that case it will be used instead of production one.


Staging feature is not yet available. Only production addon versions will be used now.

OpenPype addon Commands

contextselectionOpen Context selection dialog.📑
moduleRun command line arguments of addons/modules.
trayLaunch AYON Tray.📑
publishAYON takes JSON from the provided path and uses it to publish data in it.📑
extractenvironmentsExtract environment variables for the entered context to a JSON file.📑
runExecute the given Python script within AYON environment.📑
interactiveStart Python-like interactive console session.

tray Arguments

ayon tray

contextselection Arguments

output_json_pathPath to a JSON file where the output will be stored.
--projectPre-define project context. The project cannot be changed when passed.
--assetPre-define folder (asset) in the project. The project must be passed.
--strictThe full context must be set, or the dialog cannot be confirmed.

Example output:

"project": "OP01_CG_Demo",
"asset": "robot",
"task": "modeling"
ayon contextselection <PATH_TO_JSON> 

publish Arguments

Run publishing based on metadata passed in the JSON file, for example, on a farm.

--targetsDefine publishing targets (e.g., "farm").
--gui (-g)Show publishing.
Positional argumentPath to metadata JSON file.
ayon publish <PATH_TO_JSON> --targets farm

extractenvironments Arguments

The entered output filepath will be created if it does not exist. All context options must be passed; otherwise, only AYON's global environments will be extracted. Context options are project, asset, task, app.

output_json_pathAbsolute path to the exported JSON file.
--projectProject name.
--assetFolder (asset) name.
--taskTask name.
--appApplication name.
ayon extractenvironments /home/openpype/env.json --project Foo --asset Bar --task modeling --app maya-2019

run arguments

--scriptrun specified python script

Note that additional arguments are passed to the script.

ayon run --script /foo/bar/ arg1 arg2

AYON launcher does support to run script directly which makes this command deprecated.

ayon /foo/bar/ arg1 arg2


Running AYON without any commands will default to tray.


You can substitute ayon with poetry run python if you want to run it directly from sources.