The Scalr Agent configuration is managed through environment variables. Specify the variables in a configuration file for your runtime environment.

For Docker installations, use the -e flag or the --env-file CLI option to pass environment variables. If you have many variables to inject, it's usually more convenient to define them in a docker-compose.yml file.

For Kubernetes installations, environment variables can be set using the extraEnv helm chart option. For example:

helm install ... --set extraEnv.SCALR_AGENT_PROVIDER_CACHE_ENABLED=true

Configuration Options

Core

Basic Scalr Agent configuration options.

SCALR_URL

The Scalr API endpoint. For tokens generated after Scalr version 8.162.0, this value is optional, as the domain can be extracted from the token payload. However, it is recommended to specify the URL explicitly for long-lived services to avoid issues if the account is renamed.

SCALR_AGENT_TOKEN

The agent pool token for the Scalr API.

SCALR_AGENT_DEBUG

Enable debug logs.

Default: false

SCALR_AGENT_DATA_DIR

The agent data directory for the Runs data files, the configuration versions and OpenTofu/Terraform plugins cache. The data directory must be readable, writable, and executable (to execute the OpenTofu/Terraform plugin binaries).

SCALR_AGENT_CACHE_DIR

The path to a directory used to store all cache data, including cached OpenTofu/Terraform/OPA/Infracost release binaries and Terraform/OpenTofu provider caches. It is important to ensure that this directory is backed by sufficient storage. Defaults to $SCALR_AGENT_DATA_DIR.

SCALR_AGENT_HOOKS_DIR

The path to the directory containing the agent hooks. If running the agent within Docker, ensure the directory is mounted to an agent container or build into the agent image.

SCALR_AGENT_NAME

The unique name of the agent. Once set it can be changed.

SCALR_AGENT_CONCURRENCY

The maximum number of Scalr run tasks the Scalr Agent can execute concurrently. This setting is configurable only for the system agent pool. It must not exceed the worker_concurrency settings and does not include service agent tasks, such as cancel.

Default: 5

SCALR_AGENT_LOG_FORMAT

The log formatter. Options: plain, dev or json.

Default: plain

SCALR_AGENT_DISCONNECT_ON_STOP

Determines whether the agent should automatically disconnect from the Scalr agent pool when the service is stopping.

Default: false

SCALR_AGENT_SKIP_OS_CHECK

Determines whether the agent should skip an operating system compatibility check.

Default: false

SCALR_AGENT_CA_CERT

The CA certificates bundle to use for all agent requests and container tasks. The CA file can be located inside the agent VM, allowing selection of a certificate by its path. If running the agent within Docker, ensure the certificate is mounted to an agent container. Alternatively, a base64 string containing the certificate bundle can be used. The example encoding it: cat /path/to/bundle.ca | base64.The bundle should include both your private CAs and the standard set of public CAs.

SCALR_AGENT_SINGLE

Determines whether the agent should run in a single mode. Agent pulls one task, executes it and terminates.

Default: false

SCALR_AGENT_RUNTIME

The Scalr Agent runtime. Determines the environment in which the Scalr Agent is running. By default, the runtime is automatically selected based on environment attributes. This option is not meant to be overridden unless required for edge cases where it cannot be correctly determined. The runtime option is primarily informational and used for statistics and minor behavioral tweaks, such as logging or error messages. It is also used to auto-select the default driver.

Default: unknown

SCALR_AGENT_DRIVER

The execution driver for the agent tasks. Determines how the Scalr Agent isolates task execution environments for running user-executable code (like Opentofu/Terraform applies). By default driver is auto-selected between docker and kubernetes based on runtime. If the local driver is selected, the Scalr Agent will execute tasks directly in the same environment where it is running, without isolation.

SCALR_AGENT_TASK_ACQUIRE_RATE

Defines the probability (as a fraction) that an agent will attempt to acquire a task. For example, a value of 0.1 means the agent will skip the acquire attempt 90% of the time.By default, the agent attempts to acquire tasks every 10 seconds, or when it receives an Acquire Task message from the Scalr Platform (if Scalr-to-Agent messaging is supported) aiming for the equal distibution across all agents in the pool.

Default: 1.0

SCALR_AGENT_STATE_PERSISTENCE_ENABLED

Option to control whether the agent persists connection state to disk. When set to false, the agent operates in stateless mode. It does not store connection information in $SCALR_AGENT_DATA_DIR/.agent.state and reconnects using its configured name on each startup ($SCALR_AGENT_NAME or hostname). The agent automatically disconnects on shutdown to prevent name conflicts. This option is particularly useful for stateless workloads such as serverless agents and ephemeral containers, and improves agent startup time. Disabled persistence is planned to become the default behavior in future releases to simplify agent lifecycle management.

Default: true

SCALR_AGENT_RUNNER_LIVECHECK_ENABLED

Enable runner container/subprocess liveness checks. This performs periodic checks via the driver platform (Docker, Kubernetes, etc.) to ensure the runner container is still alive. This handles cases when the container is killed manually or by the runtime (Kubernetes Pod eviction, OOM kill, etc.).

Default: true

SCALR_AGENT_RUNNER_LIVECHECK_INTERVAL

Interval in seconds between liveness check executions.

Default: 30

Docker

The Docker Driver configuration options.

SCALR_AGENT_DOCKER_HOST_URL

The path to the docker daemon socket.

Default: unix:///var/run/docker.sock

Kubernetes

The Kubernetes Driver configuration options.

SCALR_AGENT_KUBERNETES_SERVICE_ACCOUNT

The path to the service account file.

Default: /var/run/secrets/kubernetes.io/serviceaccount

SCALR_AGENT_KUBERNETES_URL

The kubernetes API endpoint.

Default: kubernetes.default.svc

SCALR_AGENT_KUBERNETES_CERTIFICATE

The kubernetes certificate for the API endpoint.

SCALR_AGENT_KUBERNETES_TOKEN

The kubernetes API token.

SCALR_AGENT_KUBERNETES_NAMESPACE

The kubernetes namespace to create the task pods within.

SCALR_AGENT_KUBERNETES_MODE

The mode that limits the set of responsibilities for the Scalr agent deployed on the Kubernetes cluster includes three options. The controller option means the agent is responsible for consuming the Scalr agent's task queue and scheduling the pods on the cluster. The worker option indicates the agent is responsible for watching incoming pods on the local node, supervising them, and committing results to the Scalr API. Despite this, the worker still connects to Scalr agent pools to receive service tasks.

Default: default

SCALR_AGENT_KUBERNETES_TASK_LABELS

Extra labels to apply to the agent task pods.

SCALR_AGENT_KUBERNETES_TASK_ANNOTATIONS

Extra annotations to apply to the agent task pods

SCALR_AGENT_KUBERNETES_TASK_NODE_SELECTOR

The Kubernetes Node Selector to assign the agent tasks pods to the specific nodes in the cluster. The selector must match a node's labels for the pod to be scheduled on that node. See: https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes

SCALR_AGENT_KUBERNETES_TASK_TOLERATIONS

The Kubernetes Node Tolerations for the agent worker and the agent task pods.See: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#toleration-v1-core

SCALR_AGENT_KUBERNETES_EFS_CLAIM_NAME

The name of the EFS Persistent Volume Claim. Enables shared EFS usage instead of using a host disk.

SCALR_AGENT_KUBERNETES_AUTOMOUNT_SERVICE_ACCOUNT_TOKEN

Enable automatic mounting of the service account token into the agent task pods.

Default: false

SCALR_AGENT_KUBERNETES_TERMINATION_GRACE_PERIOD_SECONDS

The duration, in seconds, that an agent task pod is allowed to shut down gracefully before it is forcefully terminated. A value of 0 forces immediate deletion.

Default: 30

SCALR_AGENT_KUBERNETES_JOB_TEMPLATE

The name of the AgentTask resource template for agent tasks. AgentTask is a CRD resource (atasks.scalr.io) containing a Kubernetes Job template used to create agent task jobs.

Default: scalr-agent-task

Container Tasks

Container task settings control how the Scalr Agent isolates Scalr tasks (run stages) using container runtimes.
These settings are relevant for the docker and kubernetes drivers (see SCALR_AGENT_DRIVER config option).

SCALR_AGENT_CONTAINER_TASK_SCHEDULING_TIMEOUT

The container task's (e.g. Kubernetes Pod) scheduling timeout in seconds. The task will be waiting for the scheduling in the queued status, if the cluster does not allocate resources for the container in that timeout the task will be switched to the errored status.

Default: 120

SCALR_AGENT_CONTAINER_TASK_ACQUIRE_TIMEOUT

The timeout in seconds for the agent worker to acquire the container task (e.g., Kubernetes Pod). This timeout is primarily relevant in Kubernetes node autoscaling scenarios. It includes the time to spin up a new Kubernetes node, pull the agent worker image onto it, deploy the agent worker as part of a DaemonSet, and the time for the worker to launch and acquire the task to continue the run's execution.

Default: 180

SCALR_AGENT_CONTAINER_TASK_CPU_REQUEST

CPU resource request defined in cores. If your container needs two full cores to run, you would put the value 2. If your container only needs ¼ of a core, you would put a value of 0.25 cores.

Default: 1.0

SCALR_AGENT_CONTAINER_TASK_CPU_LIMIT

CPU resource limit defined in cores. If your container needs two full cores to run, you would put the value 2. If your container only needs ¼ of a core, you would put a value of 0.25 cores.

Default: 8.0

SCALR_AGENT_CONTAINER_TASK_MEM_REQUEST

Memory resource request defined in megabytes.

Default: 1024

SCALR_AGENT_CONTAINER_TASK_MEM_LIMIT

Memory resource limit defined in megabytes

Default: 16384

SCALR_AGENT_CONTAINER_TASK_CPU_QOS

Memory QoS controls the ratio of guaranteed memory resources a Run can use, relative to the total limit allowed by the billing plan (applies to plan and apply tasks). This configuration is applicable only to System Agents.

Default: 0.1

SCALR_AGENT_CONTAINER_TASK_MEM_QOS

CPU QoS controls the ratio of guaranteed CPU resources a Run can use, relative to the total limit allowed by the billing plan (applies to plan and apply tasks). This configuration is applicable only to System Agents.

Default: 0.1

SCALR_AGENT_CONTAINER_TASK_PIDS_LIMIT

The maximum number of process IDs (PIDs) a container can spawn.

Default: 8192

SCALR_AGENT_CONTAINER_TASK_CA_CERT

The CA certificates bundle to mount it into the container task at /etc/ssl/certs/ca-certificates.crt. The CA file can be located inside the agent VM, allowing selection of a certificate by its path. If running the agent within Docker, ensure the certificate is mounted to an agent container. Alternatively, a base64 string containing the certificate bundle can be used. The example encoding it: cat /path/to/bundle.ca | base64.The bundle should include both your private CAs and the standard set of public CAs.

SCALR_AGENT_CONTAINER_TASK_PRESERVE

Do not delete the containers immediately after the tasks completion. In this mode, containers will remain for some time until they are deleted by GC. This option is intended for debugging issues with the containers.

Default: false

SCALR_AGENT_CONTAINER_TASK_IMAGE_REGISTRY

Enforce the use of a custom image registry to pull all container task images. All images must be preemptively pushed to this registry for the agent to work with this option. The registry path may include a repository to be replaced. If the path ends with a trailing slash, it will be appended to the original repository.Example: 'mirror.io', 'mirror.io/myproject' or 'mirror.io/myproject/'.

SCALR_AGENT_CONTAINER_TASK_IMAGE

Enforce the use of a custom runner image instead of the default scalr/runner:x.y.z. It can also be used to pin a specific version of the scalr/runner image, as by default this is controlled by the Scalr platform settings. This option only applies if software binary releases are enabled for the agent pool's account. This option will ignore SCALR_AGENT_CONTAINER_TASK_IMAGE_REGISTRY.

Provider Cache

OpenTofu/Terraform provider cache settings. Learn more about provider cache.

SCALR_AGENT_PROVIDER_CACHE_ENABLED

Enables or disables the OpenTofu/Terraform provider cache. When enabled, the Scalr Agent can download providers pinned via the dependency lockfile concurrently across all runs, cache them using a Terraform plugins filesystem mirror, and handle missing records for platform-specific hashes absent in the lockfile.

Default: true

SCALR_AGENT_PROVIDER_CACHE_INSTALL_TIMEOUT_SEC

Timeout in seconds for downloading and installing all provider plugins for OpenTofu/Terraform locked via the dependency file. This setting defines the maximum number of seconds a run can spend on provider installation by the Scalr Agent, outside of the Terraform initialization phase.

Default: 60

SCALR_AGENT_PROVIDER_CACHE_WARM_UP_FROM_LOCKFILE

Warm up the Provider Cache by downloading providers listed in the lockfile concurrently using the Scalr Agent, before OpenTofu/Terraform initialization begins, instead of relying on the OpenTofu/Terraform core process.

Default: true

SCALR_AGENT_PROVIDER_CACHE_CONCURRENCY

Maximum number of threads used for provider installations. This value is global for the Scalr service and applies across all concurrent runs. Increasing it will increase resource consumption and may improve provider installation speed, but the effect depends on individual setups.

Default: 10

SCALR_AGENT_PROVIDER_CACHE_SIZE_LIMIT_MB

Maximum size (in megabytes) for the OpenTofu/Terraform Provider Cache.

SCALR_AGENT_PROVIDER_CACHE_THRESHOLD_DAYS

Threshold for unused plugins (in days). If a provider is not used for more than N days, it will be removed from the OpenTofu/Terraform Provider Cache.

Default: 10

SCALR_AGENT_PROVIDER_CACHE_DROP_KERNEL_PAGES

Whether to drop Linux kernel page cache entries for the OpenTofu/Terraform Provider Cache directory. This frees cached filesystem pages but does not remove any actual provider files.

Default: true

Module Cache

OpenTofu/Terraform module cache settings. Learn more about module cache.

SCALR_AGENT_MODULE_CACHE_ENABLED

Enables or disables the Terraform/OpenTofu module cache. When enabled, the agent initializes .terraform/modules from a global cache before init and caches newly downloaded modules after init.

Default: false

SCALR_AGENT_MODULE_CACHE_SIZE_LIMIT_MB

Maximum size (in megabytes) for the module cache. This is a soft limit: modules used within the last 12 hours are not deleted, and actual disk usage may exceed this value.

Default: 10240

SCALR_AGENT_MODULE_CACHE_THRESHOLD_DAYS

Time-to-live for cached modules, in days.

Default: 10

SCALR_AGENT_MODULE_CACHE_CONCURRENCY

Maximum number of threads used for module cache operations (initialization and caching). This value is global for the Scalr service and applies across all concurrent runs. Increasing it will increase resource consumption and may improve module cache speed, but the effect depends on individual setups.

Default: 10

Telemetry

The OpenTelemetry configuration.

SCALR_AGENT_OTLP_ENDPOINT

The host:port address of an OpenTelemetry collector – a gRPC server running an OTLP collector.

SCALR_AGENT_OTLP_TRACES_ENABLED

Enable OpenTelemetry tracing.

Default: false

SCALR_AGENT_OTLP_METRICS_ENABLED

Enable OpenTelemetry metrics.

Default: false

SCALR_AGENT_SENTRY_DSN

Sentry DSN for error reporting. Set to enable Sentry integration.

SCALR_AGENT_SENTRY_ENVIRONMENT

Environment name for Sentry (e.g., 'production', 'staging', 'dev').

HTTP Proxy

To configure an HTTP proxy, set the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables.

Example of running agent with HTTP proxy enabled:

$~ docker run \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/scalr-agent:/var/lib/scalr-agent \
  -e SCALR_AGENT_TOKEN={token} \
  -e HTTP_PROXY="{proxy-address}" \
  -e HTTPS_PROXY="{proxy-address}" \
  -e NO_PROXY="{addr1},{addr2}" \
  --rm -it --pull=always --name=scalr-agent scalr/agent:latest run

SSL Certificate Bundles

To configure SSL certificates globally, use the SCALR_AGENT_CA_CERT option.
To configure SSL certificates only for isolated containers for the tasks (e.g. tofu/terraform/infracost operations), set the SCALR_AGENT_CONTAINER_TASK_CA_CERT option.

The CA file can be located on the agent's VM, allowing a certificate to be selected by its file path.
If the agent is running within Docker, ensure the certificate is mounted into the agent container.

Alternatively, a base64-encoded string containing the certificate bundle can be used.

Example of encoding a bundle:

$~ cat /path/to/bundle.ca | base64

Example of running agent with custom CA certifcates:

$~ docker run \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/scalr-agent:/var/lib/scalr-agent \
  -e SCALR_AGENT_TOKEN={token} \
  -e SCALR_AGENT_CA_CERT=/var/lib/scalr-agent/ca.cert \
  --rm -it --pull=always --name=scalr-agent scalr/agent:latest run

Note that the certificate is located in the /var/lib/scalr-agent/ directory, which is mounted into the container.

You can optionally bundle your certificate into an agent image. Place the custom CA file at extra_ca_root.crt and build the customized image:

FROM scalr/agent:latest

ADD extra_ca_root.crt /usr/local/share/ca-certificates/extra-ca.crt
RUN apt update \
    apt install ca-certificates -y \
    chmod 644 /usr/local/share/ca-certificates/extra-ca.crt \
    update-ca-certificates
ENV SCALR_AGENT_CA_CERT="/etc/ssl/certs/ca-certificates.crt"

This step also bundles your certificate with the set of public certificates provided by ca-certificates
system package. You can optionally skip this step and instead point SCALR_AGENT_CA_CERT to your certificate
if it already includes public CA certificates or if they are not needed (e.g., in a setup completely
hidden behind a proxy).

Note that by default, the scalr agent uses the certificate bundle provided by the certifi package instead of the system certificate bundle provided by the ca-certificates package.