To execute a Keyword, an agent needs the files that belong to it: the Automation Package, the Keyword package (JAR, DLL), or the script. These files originate from the controller and are transferred to the agent on demand. Every component along that path keeps a local copy in a file cache so the same file does not have to be transferred again for the next execution.

Their size is driven by your automation content, not by the number of executions. On the Grid Proxy and the agents, they are the main consumer of disk space. On the controller they come on top of the durable data — resource files (including keyword assets, datasets, and execution attachments) — which usually accounts for the larger share. This guide explains what determines the size of the caches and how to translate that into a storage size.

For CPU and memory sizing, refer to the Requirements and the Agent Sizing Guide.

Why the controller keeps its own copy

Before an artifact can be sent to an agent, the controller stores its own copy of it under its file cache. This copy — and not the original resource, package or folder — is what every agent, agent forker and Grid Proxy downloads from. It is kept as long as it keeps being used, according to the cleanup rules described below.

Consistency. The copy is a snapshot taken at the moment the artifact is first needed by an execution. Artifacts come from many places — a resource uploaded in Step, an Automation Package, a Keyword package or a tool installation sitting on the controller’s file system — and several of them can change while an execution is still running. The snapshot guarantees that all agents taking part in an execution use exactly the same artifact from the first Keyword call to the last, including an agent joining late or retrying.

Cost. Preparing an artifact for transfer is not free: folders such as Keyword packages, tool installations or test projects have to be packed into a single archive first. The controller does this once, when the artifact is first requested, and then serves the result to every agent that needs it — the same repeated work that the proxy-side and agent-side caches avoid further down the chain.

Where the file caches are located

Only the files required to execute Keywords on an agent are cached in this way. Files that are used exclusively on the controller side — datasets and their CSV files, for instance — are never transferred to the agents and therefore do not contribute to any of these caches.

The cache locations are the same in every setup; only the storage backing them differs. In a binary installation, they are plain folders on the filesystem of the host and the figures below apply to the free disk space of that filesystem. The rest of this guide uses the Kubernetes terms (PersistentVolumeClaim, ephemeral storage), since that is the most common deployment, but the sizing model itself is identical in both cases. It likewise refers to Automation Packages, standalone Keyword packages and scripts collectively as “Automation Package”, since all three are cached the same way.

What drives the cache size

The size of the cache of a given component can be estimated with:

cache size ≈ P × S × V × (1 + headroom)

  P        Automation Packages reaching this component within the cleanup window
  S        average size of one Automation Package
  V        versions of one Automation Package accessed within the cleanup window
  headroom 30–50%, covering the cleanup interval and deployment bursts

The headroom matters because the cleanup job runs periodically (cleanupFrequencyMinutes, default 60): files stay on disk until the next run after they became eligible, so the cache regularly exceeds its steady-state size.

The three factors are detailed below. On Java agents, Forked Agent Mode adds a fourth term, and the Node.js and .NET agents follow different rules.

P — Automation Packages reaching the component

One cache entry corresponds to one version of one Automation Package: its package file and the resources it embeds.

Files enter a cache when they are transferred, not when they are deployed. P is therefore the number of distinct Automation Packages actually executed within the cleanup window, not the number registered in the platform: 100 Automation Packages of which 30 are executed daily gives P = 30 against the default 24-hour window, not 100. Automation Packages that are not executed within that window cost nothing in the caches — they only occupy the durable resource storage of the controller.

Which Automation Packages reach a component differs substantially:

• Controller: every Automation Package executed anywhere on the platform, since it is the origin for all agents.
• Grid Proxy: the union of those executed by all the agents behind it.
• Agent: everything routed to its pool. Because Keyword routing selects any free token in a matching pool, any agent of a pool may end up executing any Keyword of that pool. Size for the whole set routed to the pool, not for an even share of it.

S — size of one Automation Package

This varies by orders of magnitude depending on how the Keywords are packaged:

• A few KB for script-based Keywords, for instance a JMeter or k6 script.
• Tens to hundreds of MB for a fat JAR bundling its dependencies, for instance one embedding Playwright and its browser drivers.

Because of that spread, an average is only meaningful when your packages are reasonably homogeneous. If a handful of large packages dominate, add up their actual sizes instead of multiplying by an average.

V — versions kept within the cleanup window

This is the factor most often underestimated. Each time an Automation Package is redeployed, its files get a new identity and are cached as a new entry — the previous one is not replaced.

This is amplified by isolated executions of Automation Packages (CI runs without deployments), since each contributes a new version — even when the package content itself is unchanged since the previous run. Re-running an isolated execution directly from the Step UI however reuses its entry.

Cached files are evicted based on their last access time, after cleanupTimeToLiveMinutes (grid.filemanager.file.cleanup.last.access.threshold.minutes on the controller). Every version accessed within that window therefore stays on disk simultaneously. In a CI setup running a package 20 times a day against the default 24-hour window, roughly 20 versions of that package are resident, not one.

Forked Agent Mode

When Forked Agent Mode is enabled, each forked agent keeps its own copy of the files of its session under its execution directory, in addition to the copy held by the main agent’s cache. These copies are transient — they are removed when the session ends — but they are all present simultaneously at peak, so they add to the agent’s ephemeral storage requirement:

concurrent sessions × size of the files used per session

Node.js and .NET agents

The cleanup window described above only exists for the Java agent. The file caches of the Node.js and .NET agents have no automatic cleanup: every version of every Keyword project executed since the last start of the agent stays on disk, and the cache is only emptied when the agent restarts. For these agents, the cleanup window in the formula is therefore the time between two agent restarts, and the cache keeps growing with each new version deployed. Plan regular restarts of long-running agents, or size their storage for the versions accumulated between two restarts.

The Node.js agent additionally keeps a copy of each Keyword project, including its installed node_modules, in an npm project workspace per token. These workspaces are deleted after an idle time defined by npmProjectWorkspaceCleanupIdleTimeMs (default 1 hour), and add to the agent cache:

tokens × Node.js projects executed per token within the idle time × size of a project including node_modules

As node_modules is installed on the agent, a workspace is usually much larger than the package that was downloaded, in particular with browser automation libraries.

Worked example

Assume 40 Automation Packages executed daily, averaging 80 MB, each redeployed about 3 times a day, with the default 24-hour cleanup window (V ≈ 3) and 50% headroom. The estimates apply to any setup; the conclusions compare them against the defaults of the Helm chart:

These figures are a starting point. Replace them with your own measurements as described in Monitoring actual usage.

Per-component recommendations

Controller

The file cache shares its storage with the durable controller data — resource files (including keyword assets, datasets, and execution attachments) — which grows over time independently of the cache and usually accounts for the larger share. On Kubernetes, both live on the same data PVC. Size it as durable data + cache estimate, and keep both in mind when the volume starts filling up: growth of the durable data alone can be enough to leave the cache without space, which makes file transfers to the agents fail.

Grid Proxy

The Grid Proxy cache is a warm-start optimization in terms of content: it survives restarts, and anything missing or evicted is simply fetched again from the primary grid, so losing the cache never loses data. Its storage, however, is not optional. Because files are only evicted after their time to live has elapsed, a volume that is too small does not degrade gracefully into a smaller cache — it fills up, and the Grid Proxy can then no longer store the files it downloads. From that point on, file transfers to the agents fail and the Keyword executions depending on them fail with a functional error.

Size it for the union of what all agents behind the proxy execute, and make sure the volume never runs full (see Monitoring actual usage).

If persistence is disabled, the cache falls back to the pod’s ephemeral storage and is rebuilt from scratch on every restart — the sizing still applies, but to ephemeral storage instead.

Agents

The agent cache is not backed by a dedicated volume: it shares its storage with the agent logs, the forked agent execution directories, and everything the automated tool itself writes (browser profiles, screenshots, downloads). Budget for all of these together.

On Kubernetes, this storage is the pod’s ephemeral storage. Set ephemeral-storage requests and limits explicitly through agent.pools[N].resources: without a request, the pod competes for node disk with no guarantee, and a node running out of disk gets its pods evicted by the kubelet. In a binary installation, the cache is part of the agent working directory and consumes the free space of the disk holding the installation — the 2 GB in the Requirements covers the installation itself, not the cache.

Since agents are usually the most numerous component, this is also where reducing the footprint pays off the most — see below.

Reducing the footprint

• Shorten the cleanup window (cleanupTimeToLiveMinutes): the most direct lever, as it caps how many versions stay resident. It is a trade-off — a shorter window means more re-downloads, lower execution throughput, and more load on the controller and network, as noted in the agent cleanup configuration.
• Run the cleanup job more often (cleanupFrequencyMinutes): reduces the overshoot above the steady-state size, and lets you work with less headroom.
• Keep the packages slim: a fat JAR bundling browsers or drivers is cached in full on every component of the path, once per version. Shipping large binaries with the image or the agent installation instead of the package removes them from the cache entirely.
• Narrow the pools: routing a package to a dedicated pool reduces the number of distinct Automation Packages that each agent of the other pools has to cache.

Monitoring actual usage

Measure rather than estimate as soon as the setup runs a representative workload:

• Controller and Grid Proxy: monitor the usage of the volume holding the cache (the PVC on Kubernetes, the filesystem otherwise), and alert well before it is full — a full volume makes file transfers fail, and Keyword executions fail with them.
• Agents: monitor the storage holding the agent working directory. On Kubernetes, exceeding the ephemeral storage limit results in the pod being evicted during execution, which typically appears as executions failing on agents that disappear from the grid.
• Check the size of the cache folder directly (filemanager, or tmp under the controller data folder) to compare the real steady-state size against your estimate, and adjust the volume or the cleanup window accordingly.

Tip: Take the measurement after at least one full cleanup window has elapsed under normal load. Before that, the cache has not reached its steady state and will understate the requirement.