Replicas and load balancing
A scale group is several copies of the same lab — replicas — serving one domain. Every request to that domain is handed to the next replica in turn (round-robin), so the load is spread and one replica going down does not take the site with it.
This page walks you through creating a group and explains which options to turn on for your kind of app.
When to use one
| Use a scale group when | Use a single lab or an extra copy when |
|---|---|
| A public web app needs to handle more traffic than one lab can | You are developing, or only you use it |
| You want the site to stay up while one replica restarts | The app keeps its state in memory or local files and cannot be split |
| You want to try a new version on a slice of real traffic first | You want separate machines for separate projects |
- A lab whose template allows copies. The Scale button is on the lab's Deployments tab only when it does.
- At least one domain. The group is reached through it.
- An app that listens on a port inside the lab.
- A lab that supports HTTP Proxies — its Preferences tab has an HTTP Proxies section. The group's domain is attached to replicas the same way.
Every replica is an ordinary copy, so the group can never have more replicas than your copy limit allows — 2 on the free plan and 4 on a paid plan, unless your administrator set something different — and running replicas count toward your running-labs limit. Plan the size of the group around those numbers, whatever the wizard's maximum says.
1. Open the wizard
Open the lab, go to Deployments and select Scale. The wizard has six steps; Next checks each one before moving on.
2. Name the group and point at your app
| Field | What to enter |
|---|---|
| Scale group | A name for the group — lowercase letters, digits and dashes, up to 32 characters |
| App port | The port your app listens on inside the lab, for example 8080 |
The first step of the wizard explains the idea and shows what the replicas will share — for example that your account home is mounted on every one.
3. Choose what replicas see
| Option | What it means |
|---|---|
| Shared account home (default) | Replicas see the same files as all your other labs. Edits show up everywhere. |
| Isolated group storage | One private home shared by this group only. It lasts until the last replica is removed. |
With isolated storage you choose how it starts: Fresh empty home or Clone my home. Cloning is cheap where your storage supports it, and grayed out where it does not — the same rule as for extra copies.
Every replica in a group reads and writes the same files. That is right for stateless or read-mostly apps. If your app writes files that another replica might overwrite, keep that data in a database instead.
4. Decide how many replicas
Fixed count runs exactly the number you choose, from 2 to 16.
Autoscale adds and removes replicas for you:
| Setting | Meaning |
|---|---|
| Min replicas / Max replicas | The range the group stays within, up to 16 |
| CPU | Add replicas when the group is busier than this percentage |
| Memory | Add replicas above this percentage |
Pick at least one of CPU or memory. Each target can be set from 10% to 95%; the defaults are 70% for CPU and 80% for memory. The step also tells you how many replicas of this size your plan can afford.
If your plan's compute budget is zero, the Autoscale option is disabled and you can only run a fixed count.
How autoscaling behaves:
- It checks the group about once a minute.
- It grows a few replicas at a time and shrinks one at a time, so traffic does not swing wildly.
- The memory signal only ever adds replicas; it never removes them.
- Every replica still counts against your copy limit, so the group cannot grow past it whatever Max replicas says.
In more detail:
| Rule | What it means for you |
|---|---|
| Averages across replicas | The group's load is the average of its running replicas. Within about 10% of your target, nothing changes. |
| Up to 2 at a time, down 1 at a time | A busy group grows by at most two replicas per check, and shrinks by one |
| At least a minute between changes | After any change, it waits before changing again |
| No shrinking right after growth | For five minutes after adding replicas, it will not remove any |
| Never below Min | If the group falls below Min replicas, replicas are added straight away |
| Crashed replicas are replaced | A replica that has disappeared is cleaned up and a new one is deployed |
| Quietest replicas go first | When shrinking, it removes the replica using the least CPU. The replica gets about 30 seconds to finish what it is doing, then goes to the Trash. |
| No data, no action | If it cannot read any load figures for the group, it does nothing |
The compute budget. On a paid plan, all your autoscaled groups together can use up to 8 CPU cores and 16 GB of memory, counted as replicas × the size of one replica on your plan. When a group wants more than that, it stays at what the budget allows and you get a notification — at most one every six hours. Your administrator can change the budget for you.
When new replicas keep failing. After three failed attempts in a row you get a notification, and the group waits longer and longer between attempts until a deploy succeeds. The usual causes are your copy limit, your running-labs limit, or a deploy that fails — check Deploy attempts on a replica's Activity tab.
With Fixed count, nothing watches the group. A replica that crashes or that you stop stays down until you redeploy it or add another with Add replica.
Groups owned by an organization are not autoscaled.
5. Traffic and safety
| Option | What it does | Turn it on when |
|---|---|---|
| Domains for this group | The shared URL. Pick at least one. | Always |
| Sticky sessions (on by default) | Keeps each visitor on the same replica | Your app has logins or sessions held in memory |
| Compress responses (gzip/br) | Compresses pages on the way out | Text-heavy sites |
| Health-check path | A path such as /health that must answer successfully; replicas that fail it are taken out of rotation until they recover | Always with autoscale, and recommended otherwise |
| Restrict to IPs / CIDRs | Only these addresses can reach the site, comma-separated, e.g. 203.0.113.0/24 | Staging sites, internal tools |
| Basic-auth user / password | Visitors must enter this user name and password | A quick lock on a preview site |
6. Review and create
Check the summary and select Create scale group. The starting replicas are deployed one after another — for autoscale, that is the Min replicas number — and the policy is saved. You land on the lab's Deployments tab with the new group card.
A message tells you how many replicas started, for example Deployed 2/3 replica(s) (1 failed). The usual cause of a failure is a limit — your copy limit or your running-labs limit. Each replica is named after the lab, the group and a number, for example Ubuntu · shop #2.
The group card
Groups appear on the lab's Deployments tab and under Instances → My Instances → Scale groups.
| On the card | Meaning |
|---|---|
| Scale group: name | The group |
| X/Y running | Replicas up, out of the replicas in the group |
| Domain badges | The shared URL — select one to open it |
| auto 2–4 · cpu 70% | Autoscaling on, with its range and signal |
| fixed 3 | A fixed count, autoscaling off |
The card also lists the group's last few scaling events — the time, what happened (for example up 2→4), and why — and has three buttons:
| Button | Use it to |
|---|---|
| Scaling | Change the policy — fixed or autoscale, the range and the signals |
| Canary | Try a new version on part of the traffic (below) |
| Add replica | Add one or more replicas to the group by hand |
Each replica is an ordinary lab copy underneath, with its own row, dashboard and Activity tab.
Scaling opens the policy: Autoscale this group on or off, Min and Max, the CPU and memory targets, how many replicas your budget allows, and the last five scaling events. Add replica asks how many to add to the same group, on the same domain and settings.
Stopping and removing replicas
| You | What happens to the group |
|---|---|
| Stop or terminate one replica | Its share of traffic goes to the others. If it held the group's domain, the domain moves to a replica that is still running, so the site stays up. |
| Stop or terminate the last running replica | The domain is released — the site stops answering until you deploy a replica again |
| Terminate every replica of an isolated group | The group's private storage goes with the last one — to the trash, or erased with Delete permanently |
| Stop the canary | The group's domain goes back to sending all traffic to the main replicas |
With autoscale on, stopping or terminating replicas can take the group below Min replicas — it adds replicas back within about a minute. Turn autoscaling off, or lower Min, first.
Canary releases
A canary is one extra replica on the same URL that takes a controlled share of traffic, so you can try a change before every visitor sees it.
Select Canary on the group card and choose a mode:
| Mode | What happens |
|---|---|
| Weighted | A percentage of real traffic (1–99%, set with the slider) goes to the canary |
| Mirror | The canary receives a copy of all traffic, but its responses are thrown away — visitors are never affected |
Select Deploy canary. To send 100% of traffic to the main replicas again, stop the canary.
Mirror mode is the safe way to see whether a new version crashes under real requests. Once it works well, redeploy it as a weighted canary at a small percentage.
Limits
| Limit | Value |
|---|---|
| Replicas per group | 2 to 16 at creation; up to 16 with autoscale |
| Copy limit | Every replica counts, running or stopped — see Running extra labs |
| Autoscale | Paid plans only |
| Autoscale budget | 8 CPU cores and 16 GB of memory across all your autoscaled groups, on a paid plan |
| Domains | At least one per group — only your verified domains not attached to another lab are offered |
| Group name | Lowercase letters, digits and dashes, up to 32 characters |
Pausing a replica
If the group has no health check, a paused replica stays in rotation and its share of requests hangs. The dashboard warns you before pausing it. Add a health-check path, or stop the replica instead of pausing it.
Do it with an AI assistant
Scale groups are set up in the dashboard only; an AI assistant connected over MCP cannot create or change one. It can list the replicas with list_labs and check each one with lab_status and lab_stats.
Next
- Running extra labs — single independent copies
- Domains — add the domain the group serves
- Sharing and workgroups — let others operate your replicas