Guides
Log InSign UpBlog
Start typing to search…

Configuration Options

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

Boolean flag to enable debug logs. Defaults to false.

SCALR_AGENT_DATA_DIR

The agent data directory for the run data files, the configuration versions, and the OpenTofu/Terraform plugins cache. The data home directory must be readable, writable, and executable (to execute the OpenTofu/Terraform plugin binaries). Defaults to /var/lib/scalr-agent.

SCALR_AGENT_NAME

The unique name of the agent. Once set, it can be changed. Defaults to hostname.

SCALR_AGENT_BACKEND

The Scalr Agent backend. Determines the environment in which the Scalr Agent is running. By default, the backend is automatically selected based on environment attributes. This option is not meant to be overridden, unless required for edge cases — e.g., Docker-in-Docker on Kubernetes. The backend 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. Options: "vm", "fargate", "docker", "kubernetes", "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, the driver is auto-selected between Docker and Kubernetes based on backend. If the local driver is selected, the Scalr Agent will execute tasks directly in the same environment where it is running, without isolation. Options: "local", "kubernetes", "docker". Defaults to docker.

SCALR_AGENT_SINGLE

Determines whether the agent should run in a single mode. The agent pulls one task, executes it, and terminates. The SCALR_AGENT_CONCURRENCY is limited to 1 in single mode. Defaults to false.

SCALR_AGENT_CONCURRENCY

The maximum number of Scalr tasks (run stages) the Scalr Agent can execute concurrently. The maximum value is limited to 5.

SCALR_AGENT_LOG_FORMAT

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

SCALR_AGENT_DISCONNECT_ON_STOP

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

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.

Docker

SCALR_AGENT_DOCKER_HOST_URL

The path to the Docker daemon socket. Default: unix:///var/run/docker.sock

Kubernetes

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. Default: None

SCALR_AGENT_KUBERNETES_TOKEN

The Kubernetes API token. Default: None

SCALR_AGENT_KUBERNETES_NAMESPACE

The Kubernetes namespace to create the task pods within. Default: None

SCALR_AGENT_KUBERNETES_MODE

The mode that limits the set of responsibilities for the Scalr agent deployed on the Kubernetes cluster. Options: controller, worker, default Default: default

  • controller: The agent is responsible for consuming the Scalr agent's task queue and scheduling the pods on the cluster.
  • worker: The agent watches incoming pods on the local node, supervises them, and commits results to the Scalr API. The worker still connects to Scalr agent pools for service tasks.
  • default: The agent acts as both controller and worker simultaneously.

SCALR_AGENT_KUBERNETES_TASK_LABELS

Extra labels to apply to the agent task pods. Default: None

SCALR_AGENT_KUBERNETES_TASK_ANNOTATIONS

Extra annotations to apply to the agent task pods. Default: None

SCALR_AGENT_KUBERNETES_TASK_NODE_SELECTOR

The Kubernetes Node Selector to assign agent task pods to specific nodes in the cluster. The selector must match a node’s labels for the pod to be scheduled. Default: None See the Kubernetes Node Selector documentation

SCALR_AGENT_KUBERNETES_TASK_TOLERATIONS

The Kubernetes Node Tolerations for the agent worker and the agent task pods. Default: None See the Kubernetes Node Tolerations documentation

SCALR_AGENT_KUBERNETES_EFS_CLAIM_NAME

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

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 seconds

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).

See for more.

SCALR_AGENT_CONTAINER_TASK_SCHEDULING_TIMEOUT

The container task's (e.g., Kubernetes Pod) scheduling timeout in seconds. The task will wait in the queued status; if the cluster does not allocate resources within the timeout, the task switches 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). Primarily relevant in Kubernetes node autoscaling scenarios. Default: 180

SCALR_AGENT_CONTAINER_TASK_CPU_REQUEST

CPU resource request defined in cores. Default: 1.0

SCALR_AGENT_CONTAINER_TASK_CPU_LIMIT

CPU resource limit defined in 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_PIDS_LIMIT

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

SCALR_AGENT_CONTAINER_TASK_DISK_QUOTA_ENABLED

Enable the container task disk quota for the data volume. If enabled, the agent will set up XFS quotas based on the container task volume specification. Default: False

SCALR_AGENT_CONTAINER_TASK_CA_CERT

The CA certificates bundle to mount into the container task at /etc/ssl/certs/ca-certificates.crt. The CA file can be located inside the agent VM, allowing selection by path. If running in Docker, ensure the certificate is mounted to the agent container. Alternatively, use a base64 string containing the certificate bundle (e.g., cat /path/to/bundle.ca | base64). The bundle should include both your private CAs and the standard set of public CAs. Default: None

SCALR_AGENT_CONTAINER_TASK_PRESERVE

Do not delete the containers immediately after task completion. In this mode, containers will remain for some time until deleted by garbage collection. Intended for debugging issues with 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/. Default: None

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." Default: None

Provider Cache

OpenTofu/Terraform provider cache settings. See for more

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_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_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_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. Old name: SCALR_AGENT_GC_PLUGINS_GLOBAL_SIZE_LIMIT. Default: 2560

SCALR_AGENT_PROVIDER_CACHE_TREASHDOLD_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

Agent Worker

Configuration options for the tasks worker. The tasks worker is responsible for executing tasks concurrently.

SCALR_AGENT_WORKER_CONCURRENCY

The maximum number of total tasks (both Scalr tasks and internal tasks) that the worker can handle at the same time. Default: 10

SCALR_AGENT_WORKER_ON_STOP_ACTION

Defines the SIGTERM/SIGHUP/SIGINT signal handler's shutdown behavior. Options: drain, grace-shutdown, force-shutdown Default: grace-shutdown

  • drain: Partially stops the consumer and waits for all active jobs to complete before exiting. If a drain_timeout is specified, the process will transition to a grace-shutdown routine after the designated time. A sequential SIGTERM also triggers grace-shutdown, where actual jobs are rejected (e.g., terraform.plan, terraform.apply), but service tasks like worker.task.cancel are allowed.
  • grace-shutdown: Stops the consumer, sends a SIGTERM signal to all active jobs, and waits for them to conclude before shutting down. If jobs do not finish within the graceful_shutdown_timeout, the process shifts to a force-shutdown routine. Similarly, a sequential SIGTERM prompts a transition to force-shutdown.
  • force-shutdown: Stops the consumer, sends a SIGKILL signal to all active jobs, and allows 10 seconds for all tasks to terminate before exiting.

SCALR_AGENT_WORKER_DRAIN_TIMEOUT

The timeout for draining worker tasks in seconds. After this timeout, tasks will be terminated via the SIGTERM signal. Default: None

SCALR_AGENT_WORKER_GRACE_SHUTDOWN_TIMEOUT

The timeout in seconds for gracefully shutting down active tasks via the SIGTERM signal. After this timeout, tasks will be terminated with the SIGKILL signal. Default: 60

Telemetry

The OpenTelemetry configuration.

SCALR_AGENT_OTLP_ENDPOINT

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

SCALR_AGENT_OTLP_TRACES_ENABLED

Enable OpenTelemetry tracing.

SCALR_AGENT_OTLP_METRICS_ENABLED

Enable OpenTelemetry metrics.

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.


Updated 1 day ago