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

# Configure state store backend

Starting with Airflow 3.3 (Astro Runtime 3.3), tasks and asset watchers can persist state between runs through the Airflow worker-side state store. Remote Execution Agents store this state in a backend that you control, so it stays in your execution plane. This guide covers the default configuration that the Remote Execution Agent Helm chart applies and how to configure object storage for production.

## Overview

Airflow 3.3 introduces a worker-side state store that tasks and asset watchers use to persist small state values between runs. For example, an asset watcher uses it to track its position in an event stream. By default, Airflow stores this state in the metadata database. With Remote Execution, the metadata database resides in the Astro orchestration plane, so a custom state store backend keeps the data in storage that you control instead. This is the same pattern as the [XCom backend](/docs/astro/remote-execution-configure-xcom-backend).

Agent Client 1.8.0 and later enforce this on Astro Runtime 3.3 and later images: agents don't start until you set the `AIRFLOW__WORKERS__STATE_STORE_BACKEND` environment variable. Runtime versions earlier than 3.3 don't include the state store, and agents apply no state store configuration there.

## Prerequisites

* Remote Execution Agent Helm chart 2.3.0 or later. For earlier chart versions, see [Configure the backend on chart versions earlier than 2.3.0](#configure-the-backend-on-chart-versions-earlier-than-2-3-0).
* For production use, an object storage bucket and workload identity configured for your Kubernetes cluster, as described in [Configure XCom backend](/docs/astro/remote-execution-configure-xcom-backend).

## Default configuration

Remote Execution Agent Helm chart 2.3.0 and later configure the state store backend automatically. The `stateStoreBackend` value defaults to the object storage backend from the Common IO provider:

```yaml title="values.yaml" wrap theme={null}
stateStoreBackend: airflow.providers.common.io.state_store.backend.StateStoreObjectStorageBackend
```

The chart sets `AIRFLOW__WORKERS__STATE_STORE_BACKEND` to this class on every agent component. If you don't configure a storage path yourself, the chart also applies a local file path default:

```text wrap theme={null}
AIRFLOW__COMMON_IO__STATE_STORE_OBJECTSTORAGE_PATH=file:///usr/local/airflow/state-store
```

<Warning>
  **Local path default is for evaluation only**

  With the local file path, each agent Pod writes state to its own container filesystem: state isn't shared between Pods and doesn't survive Pod restarts. Configure shared object storage for production deployments.
</Warning>

## Configure object storage for production

Point the state store at shared object storage by setting the storage path in `commonEnv`:

```yaml title="values.yaml" wrap theme={null}
stateStoreBackend: airflow.providers.common.io.state_store.backend.StateStoreObjectStorageBackend

commonEnv:
  - name: AIRFLOW__COMMON_IO__STATE_STORE_OBJECTSTORAGE_PATH
    value: "s3://<connection-id>@<bucket-name>/<path-to-state-store>"
```

The path format and authentication follow the same patterns as the XCom backend, and you can reuse the same bucket and connection with a different path prefix. See [Configure XCom backend](/docs/astro/remote-execution-configure-xcom-backend) for cloud-specific instructions for AWS S3, Azure Blob Storage, and GCP Cloud Storage, including bucket setup, workload identity, and connection configuration.

After updating your values, apply the configuration:

```sh wrap theme={null}
helm upgrade astro-agent astronomer/astro-remote-execution-agent -f values.yaml
```

## Configure the backend on chart versions earlier than 2.3.0

Helm chart versions earlier than 2.3.0 don't include the `stateStoreBackend` value. Before you move agents to a Runtime 3.3 image, either upgrade to chart 2.3.0 or later, or set the environment variables on all agent components through `commonEnv`:

```yaml title="values.yaml" wrap theme={null}
commonEnv:
  - name: AIRFLOW__WORKERS__STATE_STORE_BACKEND
    value: "airflow.providers.common.io.state_store.backend.StateStoreObjectStorageBackend"
  - name: AIRFLOW__COMMON_IO__STATE_STORE_OBJECTSTORAGE_PATH
    value: "s3://<connection-id>@<bucket-name>/<path-to-state-store>"
```

## Custom backend classes

If you use a different state store backend class, set `stateStoreBackend` to your class and configure its settings through `commonEnv`. The chart only applies the local path default for the object storage backend.

## Verify configuration

After applying your configuration:

1. Confirm all agent Pods start successfully. On Runtime 3.3 images, an agent fails to start with a validation error if `AIRFLOW__WORKERS__STATE_STORE_BACKEND` isn't set.
2. Trigger a Dag that uses the state store, for example through an asset watcher.
3. Verify that state objects appear under your configured storage path.

## Next steps

* [Configure XCom backend](/docs/astro/remote-execution-configure-xcom-backend) - Object storage for passing data between tasks
* [Configure Dag sources](/docs/astro/remote-execution-configure-dag-sources) - Define how agents access Dag code

## Related documentation

* [Remote Execution overview](/docs/astro/remote-execution-overview)
* [Helm chart configuration reference](/docs/astro/remote-agents-helm-reference)
* [Remote Execution Agent release notes](/docs/astro/agent-release-notes)