> ## 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.

# Restrict a Maia runner

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 m_runner = "Maia runner";

export const designer = "Designer";

export const maia = "Maia";

You can restrict which {m_runner}s are available to a specific project or environment. This is useful if you have multiple {m_runner}s and want to ensure that a {m_runner} is only available to specific projects. You can also ensure that only specific environments are allowed to use {m_runner}s, thus preventing access within a project to any user who doesn't have access to that environment.

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

In addition to the process described below, you can also restrict {m_runner}s using the [Update an agent](api-reference/agents/update-an-agent) endpoint, and manage the {m_runner}'s allow list using the [Set allow list](api-reference/agents/set-agent-allow-list) and [Remove project from allow list](/api-reference/agents/remove-project-from-agent-allow-list) endpoints.

***

## How to restrict a Maia runner

<Note>
  You can restrict a {m_runner} regardless of its current status (Running, Stopped, etc.).
</Note>

1. In the left navigation, click <Runners />. Then, select **Runners** from the menu.
2. Locate the {m_runner} you want to restrict and click the {m_runner}'s name to open the {m_runner} details page.
3. Click the **Allow List** tab.
4. Click the **Restrict agent** toggle to enable restrictions. This will reveal the list of projects that can use the {m_runner}, along with the number of environments in each project that can use the {m_runner} ("All environments", "1 environment", "2 environments", etc.).
5. Click **Manage** next to the **Projects** heading. This will open the **Manage projects** dialog.
6. The **Manage projects** dialog lists all the projects in your {maia} account. To allow a project to use the {m_runner}, click the project name and then click the right-arrow button. This will move the project to the **Allowed projects** list on the right. You can use the left-arrow button to remove a project from the **Allowed projects** list.
7. Click **Save** to save your changes and close the dialog.

By default, every environment in an allowed project can use the {m_runner}. If you want to further restrict the {m_runner} to a specific environment or set of environments within the project:

1. Click **environments** next to the project name (it may say "All environments", "1 environment", "2 environments", etc.). This will open the **Manage environments** dialog.
2. The **Manage environments** dialog lists all the environments used by the project. To allow an environment to use the {m_runner}, click the environment name and then click the right-arrow button. This will move the environment to the **Allowed environments** list on the right. You can use the left-arrow button to remove an environment from the **Allowed environments** list.

### Reserving an environment name

If an environment doesn't yet exist but you want to ensure that when it's created it can use the {m_runner}, you can use the **Reserve environment** function to specify the name of the environment that you plan to create. To do this:

1. Click the three dots **...** to the right of the project you want to reserve an environment for.
2. Click **+ Reserve environment**. This will open the **Reserve Environment** dialog.
3. In the **Environment name** field, enter the name of the environment you plan to create.
4. Click **Reserve** to reserve the name and close the dialog. The reserved environment name will be added to the **Allowed environments** list for the project, with "(reserved)" next to its name.

You can repeat this process to reserve multiple environment names for the project.

<Note>
  This action *doesn't* create the environment. When an environment with this exact name is subsequently created in the project, this {m_runner} will be available for selection by that environment.
</Note>

When you reserve an environment name for the {m_runner}, it automatically restricts the {m_runner} to only that environment, even though it doesn't yet exist, which means no other environments can use it unless you explicitly add them to the **Allowed environments** list.

To remove a reserved environment, click the environment name in the **Allowed environments** list and then click the left-arrow button to move it to the list on the left. This will remove the reservation, and it will no longer appear in either list of the dialog.

### Turning off Maia runner restrictions

If you switch the **Restrict agent** toggle off, the {m_runner} will be made available to every project and environment. The list of allowed projects, environments, and reserved environments will be saved, however, so if you later re-enable the **Restrict agent** toggle, the previous restrictions will be restored.

***

## Using the restricted Maia runner

### In an environment

When you create an environment within a project, one of the decisions you need to make is which {m_runner} the environment will use. For details of how to create an environment, read [Environments](/docs/guides/environments).

The environment's **Runner** drop-down will only display those {m_runner}s that are unrestricted or that are restricted to the environment that is being created.

### In a schedule

When you create a schedule, one of the decisions you need to make is which {m_runner} the scheduled pipelines will use. For details of how to create a schedule, read [Schedules](/docs/guides/schedules).

The schedule's **Runner** drop-down will only display those {m_runner}s that are unrestricted or that are restricted to the project and environment that the schedule is being created in.

If you restrict a {m_runner} so that it's no longer available to a project that already uses it in a schedule, the schedule itself isn't automatically updated or disabled. However, the next scheduled execution will be recorded with a **Forbidden** status in [pipeline run history](/docs/guides/pipeline-run-history). To keep the schedule running, either re-include the project or environment in the {m_runner}'s allow list, or edit the schedule to use a different {m_runner}. No new schedules subsequently added to the project will be able to select that {m_runner}.