Skip to main content

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.

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

​
Instance lifecycle

StatusDescription
awaiting_allocationNo allocation available on the capacity right now
runningVM is up and accessible
terminatedAllocation ended or instance was manually terminated
failedSomething went wrong
An instance in awaiting_allocation starts running when the capacity’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 --capacity 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 capacity and image. 
sf instances create

​
Images

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

│ 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 --capacity 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 --capacity dev --cloud-init ./startup.yaml

​
Check instance status

sf instances ls

NAME        STATUS   CAPACITY  INSTANCE SKU  CREATED
gpu-worker  running  dev       sea-3-h100    Mar 19, 4:40pm
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

​
Terminate an instance

Stop the VM immediately. The instance moves to terminated status. 
sf instances terminate {instance-name}

​
Delete an instance

Permanently remove an instance. 
sf instances delete {instance-name}

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