> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komodor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scale agents to zero

> Run no replica while an agent is idle. A request wakes the agent, and its runs wait until a replica is ready.

An agent that scales to zero runs no replica while it is idle, so it uses no resources between
runs. When work arrives, KEDA starts a replica, and the Komodor Agentic Operation Platform (KAOP)
holds the run until the replica takes it. This works for self-hosted agents and for agents that
Komodor hosts. Use it for an agent that runs now and then, such as one that a schedule or an alert
triggers. For an agent that people chat with and expect an answer at once, keep at least one
replica.

Scale to zero is turned on per account, separately for self-hosted agents and for Komodor-hosted
agents. If the wizard does not offer it for your kind of agent, ask your account team to turn it on.

## How it works

| | While the agent is idle | When work arrives |
| - | - | - |
| **At least one replica** | A replica runs. | The run starts at once. |
| **Scale to zero** | No replica runs. | KEDA starts replicas, one per queued run by default, up to **Max replicas**. The run waits until a replica takes it. |

After a period with no work (`cooldownPeriod`, 300 seconds by default), KEDA scales the agent back
to zero.

## Turn it on for a self-hosted agent

### Before you start

* **KEDA 2.10 or later** in the agent's cluster. On a [deploy
  target](https://docs.komodor.com/manage-your-agents/build/koperator/overview), koperator can install KEDA for you (see
  [KEDA](https://docs.komodor.com/manage-your-agents/build/koperator/configure.md#keda)).
* **KEDA reaches KAOP.** KEDA asks KAOP for the agent's queue depth, with the agent's worker token,
  over outbound HTTPS to your KAOP host. If the cluster's egress goes through a proxy, KEDA needs it
  too. No replica has to run for KEDA to find the agent.
* **On a deploy target, the guardrails allow it.** The deploy target's `guardrails.runBehaviours`
  must include `scale_to_zero`, and **Max replicas** must not be above its `guardrails.maxReplicas`.
  If the deploy target cannot scale to zero, the wizard says why.

### Set the run behaviour

In the create or edit wizard, on the **Where it runs** step, choose **Scale to zero** instead of
**Always on**. Then set:

| Field | What it sets |
| - | - |
| **Max replicas** | The most replicas KEDA starts for this agent. Default 5. |
| **Hold timeout (seconds)** | How long a run waits for the agent to wake before it fails. 30 to 1800, default 300. |

On a deploy target, koperator applies the change. For an agent you install with Helm yourself, run
`helm upgrade` with the values KAOP generates; they set `autoscaling.keda.enabled: true` and
`minReplicaCount: 0` (see [Scaling with
KEDA](https://docs.komodor.com/manage-your-agents/build/deploy-a-self-hosted-agent.md#scaling-with-keda)). To wake faster,
lower `autoscaling.keda.pollingInterval` (30 seconds by default). KAOP refuses a value below 5
seconds.

> [!NOTE]
>
> Set the run behaviour in KAOP, not only in your values file. KAOP holds runs only for an agent whose
> run behaviour is **Scale to zero**. An agent with `minReplicaCount: 0` in its values but **Always
> on** in KAOP shows as offline when it has no replica, and its runs are not held.

On a deploy target, **Always on** runs a fixed replica count. To scale with the queued runs there,
choose **Scale to zero**.

## Turn it on for a Komodor-hosted agent

In the create or edit wizard, on the **Where it runs** step, set **Min replicas** to **0**. **Max
replicas** must be 1 or more, up to your account's limit. Komodor runs KEDA for you, so there is
nothing to install.

A Komodor-hosted agent differs from a self-hosted one:

* The hold timeout is 300 seconds, and KEDA polls every 30 seconds. You cannot change these values.
* A Komodor-hosted agent that you deliver from a Git repository has a fixed replica count, so it
  cannot scale to zero.
* If scale to zero is turned off for your account, the agent runs one replica. Its saved setting
  does not change, and the agent goes back to zero when scale to zero is turned on again.
* At zero, no pod pulls the image during a deploy, so KAOP asks the image's registry whether the
  image exists. If the registry says it does not, the deploy fails with "the image … was not found
  in its registry". KAOP cannot check an image in a private registry: a wrong tag then shows only
  when the first run starts a pod.

## While the agent is idle

Fleet shows the agent as **Idle**, not offline. Run, chat, Slack, direct invoke and A2A requests to
an idle agent are accepted, and each one wakes it:

| Surface | While the agent wakes |
| - | - |
| Chat | "Waking up the agent…", then the answer. |
| Slack thread | The first reply says "Waking up the agent", then changes to "Working" and to the answer. |
| Slack private command | The run-link message says "Waking up the agent", then the answer replaces it. |
| Streamed invoke and A2A | A "Waking up the agent…" status update, then the usual stream. |
| Invoke without streaming | Returns the queued run at once. |
| A2A `message:send` | Waits, then returns the task before it is finished. Read the result with `tasks/{id}`. |

The first reply after idle waits while a replica starts, which can take a minute or more. If no
replica takes the run before the hold timeout, the run fails with "The agent did not wake up in time
(5 min). Try again.", with the hold timeout in place of 5 min.

A stopped agent is not idle. A request does not wake it.

## When the agent does not wake

| You see | Do this |
| - | - |
| **Autoscaler not polling** on a self-hosted agent in Fleet | KEDA has not asked KAOP for the queue depth for three polling intervals plus a minute (about 2.5 minutes at the default interval). Check that KEDA runs and is 2.10 or later, that it reaches your KAOP host, and that the agent's worker token is not revoked. Runs wait up to the hold timeout, then fail. |
| A run fails with `cold_start_timeout` | No replica took the run in time. When the error adds `likely cause: autoscaler not polling since …` or `likely cause: autoscaler has never polled`, fix KEDA as above. Otherwise the replica started too slowly: look for a slow image pull or a pod that cannot be scheduled, or raise the hold timeout. For a Komodor-hosted agent, contact Komodor support. |
| A new self-hosted agent shows **Draft** after the install | KAOP sees the agent only when KEDA first polls, about 30 seconds after the install. A run sent before then is not held. |

## Next steps

> [card] [Deploy a self-hosted agent](https://docs.komodor.com/manage-your-agents/build/deploy-a-self-hosted-agent.md)
>
> The Helm values, including the KEDA block.

> [card] [Configure koperator](https://docs.komodor.com/manage-your-agents/build/koperator/configure.md)
>
> KEDA and the guardrails on a deploy target.


## Related topics

- [Deploy a self-hosted agent](https://docs.komodor.com/manage-your-agents/build/deploy-a-self-hosted-agent.md)
- [Deploy agents to a deploy target](https://docs.komodor.com/manage-your-agents/build/koperator/deploy-agents.md)
- [Configure koperator](https://docs.komodor.com/manage-your-agents/build/koperator/configure.md)
- [Koperator](https://docs.komodor.com/manage-your-agents/build/koperator/overview.md)
- [Uninstall koperator](https://docs.komodor.com/manage-your-agents/build/koperator/uninstall.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.