# 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](/docs/limits.md). 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`, `/proc` and 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](/docs/deploys.md). - **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](/docs/databases.md), 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: ```json { "autoscaling": {"min": 2, "max": 4, "target_cpu_percent": 70}, "health_check_path": "/healthz" } ``` ```json { "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](/docs/services.md): instance types. - [Deploys, rollbacks and downtime](/docs/deploys.md): how scaling and disks change a deploy. - [Limits and quotas](/docs/limits.md): what a workspace may run in total. - [Databases](/docs/databases.md): storage with backups.