Scale a service
Change replicas and resource limits, configure health checks, or enable sleep.
Change replicas to run more or fewer copies without a deployment. Change CPU or memory limits to resize each copy, then redeploy. Enable sleep only when waiting for a cold start is acceptable.
Before you start
- Use a persistent runtime service. Static sites and scheduled jobs do not have replicas or sleep settings.
- Read metrics to identify the pressure: CPU, memory, request rate, latency and errors.
- Keep state shared across requests in a database or another suitable store, not one replica’s memory. Requests are not pinned to a replica.
- For MCP, use a product-scoped token with Deployment
writefor scaling, updates, wake and redeploy;readfor inspection.
1. Choose the change
Symptom | Action to consider |
|---|---|
High CPU and rising latency | Add replicas or raise the CPU limit |
Memory reaches its limit before restarts | Raise memory and redeploy |
Higher request rate but steady latency and spare resources | No capacity change needed |
Errors rise while resources are idle | Investigate the database or upstream dependency before scaling |
More replicas help only when the work can run in parallel. Environment-wide capacity limits can also prevent a deploy or scale-out; reduce another workload or move work if that ceiling is reached.
2. Apply the setting
For replicas, open Service → Settings → Replicas, or call deployment_service_scale with id and replicas. The accepted range is 0–50; new services default to one. New copies use the active image and variables. Removed replicas get a grace period to finish requests. No build or deployment entry is created.
Setting zero stops the service while keeping its domains, configuration, storage and history. Set a positive count to start the same release again. Read the push behavior below before relying on it staying stopped.
For per-replica CPU and memory, use Settings → Resources, or resources.limits in deployment_service_update.
Preset | CPU | Memory |
|---|---|---|
XS | 250m | 512Mi |
S (default) | 500m | 1Gi |
M | 1 | 2Gi |
L | 2 | 4Gi |
XL | 4 | 8Gi |
2XL | 8 | 16Gi |
CPU accepts cores (2, 0.5) or thousandths of a core (500m), from 50m to 32 cores. Memory accepts whole numbers with Ki, Mi, Gi or Ti, or bytes without a suffix, from 64Mi to 32Gi. Invalid or out-of-range values are rejected on save.
CPU limits throttle excess demand. Exceeding the memory limit stops and restarts the replica. These are ceilings per replica, not reserved consumption.
3. Redeploy resource changes
After changing CPU or memory, choose Redeploy or call deployment_service_redeploy. Saving resource limits alone does not resize running replicas.
A runtime rollout normally starts replacements before removing old replicas. A service with a volume must stop the old container first and has an interruption; do not assume that a mounted disk can be shared by multiple replicas.
Verify it works
Inspect the service’s replica count and configuration. For a resource change, wait for the new deployment to become Active. Repeat the request or workload that exposed the problem and compare latency, memory, CPU and restart events over the same time window.
Sleep when idle
Under Settings → Scale to zero, enable Sleep when idle and choose an idle window of 5–60 minutes (default 15). Sleep is off by default. After enabling it, a 15-minute grace period prevents immediate sleep.
Once asleep, a request waits while the service starts on the same release, variables and volumes. Calls from another service in the same environment also wake it. Startup can take seconds or longer for a slow application. Wake on the sleeping service’s panel, or deployment_service_wake, starts it before visitors arrive.
To verify sleep behavior, wait through the grace period and idle window, inspect the sleep state, then make a request and confirm a wake event and a response. Allow for startup latency.
Pushes at zero replicas
These rules apply when automatic deployment is enabled. With autoDeploy: false, pushes do not deploy the service.
Repository service state | Push to the tracked branch |
|---|---|
Asleep after its idle window | Deploys and returns to its pre-sleep replica count |
Manually stopped, sleep enabled | Starts the service again |
Manually stopped, sleep disabled | Ignored: no build, history entry or deploy timeline entry |
To keep a service stopped across pushes, disable sleep before setting zero replicas. When ready to use an ignored commit, raise the count and redeploy.
Configure health checks
Settings → Readiness probe controls when a replica receives traffic. Liveness probe restarts a running replica that stops responding. Both use an HTTP path beginning with /, such as your application’s /health endpoint.
Setting | Readiness default | Liveness default |
|---|---|---|
port | Service container port | Service container port |
initialDelaySeconds | 0 | 10 |
periodSeconds | 10 | 10 |
timeoutSeconds | 1 | 1 |
failureThreshold | 3 | 3 |
successThreshold | 1 | 1 |
Configure a path your application actually serves and redeploy to apply the probe configuration. Without checks, a container counts as ready when it starts. A liveness endpoint should do little work: a slow endpoint with a short timeout can restart a healthy but busy process. After deployment, inspect readiness and restart events to confirm the probes behave as intended.