Instances - San Francisco Compute Docs

This feature is in public preview.

An instance is a GPU machine that runs a VM image. You create an instance, attach it to a pool, choose an image, and optionally provide a cloud-init script. The instance waits for compute time (from orders) before starting.

Instance lifecycle

Status	Description
awaiting_allocation	No allocation available on the pool right now
running	VM is up and accessible
terminated	Allocation ended or instance was manually terminated
failed	Something went wrong

An instance in awaiting_allocation starts running when the pool’s allocation schedule covers the current time. For example, if you buy compute starting at now, the instance starts within about a minute. If the order starts in the future, the instance waits until then. The image download and boot process takes up to 10 minutes before SSH is available.

Create an instance

sf instances create --pool dev --image ubuntu-22.04.5-cuda-12.7 --cloud-init ./startup.sh

All flags are optional in interactive mode — omit them to use pickers for pool and image.

sf instances create

Images

List available images to find one to use with your instance.

sf images list

│ NAME        ubuntu-22.04.5-cuda-12.7
│ ID          image_TQiHEBzCA18ToAQqBtOr_
│ VISIBILITY  public
│ STATUS      completed
│ SIZE        8 GB
└ CREATED     Feb 23, 6:50pm UTC

Pass the image ID when creating an instance.

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

To build and upload your own custom image, see Custom Images.

Cloud-init

Pass a startup script or cloud-config YAML via --cloud-init to configure the VM on first boot. Shell script — inject your SSH public key:

cat >startup.sh <<SCRIPT
#!/bin/bash

mkdir -p /root/.ssh
cat >>/root/.ssh/authorized_keys <<"EOF"
$(cat ~/.ssh/id_rsa.pub 2>/dev/null)
$(cat ~/.ssh/id_ecdsa.pub 2>/dev/null)
$(cat ~/.ssh/id_ecdsa_sk.pub 2>/dev/null)
$(cat ~/.ssh/id_ed25519.pub 2>/dev/null)
$(cat ~/.ssh/id_ed25519_sk.pub 2>/dev/null)
$(cat ~/.ssh/id_xmss.pub 2>/dev/null)
$(cat ~/.ssh/id_dsa.pub 2>/dev/null)
EOF
SCRIPT

Cloud-config YAML — set up users and keys declaratively:

startup.yaml

#cloud-config
disable_root: false
ssh_pwauth: false
users:
  - name: root
    ssh_authorized_keys:
      - ssh-ed25519 AAAA... you@example.com

sf instances create --pool dev --cloud-init ./startup.yaml

Check instance status

sf instances list

NAME        STATUS   POOL      INSTANCE SKU  CREATED
gpu-worker  running  dev       sea-3-h100    Mar 19, 4:40pm

Filter by time range.

# Instances from the last 24 hours
sf instances list --created-after 24h

# Instances within a specific window
sf instances list --created-after 2025-03-01 --created-before 2025-03-08

# Instances from a specific calendar month
sf instances list --month 2025-05

--created-after and --created-before accept a datetime, Unix timestamp, or a duration like 24h or 7d (meaning 24 hours or 7 days ago, respectively). You can also use --since and --until as aliases. Get details on a specific instance.

sf instances get gpu-worker

SSH into an instance

sf instances ssh {instance-name}

The instance must be in running status and the image must be fully booted. This can take up to 10 minutes after the instance starts.

View logs

sf instances logs {instance-name}

Show more lines.

sf instances logs {instance-name} --limit 500

Filter by time range.

# Lines from the last hour
sf instances logs {instance-name} --after "in -1h"

# Lines within a window
sf instances logs {instance-name} --after 2025-05-22 --before "now"

--after and --before accept flexible time expressions: "now", "in -1h", a date like mar 1, ISO 8601, or a Unix timestamp.

Terminate an instance

Stop the VM immediately. The instance moves to terminated status.

sf instances terminate {instance-name}

Replace an instance

Replace an instance with a new one on the same pool. The original instance is terminated and a new instance is created with the specified image.

sf instances replace {instance-name} --image ubuntu-22.04

Provide a cloud-init script for the replacement:

sf instances replace {instance-name} --image ubuntu-22.04 --cloud-init ./startup.yaml

Give the replacement instance a specific name:

sf instances replace {instance-name} --image ubuntu-22.04 --name worker-2

Cloud-init is not carried over from the original instance. If you omit --cloud-init, the replacement boots with no startup script and you won’t be able to SSH into it.

Delete an instance

Permanently remove an instance.

sf instances delete {instance-name}

Replace an instance

Replace an instance with a new one on the same pool and SKU. The original instance is terminated and a fresh instance is created with a new image (and optionally a new startup script and name).

sf instances replace {instance-name} --image ubuntu-22.04.5-cuda-12.7

The replacement inherits the original’s pool, SKU, subnet, public IPv4 setting, firewall, tags, and priority. Replace with a new startup script

sf instances replace {instance-name} --image ubuntu-22.04.5-cuda-12.7 --cloud-init ./new-startup.sh

If you omit --cloud-init, the replacement starts with no startup script — you will not be able to SSH into it. Pass a cloud-init file to configure SSH access.

Replace with a specific name

sf instances replace {instance-name} --image ubuntu-22.04.5-cuda-12.7 --name worker-2

There is no persistent storage attached to an instance. Replacing an instance will result in loss of all data stored on the original.

Instance priority

When a pool’s quota drops below the number of running instances, the system terminates instances to match. Instance priority controls which ones survive. Higher-priority instances are kept longer; lower-priority ones are terminated first. Priority has four arms, ordered yield < normal < preferred < critical. Every instance defaults to normal. The expected_shutdown_at field on instance responses is deprecated and always null.

Arm	Meaning
`yield`	Surrender this instance first when the pool shrinks.
`normal`	Default. No special preference.
`preferred`	Keep this instance over `normal` ones when possible.
`critical`	Keep this instance over everything else.

Set priority on an existing instance.

sf instances set gpu-worker --priority critical

Set priority at create time.

sf instances create --pool dev --image ubuntu-22.04.5-cuda-12.7 --priority critical

The same surface is available over the API. Pass priority_level in the body of POST /preview/v2/instances to set it at create time.

POST /preview/v2/instances
{
  "pool": "pool_xxx",
  "image": "img_xxx",
  "priority_level": "critical"
}

Omit priority_level to default to normal. Update one instance with PATCH /preview/v2/instances/{id}.

PATCH /preview/v2/instances/inst_xxx
{ "priority_level": "preferred" }

Omit priority_level to leave it unchanged. Pass "normal" to reset to the default. Update many instances atomically by PATCHing the collection.

PATCH /preview/v2/instances
{
  "data": [
    { "id": "inst_aaa", "priority_level": "critical" },
    { "id": "inst_bbb", "priority_level": "yield" },
    { "id": "inst_ccc", "priority_level": "normal" }
  ]
}

If any entry is rejected (unknown id, cross-account id, missing permissions), the entire request rolls back with a 422 and no instance is touched. Up to 10,000 entries per call. An empty data returns 200 with no writes. When the same id appears more than once, the last occurrence wins. The response includes the updated instance for each entry, so you can confirm the result in one round-trip. When two instances have the same priority, the newer one is terminated first.

`critical` and procurement automations

critical cannot be set on an instance whose pool has an active procurement automation — procurement-backed pools resize automatically, so critical can’t be honored there. The constraint applies in both directions:

Setting priority_level: critical on such an instance returns 422.
Creating a procurement on a pool that already has critical instances returns 422 — downgrade the affected instances (for example, to preferred) first.

Use preferred instead when the pool is procurement-backed, or disable the procurement before setting critical. Setting priority requires the Node: Write permission. Read-only tokens see priority_level on GET responses but receive 403 on writes.

Limitations

No persistent storage. If the underlying machine dies, you get a replacement but not the same disk.
No public IPs. To serve inference, set up a proxy in another cloud and connect it via VPN.
No InfiniBand.
Instances don’t share a VPC or VLAN. Configure a VPN if you need connectivity between instances.
Boot time can be up to 10 minutes for image download and startup.
No GPU monitoring. GPUs may occasionally fall off the bus — terminate and recreate the instance, or contact us.

API reference

See the Instances API for programmatic access.

​Instance lifecycle

​Create an instance

​Images

​Cloud-init

​Check instance status

​SSH into an instance

​View logs

​Terminate an instance

​Replace an instance

​Delete an instance

​Replace an instance

​Instance priority

​critical and procurement automations

​Limitations

​API reference

Instance lifecycle

Create an instance

Images

Cloud-init

Check instance status

SSH into an instance

View logs

Terminate an instance

Replace an instance

Delete an instance

Replace an instance

Instance priority

`critical` and procurement automations

Limitations

API reference