> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage runners

export const Runners = () => <>the <strong>Runners & Instances</strong> icon <span style={{
  whiteSpace: "nowrap"
}}><img src="/images/global-nav/runners-instances.png" width="20" height="20" style={{
  verticalAlign: "text-bottom",
  display: "inline",
  margin: "0 1px"
}} /></span></>;

export const s_runner = "Streaming runner";

export const m_runner = "Maia runner";

export const maia = "Maia";

export const RunnerMetadata = ({runnerType, platforms = []}) => {
  return <div style={{
    background: 'var(--colors-background-light, #f9fafb)',
    border: '1px solid var(--colors-border-default, #e5e7eb)',
    borderRadius: '12px',
    padding: '20px 28px',
    marginBottom: '28px'
  }}>
      <table style={{
    width: '100%',
    borderCollapse: 'collapse'
  }}>
        <tbody>
          <tr>
            <td style={{
    fontWeight: '600',
    paddingRight: '32px',
    paddingBottom: '14px',
    whiteSpace: 'nowrap',
    verticalAlign: 'middle',
    width: '180px'
  }}>Runner type</td>
            <td style={{
    paddingBottom: '14px',
    verticalAlign: 'middle'
  }}>{runnerType}</td>
          </tr>
          <tr>
            <td style={{
    fontWeight: '600',
    paddingRight: '32px',
    whiteSpace: 'nowrap',
    verticalAlign: 'middle'
  }}>Runner platform</td>
            <td style={{
    verticalAlign: 'middle'
  }}>
              <div style={{
    display: 'flex',
    flexWrap: 'wrap',
    gap: '8px'
  }}>
                {platforms.map((platform, i) => <span key={i} style={{
    background: '#dcfce7',
    color: '#15803d',
    border: '1px solid #bbf7d0',
    borderRadius: '9999px',
    padding: '3px 12px',
    fontSize: '0.85rem',
    fontWeight: '500',
    whiteSpace: 'nowrap'
  }}>
                    {platform} ✅
                  </span>)}
              </div>
            </td>
          </tr>
        </tbody>
      </table>
    </div>;
};

<RunnerMetadata runnerType={`${maia} Hybrid`} platforms={["AWS", "Azure", "Google Cloud", "Snowflake"]} />

If your {m_runner}s are deployed in your own cloud infrastructure in a [Hybrid SaaS](/docs/guides/runner-overview#hybrid-saas) configuration, there are certain {m_runner} management tasks you can perform directly in {maia}. This article discusses those management tasks.

<Note>
  This article covers {m_runner}s *only*. For {s_runner}s, read [Create a {s_runner}](/docs/streaming/create-streaming-agent).
</Note>

***

## List Maia runner instances

To see a full list of {m_runner}s, in the left navigation, click <Runners />. Then, select **Runners** from the menu.

The **Runners** list shows all {m_runner}s currently created, and for each {m_runner} it shows:

* **Runner:** The name of the {m_runner}. Click the name to display the full [details](#maia-runner-details) for the {m_runner}.
* **Status:** The status of the {m_runner}. This will be one of the following:
  * **Pending:** The {m_runner} has been created but hasn't yet connected to {maia}.
  * **Running:** The {m_runner} is connected and ready for development and pipeline tasks.
  * **Unknown:** The {m_runner} is in an unknown state.
  * **Stopping:** The {m_runner} is in the process of shutting down. Existing tasks are being allowed to complete, including any open transactions.
  * **Stopped:** The {m_runner} has been stopped.
  * **Pausing:** The {m_runner} has had a [Pause](/docs/guides/pause-runner) request and is finishing existing tasks and/or transactions.
  * **Paused:** The {m_runner} has completed all work and any new requests are being queued. The {m_runner} may also have been stopped on the cloud provider if the offline indicator is present.
* **Platform:** The cloud platform that the {m_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.
  * Google Cloud GKE.
  * Matillion Hosted. This is a [Full SaaS {m_runner}](/docs/guides/runner-overview#matillion-full-saas) hosted and managed by Matillion. You will not be able to view further details or perform management actions on this {m_runner}.
* **Type:** The type of {m_runner}, which will be **{maia}** or **Streaming**. For more details of {s_runner}s, read [Create a {s_runner}](/docs/streaming/create-streaming-agent).
* **Version reported by runner:** This is the version of the {m_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](#actions) menu for the {m_runner}.

<Note>
  The **Runners** list does not show which {m_runner}s are assigned to which projects. To see which {m_runner} is assigned to a project, go to the [Environments](/docs/guides/environments#manage-environments) tab of the project and observe the **Default Runner** column.

  You can also query environments via the API and get the {m_runner} name associated with each environment. Read the [API documentation](/docs/api-reference/executing-and-managing-a-pipeline#step-2-get-the-environment-details) for details.
</Note>

***

## Maia runner details

On the **Runners** list, locate the {m_runner} you want to pause and click the {m_runner}'s name to open its details page.

The {m_runner} details page displays information in four tabs:

### Overview

* **Runner name:** The name of the {m_runner}.

* **Description:** The optional description you entered when you created the {m_runner}.

* **Runner status:** The status of the {m_runner}. This will be one of the following:
  * **Pending:** The {m_runner} has been created but hasn't yet connected to {maia}.
  * **Running:** The {m_runner} is connected and ready for development and pipeline tasks.
  * **Unknown:** The {m_runner} is in an unknown state.
  * **Stopping:** The {m_runner} is in the process of shutting down. Existing tasks are being allowed to complete, including any open transactions.
  * **Stopped:** The {m_runner} has been stopped.
  * **Pausing:** The {m_runner} has had a [Pause](/docs/guides/pause-runner) request and is finishing existing tasks and/or transactions.
  * **Paused:** The {m_runner} has completed all work and any new requests are being queued. The {m_runner} may also have been stopped on the cloud provider if the offline indicator is present.

* **Type:** The type of {m_runner}, which will be **{maia}** or **Streaming**. For more details of {s_runner}s, read [Create a {s_runner}](/docs/streaming/create-streaming-agent).

* **Cloud provider:** The cloud platform that the {m_runner} is installed on. Currently, **Snowflake**, **AWS**, **Azure**, and **Google Cloud** are supported.

* **Deployment:** The supported deployment method for the given cloud provider. Currently, Native App for Snowflake, Fargate for AWS, Container App/ACI for Azure, and GKE for Google Cloud are supported.

* **Auto update:** If the {m_runner} has auto update enabled, then whenever a new version is released on its version track, the {m_runner} will be automatically updated to that version. You can change a {m_runner}'s auto update status at any time by toggling **Auto update**. Read [Auto update](/docs/guides/runner-updates#auto-update) for details of how this setting is applied.

* **Version track:** The release version track that the {m_runner} is using, **Current** or **Stable**. Read [Version tracks](/docs/guides/runner-updates#version-tracks) for details.

  If you need to change the track that an existing {m_runner} is on, you can use the [Update a {m_runner}](/api-reference/agents/update-an-agent) public API endpoint. However, take note of the following:

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

* **Latest version:** The latest version of the {m_runner} that's available on the version track.

* **Version release date:** The date that the latest version of the {m_runner} was released by Matillion.

* **Version reported by runner:** This is the version of the {m_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 {m_runner}. If you have enabled **Auto update**, the versions should be in sync.

* **Update available:** This will be displayed if a new {m_runner} version is available.

### Deployment

This tab contains links to the template or guide (for example, [AWS CloudFormation](/docs/guides/runner-installation-cloudformation-quick-create), [Azure ARM](/docs/guides/azure-arm-runner-install), or the [GKE deployment guide](/docs/guides/gke-deployment-guide)) used to deploy the {m_runner} in your cloud infrastructure.

This tab will not be visible if there is no deployment option for the {m_runner} type, for example with [Snowflake {m_runner}s](/docs/guides/snowflake-runner-install).

### Parameters

This tab displays the parameters you need to install your {m_runner}, and also [optional parameters](/docs/guides/optional-runner-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 {m_runner}. These credentials are generated when you create the {m_runner}, and are required for the {m_runner} to connect to {maia}. Each {m_runner} must use its own unique **Client ID** and **Client Secret**, as credentials are specific to the individual {m_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 {m_runner} is not currently using them. Read [Refresh {m_runner} credentials](/docs/guides/refresh-credentials) for more details.

### Allow list

This tab lets you restrict which projects or environments can use the {m_runner}. This is useful if you have multiple {m_runner}s and want to ensure that a project only uses specific ones. Read [Restricting {m_runner}s](/docs/guides/restrict-a-runner) for details of this function.

***

## Actions

To carry out management actions on a {m_runner}:

On the **Runners** list, locate the {m_runner} in the **Runners** 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 {m_runner} details page, described above.
* **Test connectivity:** Select this action to [test connectivity](#test-connectivity) for the {m_runner}.
* **Restart agent:** Select this action to restart the {m_runner}. Read [Restart a {m_runner}](/docs/guides/restart-runner) for details.
* **Pause agent:** Select this action to pause the {m_runner}. Read [Pause a {m_runner}](/docs/guides/pause-runner) for details.
* **Remove agent:** Select this action to delete the {m_runner}. Deleting the {m_runner} here doesn't remove the underlying cloud resources. You should go into [Snowflake's Snowpark Container Services](https://docs.snowflake.com/en/snowpark-container-services), [AWS Console](https://aws.amazon.com/console/), [Azure Portal](https://portal.azure.com/#home), or [Google Cloud Console](https://console.cloud.google.com/) and clean up any resources that you no longer require.

<Warning>
  Deleting a {m_runner} that is currently running may interrupt scheduled pipelines or pipelines that are currently running. Therefore, you should always stop the {m_runner} service before deleting it.
</Warning>

***

## Test connectivity

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

A connection test can only be performed for a **Running** {m_runner}. If the {m_runner} has any other status, the option will be unavailable.

To perform the test:

1. On the **Runners** list, locate the {m_runner} in the **Runners** 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:

```json theme={null}
{
  "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 **Runner task failed: The runner version does not support this feature**, you should upgrade your {m_runner} version as described in [{m_runner} updates](/docs/guides/runner-updates).