> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/4/configure-caching/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Configure caching

> Learn how to enable and configure the caching system in Itential Gateway to reduce load from repeated discovery operations.

Gateway 4.3.12+

Itential Gateway can cache the results of discovery operations to disk instead of running live discovery every time. Caching reduces repeated discovery load, which is especially useful for gateways with large inventories or frequent discovery requests.

This topic explains how caching works, how to configure it, and what to consider when running multiple Gateway instances on the same host.

## How caching works

When caching is enabled, Gateway writes the results of each discovery type to a dedicated JSON file in a configured directory. On subsequent requests, Gateway reads from these files instead of running live discovery, which reduces the time and load associated with repeated discovery operations.

Gateway creates one cache file per discovery type:

| Discovery type | Cache file               |
| -------------- | ------------------------ |
| Collections    | `collections_cache.json` |
| Modules        | `modules_cache.json`     |
| Playbooks      | `playbooks_cache.json`   |
| Scripts        | `scripts_cache.json`     |
| Terraforms     | `terraforms_cache.json`  |
| Devices        | `devices.json`           |
| Groups         | `groups.json`            |

When caching is disabled, Gateway always runs live discovery and doesn't read or write these files.

## Configuration properties

Caching is controlled by two top-level properties in `properties.yml`:

```yaml
#### Cache ####
# Enable cache
global_cache_enabled: True

# Path to the global cache
global_cache_directory: '/tmp'
```

| Property                 | Description                                 | Default |
| ------------------------ | ------------------------------------------- | ------- |
| `global_cache_enabled`   | Enables or disables caching.                | `True`  |
| `global_cache_directory` | Directory where Gateway writes cache files. | `/tmp`  |

## Configure caching

`global_cache_enabled` and `global_cache_directory` are part of the **System** section of `properties.yml`, so you must edit them directly on the Gateway instance rather than through the UI. Changes to `properties.yml` require a reboot.

1. On the Gateway instance, open `properties.yml` in a text editor.
2. Set `global_cache_enabled` to `True` or `False`.
3. Set `global_cache_directory` to the path where you want Gateway to write cache files.
4. Save the file.
5. Restart the Gateway service to apply the changes.

You can review these values under **Cache Enabled** and **Global Cache Directory** in the **System Configuration** section of the UI. This section is locked, since it can only be edited in `properties.yml`, followed by a server restart.

## Cache directory availability

At startup, Gateway checks whether the configured cache directory exists and is writable. If it doesn't exist or isn't writable, Gateway logs a warning and continues running without caching rather than failing to start.

If you see a caching warning at startup, verify that `global_cache_directory` points to a directory that exists on the Gateway instance and that the Gateway service account has write permission to it.

## Multiple Gateway instances

If you run multiple Gateway instances on the same host, set a distinct `global_cache_directory` for each instance. Instances that share a cache directory can overwrite each other's cache files, which can lead to inconsistent discovery results.

> Learn how to enable and configure the caching system in Itential Gateway to reduce load from repeated discovery operations.