Skip to content

Manage Maia Foundation runners🔗

Agent Type:
Maia Hybrid
Agent Platform:
AWS ✅ Azure ✅ Snowflake ✅ Matillion ✅

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

Note

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

List Maia Foundation runners🔗

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

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

  • Agent: The name of the Maia Foundation runner. Click the name to display the full Maia Foundation runner details for the Maia Foundation runner.
  • Status: The status of the Maia Foundation runner. This will be one of the following:
    • Pending: The Maia Foundation runner has been created but hasn't yet connected to Maia.
    • Running: The Maia Foundation runner is connected and ready for development and pipeline tasks.
    • Unknown: The Maia Foundation runner is in an unknown state.
    • Stopping: The Maia Foundation runner is in the process of shutting down. Existing tasks are being allowed to complete, including any open transactions.
    • Stopped: The Maia Foundation runner has been stopped.
    • Pausing: The Maia Foundation runner has had a Pause request and is finishing existing tasks and/or transactions.
    • Paused: The Maia Foundation runner has completed all work and any new requests are being queued. The Maia Foundation runner may also have been stopped on the cloud provider if the offline indicator is present.
  • Platform: The cloud platform that the Maia Foundation 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 Foundation runner hosted and managed by Matillion. You will not be able to view further details or perform management actions on this Maia Foundation runner.
  • Type: The type of Maia Foundation runner, which will be Maia or Streaming. For more details of Streaming runners, read Create a Streaming runner.
  • Version reported by agent: This is the version of the Maia Foundation 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 Foundation runner.

Note

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

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

Agent details🔗

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

The Maia Foundation runner details page displays information in four tabs:

Overview🔗

  • Agent name: The name of the Maia Foundation runner.
  • Description: The optional description you entered when you created the Maia Foundation runner.
  • Agent status: The status of the Maia Foundation runner. This will be one of the following:
    • Pending: The Maia Foundation runner has been created but hasn't yet connected to Maia.
    • Running: The Maia Foundation runner is connected and ready for development and pipeline tasks.
    • Unknown: The Maia Foundation runner is in an unknown state.
    • Stopping: The Maia Foundation runner is in the process of shutting down. Existing tasks are being allowed to complete, including any open transactions.
    • Stopped: The Maia Foundation runner has been stopped.
    • Pausing: The Maia Foundation runner has had a Pause request and is finishing existing tasks and/or transactions.
    • Paused: The Maia Foundation runner has completed all work and any new requests are being queued. The Maia Foundation runner may also have been stopped on the cloud provider if the offline indicator is present.
  • Type: The type of Maia Foundation 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 Foundation 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 Foundation runner has auto update enabled, then whenever a new version is released on its version track the Maia Foundation runner will be automatically updated to that version. You can change a Maia Foundation runner's auto update status at any time by clicking the toggle button. Read Auto update for details of how this setting is applied.

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

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

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

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

  • Version release date: The date that the latest version of the Maia Foundation runner was released by Matillion.
  • Version reported by agent: This is the version of the Maia Foundation 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 Foundation runner. If you have enabled Auto update, the versions should be in sync.
  • Update Available: This will be displayed if a new Maia Foundation runner version is available.

Deployment🔗

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

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

Parameters🔗

This tab displays the parameters you need to install your Maia Foundation 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 Foundation runner. These credentials are generated when you create the Maia Foundation runner, and are required for the Maia Foundation runner to connect to Maia.

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 Foundation runner is not currently using them. Read Refresh Maia Foundation runner credentials for more details.

Allow List🔗

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

Actions🔗

To carry out management actions on a Maia Foundation runner:

On the Agents page, locate the Maia Foundation 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.

  • Agent details: Select this action to view the full Maia Foundation runner details page, described above.
  • Test connectivity: Select this action to test connectivity for the Maia Foundation runner.
  • Restart agent: Select this action to restart the Maia Foundation runner. Read Restart a Maia Foundation runner for details.
  • Pause agent: Select this action to pause the Maia Foundation runner. Read Pause a Maia Foundation runner for details.
  • Remove agent: Select this action to delete the Maia Foundation runner. Deleting the Maia Foundation 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 Foundation runner that is currently running may interrupt scheduled pipelines or pipelines that are currently running. Therefore, you should always stop the Maia Foundation runner service before deleting it.

Test connectivity🔗

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

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

To perform the test:

  1. On the Agents page, locate the Maia Foundation 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 Foundation runner version as described in Maia Foundation runner updates.

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