The Scalr Agent can be run as a Docker service, a Kubernetes deployment, or as a containerized service on platforms like AWS Fargate or Google Cloud Run.

Before installing an agent, you must first create an Agent Pool to connect it to, and obtain an Scalr agent token by registering a new agent on the Agent Pool page.

Docker

To deploy a run agent, use the following command:

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} \
  --rm -it --pull=always --name=scalr-agent scalr/agent:latest

You need to mount SCALR_AGENT_DATA_DIR for data persistence and provide the Docker socket to enable multi-concurrency with the Docker driver.

To deploy a VCS agent, provide only the Scalr agent token:

$~ docker run \
  -e SCALR_AGENT_TOKEN={token} \
  --rm -it --pull=always --name=scalr-agent scalr/agent:latest

You can also use Docker Compose to run agents as a service.
Below is an example docker-compose.yml file for a run agent:

services:
  scalr-agent:
    image: scalr/agent:latest
    container_name: scalr-agent
    environment:
      - SCALR_AGENT_TOKEN=${SCALR_AGENT_TOKEN}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/scalr-agent:/var/lib/scalr-agent
    pull_policy: always
    restart: unless-stopped

Place the content in the file and run the following command from the same directory:

docker compose up -d

Kubernetes

The agent can be deployed onto a Kubernetes cluster using one of the available Helm charts from https://github.com/Scalr/agent-helm.

agent-local

Deploys a static number of agents and executes runs in shared agent pods. This is the recommended default option for run agent pools and the only option for VCS agent pools.

Installation instructions · Changelog.

agent-job

Deploys an agent controller and executes runs in isolated stateless jobs. Suitable for environments with strict multi-tenancy requirements.

Installation instructions · Changelog.

agent-k8s

Deploys an agent controller with a set of stateful agent workers and executes runs in isolated pods. Suitable for environments with strict multi-tenancy requirements, but requires more complex configuration and a dedicated node pool.

Installation instructions · Changelog.

Chart versioning

The Scalr Agent (the scalr/agent image) supports runtimes beyond Kubernetes, so it is versioned independently from the chart's own version. Each chart records the agent version it was built and tested against in its appVersion field, and every new agent release triggers a new chart release with an updated appVersion.

Upgrade the agent by upgrading the chart to a release that ships the agent version you want.

Two changelogs cover different scopes:

• The Scalr Agent changelog — application-level changes and new Scalr platform functionality.
• Each chart's CHANGELOG.md on GitHub — chart-level changes: Kubernetes resources, values, and defaults.

Serverless

To run a long-lived agent on a container platform such as AWS Fargate or Google Cloud Run, deploy the scalr/agent image as a service.

To run agents on demand on platforms such as AWS Fargate, use a serverless agent pool. Scalr calls your webhook endpoint for each agent task, and the endpoint starts a container with SCALR_AGENT_SINGLE=true. See Serverless Agents.

Choose a deployment method for your serverless agent pool:

• Terraform or OpenTofu on AWS or Azure: use terraform-scalr-serverless to provision the cloud infrastructure and Scalr agent pool from code.
• Manual setup on AWS: follow Serverless Agent Pool on AWS Fargate to create and configure the resources step by step in the AWS and Scalr consoles.

Linux Packages Deprecation

The DEB and RPM Linux packages are planned for deprecation after March 31th, 2026.

After that date, Linux packages will still be available but will not receive any updates.

If you have any concerns, questions, or need help with the upgrade, please raise an issue via Scalr Support Center.

Upgrade Guide

To prepare for this change, please begin transitioning your agents to our recommended Docker or Kubernetes deployment methods. We recommend using Docker Compose to run agents as a service as the easiest drop-in replacement for Linux packages. This allows you to reconfigure the existing Scalr Agent on your instance to run under the system Docker daemon instead of the embedded one as part of the regular upgrade process.

Remove the existing Linux package

For Debian/Ubuntu (DEB):

sudo systemctl stop scalr-agent
sudo apt-get remove scalr-agent

For RHEL/CentOS/Fedora (RPM):

sudo systemctl stop scalr-agent
sudo yum remove scalr-agent
# or for newer systems
sudo dnf remove scalr-agent

Install Docker and Docker Compose

Follow the official Docker installation instructions for your platform: https://docs.docker.com/engine/install/

If you want to manage Docker as a non-root user, follow these post-installation steps: https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user

Create Docker Compose configuration

Create a docker-compose.yml file in a directory of your choice. In this example, we'll use /opt/scalr-agent:

services:
  scalr-agent:
    image: scalr/agent:latest
    container_name: scalr-agent
    restart: unless-stopped
    env_file:
      - /etc/scalr-agent/agent.conf
    volumes:
      - /var/lib/scalr-agent:/var/lib/scalr-agent
      - /var/run/docker.sock:/var/run/docker.sock
    pull_policy: always
    restart: unless-stopped

The SCALR_AGENT_TOKEN (or SCALR_TOKEN) is expected to be present in the existing /etc/scalr-agent/agent.conf configuration file. If it missing, add it to your Docker Compose configuration:

...
services:
  scalr-agent:
    image: scalr/agent:latest
    container_name: scalr-agent
    restart: unless-stopped
    environment:
      - SCALR_AGENT_TOKEN=<your-token-here>
    ...

Start the agent

cd /opt/scalr-agent/
docker compose up -d

Verify the agent is running

Check the agent logs:

docker logs scalr-agent

Verify the agent is connected to your pool in the Scalr UI.

Check the container status:

docker ps | grep scalr-agent

Enable automatic startup

The restart: unless-stopped policy in the Docker Compose file ensures the agent starts automatically on system boot. To verify Docker starts on boot:

sudo systemctl enable docker