On this page
Disks and scaling
A service can keep files on a persistent disk, run several instances, or autoscale between a minimum and a maximum number of instances. When you create a service from an image, you set all three under Advanced. When you create one from a repository, the plan screen has an Instances row (a fixed number or autoscaling), and you add a disk afterwards. All three can be changed later in the service's Settings. Where the plan has no autoscaling, the choice is off and a note next to it says why.
Instances and autoscaling#
- A fixed number: 1 to 10 instances. Requests are spread across them.
- Autoscaling: a minimum, a maximum (higher than the minimum, up to 10) and a CPU target between 10% and 95%. Kilby adds instances when the average CPU use passes the target, as a share of the instance type's CPU, and removes them when it drops. Autoscaling needs CPU measurements; without them the service stays at its minimum, and the dashboard says so.
- Cron jobs always run one instance at a time. Workers, private services and web services can scale. A service with a disk cannot.
Autoscaling is included on Pro and up. A workspace created before November 18, 2026 keeps it on every plan. A service that autoscales already keeps doing so after a move to a smaller plan, up to its current maximum: only a new autoscaler, or a higher maximum, is refused. On the other plans, set a fixed number of instances.
Every instance counts against the workspace's CPU and memory limits, and with autoscaling the maximum counts, so a service can always scale up to it. A workspace has 2 CPU cores, so it can run at most 4 Starter instances at once, whatever mix of services they belong to. See Limits and quotas.
Your program must not keep state that matters in one instance's memory or files: requests can go to any instance, and an instance can be replaced at any time. Keep state in Postgres or on a disk (one instance only).
Disks#
A disk is an encrypted volume that stays when a deploy replaces the instance.
- Size: 1 to 50 GB.
- Mount path: an absolute path such as
/data. Mounting over a folder of the image hides what the image has there. A few system folders (/etc,/usr,/bin,/procand the like) and/cannot be used. - Who can write: the top folder of a new disk is writable by root and by group 1000, and every process of the service runs with group 1000 as an extra group, so both root and non-root users can write.
- One instance: a service with a disk runs exactly one instance, because a disk attaches to one machine at a time.
- Deploys: because of that, a deploy stops the old instance before it starts the new one, so there is a short downtime on every deploy and on every change that restarts the service. If a deploy fails, the old instance is already stopped, so the service is not running until you roll back or deploy again. See Deploys.
- Grow, never shrink: a disk can be made bigger, at most once every 6 hours. It cannot be made smaller or removed.
- Deleting the service deletes its disk, with every file on it. A suspended service keeps its disk.
- Not backed up: Kilby does not back up service disks. Keep copies of what you cannot lose, or store it in a Postgres database, which is backed up.
- Counted: a disk counts against the workspace's disk limit (50 GB for disks and databases together).
- Cron jobs cannot have a disk: each run starts fresh.
With the API#
Send instances or autoscaling, and disk, when you create or change a service:
{
"autoscaling": {"min": 2, "max": 4, "target_cpu_percent": 70},
"health_check_path": "/healthz"
}{
"instances": 1,
"disk": {"mount_path": "/data", "size_gb": 10}
}Send either instances or autoscaling, not both. The service object reports instances_running and instances_desired.
Related#
- Services: instance types.
- Deploys, rollbacks and downtime: how scaling and disks change a deploy.
- Limits and quotas: what a workspace may run in total.
- Databases: storage with backups.