> ## 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.

# Pools

> Manage compute allocation

<Warning>
  This feature is in [public preview](/preview/roadmap).
</Warning>

A pool is a named container that holds a compute allocation schedule. You buy compute time into
a pool with orders, and instances on the pool run during the scheduled time slots. Buy
orders add time to the schedule, sell orders remove it. You can also move compute between
pools with [transfers](#transfers).

## Create a pool

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

## List pools

```bash theme={null}
sf pools list
NAME  NODES  PERIOD
dev       -  -
```

## View a pool

```bash theme={null}
sf pools get dev
│ POOL ID         pool_nuO4nVSM8O3NnsRE7udBe
│ NAME            dev
│ KIND            market
│ CREATED         Feb 17, 5:23pm PDT
│ TOTAL SCHEDULE  Today, 5:00pm → Tomorrow, 5:00pm: 1 node
└ PROCUREMENTS    dev-proc
```

## Allocation schedule

The allocation schedule shows how many nodes you have over time on this pool. Each time a buy
order fills, the schedule gains time. Each time a sell order fills, it loses time.

Instances on the pool can be created before there is allocation. They start running when
allocation becomes available and are terminated when it runs out.

## Mixed hardware

A single pool can hold allocation across several [instance SKUs](/preview/instance-skus). Each
order is filled against whatever SKU matches its requirements, and the allocation for each SKU is
tracked independently.

For example, a pool might hold 100 H100 nodes in `sea-3` from 9am to 5pm today, plus 50 H100
nodes in `ams-1` from 5pm today to 9am tomorrow. The SKUs do not need to overlap in time; the
schedule simply records what was bought and when.

Run `sf pools get <name> --verbose` to see a separate schedule block per SKU in addition to the
aggregate `TOTAL SCHEDULE`.

### Buy more on an existing SKU

To add allocation to a SKU you already have, pass its id via `--instance-sku` on the buy order or
procurement. Each SKU has a stable id (`isku_...`) that targets exactly that pool.

```bash theme={null}
sf orders create --side buy --pool dev --nodes 1 --start now --duration 1h \
  --max-rate 20.00 \
  --instance-sku isku_xxxxxxxx
```

Run `sf pools get <name> --verbose` or `sf instance-skus list` to find the id.

## Transfers

Transfers move nodes between two pools for a specified window of time.

### Create a transfer

```bash theme={null}
sf pools transfers create \
  --from dev \
  --to prod \
  --start-at "tomorrow" \
  --end-at "in 7d" \
  --node-count 4 \
  --instance-sku isku_4UpxzQw7A8N
```

Start and end times must be aligned to a minute boundary. Relative times are rounded up to align
with the next minute.

Omitting a required flag opens an interactive picker to help you fill in the remaining values.

Specify the full resource path if the `--from` or `--to` pool is located in a
different workspace.

```bash theme={null}
sf pools transfers create \
  --from dev \
  --to sfc:pool:user:prod_ws:prod \
  --start-at "tomorrow" \
  --end-at "in 7d" \
  --node-count 4 \
  --instance-sku isku_4UpxzQw7A8N
```

### List transfers

```bash theme={null}
sf pools transfers list
```

```
ID            CREATED AT  STATUS    FROM        TO    INSTANCE SKU
pxfr_abc123   Mar 19      executed  dev         prod  sea-3-h100
pxfr_def456   Mar 18      pending   dev         prod  sea-3-h100
pxfr_ghi789   Mar 18      rejected  inference   prod  sea-3-h100
```

Filter by pool (repeatable) or status, or pass `--verbose` for the full schedule of each
transfer.

```bash theme={null}
sf pools transfers list --pool prod --status executed
```

```
ID CREATED AT STATUS FROM TO INSTANCE SKU
pxfr_abc123 Mar 19 executed dev prod sea-3-h100
```

### Get a transfer

```bash theme={null}
sf pools transfers get pxfr_abc123
```

```
│ TRANSFER ID    pxfr_abc123
│ STATUS         executed
│ FROM POOL      dev
│ TO POOL        prod
│ INSTANCE SKU   isku_4UpxzQw7A8N (sea-3-h100)
│ CREATED        Mar 19, 4:40pm PDT
└ SCHEDULE       Mar 20, 12:00am → Mar 27, 12:00am: 4 nodes
```

### Protect nodes from termination

When a pool's allocation drops below the number of running nodes (a sell order fills, a
[procurement](/preview/procurements) scales down, or a transfer leaves), the newest nodes are
terminated until the schedule and the running count match.

To protect specific nodes against sale down, transfer their allocation onto a separate pool with no
procurement and no standing sell orders. Allocation on that pool can only shrink through
explicit action, so the nodes there stay up.

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

sf pools transfers create \
  --from dev \
  --to prod-protected \
  --start-at now \
  --end-at "in 30d" \
  --node-count 4 \
```

## Rename a pool

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

## Delete a pool

```bash theme={null}
sf pools delete dev
```

## Extend a pool

```bash theme={null}
sf pools extend dev
```

This will automatically place an order that extends the node count at the end of the pool schedule out to a desired end time. For instance, consider the following pool.

```bash theme={null}
sf pools get dev
│ POOL ID         pool_nuO4nVSM8O3NnsRE7udBe
│ NAME            dev
│ KIND            market
│ CREATED         Feb 17, 5:23pm PDT
│ TOTAL SCHEDULE  Today, 5:00pm: 2 nodes
│                 Tomorrow, 5:00pm: 0 nodes
└ PROCUREMENTS    dev-proc
```

We can extend it for two hours. Notice that the end time has extended by two hours.

```bash theme={null}
sf pools extend dev
  note: pool currently ends at May 17, 5:00pm PDT
> Extend by duration or until time: 2h
  note: 1 node = 8x GPU
> Max rate ($/node-hour): 20
> Allow as standing order until filled? No

│ ACTION                  extend pool
│ POOL                    dev (pool_nuO4nVSM8O3NnsRE7udBe)
│ NODES                   2
│ EXTENDING FROM          Tomorrow, 5:00pm PDT
│ EXTENDING TO            Tomorrow, 7:00pm PDT
│ RATE (PER 8X GPU NODE)  $20.00/node/hr
│ TOTAL                   $80.00
│ INSTANCE SKU            sea-3-h100 (isku_4UpxzQw7A8N)
│ STANDING                false
└ to be placed
> Place this order? Yes
✓ Order ordr_HV6cjCNfgs2y9HCIOJITO filled
```

```bash theme={null}
sf pools show dev
│ POOL ID         pool_nuO4nVSM8O3NnsRE7udBe
│ NAME            dev
│ RESOURCE PATH   sfc:pool:sfcompute-com-seb:default:dev
│ KIND            market
│ CREATED         Feb 17, 5:23pm PDT
│
│ TOTAL SCHEDULE  Today, 5:00pm: 2 nodes
│                 Tomorrow, 7:00pm: 0 nodes
└ PROCUREMENTS    dev-proc
```

Extension requires availability during the requested window.

### API reference

See the [Pools API](/preview/api-reference/pools/list-pools) for programmatic access.