🚧

This feature is in an alpha, please use it carefully in production. If you encounter issues with modules when cache is enabled, please open a Scalr Support request at

Scalr Support Center

with logs. And as a workaround, disable the cache.

By default, OpenTofu/Terraform downloads all modules from your configuration on every init. If module cache is enabled, Scalr automatically optimizes your Terraform or OpenTofu runs by using a module cache, which speeds up workspace initialization and reduces unnecessary network downloads. The caching mechanism works in two main phases: loading from cache and saving to cache

How it works

The Module Cache uses an opt-in architecture and is disabled by default. See SCALR_AGENT_MODULE_CACHE_ENABLED for details.

When you run a Scalr Plan with module caching enabled, Scalr checks whether the modules your workspace needs are already available in the cache.

• If cached versions are available and verified, Scalr reuses them immediately, significantly reducing initialization time.
• If modules are missing, Scalr automatically downloads the latest versions and updates the cache accordingly.

The process uses the standard terraform/tofu get command behind the scenes, ensuring compatibility with both Terraform and OpenTofu workflows.

What you'll see during initialization

During the first run of a workspace, Scalr will download and initialize all required modules. The logs will look similar to this:

Initializing modules...
Downloading registry.opentofu.org/terraform-aws-modules/iam/aws 6.2.3 for iam_account...
- iam_account in .terraform/modules/iam_account/modules/iam-account
Downloading registry.opentofu.org/terraform-aws-modules/iam/aws 6.2.3 for iam_oidc_provider...
- iam_oidc_provider in .terraform/modules/iam_oidc_provider/modules/iam-oidc-provider
Downloading registry.opentofu.org/terraform-aws-modules/lambda/aws 8.1.2 for lambda_function...
- lambda_function in .terraform/modules/lambda_function
Downloading registry.opentofu.org/terraform-aws-modules/s3-bucket/aws 5.9.0 for s3-bucket_example_account-public-access...
- s3-bucket_example_account-public-access in .terraform/modules/s3-bucket_example_account-public-access/examples/account-public-access
- s3-bucket_example_account-public-access.account_public_access in .terraform/modules/s3-bucket_example_account-public-access/modules/account-public-access
Downloading registry.opentofu.org/terraform-aws-modules/s3-bucket/aws 5.9.0 for s3-bucket_example_table-bucket...
- s3-bucket_example_table-bucket in .terraform/modules/s3-bucket_example_table-bucket/examples/table-bucket
Downloading registry.opentofu.org/terraform-aws-modules/kms/aws 3.1.1 for s3-bucket_example_table-bucket.kms...
- s3-bucket_example_table-bucket.kms in .terraform/modules/s3-bucket_example_table-bucket.kms
- s3-bucket_example_table-bucket.table_bucket in .terraform/modules/s3-bucket_example_table-bucket/modules/table-bucket

Initialized 6 modules in 8.45s (6 downloaded, 6 cached)
Initializing plugins...sa
Initialized 6 plugins in 2.85s (6 used from cache)

For subsequent runs, you'll notice a speed improvement, as modules are now loaded from the cache:

Initializing modules...
Initialized 6 modules in 1.01s (6 used from cache)
Initializing plugins...
Initialized 6 plugins in 3.05s (6 used from cache)

Where cached modules are stored

Modules and their related metadata are stored locally on the Scalr Agent, typically under:

/var/lib/scalr-agent/modules/

This directory includes:

• archives/ – stores the actual cached module files.
• metadata/ – contains integrity and version information for each workspace to ensure that the right modules are used every time.

These files allow Scalr to verify that a workspace's modules match the expected versions and checksums before reusing them.

Garbage Collection

Over time, the module cache can grow significantly on disk. The Scalr Agent performs periodic cleanups of stale or rarely used modules.

The garbage collection task removes modules based on two criteria:

1. Age-based removal: Modules not accessed for more than the threshold (configured via SCALR_AGENT_MODULE_CACHE_THRESHOLD_DAYS, default: 10 days)
2. Size-based removal: When total cache size exceeds SCALR_AGENT_MODULE_CACHE_SIZE_LIMIT_MB (default: 10240 MB / 10 GB)

Protection Window

Modules accessed within the last 12 hours are protected from size-based removal, even if the cache exceeds the size limit. This prevents disruption to active workloads.

Workspace Metadata Cleanup

The garbage collector also removes workspace metadata directories that haven't been accessed since the date limit, cleaning up metadata for inactive workspaces.

📘

The actual cache usage may temporarily exceed SCALR_AGENT_MODULE_CACHE_SIZE_LIMIT_MB depending on active run workloads. The garbage collector uses a best-effort approach to maintain this limit.

Limitations

• Use pre-init hooks to prevent adding artifacts to the module source code.
• Local modules are not cached because caching provides little or no performance benefit.
• Modules without explicit version information (for example, VCS modules lacking ?ref=) may not be cached reliably and can be redownloaded if their code changes.
• The maximum archive size per module is 500 MB.
• Terragrunt runs currently do not use module cache, support may be added in a future release.