Manual Scaling

Manual scaling lets you explicitly control the number of Instances running for a Service. This mode is useful when you want full control over capacity without relying on automatic scaling rules. When manual scaling is enabled, the Instance count you define takes precedence over the scaling configuration defined in the deployment (autoscaling or fixed scaling). You can disable manual scaling at any time to return to deployment-defined behavior.

How manual scaling works

Manual scaling allows you to set a target number of Instances for a Service without triggering a redeployment. Depending on the Service state, scaling may apply immediately or be deferred.

Running Service states

When the Service is healthy, degraded, unhealthy, or starting:

You can set the number of Instances explicitly.
Scaling is applied immediately.
The scaling configuration defined in the current deployment is overridden.

Other Service states

When the service is pausing, paused, or resuming:

You can set the number of Instances.
The new Instance count is applied when a new deployment is triggered.

Light Sleep and Deep Sleep

Manual scaling is supported while the Service is asleep:

Light Sleep: scaling is applied immediately.
Deep Sleep: scaling is applied when the Service wakes up on incoming traffic.

Manual scaling requests are not supported in the following cases:

Quotas are exceeded (max_instances_by_type or memory_mb).
The Instance count is set to zero.
The service type is Database or Sandbox.

Disabling manual scaling

You can disable manual scaling on a Service at any time. When disabled, the Service immediately returns to using the scaling configuration defined in the deployment (autoscaling or fixed scaling), without requiring a redeployment.

Configuring manual scaling

Manual scaling is fully supported in the Koyeb control panel and using the Koyeb CLI, allowing you to scale Services, inspect current scaling overrides, and disable manual scaling visually and programmatically.

Koyeb control panel

You can manually scale a service directly from the Koyeb control panel.

Navigate to the Overview for your Service and scroll to the Scaling section.
Click the Manual Scaling button.
Use the + and - buttons to adjust the desired number of Instances per region.
Click the Apply button to confirm the change.
Review the confirmation message indicating when the change will apply.

When manual scaling is active, the Instance count you set overrides the scaling configuration defined in the deployment.

To disable manual scaling and return to deployment-defined scaling (autoscaling or fixed scaling), click Reset default scaling in the Scaling settings.

Example: Manual scaling override with Scale-to-Zero

This example illustrates how manual scaling interacts with a Service configured with Scale-to-Zero when Light Sleep is enabled.

A service is created with Scale-to-Zero enabled (Light Sleep, maximum of 1 Instance).
After deployment, the single Instance becomes idle and enters Light Sleep.
Manual scaling is enabled and the Instance count is set to 3.

Manual scaling requests is applied right away. Two additional Instances start immediately.
The original sleeping Instance remains in Light Sleep while the two new Instances are running.
Incoming traffic is sent to the Service.

The sleeping Instance wakes up immediately and starts serving traffic, alongside the two manually scaled Instances.
After the Scale-to-Zero idle timeout elapses, the Service does not return to Light Sleep.

Because manual scaling is active, all Instances remain running and healthy. Deployment scaling configuration is overridden.
Manual scaling is disabled.

The two Instances created by manual scaling are stopped, and the Service returns to its deployment-defined behavior. Because the idle timeout elapsed in step 5, the remaining Instance becomes idle and transitions back to Light Sleep as expected.

This example demonstrates that manual scaling fully overrides Scale-to-Zero behavior while active, and that disabling manual scaling cleanly restores the original deployment scaling configuration.