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

# Deployments

> Automate instance creation and management

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

A deployment manages a fleet of [instances](/preview/instances) running on a
[pool](/preview/pools). You specify an [instance template](/preview/instance-templates)
and a target instance count. The deployment creates and removes instances to match the target.

Without a deployment, you create and manage instances manually. If an instance is destroyed because
its allocation ended, nothing replaces it. A deployment maintains your target count by creating a
new instance in `awaiting_allocation` state, which starts running when allocation becomes available.

## Create a deployment

```bash theme={null}
sf deployments create \
  --pool dev \
  --instance-template prod-ubuntu \
  --target-instance-count 4
```

This creates a deployment that maintains 4 instances on the `dev` pool, each configured
according to the referenced instance template.

## Instance templates

A deployment references an [instance template](/preview/instance-templates) that defines the image,
cloud-init script, and other configuration for each instance. Create an instance template first,
then reference it in the deployment.

Updating the instance template only affects new instances created by the deployment.

## Instance name templates

Instances created by a deployment get auto-generated names. You can provide a naming pattern with
`--instance-name-template` to give instances predictable names.

```bash theme={null}
sf deployments create \
  --pool dev \
  --instance-template prod-ubuntu \
  --target-instance-count 4 \
  --instance-name-template "worker-{{nanoid(10)}}"
```

## List deployments

```bash theme={null}
sf deployments list
```

```
NAME              POOL          INSTANCES  STATUS  MESSAGE
prod-workers      prod-cluster  8          info    running
ml-training-pool  ml-training   32         info    running
```

## Get deployment details

```bash theme={null}
sf deployments get prod-workers
```

```
│ DEPLOYMENT ID      depl_Xm9pR2wLk7Nf3Qy8Td5V
│ NAME               prod-workers
│ POOL               prod-cluster (pool_yIwQRIaE8bJo4Gs0000)
│ INSTANCE TEMPLATE  prod-ubuntu (ntmpl_Gw5rT8mKn2Pj4Lx9Qf7Y)
│ TARGET INSTANCES   8
│ NAME TEMPLATE      {{adjective}}-{{noun}}-{{nanoid(6)}}
│ STATUS             info
│ MESSAGE            running
│ CREATED            Mar 25, 2:00pm PDT
└ UPDATED            Mar 30, 1:00pm PDT
```

## Update a deployment

Change the target instance count, instance template, or name.

```bash theme={null}
sf deployments set prod-workers --target-instance-count 16
```

Switch to a different instance template.

```bash theme={null}
sf deployments set prod-workers --instance-template prod-ubuntu-v2
```

## Delete a deployment

```bash theme={null}
sf deployments delete prod-workers
```

Deleting a deployment deletes all instances that are running under that deployment.

### API reference

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