Skip to main content
This feature is in public preview.
A deployment manages a fleet of instances running on a pool. You specify an instance template and a target instance count. The deployment creates and removes instances to match the target. A deployment does not buy or sell compute time. Place buy orders on the pool, or pair it with a procurement, to keep it allocated. A procurement trades compute time, and a deployment manages the instances that run on it. Use both together. 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. Standard deployments run instances on compute time you already bought. Spot deployments buy compute time automatically.

​
Create a deployment

Specify a pool, an instance template, a SKU, and a target instance count.
This creates a deployment named prod-workers that maintains 8 instances on the prod-cluster pool. Each instance runs the specified SKU and uses the referenced instance template. List available SKUs with sf skus list. If you omit --name, the deployment gets a generated name. Deployment creation does not take an idempotency key. Names are unique, and each pool and SKU pair can back only one deployment or spot deployment. A duplicate create returns an error rather than a second deployment. To retry a create safely, reuse the same --name. If the first attempt already succeeded, the retry fails with a name conflict instead of creating a duplicate.

​
Instance templates

A deployment references an instance template 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. To move existing instances onto the updated template, delete them. The deployment then creates replacements from the updated template to maintain the target count.

​
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.
Name templates use {{variable}} placeholders. Exactly 3 variables are available.
  • {{adjective}} and {{noun}} each insert a random word from a fixed word list.
  • {{nanoid(n)}} inserts a random alphanumeric identifier of n characters, where n is 1 to 21.
The deployment renders the template once per instance, so every variable resolves to a fresh random value. Literal text stays fixed. A {{nanoid(n)}} is what keeps each name unique. The template must start with an alphanumeric character or a variable. It must also produce at least as many combinations as the default {{adjective}}-{{noun}}-{{nanoid(6)}}. Resolved names are capped at 255 characters.

​
List deployments

List your deployments.

​
Get deployment details

Get a deployment by name or ID.

​
Update a deployment

Change the target instance count, instance template, name, or instance name template.
When you lower the target, the deployment stops the excess instances in the same order as any other pool scale-down (see instance priority). It stops the lowest priority first. Among instances of equal priority, it stops the most recently created first. The deployment does not set a priority on the instances it creates, so they rank equally. To keep a specific instance through a scale-down, raise its priority with sf instances set <name> --priority preferred (or critical). To shed one first, set it to yield. There is no separate protect or drain flag. Switch to a different instance template.

​
Replace a single instance

To rotate out a bad instance, terminate it directly with sf instances terminate <name>. The deployment counts the instance as gone and, on its next reconciliation pass, creates a replacement to restore the target. The target instance count is unchanged, so you do not resize the deployment to do this.

​
Delete a deployment

Delete a deployment by name or ID.
Deleting a standard deployment deletes all instances managed by that deployment, including instances that are still awaiting allocation. It does not sell the pool’s allocation.

​
Rate limits and monitoring

The deployments API has no endpoint-specific rate limit. SF Compute applies a shared request rate limit across the API. Requests over the limit get a 429 response with rate-limit headers. Retry on 429 after backing off. There is no event stream or webhook for deployment or instance state changes. Poll sf deployments get, sf deployments list, and sf instances list to observe transitions such as an instance moving from awaiting_allocation to running.

​
API reference

See the Deployments API for programmatic access.