> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Warm Slots

> Reserved warm capacity for a project and VM size, bounded by your subscription tier.

A warm slot keeps one prewarmed machine ready for a project at a specific [VM size](/concepts/pricing-and-tiers). Assigning a slot means choosing both the project and the size: `small`, `medium`, or `large`.

Projects do not have a hardware default. A single project can hold slots at several sizes, and each `(project, size)` pair is a separate warm pool. The number of slots assigned to that pair is the number of prewarmed machines Aether keeps ready for it.

## How Warm Starts Match Tasks

Every task chooses its VM size when it is created. A task starts immediately only when its project has a ready machine in the warm pool for that exact size. If no matching machine is ready, Aether cold-starts a machine at the requested size.

<Warning>
  Aether never substitutes another size during startup. A `large` task cannot consume a ready `medium` machine; without a ready `large` machine, it cold-starts at `large`. You can [resize its workspace](/guides/workspaces#updating-vm-size) later.
</Warning>

The web composer uses availability for the selected project. It shows a **Warm** badge on sizes that currently have ready machines and a **Warming** badge on sizes with configured slots but no ready machine.

## Tier-Bounded Quota

The number of warm slots you can use is set by your [subscription tier](/concepts/pricing-and-tiers):

| Tier | Warm slots |
| - | - |
| Free | 1 |
| Starter | 2 |
| Pro | 3 |
| Max | 5 |

Slots beyond your tier's quota cannot be assigned. The web app renders a fixed grid of slot cards sized to your tier; empty cards show as `unassigned`. [`aether warm-slot list`](/cli/warm-slot) prints the same numbered slots as rows.

Every plan can assign slots at any of the three sizes. The sizes differ in shape and credits/hour, not plan availability.

## Requirements

A slot assignment must meet two conditions:

* The project is **linked to a GitHub repository** so Aether can build its prewarmed environment from the repository source.
* The selected size maps to a **pool-eligible runtime class**. Pool eligibility belongs to the size's runtime class, not to the project.

Assigning a project and size to an occupied slot evicts the assignment that was there before.

## Automatic Slots

Slots you have not pinned fill automatically with your organization's most recently active projects, so a project you work in gets a warm pool for its next tasks without an assignment. A project's activity is when its newest task was created.

* An automatic slot warms its project at the size of the project's newest task.
* When every slot you are entitled to is taken, a project that becomes more recently active than an automatic slot's project takes that slot. Slots you pinned are never moved.
* Pinning always wins: a pin replaces an automatic slot, and a pinned project never also holds an automatic slot.
* Releasing a pinned slot hands it back to automatic filling. An automatic slot is released once its project goes 7 days without a task.

The web app labels automatic slots **Auto**.

## Slot Statuses

| Status | Meaning |
| - | - |
| `unassigned` | No project and size bound to the slot. |
| `provisioning` | Building warm capacity for the assigned project and size. |
| `ready` | One machine at the assigned size is available for an immediate start. |
| `stale` | The prewarmed environment needs a rebuild before it can serve a warm start. |
| `dormant` | The slot was neither assigned nor used for 7 days, so Aether stopped keeping it warm. The project's next task starts cold and warms the slot again. |

Building or rebuilding a pool's prewarmed environment does not consume credits.

## Managing Slots

<Tabs>
  <Tab title="Web">
    Open the warm-slots grid in settings, choose a slot, then select the project and machine size. Both selections are required. Release a pinned slot when you no longer want it reserved for that project; Aether then fills it automatically.
  </Tab>

  <Tab title="CLI">
    ```bash theme={"dark"}
    aether warm-slot list
    aether warm-slot assign --slot 0 --project <project-id> --size medium
    aether warm-slot release <slot-id>
    ```

    `--size` is required when assigning a slot; the CLI does not choose a default.
  </Tab>
</Tabs>

You can also manage slots over the API — see [warm-slot endpoints](/api-reference/account/billing/get-billing-slots).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.