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_:

Variable	Description
`SCALR_RUN_ID`	The ID of the current run.
`SCALR_HOSTNAME`	The Scalr hostname.
`SCALR_TERRAFORM_OPERATION`	The current Terraform operation (`plan` or `apply`).
`SCALR_TERRAFORM_EXIT_CODE`	The exit code (`0` or `1`) of the previous operation. Available only in after hooks.
`SCALR_RUN_IS_DESTROY`	`1` if the run is equivalent to a `terraform destroy`, `0` if it's a regular `apply`. Useful for conditional logic in custom hooks.
`SCALR_RUN_VCS_BRANCH`	The VCS branch name (e.g., `main`).
`SCALR_RUN_VCS_COMMIT`	The commit hash for a VCS-triggered run (e.g., `e59f09e`).
`SCALR_RUN_MODE`	Type of run executed. Possible values: `apply` (Plan & Apply), `dry` (Plan only), `refresh` (Refresh only), `skip_refresh` (Skip refresh).
`SCALR_RUN_SOURCE`	The source that triggered the run. Possible values: `vcs`, `cli`, `scalr-cli`, `run-trigger`, `schedule`, `api`, `configuration version`, `ui`.
`SCALR_WORKSPACE_NAME`	The name of the workspace the run is executing in.
`SCALR_WORKSPACE_ID`	The ID of the workspace.
`SCALR_ENVIRONMENT_ID`	The ID of the environment.
`SCALR_ENVIRONMENT_NAME`	The name of the environment.
`SCALR_RUN_CONTENT_ROOT`	The absolute path to the root of the configuration being executed.
`SCALR_AGENT_ENV`	Path to the file containing custom environment variables, which can be injected into the Scalr Run by hook scripts during execution. Learn more.

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.

This third-party software is typically provisioned via Docker images (e.g., scalr/opentofu:x.y.z). When an agent starts a run, it uses the corresponding software image to launch the run container. Recent versions of the agent (v0.42 and later) offer an alternative mode for provisioning software releases as binary executables.

In this mode, the agent downloads and installs third-party software as binaries. For containerized drivers like Docker and Kubernetes, it uses the scalr/runner image (also known as the Golden Image) as the base container environment. Using a single image simplifies maintenance and customization. When software binaries are enabled, the following entries appear in the Run Console for each run stage:

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

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

🚧
The software binaries for Docker and Kubernetes drivers are not available for all accounts by default and will become gradually rolling out depending of software version availability. To enable software binaries to your account please open a Scalr Support request at Scalr Support Center.

Customizing the 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.

The agent release includes three images:

scalr/agent: A minimal image containing the Scalr agent service, optimized for small size and fast provisioning. Tagged with the agent release.
scalr/runner: The default image for the run environment of containerized drivers like Docker and Kubernetes. Includes a comprehensive set of additional tooling for Terraform operations. Has an independent release cycle, see https://github.com/Scalr/runner for details. The scalr/agent service uses this image to launch isolated Scalr run containers.
scalr/agent-runner: A combined build of the scalr/agent and scalr/runner images for the Local driver. This third image is needed because the Local driver executes Scalr runs operations directly in the current environment and does not isolate them in containers. Tagged to match the agent release.

All images based on debian:trixie-slim.

If you need to customize the run environment for Docker or Kubernetes drivers, build your image based on scalr/runner, or use debian:trixie-slim if you prefer to build the environment from scratch. Then set it via SCALR_AGENT_CONTAINER_TASK_IMAGE.

If you need to customize the run environment for Local driver, build your image based on scalr/agent-runner, or use scalr/agent if you prefer to build the environment from scratch. Use this image to launch an agent service.

Using private Docker images

To use private Docker images, republish or build the scalr/runner image in your own registry, and use SCALR_AGENT_CONTAINER_TASK_IMAGE to specify the image path.

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.