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

# Instances and Pools

> How SF Compute decouples compute allocation from infrastructure management

SF Compute is built on two key primitives: instances and pools.

## Instances

An [instance](/preview/instances) is a GPU machine that runs a VM image. Like instances on other
clouds, it has hardware, an operating system image, startup configuration, logs, SSH access, and
lifecycle state. You create it, connect to it, run your workload, and terminate it when you are
done.

The only difference is that an SF Compute instance consumes compute time when it runs. It won't
start until it has compute time allocated to it.

That is what pools are for.

## Pools

A [pool](/preview/pools) is a named container that holds an allocation of compute time. It is
represented as a schedule: how many nodes you own, on which hardware, and for which windows of
time.

For example, a pool might have this schedule:

| Hardware                        | Window                        | Allocation |
| ------------------------------- | ----------------------------- | ---------- |
| H100, EU North, InfiniBand, ... | Mar 20, 09:00 → Mar 20, 17:00 | 4 nodes    |
| H100, EU North, InfiniBand, ... | Mar 20, 17:00 → Mar 21, 00:00 | 8 nodes    |
| H200, US East, No RDMA, ...     | Mar 21, 09:00 → Mar 21, 17:00 | 2 nodes    |

The pool's schedule changes as compute is bought, sold, transferred, or expires.

## Instance SKUs

Each pool tracks a separate schedule for each [instance SKU](/preview/instance-skus). An instance
SKU represents a specific set of interchangeable hardware, including:

* Accelerator type, such as H100 or H200
* Node specs like number of CPUs, RAM, and local storage
* Interconnect type
* Zone or location
* Other operator-defined hardware properties

Orders, transfers, and instances are pinned to an instance SKU. That is what tells
SF Compute which hardware the allocation comes from.

## Starting an instance

When you create an instance, you attach it to a pool. The instance starts in `awaiting_allocation`
if the pool does not currently have available compute for the hardware it will run on.

To add compute, place a buy [order](/preview/orders) on the pool. When the order fills, it adds to
the pool's allocation schedule for the order's instance SKU. Once the schedule covers the current
time and there is enough matching allocation, the instance starts booting.

```bash theme={null}
sf pools create --name dev

sf instances create \
  --pool dev \
  --image ubuntu-22.04.5-cuda-12.7

sf orders create \
  --side buy \
  --pool dev \
  --nodes 1 \
  --start now \
  --duration 2h \
  --max-rate 20.00 \
  --instance-sku isku_4UpxzQw7A8N
```

The instance can be created before the order fills. It will wait until matching allocation exists.

At this point, the two primitives fit together: instances define what should run, and pools define
when there is compute available to run it.

## Instance lifecycle

A pool's allocation determines whether attached instances can run.

| Pool state                             | Instance behavior                                     |
| -------------------------------------- | ----------------------------------------------------- |
| No matching allocation                 | Instance waits in `awaiting_allocation`               |
| Allocation becomes available           | Waiting instances start booting                       |
| Allocation covers the running instance | Instance stays `running`                              |
| Allocation shrinks below demand        | Instances are terminated until demand fits allocation |

Terminating an instance does not free its allocation. The allocation remains in the pool's
schedule until it is sold, transferred, or expires.

When allocation grows, waiting instances can start. If you use a
[deployment](/preview/deployments), the deployment can also create more instances to match its
target count, and those instances start when allocation is available.

When allocation shrinks below the number of running instances, SF Compute terminates instances
until the running count fits the pool schedule. Lower-priority instances are terminated first, and
among instances with the same priority, newer ones go first. If you need control over which work
survives a planned shrink, set [instance priority](/preview/instances) before selling,
transferring, or letting allocation expire.

Through this lifecycle, compute allocation is decoupled from what you run. You can buy compute
before you launch instances, recreate instances without losing reserved time, sell unused time
without deleting the pool, and move allocation between workloads.

You can think about it as analogous to a power grid. Pools are the circuits. Orders add compute to
those circuits, transfers move compute between circuits, and instances draw compute from the pool
they are attached to. If a circuit has enough scheduled compute, the attached instances can run.
If it does not, they wait or terminate.

## One pool or many

You can attach multiple instances to a single pool, or create a separate pool for each instance or
workload.

Use a separate pool when the instance should be managed independently.

* A personal dev box should usually have its own pool.
* A one-off debugging machine should usually have its own pool.
* A customer-isolated workload should use its own pool if selling or expiration should not affect
  other customers.

Use one shared pool when the instances are part of the same fleet and can share allocation
decisions.

* An inference fleet should usually use one pool and one deployment.
* Batch workers for the same queue can usually share one pool.
* A training job with many identical workers can usually share one pool.

The rule of thumb: put instances in the same pool only when they can be scaled, interrupted,
extended, sold, or transferred together.

## Transfers

Compute time can be transferred between pools. This lets you manage allocation like any other
resource: assign it to projects, teams, or workloads, then move it when it is not being used.

For example, a platform team might buy a large block of H100 time into a shared pool, then
transfer pieces of that allocation to separate pools for `training`, `inference`, and
`experiments`. If `experiments` does not need its allocation, the team can transfer it back or
move it to another project.

Transfers affect the same schedule that orders affect. If compute leaves a pool, attached
instances may terminate if the remaining allocation no longer covers them. If compute arrives,
waiting instances can start.

## What to read next

* [Orders](/preview/orders) covers buying and selling compute time.
* [Pools](/preview/pools) is the command reference for pool operations, including transfers.
* [Instances](/preview/instances) is the command reference for instance lifecycle operations.