Skip to main content
Cake Agents can automatically grow each session’s persistent volume as it fills up. The control plane periodically reads disk usage for every running session from the kubelet and expands the session’s PersistentVolumeClaim when usage crosses a high watermark. Autoscaling is enabled by default in the Helm chart.

​
Why autoscaling helps

  • Sessions clone large repositories or produce build artifacts that outgrow the initial volume size.
  • You want to keep sessionVolume.initialSize small and pay only for storage that sessions actually use. See the Helm values reference for the sessionVolume block.
If autoscaling is disabled, sessions keep their initial volume size and can run out of disk space during long or storage-heavy work.

​
When to disable autoscaling

Set diskAutoscale.enabled: false when your cluster cannot meet the prerequisites below, such as clusters that are not on EKS or that lack kubelet fine-grained authorization.

​
Prerequisites

  • An EKS cluster with kubelet fine-grained authorization enabled. The control plane reads volume telemetry directly from each node’s kubelet, which must accept the control plane’s service account token.
  • A StorageClass with allowVolumeExpansion: true for session volumes. Cake Agents skips expansion when the StorageClass does not allow it.
  • rbac.enabled: true in the Helm chart. When autoscaling is enabled, the chart adds a ClusterRole that grants the control plane get on nodes/metrics and storageclasses.

​
Configure with Helm values

Tune or disable autoscaling through the diskAutoscale block:
The chart maps these values to SESSION_DISK_AUTOSCALE_* environment variables on the control plane. The control plane validates the configuration at startup and rejects invalid ratios, scale factors, storage quantities, and cron expressions.

​
Configure in the UI

You can also manage autoscaling from the organization settings:
  1. Go to Settings → Organization → Sessions.
  2. In the Autoscaling section, make sure Enabled is toggled on.
  3. Adjust the fields:
    • Starting Volume Size — the size each new session volume starts at. Whole GiB values only, at least 1 Gi, and no larger than the max volume size. Applies to newly created sessions.
    • High Watermark Ratio — usage fraction that triggers expansion. Must be between 0 and 1, exclusive.
    • Max Volume Size — hard cap on any session volume’s size. Must be at least 1 Gi.
    • Minimum Increment — smallest amount a volume grows in a single expansion.
    • Scale Factor — multiplier applied to current usage to compute the new size. Must be greater than 1.
  4. Select Save.
Changes apply only when you save. The form validates all fields together and rejects a starting volume size that exceeds the max volume size. Saved changes take effect on the next scheduled reconciliation run without a control plane restart.

​
Settings precedence

  • Until you save autoscaling settings in the UI, the control plane uses the Helm values (diskAutoscale and sessionVolume.initialSize).
  • Before your first save, the Autoscaling section shows these Helm values. If diskAutoscale.enabled is true, the section appears enabled and its fields show the effective configuration. Sizes in units other than Mi or Gi, such as 2Ti, appear converted to Gi.
  • Once saved, UI settings replace the Helm values for the expansion policy and the starting volume size.
  • Disabling autoscaling in the UI turns it off even when diskAutoscale.enabled is true in Helm.
  • The reconciliation schedule (cronExpression) always comes from Helm.

​
How expansion works

On each scheduled run, the control plane:
  1. Lists running session pods and collects filesystem telemetry for each session volume from the node’s kubelet. Stale or malformed telemetry is rejected and logged, and that volume is skipped for the run.
  2. Compares used bytes against the volume’s current size. Volumes below highWatermarkRatio are left unchanged.
  3. Computes the new size as the larger of current size + minIncrement and used bytes × scaleFactor, capped at maxVolumeSize.
  4. Patches the PersistentVolumeClaim with the new size. The storage provider then expands the underlying volume.
Volumes already at maxVolumeSize are never expanded further. Expansion is one-way: Cake Agents never shrinks a session volume.

​
Autoscaling inside sessions

/workspace and the home directory (/root) are both backed by the session volume and survive restarts. Files anywhere else, such as /tmp, are ephemeral. The default agent prompt instructs agents to keep important files under /workspace. Because the home directory shares the session volume, package manager caches such as ~/.npm and ~/.cache count toward its usage and can trigger expansion. Archiving a session uploads /workspace, session history, and attachments, but not the home directory. When autoscaling is enabled, session agents also get a wait_for_volume_autoscale tool. If a write to /workspace fails because the disk is full, the agent can call this tool to wait for the volume to grow, then retry. The tool:
  • Waits up to a configurable timeout (default 300 seconds, maximum 900) and returns as soon as /workspace capacity has grown.
  • Returns immediately with the reason and suggested next steps when the autoscaler decides not to expand, for example when usage is below the high watermark, the volume is at its maximum size, or the StorageClass does not allow expansion.
  • Reports that autoscaling is disabled if it was turned off after the session started.
The tool is only registered in sessions created while autoscaling is enabled.

​
Expansion progress in the session view

Users can follow storage expansions directly in the session:
  • While an expansion runs, a progress indicator appears at the bottom of the message history, above the message box. It shows the current and target volume sizes, for example Disk hit 90% · autoscaling storage 10.7 GB → 16.1 GB. The percentage reflects the configured high watermark ratio.
  • After an expansion completes, the indicator disappears. Cake Agents adds a divider to the session history that records the change and when it finished, for example Storage autoscaled 10.7 GB → 16.1 GB, followed by the completion time.
Completed expansion entries stay in the session history, so you can see every time the session’s volume grew. Sizes appear in decimal units, so a 10Gi volume displays as 10.7 GB.

​
Resuming after expansion

A full volume can interrupt the agent’s current turn and leave the session stalled with its task unfinished. After an expansion finishes, the control plane posts a synthetic Autoscaling completed message to the session. This message prompts the agent to pick up the interrupted task without any action from you. If the agent was not interrupted, it can ignore the message. The control plane sends this message once per expansion. If the session is still starting or cannot receive the message, the control plane retries on later reconciliation runs for up to 30 minutes. It stops retrying if the session is archived or deleted.