> ## Documentation Index
> Fetch the complete documentation index at: https://paper.brimble.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure scaling
> Run more than one container for a project, with bounds you control.
Run more than one container for a project, with bounds you control. Brimble's scaling is organized into **scaling groups**, each group can run in fixed or auto-scaling mode.
By default, a Brimble project runs as a single container. Scaling groups let you run more, either at a fixed count or with automatic scaling tied to CPU and memory thresholds.
## Prerequisites
* A project on a paid plan that includes scaling.
* The project must be a web service or worker. Static sites serve from the edge and don't need scaling; databases scale separately.
## Open the scaling page
In the sidebar, click **Scaling**. The page lists every scaling group in the workspace. Each card shows:
* The group's name.
* Whether auto-scaling is on or off.
* The instance range (min → max) for autoscaling, or fixed count.
* Currently running instances.
* CPU and memory thresholds (if autoscaling).
* Active / inactive toggle.
* Edit and delete actions.
## Create a scaling group
1. Click **Create scaling group** (or **Add scaling group** if groups already exist).
2. Fill in:
* **Group name**, a label so you can identify the group later (e.g. `web-frontend`).
* **Auto-scaling**, toggle on or off.
The next set of fields depends on which mode you picked.
### Fixed mode (auto-scaling off)
* **Number of instances**, pick from 1 to 10.
The group runs exactly that many containers, no more, no less.
### Auto-scaling mode (auto-scaling on)
* **Instance range**, minimum and maximum, each between 1 and 5. Maximum must be greater than minimum.
* **CPU threshold**, between 1% and 100%. When average CPU across running containers crosses this, Brimble adds a container (up to the maximum).
* **Memory threshold**, between 10% and 100%, in 5% increments. When average memory crosses this, Brimble adds a container.
Save. The group activates immediately. The container count adjusts on the next scaling cycle.
## Recommended starting values
For a typical web service:
* Mode: auto-scaling
* Instance range: 2–5
* CPU threshold: 70%
* Memory threshold: 75%
Start narrow. Widen the range once you have data on what your traffic actually looks like.
If your service has steady, predictable traffic, fixed mode with 2 or 3 instances is simpler, autoscaling adds complexity that only pays off when traffic varies meaningfully.
**Each running container is billed for its compute size.** If your project is provisioned at 2 vCPU / 4 GB and the autoscaler runs five containers, you're paying for 10 vCPU and 20 GB of running compute for the time those containers are alive. Set a maximum that reflects what you're willing to spend during a traffic spike, not just what your service can technically handle.
## Workers
For background workers, scaling adjusts the number of consumer containers. Four containers means four copies of your worker run at once, each consuming from the queue. Make sure your queue protocol distributes work safely (Redis BLPOP, RabbitMQ work queues, BullMQ workers, all of these distribute correctly).
If your worker maintains in-process singleton state, don't scale past one container. Set fixed mode with 1 instance, or auto-scaling with min and max both at 1.
## Edit a group
Click the edit (pencil) icon on the group's card. The same form opens with current values. Save when done. Changes take effect on the next scaling cycle.
## Pause or remove a group
Toggle **Active** off on the group's card to pause without losing the configuration. The current container count freezes; future scaling cycles do nothing while paused.
To remove the group entirely, click **Delete** and confirm. Containers stop scaling under the group's rules, and the project reverts to whatever the rest of its configuration says (typically a single container).
## Permissions
Viewers cannot create, edit, or delete scaling groups, only see them. Members and Administrators can.
## Verification
Generate load against the project (with `wrk`, `vegeta`, or real traffic). Watch the **Running instances** count on the group card. In auto-scaling mode it should rise toward the maximum as your CPU/memory crosses thresholds, then drop back toward the minimum after load ends.
```bash theme={null}
wrk -t4 -c200 -d2m https://.brimble.app/
```
## Troubleshooting
**Auto-scaling never triggers.** CPU or memory isn't actually crossing the threshold. Open the project's **Observability** tab, if the gauge stays well below your threshold during traffic, lower it (or pick the metric that does spike).
**Containers scale up and stay at the max.** Either traffic genuinely demands the cap, or the metric stays elevated for a downstream reason (a slow database, a stuck queue). Investigate the bottleneck before raising the cap.
**Containers flap up and down rapidly.** Thresholds too tight relative to the per-container ceiling, or traffic is bursty. Widen the instance range, or move to fixed mode if bursts are normal.
**"For auto-scaling to work, max instances must be greater than min instances."** The form blocks save. Set the maximum at least one above the minimum.
**Scaling group exists but the project still runs as one container.** The group might be inactive. Toggle **Active** on the group's card.
## Next steps
* [Deployments](../projects/deployments), how new containers come online and pass health checks.
* [Plans and pricing](../billing/plans), billing for additional containers.