Once you are happy with the MIRO application you developed, you can deploy it. This chapter guides you through this process.

    Deploying a MIRO application is the process of exporting and installing your app so that it can be easily shared and used in the daily business of your end users. Before you can deploy an app, it needs to be fully set up: no further changes to the model or the configuration can be made once it is deployed. In case you did not configure your MIRO app yet, read the chapters about model preparation and configuration.

    App deployment - step by step

    The deployment of an application consists of two parts: The creation of a self-contained app bundle and its installation.

    Create an app bundle

    The model assembly file:

    Before you export your app bundle, MIRO needs to know about the files that belong to your model. This is primarily the main model file, but also all files necessary to calculate all inputs and outputs, e.g. files that are included in the model. To tell MIRO about these files, create a text file in the root directory of your model called <modelname>_files.txt or use GAMS Studio to create this file for you. For the latter go to MIROAssembly and Deploy. In the Assembly File section you can select those folders and files which are needed. If you select a folder, all files in it will be included. If you want to use only single files of a folder, you have to expand the folder and select the corresponding file(s).

    create model assembly file

    Files or folders created by MIRO (e.g. conf_<modelname>, data_<modelname>, static_<modelname>) do not need to be included in the assembly file. MIRO knows about these files and includes them automatically.

    If you want to create the text file on your own, specify the relative paths to the files that are part of your model separated by a new line. An example for a model named example can be found below:


    This would result in the files example.gms, inc/, inc/ and the entire directory data to be included.

    Export app:

    Once you specified the files that belong to your model, you are ready to export your MIRO app!

    Deploy MIRO model

    In GAMS Studio, select Assembly and Deploy. In the Deploy Configuration section specify which MIRO modes you want to support in your MIRO app (Base Mode/Hypercube Mode or both). If the Base Mode is selected, you also need to decide how your model shall be executed (execution environment). There are three options:

    1. Multi-user: This option allows your app to be used by multiple users simultaneously. Your model files are extracted at a random location, which is different for each user, and your model is executed from there.
    2. Single-user: Your model is executed inside the model directory. No extraction of your model files is required, but this means that you can NOT have multiple users accessing your MIRO app at the same time.
    3. Local multi-user (uses idir): With this third option, your model is again executed from a random location, but this time no model data is extracted here. Instead, GAMS is executed with an input directory pointing to the path where your model files are located. Choose this option ONLY if you have many large files that belong to your model and extracting them would take a long time. Be aware that due to the fact that idir is used, your model might brake! For example, if you use $call or the execution-time equivalent execute (or related functions), the relative paths used in these calls will no longer exist (since the curdir is now a random location). The solution is to prefix all these relative paths with %gams.idir1%. For example, in order to import an Excel file test.xlsx, GDXXRW needs to be called like this: $call gdxxrw i=%gams.idir1%test.xlsx. Alternatively, you can also use absolute paths (e.g. via $setNames "%gams.input%" fp fn fe (see here).
      Adjusting all affected paths is potentially a lot of work, so we strongly advise against using this option unless you know what you are doing!

    With MIRO version 2.1, the Hypercube Mode is deprecated and and no longer exists as a separate module. You can now submit Hypercube jobs from the Base Mode if you are using GAMS MIRO with a GAMS Engine backend (GAMS MIRO Server or GAMS MIRO Desktop - boosted by GAMS Engine). You can find the most recent documentation here.


    We advise you to test your MIRO app before distributing it. GAMS Studio offers an option test deployment. This simulates how your end users will experience the MIRO app (e.g. for the Base Mode MIRO is launched in the specified execution environment). In particular, you should check whether you forgot to include important files in the model assembly file.

    Bundling data with your app

    In case you want to distribute scenario data with your MIRO application, you can do so by simply placing MIROSCEN, GDX, CSV or XLSX files in the data_<modelname> directory. When your MIRO app is started for the first time, these datasets will be stored in the MIRO database. The filename is used as the scenario name. To learn more, read the chapter on importing multiple scenarios on startup. Note that the owner of these scenarios is the user that launches the MIRO app for the first time!

    Assign a default logo

    When adding the MIRO app to the MIRO library, the user has the option to choose a logo to quickly identify your app. If you want to suggest a logo, simply place am image (format: png/jpg/jpeg; aspect ratio: 8 × 5 fits best) with the name app_logo inside the static_<modelname> folder before deploying. When a user imports your app, this logo will be suggested to them. If no such file is found, a default logo is used.

    Custom Logo for MIRO library

    Note: The app_logo logo described here is located in the same folder, but is independent of the logo set in the Configuration Mode.

    Specify a default title and description for your app

    When adding a new MIRO app to the library, a user can specify an app title as well as a short description. If you want to provide defaults for these, you can do so via a JSON file app_info.json inside the static_<modelname> folder. The JSON file has to have the following structure:

        "title": "Example app",
        "description": "This is my first MIRO app"

    If everything is set, click on Deploy. That's it! A new file <modelname>.miroapp is created in your model directory. You can now distribute this MIRO app directly to your end users!

    Advanced: Export MIRO app using the command line

    Install the MIRO app

    To install a new MIRO app, launch GAMS MIRO Desktop. You will see your personal MIRO library with all the MIRO apps you have installed.

    MIRO gallery example

    To add a new app to the library, either double click the app in your file browser (only on Windows/macOS) or click on "Edit" (Ctrl + E or + E on macOS) and drag&drop the app onto the "+" button. Alternatively, you can click on the "+" button and browse to the location of the new app manually.

    Add new app

    Once MIRO validated the new app, you can assign a title, a short description as well as a logo.

    Edit MIRO app

    Once you are happy with the setup, click on Add app. Your app is now installed in your library and you can launch it by clicking the Launch button. In case your app supports both the Base Mode and the Hypercube Mode, the Launch button turns into a dropdown menu that lets you select which mode to launch.

    Launch Base or Hypercube Mode

    It is not possible to start MIRO applications in development mode (via GAMS Studio or command line) when the MIRO library is open!

    Customize your installed MIRO apps

    The MIRO Desktop interface offers several ways to control the behavior of your MIRO apps. To access these settings click on FilePreferences (or GAMS MIROPreferences if you are on macOS). Alternatively, press F7 (or + , on macOS). You will notice that there are three categories of settings: General settings, settings related to Paths and to the Environment. In the General category you can specify whether you want to launch your MIRO apps in a new window of the MIRO Launcher or in your default browser. You can set the language, specify the level of detail of information to be logged as well as the number of days you want your log files to be stored for (-1 being no limit).

    In the Paths section, you can control the location where your MIRO apps are stored/loaded from and the location where log files are kept. Additionally, in case you want to use a specific GAMS version or the MIRO Launcher was unable to locate GAMS automatically, you can set the path to GAMS here. On Linux, you can also specify the path to the required R installation here.

    Option Description
    General Launch MIRO apps in your browser? If this option is set, MIRO applications are started in the users default web browser. If not set, the internal chromium browser is used instead.
    Language Sets the language. The user can choose between English, German and Chinese. Further languages are planned.
    Execution of models on GAMS Engine? If enabled, GAMS jobs can be run in the cloud instead of on the local machine. For this purpose the server information must be specified in the MIRO application. This option can also be enabled by setting the environment variable MIRO_REMOTE_EXEC to true.
    Logging level Determines the logging scope. TRACE = very high, FATAL = very low
    Number of days log files are stored A value of -1 means that the logs are never deleted.
    Paths MIRO app path Path to the working directory of GAMS MIRO. There deployed apps are stored, Hypercube Jobs are executed and log files are written. On Windows the default location is C:\Users\<username>\.miro
    GAMS path Path to the GAMS installation folder.
    Log path Location where the log files should be saved.
    R path (Linux only) Path to the R location. A current R version (3.6 or later) is required for using GAMS MIRO. Since R is bundled with MIRO on Windows and MacOS, this option is only available on Linux systems.

    In the Environment section, you can import a customized environment to be used by your MIRO apps. This is useful, for example, if you want to run custom analysis scripts that require external software not in your PATH or to store credentials to be used by remote data exchange modules.

    Environment files are JSON files of the following form:

        "ENV_VAR_1": "VAL_1",
        "ENV_VAR_2": "VAL_2"

    Environment variables names must consist solely of uppercase letters, digits and '_' (underscore) and must not start with a digit. Note that the PATH environment variable is special in that MIRO prepends it to the already existing PATH.

    As an example, let's say we want to run the analysis script that comes with the pickstock example. We do this by first setting up a Python environment for it:

    > python -m venv venv
    > venv\Scripts\activate.bat
    (venv) > pip install jupyter pandas matplotlib
    (venv) > python <path_to_gams>\apifiles\Python\api_39\ build -b %TEMP% install
    > python -m venv venv
    > source venv/bin/activate
    (venv) > pip install jupyter pandas matplotlib
    (venv) > python <path_to_gams>/apifiles/Python/api_39/ build -b ${TMPDIR} install

    Now all we have to do is tell MIRO to use this Python environment by adding it to the PATH via the following environment file:

        "PATH": "<path_to_venv>/venv/bin"


    Share MIRO apps

    This section covers the options you have when you want to share MIRO apps and/or scenarios between multiple users.

    First, you need to specify a location in your file system where your MIRO apps are stored. To change the directory where MIRO apps are stored, go to PreferencesPaths and change the "MIRO app path" to a directory where all collaborating users have at least read access. Users that are allowed to add/edit/remove apps need write access as well. Note that this only handles the location of where the MIRO apps are stored and loaded from, not the location of the MIRO database that the apps use. If you want your users to share the same database (in order to collaborate), you can specify its location by clicking on Edit (Ctrl + E or + E on macOS).

    Edit database location

    Collaborators need both read and write permissions at the database location to load and save scenarios!

    Share settings

    In addition to sharing MIRO apps, you may want to share settings such as "Paths" to the GAMS/R installation or even "General" settings such as the log file verbosity. To do so, you have to create a file: settings.json at the location of the shared MIRO app path.

    Let's look at an example: You created a shared directory <sharedFolder> where you have read and write access and all the other collaborators only have read permissions. You select this directory in your MIRO settings (PreferencesPathsMIRO app path) and install your MIRO applications here. In addition, you want to set some default settings. Therefore, you create a file <sharedFolder>\settings.json:

        "gamspath": "C:\\GAMS\\win64\\30.2",
        "launchExternal": false,
        "logLifeTime": -1,
        "important": ["logLifeTime", "gamspath"]

    Users that set their MIRO app path to <sharedFolder> will now also load these settings in addition to the apps installed here (in this example the GAMS path is set to C:\GAMS\win64\30.2, the MIRO app is not launched in the default browser but inside a native MIRO window and the logs are never removed).

    The "important" key is special: settings listed here ("logLifeTime" and "gamspath") will be fixed, meaning the user can not overwrite these. This is useful if you don't want your users to change certain options.

    The schema for the settings.json file is as follows:

      configpath: {
        type: 'string',
        minLength: 2
      gamspath: {
        type: 'string',
        minLength: 2
      rpath: {
       type: 'string',
       minLength: 2
      logpath: {
        type: 'string',
        minLength: 2
      launchExternal: {
        type: 'boolean'
      logLifeTime: {
        type: 'integer',
        minimum: -1
      language: {
        type: 'string',
        enum: ['en', 'de', 'cn']
      logLevel: {
        type: 'string',
        enum: ['TRACE', 'DEBUG', 'INFO',
        'WARN', 'ERROR', 'FATAL']
      important: {
        type: 'array',
          type: 'string',
          enum: [

    Database migration

    From time to time, you may want to update your MIRO application. Most updates, such as changing the layout of your application, adjusting the renderers, or even improving your GAMS model, are not problematic. It gets more complicated when you change the GAMS/MIRO data contract, i.e. anything between the $onExternalInput / $offExternalInput or $onExternalOutput / $offExternalOutput tags. MIRO stores all of your application's data in a relational database. This means that every time you change the domains of a symbol (add/remove/rename indices) or remove/rename external input and/or output symbols, the database must be migrated to the new data contract. Fortunately, MIRO offers a Migration Wizard to assist you with this process.

    Let's look at an example where we have added a time dimension to the transport example model:

    Migration Wizard for transport model with added time dimension

    You can see that we need to migrate data from the three symbols: schedule, a0 and b. The symbols schedule and b now have an additional dimension t. Before this new version, we did not have this dimension, so we choose - here to indicate that this data is missing. If we were to load a scenario that was saved with an old version of our app, the data in these columns would be marked as NA.

    As we renamed the symbol a to a0, we indicate that data for symbol a0 should come from a.

    Note that as an alternative to migrating existing data, we also have the option to remove all existing data by clicking the Delete all database tables button in the lower left corner.


    Before you migrate the data, you should perform a backup of your database. If you are using MIRO Desktop, you can do this via the Configuration Mode. For MIRO Server, please refer to the official PostgreSQL documentation.