diff --git a/changelog.mdx b/changelog.mdx
index 3735142..ff07d95 100644
--- a/changelog.mdx
+++ b/changelog.mdx
@@ -33,6 +33,139 @@ rss: true
 {/* ravion-changelog:september-21-2026 */}
 {/* ravion-changelog:september-28-2026 */}
 {/* ravion-changelog:october-5-2026 */}
+{/* ravion-changelog:october-12-2026 */}
+
+<Update
+  label="October 12, 2026"
+  rss={{
+    title: "Faster sandbox builds and Terraform runs, AWS quota management, execution-environment usage, and more capable module builds",
+  }}
+>
+
+## Major new features
+
+### Autoscaling sandbox fleets with sticky disks
+
+Pipeline sandbox runners can make builds up to 4× faster and Terraform runs up to 10× faster, depending on your workload. Behind those faster runs is a fully managed fleet: Ravion orchestrates isolated Firecracker microVMs across EC2 hosts in your AWS account, packing multiple sandboxes onto each host and scaling the fleet up and down with demand.
+
+- **Fast starts and sticky disks.** Steps start in roughly a second on warm hosts. Cached disks keep dependencies, build output and Docker layers between runs, and saved snapshots can follow your work to another host.
+- **Automatic host selection and Spot fallback.** Ravion chooses host types unless you specify them. New pools use Spot for eligible work with `interruptible: true` when more capacity is needed, trying compatible instance types and Availability Zones before falling back to On-Demand.
+- **Disposable hosts without disposable caches.** Hosts are ephemeral by default and deleted when idle; the fleet can scale to zero without losing saved sandbox disks. Keep a warm reserve for faster starts, or use persistent hosts that stop with their disks retained and wake for later work.
+
+You configure what each step needs; Ravion manages the fleet underneath it. Read [how sandbox fleets work](https://www.ravion.com/docs/concepts/sandboxes#how-the-fleet-works) for the architecture and cost trade-offs.
+
+To get started, update your AWS account to the latest permissions with **Update AWS Permissions** in [AWS account settings](https://app.ravion.com/org/settings/aws-accounts), then follow the [sandboxes getting started guide](https://www.ravion.com/docs/concepts/sandboxes).
+
+### AWS quota management
+
+When Ravion sees an AWS quota issue, we display an in-dashboard alert and let you request an increase in one click. We have limited coverage currently, but more will be coming.
+
+## Platform
+
+### Features
+
+- **Execution environment usage:** View estimated cost, Spot and On-demand usage, capacity allocation, startup timing, and pipeline attribution.
+- **Pipeline stage descriptions:** Add optional `purpose` text to pipeline steps and groups and view it when hovering their names. [Learn more](https://www.ravion.com/docs/pipelines/config-reference).
+
+### Improvements
+
+- Environment canvas loading now uses saved card positions and keeps metric cards at a consistent height while data loads.
+- Execution environment details now open on Usage with a clearer Cost and Usage summary and a pool overview on the Sandbox hosts tab.
+
+### Fixes
+
+- Personal GitLab repositories now load without a repository-stream error.
+- Cancel controls now offer only actions that the current pipeline run supports.
+- Successful Terraform applies no longer become failed runs because of a later refresh error.
+- Project configuration applies now skip deferred values and report the correct invalid value when a new module and its references are added together.
+- Sandbox launches now fail promptly with a useful error when AWS access, capacity, or host images prevent a host from starting.
+- Failed AWS Spot requests now move to another zone or instance type instead of repeating the same request.
+
+## AWS account IAM policy 1.0.50 → 1.0.54
+
+- **Spot price history lookups:** Allow spot price history lookups for usage capture.
+- **Sandbox EC2 Fleets:** Allow sandbox EC2 Fleets.
+- **AWS Service Quotas:** Allow reading and requesting increases for all AWS service quotas.
+
+Update your [AWS account connection in organization settings](https://app.ravion.com/org/settings/aws-accounts).
+
+## Modules
+
+### [AWS Application Load Balancer](https://www.ravion.com/docs/module-definitions/catalog/rvn-aws-alb) [1.2.0](https://github.com/ravionhq/modules/releases/tag/rvn-aws-alb%401.2.0) → [1.2.2](https://github.com/ravionhq/modules/releases/tag/rvn-aws-alb%401.2.2)
+
+- Add a `web_acl_arn` output for the associated WAF web ACL.
+
+### [EC2 Service](https://www.ravion.com/docs/module-definitions/catalog/rvn-ec2-service) [2.1.0](https://github.com/ravionhq/modules/releases/tag/rvn-ec2-service%402.1.0) → [2.2.0](https://github.com/ravionhq/modules/releases/tag/rvn-ec2-service%402.2.0)
+
+- Keep sandbox build disks between runs so Docker layers and dependencies stay cached.
+- Run sandbox builds on Spot hosts and restart them on another host if AWS reclaims the host; turn off Interruptible build for commands that change state outside the build.
+- New builds now use sandbox execution with 14 vCPU and 28 GiB by default.
+
+### [ECS Cluster](https://www.ravion.com/docs/module-definitions/catalog/rvn-ecs-cluster) [2.1.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-cluster%402.1.0) → [2.1.2](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-cluster%402.1.2)
+
+- Associate the public load balancer with the WAF web ACL when a web ACL ARN is set.
+
+### [ECS Network Service](https://www.ravion.com/docs/module-definitions/catalog/rvn-ecs-nlb) [2.1.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-nlb%402.1.0) → [2.3.1](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-nlb%402.3.1)
+
+- Keep sandbox build disks between runs so Docker layers and dependencies stay cached.
+- Run sandbox builds on Spot hosts and restart them on another host if AWS reclaims the host; turn off Interruptible build for commands that change state outside the build.
+- Let TCP and TLS listeners pass the original client IP to tasks through Advanced Terraform variables.
+- New builds now use sandbox execution with 14 vCPU and 28 GiB by default.
+
+### [ECS Web Service](https://www.ravion.com/docs/module-definitions/catalog/rvn-ecs-web) [2.1.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-web%402.1.0) → [2.2.1](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-web%402.2.1)
+
+- Keep sandbox build disks between runs so Docker layers and dependencies stay cached.
+- Run sandbox builds on Spot hosts and restart them on another host if AWS reclaims the host; turn off Interruptible build for commands that change state outside the build.
+- New builds now use sandbox execution with 14 vCPU and 28 GiB by default.
+
+### [ECS Worker](https://www.ravion.com/docs/module-definitions/catalog/rvn-ecs-worker) [2.1.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-worker%402.1.0) → [2.2.1](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-worker%402.2.1)
+
+- Keep sandbox build disks between runs so Docker layers and dependencies stay cached.
+- Run sandbox builds on Spot hosts and restart them on another host if AWS reclaims the host; turn off Interruptible build for commands that change state outside the build.
+- New builds now use sandbox execution with 14 vCPU and 28 GiB by default.
+
+### [Lambda Function](https://www.ravion.com/docs/module-definitions/catalog/rvn-lambda) [1.4.0](https://github.com/ravionhq/modules/releases/tag/rvn-lambda%401.4.0) → [2.1.0](https://github.com/ravionhq/modules/releases/tag/rvn-lambda%402.1.0)
+
+- BREAKING: update callers, DNS targets, and IAM policies for the new function URL after applying the live-alias deployment change.
+- Keep sandbox build disks between runs so Docker layers and dependencies stay cached.
+- Run sandbox builds on Spot hosts and restart them on another host if AWS reclaims the host; turn off Interruptible build for commands that change state outside the build.
+- New builds now use sandbox execution with 14 vCPU and 28 GiB by default.
+
+### [S3 Bucket](https://www.ravion.com/docs/module-definitions/catalog/rvn-s3) [1.1.0](https://github.com/ravionhq/modules/releases/tag/rvn-s3%401.1.0) → [2.0.1](https://github.com/ravionhq/modules/releases/tag/rvn-s3%402.0.1)
+
+- Add Requester Pays as an advanced Terraform variable so bucket readers pay for requests and data transfer.
+- BREAKING: apply the region change only after emptying a bucket that an earlier version created in another region, because it will be replaced there.
+
+### [Static Hosting](https://www.ravion.com/docs/module-definitions/catalog/rvn-aws-static) [1.3.0](https://github.com/ravionhq/modules/releases/tag/rvn-aws-static%401.3.0) → [1.4.0](https://github.com/ravionhq/modules/releases/tag/rvn-aws-static%401.4.0)
+
+- Keep sandbox build disks between runs so Docker layers and dependencies stay cached.
+- Run sandbox builds on Spot hosts and restart them on another host if AWS reclaims the host; turn off Interruptible build for commands that change state outside the build.
+- New builds now use sandbox execution with 14 vCPU and 28 GiB by default.
+
+## CLI [1.10.1](https://github.com/ravionhq/cli/releases/tag/v1.10.1) → [1.14.12](https://github.com/ravionhq/cli/releases/tag/v1.14.12)
+
+### Breaking changes
+
+- **Sandbox interruptibility:** Move `interruptible` into the sandbox `infrastructure` block before upgrading configurations.
+
+### Features
+
+- **Multiple roles:** Assign several roles to members and service accounts with `ravion membership` and `ravion service-account` commands.
+- **API key permissions:** Limit an API key to selected permissions and inspect the available permissions for its owner with `ravion api-key`.
+- **Automatic sandbox host selection:** Let sandbox pools choose suitable instance types, create a default pool on first use, and keep a reserve of idle ephemeral hosts.
+- **Execution environment usage:** View Spot and On-demand compute, busy-host allocation, and startup timing in usage data.
+- **Sandbox capacity options:** Configure persistent or ephemeral host storage and allow interruptible steps to use Spot capacity.
+
+### Improvements
+
+- **Pipeline configuration validation:** Send `null` values in pipeline version create requests without rejecting unknown or removed fields.
+
+### Fixes
+
+- **Project configuration diffs:** Preserve written number formatting in plan diffs and keep dry runs consistent with pull request comments.
+
+</Update>
+
 <Update
   label="October 5, 2026"
   rss={{
@@ -238,17 +371,23 @@ Update your AWS account connection in [**Settings / AWS accounts**](https://app.
 >
 
 ## Platform
+
 ### Features
+
 - **Module output references:** Set any module input from another module's stack output with a `<< >>` template in the dashboard, the project config file, or a pipeline, including across environments and projects. See [output references](https://www.ravion.com/docs/modules/output-references).
 - **AMI deployments:** The new [AMI](https://www.ravion.com/docs/module-definitions/catalog/rvn-aws-ami) module releases an AMI with every deploy. Each deploy builds the image with EC2 Image Builder, copies it to every region, publishes it when requested, and retires older images. Redeploys and rollbacks release earlier images again without rebuilding.
 - **New project navigation:** A new project sidebar keeps environments and pipelines visible and easy to navigate. When viewing a module, a module sidebar lets you switch to another module.
+
 ### Improvements
+
 - Deployment logs now show that they are waiting when a running step has not produced logs yet.
 - The dashboard now uses a scaled desktop layout on phones so content fits the screen.
 - Projects pages now open the only project directly when you enter an organization with one project.
 - Route loading now shows page-specific skeletons instead of a blank dashboard shell.
 - [`instance_size`](https://www.ravion.com/docs/pipelines/config-reference#ec2stepinfrastructure) arrays are now accepted for EC2 infrastructure configuration.
+
 ### Fixes
+
 - Email verification now lets users request a fresh code when the original code expires or is rejected.
 - Published module versions now load correctly when opening a module version pane.
 - Failed resource loads now show an error with a retry option instead of an endless loading state.
@@ -257,39 +396,67 @@ Update your AWS account connection in [**Settings / AWS accounts**](https://app.
 - EKS deployments now release abandoned targets and report blocked deployments instead of waiting indefinitely.
 - Project configuration dry runs now fail clearly when a values input names no connected resource.
 - Failed requests now retry only transient network, timeout, gateway, and rate-limit errors, while deterministic errors are not resent.
+
 ## AWS account IAM policy 1.0.47 → 1.0.48
+
 - **AMI deployments:** Ravion can build images with EC2 Image Builder, copy them to other regions, tag and publish them, retire older images, and manage its own image resources.
 
 Update your AWS account connection in [**Settings / AWS accounts**](https://app.ravion.com/org/settings/aws-accounts).
 
 ## Modules
+
 ### New modules
+
 - **[AMI](https://www.ravion.com/docs/module-definitions/catalog/rvn-aws-ami)** 0.1.0: Provision EC2 Image Builder infrastructure that builds AMIs, copies them to additional regions, publishes them when requested, and retires older images.
 - **[AWS Compliance](https://www.ravion.com/docs/module-definitions/catalog/rvn-aws-compliance)** 0.1.0: Enable GuardDuty and registry-wide Basic ECR scan-on-push across selected AWS Regions. Applying replaces any existing ECR Enhanced scanning or custom filters, so review your current configuration first.
 - **[AWS Secret](https://www.ravion.com/docs/module-definitions/catalog/rvn-aws-secret)** 1.0.0: Generate random keys and passwords in Parameter Store or Secrets Manager without storing them in Terraform state or Ravion, with optional multi-Region replication.
+
 ### [Aurora Database](https://www.ravion.com/docs/module-definitions/catalog/rvn-aurora) [1.2.1](https://github.com/ravionhq/modules/releases/tag/rvn-aurora%401.2.1) → [1.3.0](https://github.com/ravionhq/modules/releases/tag/rvn-aurora%401.3.0)
+
 - Add storage capacity and read/write IOPS alarms for Aurora, including Serverless v2.
+
 ### [AWS Application Load Balancer](https://www.ravion.com/docs/module-definitions/catalog/rvn-aws-alb) [1.0.1](https://github.com/ravionhq/modules/releases/tag/rvn-aws-alb%401.0.1) → [1.1.0](https://github.com/ravionhq/modules/releases/tag/rvn-aws-alb%401.1.0)
+
 - Add default CloudWatch alarms for load balancer 5xx responses, target 5xx responses, and target response time, and retain access logs for 365 days by default.
+
 ### [CloudFront CDN](https://www.ravion.com/docs/module-definitions/catalog/rvn-cloudfront) [1.3.1](https://github.com/ravionhq/modules/releases/tag/rvn-cloudfront%401.3.1) → [1.3.2](https://github.com/ravionhq/modules/releases/tag/rvn-cloudfront%401.3.2)
+
 - Retain access logs for 365 days by default.
+
 ### [EC2 Service](https://www.ravion.com/docs/module-definitions/catalog/rvn-ec2-service) [1.6.0](https://github.com/ravionhq/modules/releases/tag/rvn-ec2-service%401.6.0) → [1.6.1](https://github.com/ravionhq/modules/releases/tag/rvn-ec2-service%401.6.1)
+
 - Document that image scanning on push is enabled by default for SOC 2 compliance.
+
 ### [ECS Cluster](https://www.ravion.com/docs/module-definitions/catalog/rvn-ecs-cluster) [1.0.2](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-cluster%401.0.2) → [1.1.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-cluster%401.1.0)
+
 - Add default log retention and CloudWatch alarms for public and private load balancers, and document that Container Insights is enabled by default for SOC 2 compliance.
+
 ### [ECS Network Service](https://www.ravion.com/docs/module-definitions/catalog/rvn-ecs-nlb) [1.5.1](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-nlb%401.5.1) → [1.6.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-nlb%401.6.0)
+
 - Add inherited log retention and default CloudWatch alarms for CPU, memory, running tasks, and load balancer target health, and document default image scanning on push for SOC 2 compliance.
+
 ### [ECS Web Service](https://www.ravion.com/docs/module-definitions/catalog/rvn-ecs-web) [1.5.1](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-web%401.5.1) → [1.6.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-web%401.6.0)
+
 - Add inherited log retention and default CloudWatch alarms for CPU, memory, running tasks, and load balancer target health, and document default image scanning on push for SOC 2 compliance.
+
 ### [ECS Worker](https://www.ravion.com/docs/module-definitions/catalog/rvn-ecs-worker) [1.5.1](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-worker%401.5.1) → [1.6.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-worker%401.6.0)
+
 - Add inherited log retention and default CloudWatch alarms for CPU, memory, running tasks, and load balancer target health, and document default image scanning on push for SOC 2 compliance.
+
 ### [Lambda Function](https://www.ravion.com/docs/module-definitions/catalog/rvn-lambda) [1.1.1](https://github.com/ravionhq/modules/releases/tag/rvn-lambda%401.1.1) → [1.1.2](https://github.com/ravionhq/modules/releases/tag/rvn-lambda%401.1.2)
+
 - Enable configurable Lambda error-rate alarms by default, including Lambda@Edge region support, and document default image scanning.
+
 ### [RDS Database](https://www.ravion.com/docs/module-definitions/catalog/rvn-rds) [1.2.1](https://github.com/ravionhq/modules/releases/tag/rvn-rds%401.2.1) → [1.3.0](https://github.com/ravionhq/modules/releases/tag/rvn-rds%401.3.0)
+
 - Add configurable read/write IOPS alarms alongside existing free storage monitoring.
+
 ### [Static Hosting](https://www.ravion.com/docs/module-definitions/catalog/rvn-aws-static) [1.1.2](https://github.com/ravionhq/modules/releases/tag/rvn-aws-static%401.1.2) → [1.1.3](https://github.com/ravionhq/modules/releases/tag/rvn-aws-static%401.1.3)
+
 - Enable CloudFront 5xx error-rate alarms and retain access logs for 365 days by default.
+
 ### [Terraform Stack](https://www.ravion.com/docs/module-definitions/catalog/rvn-stack) [1.2.4](https://github.com/ravionhq/modules/releases/tag/rvn-stack%401.2.4) → [1.3.1](https://github.com/ravionhq/modules/releases/tag/rvn-stack%401.3.1)
+
 - Add independent pull request and primary branch run controls for plan-only or plan, approve, and apply workflows.
 - Clarify that pull request plan results are viewed in Ravion.
 
@@ -379,22 +546,35 @@ Update your AWS account connection in [**Settings / AWS accounts**](https://app.
 >
 
 ## Platform
+
 ### Improvements
+
 - ECS rolling deployments now succeed as soon as new tasks are healthy while old tasks drain in the background; deployment settings can choose a lower healthy-task threshold or wait for old tasks to drain. This applies to existing ECS modules, not just the new versions.
+
 ### Fixes
+
 - GitLab code sources now refresh expiring credentials and recover access after successful reauthorization.
 - AWS account connection errors now explain that reconnection is needed and link directly to the account connection flow.
 - Orphaned EC2 runner instances are now reconciled and terminated after interrupted launches.
 - Successful EC2 deployments can now be redeployed or rolled back without failing during input resolution.
 - Organizations with billing data but no projects can now be deleted.
+
 ## Modules
+
 ### [CloudFront CDN](https://www.ravion.com/docs/module-definitions/catalog/rvn-cloudfront) [1.3.0](https://github.com/ravionhq/modules/releases/tag/rvn-cloudfront%401.3.0) → [1.3.1](https://github.com/ravionhq/modules/releases/tag/rvn-cloudfront%401.3.1)
+
 - CloudFront signed URLs now accept UUID-format key group IDs.
+
 ### [ECS Network Service](https://www.ravion.com/docs/module-definitions/catalog/rvn-ecs-nlb) [1.2.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-nlb%401.2.0) → [1.3.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-nlb%401.3.0)
+
 - Rolling deployments now succeed as soon as new tasks are healthy while old tasks drain in the background; deployment settings can choose a lower healthy-task threshold or wait for old tasks to drain.
+
 ### [ECS Web Service](https://www.ravion.com/docs/module-definitions/catalog/rvn-ecs-web) [1.2.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-web%401.2.0) → [1.3.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-web%401.3.0)
+
 - Rolling deployments now succeed as soon as new tasks are healthy while old tasks drain in the background; deployment settings can choose a lower healthy-task threshold or wait for old tasks to drain.
+
 ### [ECS Worker](https://www.ravion.com/docs/module-definitions/catalog/rvn-ecs-worker) [1.2.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-worker%401.2.0) → [1.3.0](https://github.com/ravionhq/modules/releases/tag/rvn-ecs-worker%401.3.0)
+
 - Rolling deployments now succeed as soon as new tasks are healthy while old tasks drain in the background; deployment settings can choose a lower healthy-task threshold or wait for old tasks to drain.
 
 </Update>
diff --git a/concepts/sandboxes.mdx b/concepts/sandboxes.mdx
index ce90333..cd60ae0 100644
--- a/concepts/sandboxes.mdx
+++ b/concepts/sandboxes.mdx
@@ -1,14 +1,41 @@
 ---
 title: "Sandboxes"
 sidebarTitle: "Sandboxes"
-description: "Run pipeline steps and module builds as Firecracker microVMs in your AWS account, with automatic host selection and fast starts on warm hosts."
+description: "Run pipeline steps and module builds on an autoscaling fleet of Firecracker microVMs in your AWS account, with sticky disks and Spot capacity."
 "og:image": "https://www.ravion.com/og/docs/concepts/sandboxes.png"
 "twitter:image": "https://www.ravion.com/og/docs/concepts/sandboxes.png"
 ---
 
-A sandbox runs a pipeline step or a module build as a [Firecracker](https://firecracker-microvm.github.io/) microVM. The microVM runs on a pool of EC2 hosts in your AWS account. Steps start in seconds when a host has room. When no host is available, Ravion launches one.
+A sandbox runs a pipeline step or a module build as an isolated [Firecracker](https://firecracker-microvm.github.io/) microVM. Ravion orchestrates an entire fleet of these microVMs across EC2 hosts in your AWS account, automatically scaling the hosts up and down as work arrives and finishes.
 
-Each execution environment can have one sandbox pool. The first step that targets it with `type: sandbox` creates the pool automatically. Ravion chooses the host machine types unless you set your own. Several sandboxes can share one host.
+You choose the CPU, memory and disk each step needs. Ravion handles host selection, scheduling, Spot capacity and host cleanup. Steps can start in roughly a second on warm hosts, and [sticky disks](#disk-cache) keep dependencies, build output and Docker layers ready for later runs.
+
+## How the fleet works
+
+Each execution environment can have one **sandbox pool**: the fleet of EC2 hosts that runs its sandboxes. The first step that targets it with `type: sandbox` creates the pool automatically. You don't need to provision hosts or maintain an Auto Scaling group yourself.
+
+An EC2 host is not a single runner. Several isolated sandboxes can run on it at once, each with its own CPU, memory and disk allocation. This lets steps share available host capacity instead of launching a dedicated EC2 instance for every step.
+
+1. **Use available capacity.** Ravion places steps on running hosts with enough room. When possible, it prefers the host that already has the step's cached disk data.
+2. **Scale up for waiting work.** When running hosts don't have room, Ravion launches more hosts or wakes suitable stopped hosts in persistent pools. It selects compatible machine types for your region and workload unless you restrict the selection.
+3. **Choose Spot or On-Demand capacity.** Interruptible work can use Spot hosts, with alternatives across instance types and Availability Zones and an On-Demand fallback. Work that must not be interrupted uses On-Demand hosts.
+4. **Scale down after work finishes.** Ravion stops or terminates idle hosts according to your pool settings. Normal scale-down waits for running steps to finish.
+
+The default pool can scale down to zero hosts. A later run then waits for a host to launch; the roughly one-second start applies when a warm host already has capacity.
+
+### Ephemeral hosts, persistent hosts and warm capacity
+
+Host lifetime and sandbox disk caching are separate settings. You can use disposable EC2 hosts without throwing away the sandbox's saved disk after every run.
+
+| Mode | What happens when a host becomes idle | Trade-off |
+| --- | --- | --- |
+| **Ephemeral** (default) | Ravion terminates the host and deletes its attached volumes after the idle timeout, unless a running reserve keeps it. | No idle compute charges after termination, but the next burst may need new hosts. |
+| **Persistent** | Ravion stops On-Demand hosts and retains their disks, then starts suitable hosts again when needed. | Local cached data survives a stop. Retained disks still incur storage charges, and waking a host takes time. |
+| **Warm reserve** (ephemeral pools) | Ravion keeps a chosen number of idle hosts running. | Faster starts after quiet periods, at the cost of continued compute charges. |
+
+Spot hosts are terminated rather than stopped, even in persistent pools. Stopped hosts outside a persistent pool's retained reserve are deleted after the configured retention period.
+
+You can set the reserve to a fixed count or have Ravion size it from your peak or rolling-average daily peak usage. In ephemeral pools, that reserve stays running; in persistent pools, it stays stopped with its disks retained. See [Pool settings](#pool-settings) for the controls and defaults.
 
 ## When to use sandboxes
 
@@ -105,6 +132,10 @@ To stop using sandboxes, switch your steps and module builds back to EC2. Removi
 
 `interruptible: true` says a step can be stopped partway and started over. Builds, tests and lint usually can.
 
+New pools allow Spot hosts by default. When interruptible work needs new capacity, Ravion tries compatible Spot instance types across the Availability Zones available to your execution environment. It can try other instance sizes and adjust how steps are distributed across hosts, then fall back to On-Demand if Spot capacity is unavailable.
+
+Interruptible steps can also use spare capacity on running On-Demand hosts. Setting `interruptible: true` permits Spot; it doesn't require a new Spot instance for every step.
+
 - Only interruptible steps run on spot hosts, and only in a pool with **Use spot hosts for interruptible steps** turned on. Other steps run on on-demand hosts.
 - If an interruptible step's host is lost or AWS reclaims it, Ravion reruns the step from the start on another host. The last retry always runs on an on-demand host.
 - If a step that isn't interruptible loses its host, the step fails.
@@ -115,6 +146,10 @@ Leave `interruptible` off for steps that change things outside the sandbox and c
 
 `disk_cache` controls whether a sandbox keeps its disk, with your dependencies, build output and Docker layers, between runs.
 
+These **sticky disks** save the sandbox filesystem rather than requiring you to select individual cache directories. Ravion stores the saved disk snapshots in an S3-backed chunk store in your AWS account and caches data locally on hosts. Later runs can restore a saved disk on another host, even after the original ephemeral host has been terminated.
+
+When a suitable previous host is still available, Ravion prefers it so the sandbox can reuse local cached data. Disk caching reduces repeated downloads and setup, while warm host capacity avoids waiting for EC2 to launch. Both affect how much faster your workload runs. Enable it with `disk_cache: auto` or a cache key; custom pipeline steps default to `off`.
+
 | Value | What it does |
 | --- | --- |
 | `off` | Boot the base image every run and keep nothing. This is the default. |