Instances - San Francisco Compute Docs

An instance is a GPU-backed virtual machine. You create an instance, attach it to a pool, choose an image, and attach a cloud-init script (required for SF Compute public images, optional for custom images). The instance waits for compute time (from orders) before starting.

Create an instance

Create an instance on a pool with an image and a startup script.

sf instances create --pool dev --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 --cloud-init ./startup.sh

All flags are optional in interactive mode. Omit them to use pickers for the pool, image, and SKU. Non-interactive runs (--no-input) must pass --pool, --image, and --sku (with a sku_… ID from sf skus list), plus --cloud-init when the image is an SF Compute public image.

sf instances create

Instance lifecycle

The API and CLI report the status as a snake_case value. The console shows the same status under a friendlier label.

Status	Console label	Description
`awaiting_allocation`	Pending	Created but not yet assigned to a node. No allocation is available on the pool right now.
`running`	Running	Assigned to a node and the VM is up; the image may still be booting.
`terminated`	Terminated	Allocation ended or the instance was terminated.
`failed`	Failed	The node backing the instance had a hardware fault. Terminate and recreate the instance.

An instance in awaiting_allocation starts running when the pool’s allocation schedule covers the current time. For example, if you buy compute time 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.

Why is my instance pending?

An instance stays awaiting_allocation (Pending in the console) until a node is assigned to it. A node is only assigned when the pool has allocation for the instance’s SKU at the current time. Check these in order:

The pool has no allocation. Creating an instance does not buy compute; you also need a filled buy order on the pool. Run sf pools get <pool> and check the TOTAL SCHEDULE line, or open the pool in the console. If the schedule is empty, place a buy order on the pool.
The allocation starts in the future. If the schedule’s first segment starts later than now, the instance waits until then.
The allocation is for a different SKU. An instance only runs on nodes of its own SKU. Run sf pools get <pool> --verbose to see the schedule per SKU and compare it with the instance’s SKU from sf instances get <instance>. See Mixed hardware.
The pool has fewer nodes than instances. Allocation covers a node count. If you created more instances than the pool has nodes right now, the extra ones wait. Terminate an instance or buy more nodes.
The buy order hasn’t filled yet. Orders add to the schedule only once they fill. Check the order status.

If the pool has allocation for the right SKU right now and the instance stays pending for more than a few minutes, contact support@sfcompute.com with the instance ID. The console also shows Pending in the Public IP column of a running or pending instance that was created with a public IPv4 address but hasn’t been assigned one yet. That’s a separate field from the instance status. See IP addresses. This table is the complete set of statuses today; the API may add new ones later, so don’t assume it’s exhaustive. There’s no separate status for an instance queued for preemption. A spot deployment marks an affected instance internally, but it keeps reporting running until the platform stops it and its status becomes terminated. terminated is one-way; an instance never returns to running. Terminated instances remain in sf instances list and GET /preview/v2/instances until you delete them. The CLI’s default view buckets recent terminated instances into their own section; pass --status terminated to list all of them. The platform stops an instance with no in-band push signal to the guest OS. There’s no ACPI (Advanced Configuration and Power Interface) shutdown notice before it powers off the VM (current behavior, not a guarantee). Spot-managed instances can poll ahead using the in-instance metadata endpoint described in Preemption. For everything else, build in a margin before your pool’s allocation ends instead of waiting for a signal. See Allocation schedule.

Images

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

sf images list

----------------------------------------------------------------------------------------
NAME                                               VISIBILITY  STATUS     CREATED
sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2  public      completed  Feb 23, 6:50pm

Pass the image name (as shown by sf images list) or ID when creating an instance. Public images require the full sfc:image:sfcompute:public:... name; SF Compute rejects the short trailing segment on its own.

sf instances create --pool dev --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 --cloud-init ./startup.sh

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. SSH access depends on this. SF Compute public images ship with no default password or key, and sf instances create does not add your local key, so the CLI requires --cloud-init for them: a non-interactive run fails without it, and the interactive prompt offers to create a script, pick a recent one, or provide a path. A custom image may omit it if it already includes your key. Either way, you need a cloud-init script or cloud-config that adds your public key to authorized_keys before you can connect. A shell script can inject your SSH public keys. Key files that don’t exist are skipped.

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

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

Cloud-config YAML sets 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

Pass the file when creating the instance.

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

Check instance status

List your instances and their statuses.

sf instances list

----------------------------------------------------------
NAME        STATUS   POOL  INSTANCE SKU     CREATED
gpu-worker  running  dev   sku_8FxR3pTzN6L  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. A duration counts back from now, so 24h means 24 hours ago. You can also use --since and --until as aliases. Get details on a specific instance.

sf instances get gpu-worker

SSH into an instance

Connect to a running instance over SSH.

sf instances ssh gpu-worker

The instance must be in running status and the image must be fully booted. This typically takes less than 5 minutes after the instance starts, but can take up to 10.

Permission denied (publickey) means the instance has no matching key: either its cloud-init never added one (see Cloud-init), or you’re connecting as the wrong user. sf instances ssh defaults to your local username, not root, mirroring ssh(1) and any User directive in ~/.ssh/config. If your cloud-init added the key to the root user, as in the examples above, connect with sf instances ssh gpu-worker --login root. Pin a specific local key with sf instances ssh gpu-worker -i ~/.ssh/<key>.

View logs

View an instance’s logs.

sf instances logs gpu-worker

Show more lines.

sf instances logs gpu-worker --limit 500

Filter by time range.

# Lines from the last hour
sf instances logs gpu-worker --after "in -1h"

# Lines within a window
sf instances logs gpu-worker --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 gpu-worker

Replace an instance

Replace an instance with a new one on the same pool and SKU. Replacing terminates the original and creates a fresh instance with a new image and startup script (and optionally a new name).

sf instances replace gpu-worker --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 --cloud-init ./new-startup.sh

The replacement inherits the original’s pool, SKU, subnet, public IPv4 setting, firewall, tags, and priority.

Replacing does not carry cloud-init over from the original instance. When the new image is an SF Compute public image, --cloud-init is required. For a custom image, omitting it starts the replacement with no startup script, so SSH only works if the image already includes your key.

Replace with a specific name.

sf instances replace gpu-worker --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 --cloud-init ./new-startup.sh --name worker-2

Instances have no persistent storage. Replacing an instance deletes all data on the original.

Delete an instance

Permanently delete an instance. The instance must be terminated first.

sf instances delete gpu-worker

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. The system keeps higher-priority instances longer and terminates lower-priority ones first. Among instances of equal priority, it terminates the newest first. Priority has 4 levels, ordered yield < normal < preferred < critical. Every instance defaults to normal.

Level	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 sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 \
  --cloud-init ./startup.sh --priority critical

You can also set priority through 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_nuO4nVSM8O3NnsRE7udBe",
  "image": "image_2KvMb9NpQs5",
  "instance_sku": "sku_8FxR3pTzN6L",
  "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_9dQpXk2LwZj", "priority_level": "critical" },
    { "id": "inst_Tr8mVn4BqYc", "priority_level": "yield" },
    { "id": "inst_5hGsWf7JzNd", "priority_level": "normal" }
  ]
}

Batch updates follow these rules.

A single call can include up to 10,000 entries.
All instances in a batch must belong to the same workspace.
The API rejects the whole request with a 422 if any entry has an unknown id or belongs to another organization.
A batch spanning more than one workspace is also rejected with a 422.
The entire request rolls back, so no instance is modified.
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. Setting priority requires the Instance: Write permission. Read-only tokens see priority_level on GET responses but receive 403 on writes.

Limitations

No persistent storage. If the underlying physical host dies, you get a replacement but not the same disk.
Public IPv4 is available only on SKUs that support it, and only when enabled at create time. See IP addresses.
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 become undetectable (fall off the PCIe bus). Terminate and recreate the instance, or email support@sfcompute.com.

API reference

See the Instances API for programmatic access.

​Create an instance

​Instance lifecycle

​Why is my instance pending?

​Images

​Cloud-init

​Check instance status

​SSH into an instance

​View logs

​Terminate an instance

​Replace an instance

​Delete an instance

​Instance priority

​Limitations

​API reference

Create an instance

Instance lifecycle

Why is my instance pending?

Images

Cloud-init

Check instance status

SSH into an instance

View logs

Terminate an instance

Replace an instance

Delete an instance

Instance priority

Limitations

API reference