Skip to content

Create a Maia Foundation runner in your infrastructure🔗

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

This topic explains how to create a Maia Foundation runner in your own infrastructure. For a discussion of why you might want to deploy in your own infrastructure rather than use a Matillion Full SaaS solution, read Maia Foundation runner overview. We currently support Maia Foundation runners running in Snowflake, AWS, or Azure environments.

There are two different types of Maia Foundation runner:

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

The installation process is similar for both types of Maia Foundation runner, but you must select the correct Maia Foundation runner type for the type of pipeline you want to run. You can install both Maia Foundation runners in the same infrastructure if you intend to run both types of pipeline.

Read Scaling best practices to understand how to size your Maia Foundation runner for the level of performance you need.

Prerequisites🔗

  • A Maia account. To register, read Registration. Once you have signed up, log in to the Maia.
  • An account in either Azure or AWS to host the Maia Foundation runner.

Create a Maia Foundation runner🔗

  1. In the left navigation, click the Agents & Instances icon . Then, select Agents from the menu. You will see a list of all Maia Foundation runners currently created.
  2. Click Add agent.
  3. Click Maia.

  4. Complete the following properties:

    • Agent name: A unique name for your new Maia Foundation runner. Maximum 30 characters. Accepts both uppercase and lowercase A-z, 0-9, whitespace (not the first character), hyphens and underscores.
    • Description: Optionally enter a brief description of the Maia Foundation runner.
    • Version track: Select the version track that this Maia Foundation runner will use: Current or Stable. Read Version tracks for details of this option.
    • Cloud provider: The cloud platform that the Maia Foundation runner will be deployed to. 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: Select whether you want your Maia Foundation runner to automatically update or not. Read Auto update for details of this option.

  5. Click Create agent.

Set up the Maia Foundation runner in your cloud infrastructure🔗

When created with the above process, the Maia Foundation runner needs to be set up in your cloud infrastructure. There are several different ways of doing this, and you can use whichever method suits you:

To complete these processes, you will require certain details of the created Maia Foundation runner. To obtain these details, locate the Maia Foundation runner in the list of Maia Foundation runners, and click the three dots ... next to it, then click Agent details. The parameters and values in the sections Agent image URI, Agent environment variables, and Credentials are required when configuring your Maia Foundation runner in your cloud infrastructure.

Check Maia Foundation runner status🔗

After deploying the Maia Foundation runner in your cloud infrastructure, you should return to Maia to verify that it's correctly connected and running.

  1. Click the menu button in the top left of any Maia page, then click Manage → Agents.

  2. Locate the Maia Foundation runner in the list and check the status:

    • Running: The Maia Foundation runner is connected and ready for development and pipeline tasks.
    • Unknown: The Maia Foundation runner is in an unknown state.
    • Pending: The Maia Foundation runner has been created but has not yet connected to Maia.
    • Stopped: The Maia Foundation runner has been stopped.

  3. When the Maia Foundation runner status shows Running, it's ready to use.

Restarting Maia Foundation runners🔗

There are a number of reasons why you may need to restart your Maia Foundation runner, such as receiving Maia Foundation runner updates.

To restart a Maia Foundation runner, follow the steps in Restart a Maia Foundation runner. In some cases, you may need or choose to pause the Maia Foundation runner before restarting.

Deleting Maia Foundation runners🔗

To delete a Maia Foundation runner from Maia, locate the Maia Foundation runner on the Agents page, then click the three dots ... → Remove agent.

Deleting the Maia Foundation runner from the Agents screen doesn't remove the underlying Snowflake, AWS, or Azure resources. You should go into the Snowpark Container Services, AWS Console, or Azure Portal, and clean up any resources that you no longer require.

  • Snowflake: Use Snowpark Container Services to manage and clean up any Snowflake resources associated with the Maia Foundation runner.
  • AWS: Use the AWS Console to identify and delete any resources associated with the Maia Foundation runner, such as EC2 instances and IAM roles.
  • Azure: Use the Azure Portal to locate and remove any related resources, such as virtual machines and resource groups.

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.

Using the Maia Foundation runner to develop and run pipelines🔗

To use a Maia Foundation runner for developing and then running pipelines, you need to select the Maia Foundation runner when you create an environment. See below for details of how to make Maia Foundation runners available to specific environments.

You can change which Maia Foundation runner an environment uses at any time by editing the environment and selecting a different Maia Foundation runner. This is safe to do, as the change will only affect pipelines that are run after the change. So:

  • Your open Designer session won't change.
  • Any pipelines that are currently running will continue to run using the old Maia Foundation runner.
  • Any existing schedules will continue to run using the old Maia Foundation runner. To use the new Maia Foundation runner, you would have to change the schedule.

Restricting Maia Foundation runners🔗

You can restrict which Maia Foundation runners are available to a specific project or environment. This is useful if you have multiple Maia Foundation runners and want to ensure that a project only uses specific ones.

An unrestricted Maia Foundation runner (the default state when a Maia Foundation runner is created) can always be used by any project or environment. A restricted Maia Foundation runner can only be used by the projects and environments you specify. If you restrict a Maia Foundation runner but don't specify any projects, the Maia Foundation runner won't be accessible to any project.

For details of how to restrict a Maia Foundation runner, read Restricting Maia Foundation runners.

Video🔗

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