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

# Register and configure agents

<Note>
  **Airflow 3**

  This feature is only available for Airflow 3.x Deployments.
</Note>

Remote Execution Agents execute Airflow tasks in your Kubernetes infrastructure. This guide covers registering agents with your Astro Deployment and installing the Helm chart.

## Prerequisites

* Astro Deployment configured for Remote Execution mode. See [Create a Deployment](/docs/astro/create-deployment).
* Kubernetes 1.30 or later

<Tip>
  **Recommended Kubernetes configuration**

  Configure `singleProcessOOMKill: true` in your kubelet configuration. With this setting,
  Kubernetes kills only the process that runs out of memory instead of the entire Pod. Without it, one task's
  out-of-memory error kills all tasks on the worker and loses all task logs.

  See [Kubernetes documentation](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/) for details.
</Tip>

* Helm 3 or later
* [Deployment API token](/docs/astro/deployment-api-tokens) with Deployment Admin role to pull the base Astro Remote Execution Agent Image

## Step 1: Create agent token

The agent token authenticates your agent to the Astro orchestration plane. Create this token before installing the Helm chart.

<Note>
  Save the token value in a secure location immediately after creation. You cannot retrieve it again. The limit is 50 agent tokens per Deployment.
</Note>

<Tabs>
  <Tab title="Astro UI">
    <Steps>
      <Step title="Navigate to Deployment">
        In the Astro UI, click **Deployments**, then select your Remote Execution Deployment (in the legacy UI, select a Workspace first).
      </Step>

      <Step title="Open tokens view">
        Select the **Remote Agents** tab and toggle to the **Tokens** view.
      </Step>

      <Step title="Create token">
        1. Click **+Agent Token**
        2. Enter a **Name** and **Expiration** period
        3. Optionally add a **Description**
        4. Click **Create**
      </Step>

      <Step title="Save token">
        Copy the agent token and save it securely. You will use this token in the Helm chart configuration.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Astro API">
    <Steps>
      <Step title="Get bearer token">
        Retrieve your [Deployment API token](/docs/astro/deployment-api-tokens). This authenticates API requests.
      </Step>

      <Step title="Get organization ID">
        Make a GET request to the organizations endpoint:

        ```sh wrap theme={null}
        curl https://api.astronomer.io/platform/v1beta1/organizations \
          -H "Authorization: Bearer <token>"
        ```

        Locate the `id` field in the response.
      </Step>

      <Step title="Get Deployment ID">
        Make a GET request to the deployments endpoint using your organization ID:

        ```sh wrap theme={null}
        curl https://api.astronomer.io/platform/v1beta1/organizations/<organizationId>/deployments \
          -H "Authorization: Bearer <token>"
        ```

        Locate the `id` field for your Remote Execution Deployment in the response.
      </Step>

      <Step title="Create agent token">
        Make a POST request to create the token.  Replace the `organizationId`, `deploymentId`, and `your-API-Deployment-token` placeholders with your own values. You can optionally set a description and expiration period for the token.This example sets a 30-day expiration:

        ```sh wrap theme={null}
        curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/<organizationId>/deployments/<deploymentId>/agent-tokens \
          -H "Authorization: Bearer <your-API-Deployment-token>" \
          -H "Content-Type: application/json" \
          -d '{
          "description": "Production agent token",
          "name": "prod-agent",
          "tokenExpiryPeriodInDays": 30
        }'
        ```
      </Step>

      <Step title="Save token">
        Copy the `token` field from the response and save it securely.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Step 2: Install Helm chart

<Info>
  Astronomer recommends pulling both the Remote Execution Agent image and the Sentinel image and storing them in your private registry. Sentinel provides advanced monitoring and reporting for Remote Execution Agents, starting from version 1.2.0. The Agent base images are minimal, so you might need to add packages for your pipelines to function properly. Use either an [Organization API token](/docs/astro/organization-api-tokens) with the `Org Owner` role or a [Deployment API token](/docs/astro/deployment-api-tokens) with the `Deployment Admin` role to authenticate.
</Info>

<Steps>
  <Step title="Download values file">
    1. In the Astro UI, go to the **Remote Agents** tab
    2. Toggle to the **Agents** view
    3. Click **Register a Remote Agent**
    4. Click **Download** to get the `values.yaml` file
  </Step>

  <Step title="Configure required values">
    Update the following values in `values.yaml`. All other values have working defaults.

    You must configure these values before installing the Helm chart:

    * `agentToken`, `agentTokenSecretName`, or `agentTokenFile` - See [Agent token configuration](#agent-token-configuration)
    * `imagePullSecretName` or `imagePullSecretData` - See [Image pull secret configuration](#image-pull-secret-configuration)
    * `namespace` - Kubernetes namespace for agent deployment
    * `resourceNamePrefix` - Name prefix for Kubernetes resources
    * `secretBackend` - Must be configured before agents can execute tasks. See [Configure secrets backend](/docs/astro/remote-execution-configure-secrets-backend)
    * `xcomBackend` - Must be configured before agents can execute tasks. See [Configure XCom backend](/docs/astro/remote-execution-configure-xcom-backend)
    * `stateStoreBackend` - Required on Astro Runtime 3.3 and later, where agents don't start without it. Helm chart 2.3.0 and later set a working default that isn't suitable for production. See [Configure state store backend](/docs/astro/remote-execution-configure-state-store-backend)

    See the Helm chart comments and [Helm chart configuration reference](/docs/astro/remote-agents-helm-reference) for descriptions of values.
  </Step>

  <Step title="Pull agent image for private registries">
    If self-hosting the image, log in to the image registry with your Deployment API token:

    ```sh wrap theme={null}
    docker login images.astronomer.cloud -u cli -p <your-token>
    ```

    <Note>
      **Sentinel image available with 1.2.0 and later**

      Starting with Remote Execution Agent 1.2.0, a Sentinel image is published alongside the agent images to provide monitoring for Remote Execution Agents. The Sentinel image must be pulled separately. Astronomer recommends enabling Sentinel for all deployments. To enable Sentinel, configure the service in your `values.yaml` file. See [Sentinel for Remote Execution Agents](/docs/astro/remote-agents-sentinel).
    </Note>

    After you log in, you can pull the Remote Execution Agent and Sentinel images directly. To find the latest version and image path, refer to the [Remote Execution Agent release notes](/docs/astro/agent-release-notes) for all currently hosted images and [Remote Execution Agent image reference](/docs/astro/agent-images) for their full URLs. For example:

    ```sh wrap theme={null}
    docker pull images.astronomer.cloud/baseimages/astro-remote-execution-agent:3.1-3-python-3.12-astro-agent-1.2.0
    ```

    ```sh wrap theme={null}
    docker pull images.astronomer.cloud/baseimages/astro-remote-execution-sentinel:1.2.0
    ```

    <Tip>
      **Configure scope for registry proxies**

      If you use JFrog Artifactory or a similar registry management tool to mirror or proxy `images.astronomer.cloud`, you need to configure specific include patterns instead of using the default `**/*` pattern.

      The Deployment API token has limited scope and cannot fetch manifests for all repositories. Configure your remote registry to include only these specific paths:

      * `baseimages/astro-remote-execution-agent`
      * `baseimages/astro-remote-execution-sentinel`

      Without these specific patterns, you might encounter `403 Forbidden` errors when JFrog attempts to crawl all repositories in the registry.
    </Tip>

    Pull the Remote Execution Agent image, apply customizations that your dags require, and push it to your private registry. Then update the `values.yaml` file to reference your customized image.
  </Step>

  <Step title="Install Helm chart">
    <Warning>
      You must configure `secretBackend` in your `values.yaml` before running the Helm install. The installation fails if `secretBackend` has no value. See [Configure secrets backend](/docs/astro/remote-execution-configure-secrets-backend).
    </Warning>

    Run the following commands to install the agent:

    ```sh wrap theme={null}
    helm repo add astronomer https://helm.astronomer.io
    helm repo update
    helm install astro-agent astronomer/astro-remote-execution-agent -f values.yaml
    ```
  </Step>
</Steps>

## Step 3: Optionally set allowed IP ranges

Restrict Deployment access to specific IP address ranges for additional security or network isolation between environments.

<Steps>
  <Step title="Open Deployment settings">
    In the Astro UI, click the options menu for your Deployment and select **Edit**.
  </Step>

  <Step title="Add IP ranges">
    1. In the **Advanced** section, click **+Add IP**.
    2. Enter an IP address range in CIDR format.
    3. Click **Add**.
    4. Repeat to add multiple ranges.
  </Step>
</Steps>

## Step 4: Verify agent heartbeat

Confirm the agent is connected and healthy.

<Steps>
  <Step title="Check agent status">
    In the Astro UI, go to the **Remote Agents** tab. A healthy agent shows:

    * Health status: **Healthy**
    * Last heartbeat: Within the past minute

    You can also verify locally that all agent client deployment Pods are running with `kubectl get pods -n <namespace>`. For more in-depth validation, check pod logs for heartbeat activity.

    To verify that your agents can communicate with your Astro Orchestration plane:

    1. Connect to a host or Pod within your VPC that has your Remote Execution Agent running.

    2. Run a DNS lookup to confirm the hostname resolves successfully:

       ```sh wrap theme={null}
       nslookup <AstroClusterId>.external.astronomer.run
       ```

       The response should show the Astro cluster's public load balancer's public IP addresses, or the private IP addresses assigned to your VPC Endpoint if you configured [AWS PrivateLink](/docs/astro/remote-agents-aws-privatelink).

    3. Test connectivity to the endpoint:

       ```sh wrap theme={null}
       curl -v https://<AstroClusterId>.external.astronomer.run
       ```

       The expected response is `404 page not found`. A successful connection confirms your Remote Execution Agents are able to communicate with the Astro orchestration plane over a public connection or via your private VPC endpoint.

    <Tip>
      Temporarily remove any configured [allowed IP ranges](#step-3-optionally-set-allowed-ip-ranges) if the agent is not starting up and reporting Healthy. If connecting using a public connection, your network team may need to allowlist the Astro cluster's public load balancer's public IP addresses (step 2) for outbound access from your VPC.
    </Tip>
  </Step>

  <Step title="Configure dag bundles">
    After verifying agent health, configure how agents access DAG code. See [Configure DAG sources](/docs/astro/remote-execution-configure-dag-sources).
  </Step>

  <Step title="Run test dag">
    Trigger a test DAG run to verify the agent executes tasks successfully.

    <Warning>
      If you expect tasks to run longer than the default grace period of 10 minutes, update the `terminationGracePeriodSeconds` parameter for your workers in `values.yaml`. This ensures that worker Pods have enough time to finish existing tasks before terminating. See [Worker resource configuration](/docs/astro/remote-agents-helm-reference#worker-resource-configuration).
    </Warning>
  </Step>
</Steps>

<Note>
  **HTTP/HTTPS proxy server support**

  Starting with Remote Execution Agent 1.3.2, the agents support running behind an HTTP(S) proxy server. Configure proxy settings using the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables.

  For Remote Execution Agent versions earlier than 1.3.2, proxy servers are not supported. If your Kubernetes environment automatically adds a proxy configuration to Pods, the agents will fail to establish an outbound connection to the orchestration plane. You might see errors similar to these in worker logs:

  * `"exc_type":"ReadError","exc_value":"[Errno 104] Connection reset by peer"`
  * `"exc_type":"HTTPStatusError","exc_value":"Client error '400 Bad Request' for url ...`

  **Workaround:** Remove the proxy configuration from the agent Pods, or upgrade to Agent 1.3.2 or later.
</Note>

## Agent token configuration

Provide the agent token using one of these methods:

### agentToken

Store the token directly in `values.yaml`:

```yaml title="values.yaml" wrap theme={null}
agentToken: "<your-token-value>"
```

<Warning>
  Storing tokens directly in values files exposes them in version control. Use `agentTokenSecretName` or `agentTokenFile` for better security.
</Warning>

### agentTokenSecretName

Reference an existing Kubernetes secret containing the token:

```sh wrap theme={null}
kubectl -n <namespace> create secret generic agent-token \
  --from-file=token=token.txt
```

In `values.yaml`:

```yaml title="values.yaml" wrap theme={null}
agentTokenSecretName: "agent-token"
```

### agentTokenFile

Mount a file containing the token. The agent reads the token at runtime:

```yaml title="values.yaml" wrap theme={null}
agentTokenFile: "/path/to/token/file"
```

## Image pull secret configuration

Configure image pull secrets to authenticate with your container registry. The configuration differs depending on whether you pull images directly from Astronomer's registry or from a self-hosted registry.

<Warning>
  The image pull secret requires an **Astro API token**, not an agent token. Use either an [Organization API token](/docs/astro/organization-api-tokens) with the `Org Owner` role or a [Deployment API token](/docs/astro/deployment-api-tokens) with the `Deployment Admin` role. The agent token created in Step 1 authenticates the agent to the Astro orchestration plane and cannot be used for pulling images.
</Warning>

<Tabs>
  <Tab title="Astronomer registry">
    Use this configuration when pulling images directly from `images.astronomer.cloud`.

    ### imagePullSecretName

    Reference an existing Kubernetes secret in your namespace:

    ```sh wrap theme={null}
    kubectl create secret docker-registry -n <namespace> <secretName> \
      --docker-server=images.astronomer.cloud \
      --docker-username=cli \
      --docker-password=<your-astro-api-token>
    ```

    In `values.yaml`:

    ```yaml title="values.yaml" wrap theme={null}
    imagePullSecretName: "<secretName>"
    ```

    ### imagePullSecretData

    Alternatively, provide Docker config JSON directly. The Helm chart creates a secret named `image-pull-secret`:

    ```yaml title="values.yaml" wrap theme={null}
    imagePullSecretData: |
      {
        "auths": {
          "images.astronomer.cloud": {
            "auth": "<base64-encoded-credentials>",
            "email": "<email>"
          }
        }
      }
    ```
  </Tab>

  <Tab title="Self-hosted registry">
    Use this configuration when pulling images from a self-hosted registry, proxy, or mirror.

    <Note>
      If you use a proxy or mirror for `images.astronomer.cloud`, you still need an Astro API token to authenticate with the upstream Astronomer registry. Configure this in your proxy settings. See [Pull agent image for private registries](#image-pull-secret-configuration).
    </Note>

    ### imagePullSecretName

    Reference an existing Kubernetes secret in your namespace:

    ```sh wrap theme={null}
    kubectl create secret docker-registry -n <namespace> <secretName> \
      --docker-server=<your-registry-endpoint> \
      --docker-username=<your-registry-username> \
      --docker-password=<your-registry-password>
    ```

    In `values.yaml`:

    ```yaml title="values.yaml" wrap theme={null}
    imagePullSecretName: "<secretName>"
    ```

    ### imagePullSecretData

    Alternatively, provide Docker config JSON directly. The Helm chart creates a secret named `image-pull-secret`:

    ```yaml title="values.yaml" wrap theme={null}
    imagePullSecretData: |
      {
        "auths": {
          "<your-registry-endpoint>": {
            "auth": "<base64-encoded-username:password>",
            "email": "<email>"
          }
        }
      }
    ```
  </Tab>
</Tabs>

## Manage Remote Execution Agents

You can take the following actions on your registered Remote Execution Agents:

* **Cordon:** Cordoning a Remote Execution Agent marks it as unavailable for scheduling new tasks, while allowing it to continue running and complete any tasks already in progress.

This allows you to gracefully remove the Agent from service without interrupting current workloads. For example, you can cordon an Agent to delete or perform maintenance, such as an upgrade, on the Agent or underlying infrastructure.

A cordoned Agent will not receive new work, but it remains active until all running tasks have finished. Once ready to reintroduce the Agent to the task pool, it can be uncordoned to resume normal operation.

* **Uncordon:** Uncordoning a Remote Execution Agent re-enables it to receive new tasks and resume normal scheduling.

* **Delete:** Deletes the Remote Execution Agent from the Deployment.

## Remote Execution Agent maintenance policy

Each Remote Execution Agent minor version is maintained for **6 months** from the release month.

See [Agent maintenance policy](/docs/astro/agent-maintenance-policy) for more details about versioning, support, and upgrade recommendations.

## Next steps

After registering agents, configure the required components:

* [Configure secrets backend](/docs/astro/remote-execution-configure-secrets-backend) - Required for agent operation
* [Configure XCom backend](/docs/astro/remote-execution-configure-xcom-backend) - Required for passing data between tasks
* [Configure DAG sources](/docs/astro/remote-execution-configure-dag-sources) - Required for accessing DAG code

## Related documentation

* [Remote Execution overview](/docs/astro/remote-execution-overview)
* [Remote Execution Agent failure scenarios](/docs/astro/remote-agents-failure-scenarios)
* [Helm chart configuration reference](/docs/astro/remote-agents-helm-reference)
* [Install agents in restricted Kubernetes namespaces](/docs/astro/remote-agents-restricted-kubernetes)