What is a serverless agent?

A serverless agent is a Scalr Agent that starts on demand, executes one task, and exits. It runs in a container on your compute platform, such as AWS Fargate. You can execute OpenTofu and Terraform runs without keeping agents running between tasks.

For intermittent or variable workloads, this can reduce idle compute costs. Agents start as demand grows, so you do not need to keep a fixed fleet running for peak demand.

Serverless agents use the same scalr/agent image as other agent deployments. The difference is how they start and stop: Scalr calls a webhook endpoint you configure to start an agent container. The agent shuts down after completing its task.

For deployment options, see Installation. To use another container platform, start with the webhook reference.

Set up the agent pool

You need permission to create and manage agent pools. The standard agent network requirements apply.

The webhook URL is the public HTTP address Scalr calls to start an agent container.

1. Deploy a webhook endpoint in your cloud platform that accepts POST requests and launches agent containers. Follow the webhook reference for the request format and retry handling.
2. Create a run agent pool and turn on Enable serverless execution.
3. Enter the deployed endpoint's URL in API Gateway URL. Add any custom headers your endpoint requires under Headers.
4. Save the pool. On its Tokens tab, generate an agent pool token and store it as plaintext in your platform's secret store.
5. In your platform's container definition, set the image to scalr/agent. Add the environment variable SCALR_AGENT_SINGLE=true. Inject the pool token from the secret store as SCALR_AGENT_TOKEN. See agent container settings for driver selection and optional settings.
6. Assign the pool to a workspace and start a run. Verify that an agent connects, completes a task, and stops.

An empty agent list on the pool's page is normal when the pool is idle. Agents start and register with the pool on demand when a run needs them, then disappear from the list after completing their tasks.

How serverless agents start

Scalr requests an agent by sending an HTTP POST request to the pool's webhook URL. Your endpoint translates that request into a container launch on your compute platform. On AWS, for example, API Gateway receives the request, Lambda handles it, and ECS starts the container on Fargate.

sequenceDiagram
    accTitle: Serverless agent invocation
    accDescr: Scalr calls your webhook, your platform starts an agent for the requested task, and the agent acquires that task from Scalr and reports its results before exiting.
    participant S as Scalr
    participant W as Your webhook
    participant P as Container platform
    participant A as Scalr Agent
    S->>W: Request an agent
    W->>P: Launch container
    P-->>W: Launch accepted
    W-->>S: HTTP 2xx
    P->>A: Start agent
    A->>S: Connect and acquire task
    S-->>A: Assigned task
    A->>S: Report logs and results
    Note over A: Exit after the task

The sequence is:

1. A workspace that uses the pool reaches a run stage that needs an agent.
2. Scalr creates an agent task and sends a webhook request with the task and run IDs.
3. Your endpoint asks the container platform to start a Scalr Agent for that task and responds to Scalr. It returns without waiting for the agent to finish.
4. The agent connects to Scalr using its agent pool token and acquires the task identified in the webhook.
5. The agent executes the task, reports logs and results to Scalr, and exits.

Scalr manages the run stages and the queue of agent tasks. You manage the webhook endpoint, container configuration, networking, and compute capacity.

Agent lifecycle

An agent task is one unit of work, such as a plan, an apply, or a policy check. Each serverless agent executes the task identified in its webhook request, then disconnects from Scalr and its container stops.

A run can create several agent tasks and use several isolated containers.

Set SCALR_AGENT_SINGLE=true to exit after one task. The local driver executes the task inside the agent container and is selected automatically on Fargate.

Run stages and containers

The container lifetime follows the agent task, while the run continues through its remaining stages.

A run with a plan and an apply uses at least two agent containers. Container startup adds time to each stage that needs an agent.

Single-mode agents disconnect and remove themselves from the pool when they stop. Keep the container logs in your platform's logging service so you can investigate completed tasks.

Failure handling

Webhook delivery, container startup, and task execution are separate steps. A successful response from the webhook confirms delivery of the request. It does not confirm that the container started or that the agent completed a task.

See the webhook reference for response requirements, retry timing, and handling duplicate requests.

Webhook delivery fails

Scalr retries when the endpoint cannot be reached, times out, or returns a non-2xx status. It makes up to 3 delivery attempts in total. Retries stop early if the agent task is no longer pending, for example because it was acquired or the run was canceled.

The pool's Webhook deliveries tab in Scalr lists each delivery with its HTTP status. Use the endpoint's access logs to identify where delivery fails:

• No request appears: verify that API Gateway URL on the pool includes the endpoint's full route and is publicly reachable.
• The endpoint returns 401 or 403: verify that the pool's custom headers contain the credentials your endpoint requires.
• The endpoint returns 5xx or times out: inspect the handler logs for container launch errors. The handler must respond once the launch request is accepted, without waiting for the agent to finish.

The container fails to start

After the webhook returns 2xx, Scalr considers the request delivered. A later container startup failure does not trigger a retry of that delivered webhook. Check your platform's task status and logs for image pull errors, missing secrets, network failures, or exhausted capacity.

The agent stops during a task

If a container crashes or is terminated during a task, open the affected run stage in Scalr to see its last output. Inspect the container's logs, exit code, and termination reason to identify why it stopped.

Troubleshooting

The agent exits before acquiring its task

The agent exits when it cannot acquire its assigned task before the timeout. This can happen if the run is canceled before the agent connects or if a duplicate launch creates another container for the same task.

Use the webhook's run_id to check whether the run was canceled. If several containers were launched for the same task_id, make sure the handler reuses the original launch for repeated Idempotency-Key values. See webhook retries.

Find the task a container runs

Set SCALR_AGENT_LOG_FORMAT=json and inspect the container logs:

1. Find Connected to agent pool. The agent_id and agent_name identify the agent. Its name comes from SCALR_AGENT_NAME, or the container hostname when no name is configured.
2. Find task log entries with task_id and task_name. Match task_id to the webhook's task_id, then use the request's run_id to find the run in Scalr.
3. After the task completes, look for Terminating after task completion due to single mode... and confirm that the container stops.

For AWS-specific errors, see Fargate troubleshooting.