> For the complete documentation index, see [llms.txt](https://archivedocs.stackstate.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://archivedocs.stackstate.com/5.1/develop/developer-guides/agent_check/agent-check-state.md).

# Agent check state

## Overview

Starting with the release of **Agent 2.18**, the Agent Check API exposes two new interfaces to allow stateful behavior in Agent Checks. More specific details of the Agent interfaces can be found in the [Agent check API](/5.1/develop/developer-guides/agent_check/agent-check-api.md)

## When to use Agent State

Agent State is intended for Agent Checks that need to persist state in between check runs. The type of persistence model to use depends on the use case. `Stateful Agent Checks` are able to persist state to disk after each check run, **regardless of whether the check completely successfully or data was successfully sent to StackState**. `Transactional Agent Checks` have two states; Persistent state which behaves the same as state in a `Stateful Agent Check` and transactional state. Transactional state is persisted when the check **completes successfully and the data was delivered to StackState.**

State(s) are parameters to the `stateful_check` and `transactional_check` methods and the values in the return type are eventually persisted.

⚠️ **PLEASE NOTE -** State files are persisted as plain text in JSON format, therefore no passwords / secrets should ever be stored as state.

## Agent State location

{% tabs %}
{% tab title="Linux" %}
The state files are located in the `/opt/stackstate-agent/run/{check_name}` folder for each stateful / transactional check.

The root path `/opt/stackstate-agent/run` can be updated by setting:

* `check_state_root_path` in the Agent configuration file located at: `/etc/stackstate-agent/stackstate.yaml`.
* Setting `STS_CHECK_STATE_ROOT_PATH={path}` as a environment variable.
  {% endtab %}

{% tab title="Docker" %}
The state files are located in the `/opt/stackstate-agent/run/{check_name}` folder for each stateful / transactional check.

The root path `/opt/stackstate-agent/run` can be updated by setting:

* `check_state_root_path` in the Agent configuration file located at: `/etc/stackstate-agent/stackstate.yaml`.
* Setting `STS_CHECK_STATE_ROOT_PATH={path}` as a environment variable.
* Alternatively mount a volume on the check state root path. For more information on mounting volumes for Docker, take a look here: <https://docs.docker.com/storage/volumes/>.
  {% endtab %}

{% tab title="Windows" %}
The state files are located in the `c:\programdata\stackstate-agent\run\{check_name}` folder for each stateful / transactional check.

The root path `c:\programdata\stackstate-agent\run` can be updated by setting:

* `check_state_root_path` in the Agent configuration file located at: `C:\ProgramData\StackState\stackstate.yaml`.
* Setting `STS_CHECK_STATE_ROOT_PATH={path}` as a environment variable.
  {% endtab %}
  {% endtabs %}

⚠️ **PLEASE NOTE -** Running stateful checks in Kubernetes is currently not supported by the StackState Agent Helm Chart.

## See also

* [How to develop Agent checks](/5.1/develop/developer-guides/agent_check/how_to_develop_agent_checks.md)
* [Agent check API](/5.1/develop/developer-guides/agent_check/agent-check-api.md)
* [Connect an Agent check with StackState using the Custom Synchronization StackPack](/5.1/develop/developer-guides/agent_check/connect_agent_check_with_stackstate.md)
* [Developer guide - Custom Synchronization StackPack](/5.1/develop/developer-guides/custom_synchronization_stackpack.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://archivedocs.stackstate.com/5.1/develop/developer-guides/agent_check/agent-check-state.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.