Guides
Log InSign UpBlog
Start typing to search…

Run Environment & Customization

This document covers the Scalr run environment where OpenTofu/Terraform operations, Hooks, and OPA/Infracost/Checkov integrations are executed.

Environment variables

The Scalr Agent injects a set of shell variables into the run environment.

These variables are available at runtime and can be used directly or as TF_VAR_ variables by prefixing the variable name with TF_VAR_. See the full list here.

Customizing Run Environment

It's often useful to have additional tools or files available in the run environment by default, without needing to provision them manually in each run. This can be achieved by customizing the Scalr Agent's Docker images.

Depending on your platform and Agent configuration, different agent images need to be customized:

Agent Image

Each agent release includes two images, tagged with the agent version:

  • Main image: scalr/agent. A minimal image containing the Scalr agent service and a minimal set of essential tools.

  • Extended image: scalr/agent-runner. An extended image containing the Scalr agent service and a comprehensive set of tools like kubectl, aws-cli, azure-cli, gcloud, scalr-cli, and many other tools. The image is built for containerized/serverless runtimes that cannot create individual containers for each run stage and are therefore limited to executing OpenTofu/Terraform operations within the agent service container (learn more about the Local driver).

    This image is built by combining the main scalr/agent image and the golden scalr/runner image.

    To inspect the golden runner image version used for scalr/agent-runner:

    docker inspect scalr/agent-runner:0.60.0 | jq '.[0].Config.Labels["org.opencontainers.image.base"]'
"scalr/runner:0.1.4"

The scalr/agent image is recommended as the default. The scalr/agent-runner should only be used when extra-tooling bundled in the image is required and when a larger image size is acceptable.

Build Custom Agent Image

If you need to customize the run environment for the Local driver (for example, for containerized or serverless platforms), build your image based on scalr/agent without modifying the existing ENTRYPOINT and CMD instructions, since the image must include the functional agent service.

Then run the agent using your custom image instead of scalr/agent.

🚧

The agent image build pipelines and Dockerfile are part of Scalr's internal infrastructure.

Use image inspector tools to investigate the image building steps and content, for example the built-in DockerHub "Image Layers" inspector or tools like dive.

However, keep in mind that deep modifications of the image layout, such as changing module paths, modifying the entrypoint, etc., are discouraged and will not provide any guarantee of compatibility during agent updates, as internal implementation (that is not part of public APIs like REST, CLI, etc.) is always subject to change.

While we try to keep important internal changes documented, any internal change is not considered breaking from the perspective of customized image build pipelines.

The only supported modifications are installing additional software tools, files, executables, configurations, certificate bundles, environment variables, etc.

Runner Image

The runner image is used by Docker or Kubernetes drivers when the agent is configured to isolate each run stage (like plan and apply) in an individual container.

The agent has two operation modes regarding runner images, golden and legacy:

  • In legacy runner image mode, software-specific Docker images are used to create Scalr Run containers (e.g., scalr/opentofu:x.y.z, where x.y.z depends on workspace settings). In this mode, OpenTofu/Terraform/etc. binaries come pre-built into a runner image.
  • In golden runner image mode, a single runner image will be used instead (defined by SCALR_AGENT_CONTAINER_TASK_IMAGE configuration). In this mode, OpenTofu/Terraform/etc. binaries will be shipped as binary artifacts from scalr.io rather than bundled in images. This approach allows you to use a single image for all operations, which simplifies maintenance and customization of the run environment.
🚧

For newer accounts created after August 26th, 2025 (Scalr release 2508.22.0), golden runner image mode is enforced by default by the Scalr platform.

For older accounts, legacy runner image mode is used and golden mode can be enforced using SCALR_AGENT_CONTAINER_TASK_IMAGE_MODE. Alternatively, you can open a Scalr Support request at the Scalr Support Center, and we can enable it globally for all agents within your account.

To verify the golden image is used, confirm the software binaries installation log exists during the start of the run.

The image comes with a pre-bundled set of software. To inspect a specific version, use docker inspect:

docker inspect scalr/runner:0.2.0 | jq '.[0].Config.Labels'
{
  "aws-cli.version": "2.33.2",
  "azure-cli.version": "2.82.0",
  "gcloud.version": "552.0.0",
  "kubectl.version": "v1.35.0",
  "python.version": "3.13.11",
  "scalr-cli.version": "0.17.6"
}

The golden runner image is maintained and versioned in GitHub repository: https://github.com/Scalr/runner.

Runner Image Update Policy

The default golden runner image is defined by the SCALR_AGENT_CONTAINER_TASK_IMAGE configuration option.

The golden image is regularly updated alongside agent updates. Default image updates will be reflected in the agent changelog. Important updates of internal tooling (e.g., Python upgrade from 3.X to 3.Y) will be additionally highlighted in the changelogs.

You can specify a static version to stop receiving updates and maintain the golden image default on your own.

Build Custom Runner Image

If you need to customize the run environment for Docker or Kubernetes drivers, build your image based on scalr/runner, or use any other base image if you prefer to build the environment from scratch.

If you're building an image from scratch, it must include:

  • A user with UID/GID 1000. By default, Scalr images include a scalr user with 1000:1000.
  • /bin/sh and curl tools.
  • glibc 2.32 or later.

Build the image, publish it in your own registry, and use SCALR_AGENT_CONTAINER_TASK_IMAGE to specify the image path.

Using Private Image Registry

To use a private image registry for the golden runner image, republish the scalr/runner image to your own registry, and use SCALR_AGENT_CONTAINER_TASK_IMAGE to specify the image path.

When using a private registry for the golden runner image, you must specify a static image version to prevent breaking changes during regular image updates, as the image needs to be re-pushed to your internal registry before each update.

For legacy runner images, use SCALR_AGENT_CONTAINER_TASK_IMAGE_REGISTRY. All images for all software versions used by your account need to be re-published to your registry: scalr/terraform, scalr/opentofu, openpolicyagent/opa, infracost/infracost, and bridgecrew/checkov.

Software Releases

The Scalr Agent relies on third-party software to execute Scalr run workflows, including tools such as OpenTofu, Terraform, Terragrunt, OPA, and Infracost.

The agent provisions software releases as binary executables during the run initialization phase while using the golden runner image:

Installing software binaries...
Installed software binaries in 224.27ms

The binary releases are available for all supported platforms: linux_amd64 and linux_arm64.

The binaries for each version are cached after the first run and reused for all subsequent runs

📘

Legacy runner images will ship the binary releases pre-built into the runner image instead of installing them as separate artifacts.

Custom .terraformrc Files

Add the SCALR_TERRAFORM_RC shell variable in a workspace to use a custom a .terraformrc file. The variable's value should be the contents you normally put in the custom .terraformrc file. This enables direct configuration of OpenTofu/Terraform CLI settings, including credentials, plugin caching, and proxy configurations for private module registry access and enhanced security.

Updated 11 days ago