Skip to content

Manage Maia runners🔗

Runner type:
Maia Hybrid
Runner platform:
AWS ✅ Azure ✅ Snowflake ✅ Matillion ✅

If your Maia runners are deployed in your own cloud infrastructure in a Hybrid SaaS configuration, there are certain Maia runner management tasks you can perform directly from the Maia user interface. This article discusses those management tasks.

Note

This article covers Maia runners only. For Streaming runners, read Create a Streaming runner.

List Maia runners🔗

To see a full list of Maia runners, in the left navigation, click the Runners & Instances icon . Then, select Runners from the menu.

The Runners list shows all Maia runners currently created, and for each Maia runner it shows:

  • Runner: The name of the Maia runner. Click the name to display the full Maia runner details for the Maia runner.
  • Status: The status of the Maia runner. This will be one of the following:
    • Pending: The Maia runner has been created but hasn't yet connected to Maia.
    • Running: The Maia runner is connected and ready for development and pipeline tasks.
    • Unknown: The Maia runner is in an unknown state.
    • Stopping: The Maia runner is in the process of shutting down. Existing tasks are being allowed to complete, including any open transactions.
    • Stopped: The Maia runner has been stopped.
    • Pausing: The Maia runner has had a Pause request and is finishing existing tasks and/or transactions.
    • Paused: The Maia runner has completed all work and any new requests are being queued. The Maia runner may also have been stopped on the cloud provider if the offline indicator is present.
  • Platform: The cloud platform that the Maia runner is installed on. Hover over this icon to read the description, which will include one of the following:
    • Snowflake.
    • AWS Fargate.
    • Azure Container App or ACI.
    • Matillion Hosted. This is a Full SaaS Maia runner hosted and managed by Matillion. You will not be able to view further details or perform management actions on this Maia runner.
  • Type: The type of Maia runner, which will be Maia or Streaming. For more details of Streaming runners, read Create a Streaming runner.
  • Version reported by runner: This is the version of the Maia runner currently installed in your cloud infrastructure. If a new version is available, this column will also display the notice Update Available.

Click the three dots ... to the right of this information to display the actions menu for the Maia runner.

Note

The Runners list does not show which Maia runners are assigned to which projects. To see which Maia runner is assigned to a project, go to the Environments tab of the project and observe the Default Runner column.

You can also query environments via the API and get the Maia runner name associated with each environment. Read the API documentation for details.

Runner details🔗

On the Runners page, locate the Maia runner you want to pause and click the Maia runner's name to open its details page.

The Maia runner details page displays information in four tabs:

Overview🔗

  • Runner name: The name of the Maia runner.
  • Description: The optional description you entered when you created the Maia runner.
  • Runner status: The status of the Maia runner. This will be one of the following:
    • Pending: The Maia runner has been created but hasn't yet connected to Maia.
    • Running: The Maia runner is connected and ready for development and pipeline tasks.
    • Unknown: The Maia runner is in an unknown state.
    • Stopping: The Maia runner is in the process of shutting down. Existing tasks are being allowed to complete, including any open transactions.
    • Stopped: The Maia runner has been stopped.
    • Pausing: The Maia runner has had a Pause request and is finishing existing tasks and/or transactions.
    • Paused: The Maia runner has completed all work and any new requests are being queued. The Maia runner may also have been stopped on the cloud provider if the offline indicator is present.
  • Type: The type of Maia runner, which will be Maia or Streaming. For more details of Streaming runners, read Create a Streaming runner.
  • Cloud provider: The cloud platform that the Maia runner is installed on. Currently, Snowflake, AWS, and Azure are supported.
  • Deployment: The supported deployment method for the given cloud provider. Currently, Native App for Snowflake, Fargate for AWS, and Container App/ACI for Azure are supported.
  • Auto update: If the Maia runner has auto update enabled, then whenever a new version is released on its version track, the Maia runner will be automatically updated to that version. You can change a Maia runner's auto update status at any time by toggling Auto update. Read Auto update for details of how this setting is applied.

  • Version track: The release version track that the Maia runner is using, Current or Stable. Read Version tracks for details.

    If you need to change the track that an existing Maia runner is on, you can use the Update a Maia runner public API endpoint. However, take note of the following:

    • Changing the Maia runner's version track does not update the Maia runner itself. You must update the image URI for the Maia runner service in your cloud provider. If you don't, the Maia runner version may show as "Out of support".
    • If you change the Maia runner state from Current to Stable and update the installed Maia runner service, pipelines created using a newer (Current) Maia runner version might not run as expected on an older (Stable) version.

  • Latest version: The latest version of the Maia runner that's available on the version track.

  • Version release date: The date that the latest version of the Maia runner was released by Matillion.
  • Version reported by runner: This is the version of the Maia runner currently installed in your cloud infrastructure. If there is a discrepancy between this version number and the Latest version number, you should consider upgrading the Maia runner. If you have enabled Auto update, the versions should be in sync.
  • Update Available: This will be displayed if a new Maia runner version is available.

Deployment🔗

This tab contains links to the template (either AWS CloudFormation or Azure ARM) used to deploy the Maia runner in your cloud infrastructure.

This tab will not be visible if there is no deployment option for the Maia runner type, for example with Maia runners for Snowflake.

Parameters🔗

This tab displays the parameters you need to install your Maia runner, and also optional parameters that you can set to specify functionality such as external drivers or Python libraries.

Credentials🔗

Credentials include the Client ID and Client Secret that are used to authenticate the Maia runner. These credentials are generated when you create the Maia runner, and are required for the Maia runner to connect to Maia. Each Maia runner must use its own unique Client ID and Client Secret, as credentials are specific to the individual Maia runner and can't be shared.

For security, these credentials are obscured on screen. Click Reveal to display them. You can then click the Copy icon to copy them to the clipboard. You can also click Regenerate to generate a new set of credentials. This will invalidate the old credentials, so you should only do this if you are sure that the Maia runner is not currently using them. Read Refresh Maia runner credentials for more details.

Allow List🔗

This tab lets you restrict which projects or environments can use the Maia runner. This is useful if you have multiple Maia runners and want to ensure that a project only uses specific ones. Read Restricting Maia runners for details of this function.

Actions🔗

To carry out management actions on a Maia runner:

On the Runners page, locate the Maia runner in the list, and click the three dots ... to the right of it to open the actions menu.

The actions that can be selected from this menu are described below.

  • Runner details: Select this action to view the full Maia runner details page, described above.
  • Test connectivity: Select this action to test connectivity for the Maia runner.
  • Restart runner: Select this action to restart the Maia runner. Read Restart a Maia runner for details.
  • Pause runner: Select this action to pause the Maia runner. Read Pause a Maia runner for details.
  • Remove runner: Select this action to delete the Maia runner. Deleting the Maia runner here doesn't remove the underlying AWS or Azure resources. You should go into Snowflake's Snowpark Container Services, AWS Console, or Azure Portal and clean up any resources that you no longer require.

Warning

Deleting a Maia runner that is currently running may interrupt scheduled pipelines or pipelines that are currently running. Therefore, you should always stop the Maia runner service before deleting it.

Test connectivity🔗

You can perform a basic connection test for a Maia runner. This tests the outbound connection from the Maia runner to a specified host and port, and reports the result.

A connection test can only be performed for a Running Maia runner. If the Maia runner has any other status, the option will be unavailable.

To perform the test:

  1. On the Runners page, locate the Maia runner in the list, and click the three dots ... to the right of it to open the actions menu.
  2. Click Test connectivity on the actions menu.
  3. Complete the details in the Test connectivity panel:
    • Endpoint: The domain name or IP address you want to test the connection to.
    • Port: The port number to connect to for the test.
  4. Click Test.

After a few seconds, the test response will be shown, in the following format:

{
  "result": "SUCCESS",
  "host": "matillion.com",
  "port": 80
}

The result value in the response will show SUCCESS if the connection was successfully achieved, or TIMEOUT if it was not.

If you receive the response Agent task failed: The agent version does not support this feature, you should upgrade your Maia runner version as described in Maia runner updates.

© Copyright 2026 Matillion Ltd | Legal | Privacy Policy | Disclaimer | Modern Slavery Statement