# Get the authenticated account and logged-in user
Source: https://docs.sfcompute.com/api-reference/account/get-the-authenticated-account-and-logged-in-user

/openapi.json get /preview/v2/me
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Retrieve the authenticated account and user.



# List events
Source: https://docs.sfcompute.com/api-reference/events/list-events

/openapi.json get /preview/v2/events
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

List the account's activity events. Only the last 7 days of events are returned.



# Create firewall
Source: https://docs.sfcompute.com/api-reference/firewalls/create-firewall

/openapi.json post /preview/v2/firewalls
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Create a workspace-scoped firewall with an ordered list of allow-only ingress rules.



# Delete firewall
Source: https://docs.sfcompute.com/api-reference/firewalls/delete-firewall

/openapi.json delete /preview/v2/firewalls/{id}
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Delete a firewall. The firewall must not be in use.



# Get firewall
Source: https://docs.sfcompute.com/api-reference/firewalls/get-firewall

/openapi.json get /preview/v2/firewalls/{id}
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Retrieve a firewall by ID or resource path.



# List firewalls
Source: https://docs.sfcompute.com/api-reference/firewalls/list-firewalls

/openapi.json get /preview/v2/firewalls
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

List firewalls in a workspace, including the auto-managed 'default' firewall.



# Replace a firewall's rules
Source: https://docs.sfcompute.com/api-reference/firewalls/replace-a-firewalls-rules

/openapi.json put /preview/v2/firewalls/{id}
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Replace a firewall's rules. Rule order is preserved.



# Complete image upload
Source: https://docs.sfcompute.com/api-reference/images/complete-image-upload

/openapi.json post /v2/images/{id}/complete
Finalize a multipart image upload.



# Create image
Source: https://docs.sfcompute.com/api-reference/images/create-image

/openapi.json post /v2/images
Create an image and start a multipart upload.



# Delete image
Source: https://docs.sfcompute.com/api-reference/images/delete-image

/openapi.json delete /v2/images/{id}
Delete an image.



# Download image
Source: https://docs.sfcompute.com/api-reference/images/download-image

/openapi.json get /v2/images/{id}/download
Get a presigned URL to download an image.



# Get image
Source: https://docs.sfcompute.com/api-reference/images/get-image

/openapi.json get /v2/images/{id}
Retrieve an image by ID. Returns both user-owned and public images.



# Get upload part URL
Source: https://docs.sfcompute.com/api-reference/images/get-upload-part-url

/openapi.json post /v2/images/{id}/parts
Get a presigned URL to upload one part of a multipart image upload.



# List images
Source: https://docs.sfcompute.com/api-reference/images/list-images

/openapi.json get /v2/images
List images in a workspace.



# Reinstate image
Source: https://docs.sfcompute.com/api-reference/images/reinstate-image

/openapi.json post /v2/images/{id}/reinstate
Reinstate a revoked image, making it available for new instances again



# Revoke image
Source: https://docs.sfcompute.com/api-reference/images/revoke-image

/openapi.json post /v2/images/{id}/revoke
Revoke a private image so it can't back new instances. Existing instances keep running.



# Create InfiniBand partition
Source: https://docs.sfcompute.com/api-reference/infiniband-partitions/create-infiniband-partition

/openapi.json post /preview/v2/infiniband_partitions
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Create an InfiniBand partition on a fabric.



# Delete InfiniBand partition
Source: https://docs.sfcompute.com/api-reference/infiniband-partitions/delete-infiniband-partition

/openapi.json delete /preview/v2/infiniband_partitions/{id}
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Delete an InfiniBand partition. Fails while instances are attached.



# Get InfiniBand partition
Source: https://docs.sfcompute.com/api-reference/infiniband-partitions/get-infiniband-partition

/openapi.json get /preview/v2/infiniband_partitions/{id}
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Get an InfiniBand partition by ID or resource path.



# List InfiniBand partitions
Source: https://docs.sfcompute.com/api-reference/infiniband-partitions/list-infiniband-partitions

/openapi.json get /preview/v2/infiniband_partitions
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

List InfiniBand partitions.



# List instances in an InfiniBand partition
Source: https://docs.sfcompute.com/api-reference/infiniband-partitions/list-instances-in-an-infiniband-partition

/openapi.json get /preview/v2/infiniband_partitions/{id}/instances
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

List the instances you can see that are attached to an InfiniBand partition.



# Create instance template
Source: https://docs.sfcompute.com/api-reference/instance-templates/create-instance-template

/openapi.json post /preview/v2/instance_templates
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Create a reusable instance template.



# Delete instance template
Source: https://docs.sfcompute.com/api-reference/instance-templates/delete-instance-template

/openapi.json delete /preview/v2/instance_templates/{id}
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Delete an instance template. The template must not be in use by any capacity.



# Get instance template
Source: https://docs.sfcompute.com/api-reference/instance-templates/get-instance-template

/openapi.json get /preview/v2/instance_templates/{id}
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Retrieve an instance template by ID or resource path.



# List instance templates
Source: https://docs.sfcompute.com/api-reference/instance-templates/list-instance-templates

/openapi.json get /preview/v2/instance_templates
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

List all instance templates.



# Create instance
Source: https://docs.sfcompute.com/api-reference/instances/create-instance

/openapi.json post /v2/instances
Create an instance.



# Delete instance
Source: https://docs.sfcompute.com/api-reference/instances/delete-instance

/openapi.json delete /v2/instances/{id}
Delete an instance.



# Get instance
Source: https://docs.sfcompute.com/api-reference/instances/get-instance

/openapi.json get /v2/instances/{id}
Retrieve an instance by ID or name.



# Get instance cloud-init user data
Source: https://docs.sfcompute.com/api-reference/instances/get-instance-cloud-init-user-data

/openapi.json get /v2/instances/{id}/cloud_init_user_data
Retrieve the cloud-init user data an instance was created with.



# Get instance logs
Source: https://docs.sfcompute.com/api-reference/instances/get-instance-logs

/openapi.json get /v2/instances/{id}/logs
Retrieve logs for an instance.



# Get instance SSH info
Source: https://docs.sfcompute.com/api-reference/instances/get-instance-ssh-info

/openapi.json get /v2/instances/{id}/ssh
Retrieve SSH connection details for an instance.



# List instances
Source: https://docs.sfcompute.com/api-reference/instances/list-instances

/openapi.json get /v2/instances
List all instances.



# Replace instance
Source: https://docs.sfcompute.com/api-reference/instances/replace-instance

/openapi.json post /v2/instances/{id}/replace
Replace an instance with a fresh one on the same capacity, running a new image. Subnet, firewall, public IPv4 setting, tags, and priority carry over.



# Terminate instance
Source: https://docs.sfcompute.com/api-reference/instances/terminate-instance

/openapi.json post /v2/instances/{id}/terminate
Terminates a running instance. Terminated instances can not be restarted.



# Update instance
Source: https://docs.sfcompute.com/api-reference/instances/update-instance

/openapi.json patch /v2/instances/{id}
Update an instance. Omitted fields are left unchanged.



# Get account limits
Source: https://docs.sfcompute.com/api-reference/limits/get-account-limits

/openapi.json get /preview/v2/limits
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

List the limits in effect for your account, with usage where tracked.



# Get market depth
Source: https://docs.sfcompute.com/api-reference/orderbook/get-market-depth

/openapi.json get /preview/v2/orderbook/depth
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Depth of book for the given requirements and delivery window.



# Get market quote
Source: https://docs.sfcompute.com/api-reference/orderbook/get-market-quote

/openapi.json get /preview/v2/orderbook/quote
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Top-of-book quote for the given requirements and delivery window.



# List market fills
Source: https://docs.sfcompute.com/api-reference/orderbook/list-market-fills

/openapi.json get /preview/v2/orderbook/fills
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

List fills matching the requirements and delivery window, newest first.



# List market orders
Source: https://docs.sfcompute.com/api-reference/orderbook/list-market-orders

/openapi.json get /preview/v2/orderbook/orders
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

List open and filled orders from the last 30 days matching the requirements.



# List market windows
Source: https://docs.sfcompute.com/api-reference/orderbook/list-market-windows

/openapi.json get /preview/v2/orderbook/windows
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

List delivery windows with resting orders matching the requirements in a time range.



# Cancel order
Source: https://docs.sfcompute.com/api-reference/orders/cancel-order

/openapi.json post /v2/orders/{id}/cancel
Request cancellation of an order. Cancellation is asynchronous.



# Create order
Source: https://docs.sfcompute.com/api-reference/orders/create-order

/openapi.json post /v2/orders
Place a buy or sell order.



# Estimate an order
Source: https://docs.sfcompute.com/api-reference/orders/estimate-an-order

/openapi.json post /preview/v2/order_preview
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Estimate a buy or sell order before placing it.



# Get order
Source: https://docs.sfcompute.com/api-reference/orders/get-order

/openapi.json get /v2/orders/{id}
Retrieve an order by ID.



# List orders
Source: https://docs.sfcompute.com/api-reference/orders/list-orders

/openapi.json get /v2/orders
List all orders.



# Get platform constants
Source: https://docs.sfcompute.com/api-reference/platform/get-platform-constants

/openapi.json get /preview/v2/platform_constants
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Returns current platform-wide settings. Values may change over time.



# Create pool
Source: https://docs.sfcompute.com/api-reference/pools/create-pool

/openapi.json post /v2/pools
Create a pool to hold compute.



# Create pool transfer
Source: https://docs.sfcompute.com/api-reference/pools/create-pool-transfer

/openapi.json post /v2/pool_transfers
Transfer some or all of one pool into another



# Delete pool
Source: https://docs.sfcompute.com/api-reference/pools/delete-pool

/openapi.json delete /v2/pools/{id}
Delete a pool. The pool must have no active dependencies.



# Get pool
Source: https://docs.sfcompute.com/api-reference/pools/get-pool

/openapi.json get /v2/pools/{id}
Retrieve a pool by ID, resource path, or name, including its compute schedule.



# Get pool transfer
Source: https://docs.sfcompute.com/api-reference/pools/get-pool-transfer

/openapi.json get /v2/pool_transfers/{id}
Retrieve a pool transfer by ID.



# List pool transfers
Source: https://docs.sfcompute.com/api-reference/pools/list-pool-transfers

/openapi.json get /v2/pool_transfers
List pool transfers for the caller's organization.



# List pools
Source: https://docs.sfcompute.com/api-reference/pools/list-pools

/openapi.json get /v2/pools
List all pools.



# Update pool
Source: https://docs.sfcompute.com/api-reference/pools/update-pool

/openapi.json patch /v2/pools/{id}
Update a pool. Omitted fields are left unchanged.



# Get SKU
Source: https://docs.sfcompute.com/api-reference/skus/get-sku

/openapi.json get /v2/skus/{id}
Retrieve a SKU by ID, including its properties.



# Get SKU availability
Source: https://docs.sfcompute.com/api-reference/skus/get-sku-availability

/openapi.json get /v2/skus/{id}/availability
The purchasable-capacity schedule of one SKU.



# List SKU availability
Source: https://docs.sfcompute.com/api-reference/skus/list-sku-availability

/openapi.json get /v2/skus/availability
The purchasable-capacity schedule of every SKU.



# List SKUs
Source: https://docs.sfcompute.com/api-reference/skus/list-skus

/openapi.json get /v2/skus
List the SKUs available on the market with their properties.



# Get user
Source: https://docs.sfcompute.com/api-reference/users/get-user

/openapi.json get /preview/v2/users/{id}
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

Returns user details by ID or resource path.



# List users
Source: https://docs.sfcompute.com/api-reference/users/list-users

/openapi.json get /preview/v2/users
> ⚠️ This endpoint is in [public preview](/preview/roadmap#feature-states).

List users that are members of the caller's organization.



# Create workspace
Source: https://docs.sfcompute.com/api-reference/workspaces/create-workspace

/openapi.json post /v2/workspaces
Create a workspace.



# Get workspace
Source: https://docs.sfcompute.com/api-reference/workspaces/get-workspace

/openapi.json get /v2/workspaces/{id}
Retrieve a workspace by ID or resource path.



# List workspaces
Source: https://docs.sfcompute.com/api-reference/workspaces/list-workspaces

/openapi.json get /v2/workspaces
List all workspaces for the authenticated account, newest first.



# Events
Source: https://docs.sfcompute.com/preview/events

Read an ordered log of what happened on your account, from instances starting to orders filling

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

Events form an append-only log of what happens on your account, such as [instances](/preview/instances) starting and terminating or [orders](/preview/orders) filling. Only events from the last 7 days are available. Authenticate with a bearer token, as described in [Using the API](/preview/using-the-api).

```bash theme={null}
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://api.sfcompute.com/preview/v2/events"
```

The response holds a page of events in `data`.

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "evt_x7Kp2mQhTv9rWq3s",
      "cursor": "evtc_...",
      "action": "instance.terminated",
      "occurred_at": 1755644312,
      "actor": { "type": "token", "id": "tokn_..." },
      "targets": [{ "type": "instance", "id": "inst_9dQpXk2LwZj" }]
    }
  ],
  "has_more": false,
  "cursor": "evtc_..."
}
```

`action` names what happened, and `occurred_at` records when, as a Unix timestamp in seconds. `actor` is the API token whose request caused the event, or `{ "type": "system" }` for automated actions, such as a preemption or a scheduled end. `targets` lists the resources the event is about as `{type, id}` pairs. Each `id` is the same ID the rest of the API uses for that resource.

## Event types

The table below lists each event type and its target type. To filter by resource, pass a target type as `target_type` or a single resource's ID as `target`.

| Action | Target type | Meaning |
| - | - | - |
| `instance.created` | `instance` | The instance was created and is [awaiting allocation](/preview/instances#instance-lifecycle). |
| `instance.running` | `instance` | The instance started running. SSH access becomes available once its image finishes booting. |
| `instance.termination_imminent` | `instance` | The instance will be terminated soon because its allocation is ending, whether from preemption or a scheduled end. |
| `instance.terminated` | `instance` | The instance was terminated, whether by user request, replacement, preemption, deployment teardown, or a scheduled end. |
| `instance.failed` | `instance` | The instance reported itself unhealthy. This does not terminate the instance, though work on it may be lost. [Replace](/preview/instances#replace-an-instance) or terminate it. |
| `instance.connection_lost` | `instance` | The instance stopped responding. |
| `order.created` | `order` | The order was placed. |
| `order.filled` | `order` | The order filled completely. |
| `order.cancelled` | `order` | The order was cancelled. |
| `image.revoked` | `image` | The image was [revoked](/preview/images#revoking-an-image) and can no longer back new instances. |
| `image.reinstated` | `image` | The image was reinstated and can back new instances again. |
| `trust_level.updated` | `account` | Your account's trust level changed. |
| `instance_sku_override.updated` | `instance_sku` | SF Compute set or changed property overrides on a [SKU](/preview/instance-skus) for your account. |
| `instance_sku_override.deleted` | `instance_sku` | SF Compute removed the property overrides on a SKU for your account. |

New event types are added over time, so if you don't filter by `action`, expect actions that aren't in this table. For a given instance, `instance.created`, `instance.running`, and `instance.terminated` appear in that order. An instance terminated while still awaiting allocation has no `instance.running` event.

## Consuming the stream

List events with `GET /preview/v2/events`. Events are returned oldest first, up to `limit` per request. `limit` defaults to 50 and is capped at 200. To fetch the next page, pass the response's `cursor` back as `starting_after`. `has_more` tells you whether more events are already available.

When `data` is empty and `has_more` is false, you have read everything so far. That response carries no `cursor`, so keep the one you sent and poll with it again later.

Filter with `action` for an exact event type, `target` for one resource, `target_type` for one type of resource, and `since` and `until` for inclusive bounds on `occurred_at`, given as Unix timestamps. Filters combine, so a single request can ask for one event type on one resource.

```bash theme={null}
# Everything that happened to one instance
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://api.sfcompute.com/preview/v2/events?target=inst_9dQpXk2LwZj&target_type=instance"

# All terminations since a point in time
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://api.sfcompute.com/preview/v2/events?action=instance.terminated&since=1755043200"

# When one order filled
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://api.sfcompute.com/preview/v2/events?action=order.filled&target=ordr_5Gh8kLm2Np4QwXz"
```

A cursor only works with the filters it was created with, and reusing it with different filters returns 400 Bad Request. If a saved cursor falls outside the 7-day retention window, requests with it return 410 Gone. In that case, start over without a cursor to read from the oldest available event.

## API reference

See the [Events API](/preview/api-reference/events/list-events) for every parameter and response field.


# Grants
Source: https://docs.sfcompute.com/preview/grants

Assign roles to users and tokens

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

A grant assigns a [role](/preview/roles) to a user or [token](/preview/tokens) within a
[workspace](/preview/workspaces) or across the organization.

## Granting access to a user

Grant a role directly to a user by their email.

```bash theme={null}
sf grants create \
  --workspace production \
  --user alice@acme.co \
  --role admin
```

Alice now has admin access to the `production` workspace.

As with other commands, `-w` and `SF_WORKSPACE` also set the workspace. `--org` overrides
`SF_WORKSPACE`, and can't be combined with `-w` or `--workspace`.

## Organization-wide grants

Use `--org` to grant a role across all workspaces in the organization.

```bash theme={null}
sf grants create \
  --org \
  --user alice@acme.co \
  --role admin
```

Alice now has admin access to every workspace in the organization.

## Listing grants

List all grants in the organization. With a workspace set by `-w` or `SF_WORKSPACE`, the list shows
only the grants scoped to that workspace, not organization-wide ones.

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

```text theme={null}
------------------------------------------------------------------------------------------------------------------
ID                          WORKSPACE   ROLE               TYPE   PRINCIPAL                   CREATED
grnt_k3RnX9vLm7Qp2Yw5JdA4f  (Org-wide)  admin              user   alice@acme.co               Feb 4, 2025, 12:00pm
grnt_8KvQ3mWxYpRtZn6Hb2C7j  production  training-operator  user   bob@acme.co                 Feb 3, 2025, 9:30am
grnt_9QwT4xNbVs2Lm7Cfj3W5d  production  viewer             token  tokn_5DhP2nLqWmKz8XvBt4Jc6  Feb 1, 2025, 8:15am
```

Filter by workspace or by user. Unlike `sf grants create`, which accepts an email, the `--user`
filter takes a user ID.

```bash theme={null}
sf grants list --workspace production
sf grants list --user usr_7d41c2a90b5f83e6
```

## Deleting a grant

Delete a grant by its ID, which `sf grants list` prints in the first column.

```bash theme={null}
sf grants delete grnt_k3RnX9vLm7Qp2Yw5JdA4f
```

You can also delete a workspace-scoped grant by its attributes. As with `sf grants list`, `--user`
takes a user ID.

```bash theme={null}
sf grants delete \
  --workspace production \
  --user usr_3e92f8b06c14da75 \
  --role training-operator
```

Delete an organization-wide grant.

```bash theme={null}
sf grants delete \
  --org \
  --user usr_7d41c2a90b5f83e6 \
  --role admin
```

## Multiple grants

A user or token can have multiple grants. SF Compute combines the permissions from every granted
role (a union).

```bash theme={null}
sf grants create --org --user bob@acme.co --role viewer
sf grants create --workspace production --user bob@acme.co --role training-operator
```

Bob has `viewer` access organization-wide and `training-operator` access in `production`.

## Token grants

Grant roles to tokens for CI/CD pipelines and other automation.

```bash theme={null}
sf grants create \
  --workspace production \
  --token ci-deploy \
  --role training-operator
```

Alternatively, assign a role when creating the token. `sf tokens create` takes the same
`--workspace` and `--org` flags and creates 1 grant per role.

```bash theme={null}
sf tokens create --name ci-deploy --role training-operator --workspace production
```

See [Tokens](/preview/tokens#attaching-a-role).

## How grants interact with roles

Grants bind users or tokens to roles. Roles define which actions a user or token can perform.

When a request arrives, SF Compute collects every grant the user or token holds on the target
workspace, including organization-wide grants. It then evaluates the rules from all matched roles.
See [Roles](/preview/roles) for the rule effects and evaluation semantics.

## API reference

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


# Instances and Pools
Source: https://docs.sfcompute.com/preview/guides/instances-and-pools

How instances and pools separate what you run from the compute time it runs on

You run workloads on instances and pay for the compute time they use from pools.

## Instances

An [instance](/preview/instances) is a GPU virtual machine booted from an [image](/preview/images).
Like instances on other clouds, it has hardware, an image, startup configuration, logs, SSH access,
and lifecycle state. You create it, connect to it, run your workload, and terminate it when you are
done.

The only difference is that an SF Compute instance consumes compute time when it runs. It won't
start until it has compute time allocated to it. That compute time comes from a pool.

## Pools

A [pool](/preview/pools) is a named container that holds an allocation of compute time. It
represents that allocation as a schedule. The schedule tracks how many nodes you own, on which
hardware, and for which windows of time. Each node runs 1 instance.

For example, a pool might have this schedule.

| Hardware | Window | Allocation |
| - | - | - |
| H100, EU North, InfiniBand, … | Mar 20, 09:00 → Mar 20, 17:00 | 4 nodes |
| H100, EU North, InfiniBand, … | Mar 20, 17:00 → Mar 21, 00:00 | 8 nodes |
| H200, US East, No RDMA, … | Mar 21, 09:00 → Mar 21, 17:00 | 2 nodes |

The pool's schedule changes as you buy, sell, or transfer compute time, or as it expires.

## SKUs

Each pool tracks a separate schedule for each stock-keeping unit (SKU). A
[SKU](/preview/instance-skus) represents a specific set of interchangeable hardware,
including the following.

* Accelerator type, such as H100 or H200
* Instance specs like number of CPUs, RAM, and local storage
* RDMA type, such as InfiniBand or RoCE
* Zone or location
* Other operator-defined hardware properties

You pin orders, transfers, and instances to a SKU. That tells SF Compute which hardware
the allocation comes from.

## Starting an instance

When you create an instance, you attach it to a pool. The instance starts in `awaiting_allocation`
if the pool does not currently have matching allocation for the hardware it will run on.

To add compute time, place a buy [order](/preview/orders) on the pool. When the order fills, it adds
compute time to the pool's allocation schedule for the order's SKU. Once the schedule
covers the current time and there is enough matching allocation, the instance starts booting.

```bash theme={null}
sf pools create --name dev

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

# --max-rate is the most you'll pay, in dollars per node-hour.
sf orders create \
  --side buy \
  --pool dev \
  --count 1 \
  --start now \
  --duration 2h \
  --max-rate 20.00 \
  --sku sku_4UpxzQw7A8N
```

You can create the instance before the order fills. It waits until matching allocation exists.

Instances define what should run. Pools define when there is compute time available to run it.

## Instance lifecycle

A pool's allocation determines whether attached instances can run.

| Pool state | Instance behavior |
| - | - |
| No matching allocation | Instance waits in `awaiting_allocation` |
| Allocation becomes available | Waiting instances start booting |
| Allocation covers the running instance | Instance stays `running` |
| Allocation shrinks below demand | SF Compute terminates instances until demand fits allocation |

Terminating an instance does not free its allocation. The allocation remains in the pool's
schedule until you sell it, transfer it, or let it expire.

When allocation grows, waiting instances can start. If you use a [deployment](/preview/deployments),
the deployment can also create more instances to match its target count. Those instances start when
allocation is available.

When allocation shrinks below the number of running instances, SF Compute terminates instances until
the running count fits the pool schedule. It terminates lower-priority instances first. Among
instances with the same priority, it terminates the newest first. If you need control over which
work survives a planned shrink, set [instance priority](/preview/instances) before selling,
transferring, or letting allocation expire.

Compute allocation stays separate from what you run. You can buy compute time before you launch
instances and recreate instances without losing reserved time. You can also sell unused time without
deleting the pool and move allocation between workloads.

Think of it like a power grid. Pools are the circuits.

Orders add compute time to those circuits. Transfers move it between circuits. Instances draw it
from the pool they are attached to.

If a circuit has enough scheduled compute time, the attached instances can run. If it does not, they
wait or terminate.

## One pool or many

You can attach multiple instances to a single pool, or create a separate pool for each instance or
workload.

Use a separate pool when you want to manage the instance independently.

* A personal dev box should usually have its own pool.
* A one-off debugging instance should usually have its own pool.
* A customer-isolated workload should use its own pool if selling or expiration should not affect
  other customers.

Use one shared pool when the instances are part of the same fleet and can share allocation
decisions.

* An inference fleet should usually use one pool and one deployment.
* Batch workers for the same queue can usually share one pool.
* A training job with many identical workers can usually share one pool.

As a rule of thumb, put instances in the same pool only when you can scale, interrupt, extend,
sell, or transfer them together.

## Transfers

You can transfer compute time between pools. This lets you manage allocation like any other
resource. Assign it to projects, teams, or workloads, then move it when it is not being used.

For example, a platform team might buy a large block of H100 time into a shared pool. It can then
transfer pieces of that allocation to separate pools for `training`, `inference`, and `experiments`.
If `experiments` does not need its allocation, the team can transfer it back or move it to another
project.

Transfers affect the same schedule that orders affect. If compute time leaves a pool, attached
instances may terminate if the remaining allocation no longer covers them. If compute time arrives,
waiting instances can start.

## Next steps

* [Orders](/preview/orders) covers buying and selling compute time.
* [Pools](/preview/pools) is the command reference for pool operations, including transfers.
* [Instances](/preview/instances) is the command reference for instance lifecycle operations.


# Run a PyTorch job across multiple nodes
Source: https://docs.sfcompute.com/preview/guides/multi-node-training

Create an InfiniBand partition, start instances in it, and launch torchrun on every node

This guide takes you from no instances to a `torchrun` job on 2 nodes with 8 GPUs each. The nodes find each other over a private [subnet](/preview/networking/subnets) and exchange training data over an isolated [InfiniBand partition](/preview/networking/infiniband-partitions). By the end, you'll have trained [nanoGPT](https://github.com/karpathy/nanoGPT) on a small corpus of Shakespeare and generated text from it.

## Before you start

Set up your account, a partition, a subnet, and a [pool](/preview/pools) before you create any instances. A pool holds the allocation your instances run on. You need the `sf` CLI, logged in to your account. See the [Quickstart](/preview/quick-start#install-the-cli) to install it.

The examples use landsend, a [SKU](/preview/instance-skus) with 8 H100 GPUs per node: ID `sku_4EzdPrHcTps`, region `europe-north1`, zone `a`, on the InfiniBand fabric `europe-north1-a.fab1`. A fabric is the physical InfiniBand network that a SKU's nodes connect to. To use another SKU with InfiniBand, replace these values with its own.

<Steps>
  <Step title="Enroll in the InfiniBand preview">
    Enroll your account so the `sf infiniband-partitions` commands and the `--infiniband-partition` flag become available.

    ```bash theme={null}
    sf preview set infiniband-preview=true
    ```
  </Step>

  <Step title="Create a partition on your SKU's fabric">
    Create a partition named `training` on your SKU's fabric.

    ```bash theme={null}
    sf infiniband-partitions create --name training --fabric europe-north1-a.fab1
    ```

    Only instances in the same partition can reach each other over InfiniBand. See [Create a partition](/preview/networking/infiniband-partitions#create-a-partition) for the other options.
  </Step>

  <Step title="Create a subnet in your SKU's zone">
    Create a subnet named `training` in your SKU's region and zone.

    ```bash theme={null}
    sf subnets create --name training --region europe-north1 --zone a \
      --cidr 10.1.0.0/24
    ```

    Note the subnet `id` in the output, which starts with `snet_`. You need it to delete the subnet later.

    Instances in the subnet reach each other over private IPv4 addresses. `torchrun` uses the subnet to start the job, and the NVIDIA Collective Communications Library (NCCL) sends the training traffic over InfiniBand.
  </Step>

  <Step title="Write a startup script">
    SF Compute public images ship with no SSH key. This script adds your public keys to the `root` user when the instance boots. The `$(cat ...)` lines run on your machine as you write the file. If you have none of these keys, create one with `ssh-keygen -t ed25519` first.

    To use a key stored elsewhere, see [SSH into an instance](/preview/instances#ssh-into-an-instance).

    ```bash theme={null}
    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_ed25519.pub 2>/dev/null)
    EOF
    SCRIPT
    ```

    See [Cloud-init](/preview/instances#cloud-init) for other ways to configure an instance.
  </Step>

  <Step title="Buy an allocation of 2 nodes">
    Create a [pool](/preview/pools) named `training` and buy an allocation of 2 nodes of your SKU for 4 hours. The 4 hours start as soon as the order fills, so buy last and start the next section right after. Your organization needs enough credits to cover the price.

    The `sf buy` command quotes the price and asks you to confirm before it charges your organization for the full 4 hours. To skip the prompt in a script, add `--max-rate` with the highest price per node-hour you accept, and `--yes`.

    ```bash theme={null}
    sf pools create --name training
    sf buy --pool training --sku sku_4EzdPrHcTps --count 2 --start now --duration 4h
    ```
  </Step>
</Steps>

## Launch the job

Each instance runs `torchrun` with a node rank, a number from 0 that identifies it in the job. The rank 0 instance coordinates the job, and the job needs only that instance's private subnet address.

<Steps>
  <Step title="Create one instance per node">
    Create 2 instances in the partition and the subnet. This loop names them `training-0` and `training-1` and gives them the private addresses `10.1.0.10` and `10.1.0.11`. `--public-ipv4` gives each instance a public address for `sf instances ssh` to connect to.

    ```bash theme={null}
    for i in 0 1; do
      sf instances create --name "training-$i" --pool training \
        --sku sku_4EzdPrHcTps \
        --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 \
        --cloud-init ./startup.sh --infiniband-partition training \
        --subnet training --private-ip "10.1.0.1$i" --public-ipv4 --yes
    done
    ```

    Wait until both instances show `running` in this list.

    ```bash theme={null}
    sf infiniband-partitions instances training
    ```

    SSH becomes available after the image downloads and the instance boots, which can take up to 10 minutes. See [Instances](/preview/instances#limitations). If `sf instances ssh` reports that SSH details aren't available yet, wait a minute and retry.
  </Step>

  <Step title="Find the subnet interface">
    Open one terminal per instance and connect as `root`, the user the startup script added your key to. Start with `training-0`.

    ```bash theme={null}
    sf instances ssh training-0 --login root
    ```

    On each instance, print the interface that holds the instance's subnet address.

    ```bash theme={null}
    ip -br -4 addr show to 10.1.0.0/24 | tr -s ' '
    ```

    ```text theme={null}
    ens1 UP 10.1.0.10/24
    ```

    The first field, `ens1` here, is the interface name, which can differ on each instance.
  </Step>

  <Step title="Set up nanoGPT on every instance">
    This guide trains [nanoGPT](https://github.com/karpathy/nanoGPT), a small GPT model, on 1 MB of Shakespeare. Install [uv](https://docs.astral.sh/uv/), clone nanoGPT, install its packages, and prepare the dataset. Run these commands on each instance.

    ```bash theme={null}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    source ~/.local/bin/env
    git clone https://github.com/karpathy/nanoGPT ~/nanoGPT
    uv venv ~/venv
    uv pip install --python ~/venv torch numpy tiktoken requests
    cd ~/nanoGPT && ~/venv/bin/python data/shakespeare_char/prepare.py
    ```

    `prepare.py` downloads the text and writes `train.bin` and `val.bin` to `data/shakespeare_char/`. Each instance reads its own copy.
  </Step>

  <Step title="Run torchrun on every instance">
    Start `torchrun` on each instance with its own node rank: `0` on `training-0` and `1` on `training-1`. Replace `ens1` with the instance's subnet interface.

    ```bash theme={null}
    cd ~/nanoGPT
    NCCL_SOCKET_IFNAME=ens1 NCCL_DEBUG=INFO ~/venv/bin/torchrun \
      --nnodes 2 --nproc-per-node 8 --node-rank 0 \
      --master-addr 10.1.0.10 --master-port 29500 \
      train.py config/train_shakespeare_char.py \
      --gradient_accumulation_steps=16 --max_iters=500 --lr_decay_iters=500 \
      --warmup_iters=50 --eval_interval=100 --eval_iters=20 --compile=False \
      2>&1 | grep -E "NET/IB|step "
    ```

    `NCCL_SOCKET_IFNAME` sets the interface that NCCL uses to connect the instances at startup. The subnet interface is the one the other instance can reach. NCCL then sends the training data over InfiniBand.

    The flags after the config file change nanoGPT's single-GPU defaults for 16 GPUs:

    * **`--gradient_accumulation_steps=16`**: nanoGPT splits this value across the GPUs, so it must be a multiple of the GPU count
    * **`--max_iters`, `--lr_decay_iters`, `--warmup_iters`**: shorten the run, since each step now covers 16 GPUs' worth of data
    * **`--eval_interval`, `--eval_iters`**: evaluate every 100 steps on 20 batches, so evaluation fits the short run

    Each instance waits until all `--nnodes` instances have joined, then training starts. Each GPU prints the NCCL network line, and `training-0` prints the loss every 100 steps.

    ```text theme={null}
    NCCL INFO NET/IB : Using [0]mlx5_4:1/IB … [RO]; OOB ens1:10.1.0.10<0>
    …
    step 0: train loss 4.2885, val loss 4.2831
    step 100: train loss 2.3385, val loss 2.3798
    …
    step 500: train loss 1.2817, val loss 1.5370
    ```

    The `NET/IB` line lists 1 InfiniBand device per GPU, so NCCL sends the job's traffic over InfiniBand. Device names and their order vary by node. `OOB` (out-of-band) names the subnet interface that NCCL used to connect the instances.

    On 2 landsend nodes, the run takes about 40 seconds.

    If the job exits or hangs with no output, run the command again without the final `grep` to see the full log.
  </Step>

  <Step title="Generate text from the model">
    `training-0` saves the checkpoint to `out-shakespeare-char/`. Generate 300 characters from it on `training-0`.

    ```bash theme={null}
    cd ~/nanoGPT
    ~/venv/bin/python sample.py --out_dir=out-shakespeare-char \
      --num_samples=1 --max_new_tokens=300
    ```

    ```text theme={null}
    GLOUCESTER:
    And will it there by the execution of your swell:
    There is the mark of your grieves hew you love.
    ```
  </Step>
</Steps>

## Clean up

Terminate the instances when the job ends, then delete the partition and the subnet. Run these commands on your machine, not on an instance.

```bash theme={null}
for i in 0 1; do sf instances terminate "training-$i" --yes; done
```

Delete the partition once `sf infiniband-partitions instances training` no longer lists the instances.

```bash theme={null}
sf infiniband-partitions delete training --yes
```

Deletion fails while an instance is still attached. See [Delete a partition](/preview/networking/infiniband-partitions#delete-a-partition) for the cases that block it.

Then delete the subnet. The `sf` CLI can't delete subnets, so open **Networks** in the console and delete `training`.

To use the API instead, create an [API token](/preview/using-the-api#create-an-api-token). [Grant it a role](/preview/using-the-api#grant-permissions) that can delete subnets, such as `admin`. Then send a `DELETE` request with the subnet ID:

```bash theme={null}
curl -X DELETE https://api.sfcompute.com/preview/v2/subnets/snet_1234567890123 \
  -H "Authorization: Bearer your_api_token_here"
```

If the delete fails because an instance is still attached, wait a minute for its host to finish teardown and retry.

SF Compute reserves instance names for about 5 minutes after termination. To rerun the guide sooner, use different instance names.

The `training` pool stays after cleanup, so skip `sf pools create` on a rerun.

Terminating an instance doesn't free its allocation. You paid for the 4 hours when the order filled, and the pool keeps the 2 nodes until they end.

To get credits back for allocation you don't use, place a [sell order](/preview/orders#sell-orders) on the pool. This example offers the 2 nodes for the next 2 hours at \$10.00 per node-hour or more:

```bash theme={null}
sf orders create --side sell --pool training --sku sku_4EzdPrHcTps \
  --count 2 --start now --duration 2h --min-rate 10.00 --allow-standing
```

## Next steps

Use these pages to manage the job's resources:

* [InfiniBand partitions](/preview/networking/infiniband-partitions): fabrics, partitions, and link checks
* [Subnets](/preview/networking/subnets): private networks and addresses
* [Instances](/preview/instances): instance states, priority, and termination
* [Object storage](/preview/object-storage): bring datasets to SFC and save training checkpoints
* [Pools](/preview/pools): the allocation for the nodes in your job


# Sell unused compute time
Source: https://docs.sfcompute.com/preview/guides/reselling

Choose time to sell, place an order, and check your credits after fees

Sell unused compute time through the SF Compute [orderbook](/preview/orderbook), where buyers and sellers place orders. Use this guide to choose time to sell and check the credits you receive. You receive credits only when a buyer buys the time.

## Before you sell

You need compute time that you own and access to the `sf` command-line interface (CLI). Follow the [quickstart](/preview/quick-start) to install the CLI and sign in.

Your [pool](/preview/pools) records the compute time that you own, called allocation. Each [stock keeping unit (SKU)](/preview/instance-skus) identifies a hardware configuration. Choose the pool and SKU whose time you want to sell.

The examples use the pool name `production-inference`. Replace it with your pool name, and replace `your_sku_id` with your SKU. Set the times and rates for your sale; the prices below are examples, not live quotes.

## How reselling works

Place a sell order for time that your work does not need. When a buyer purchases that time, the order fills and SF Compute removes the sold allocation from your pool.

<Steps>
  <Step title="Choose unused time">
    Keep enough allocation for planned work before you offer time for sale. Include these needs:

    * Jobs that are running
    * Jobs that are waiting to start
    * Spare nodes for new work

    Check the time held by other sell orders in your pool. A running [instance](/preview/instances) is a virtual machine that uses this time. Block new jobs on instances you plan to terminate, then check those instances for running jobs.
  </Step>

  <Step title="Check the market price">
    Check the [best bid and ask](/preview/orderbook#quote) for the SKU and exact period you want to sell. A bid is the price a buyer offers; an ask is the price a seller requests.

    Use [market depth](/preview/orderbook#depth) to check the number of nodes at each price. Set `--min-rate` to the lowest price you will accept, in dollars per node-hour.
  </Step>

  <Step title="Place the sell order">
    This example assumes you own 5 nodes for 14 days, with 2 extra nodes from day 3 to day 8. You need only 2 nodes during a 3-day holiday that starts on day 8.

    Offer 3 nodes for that holiday:

    ```bash {2,5} theme={null}
    sf orders create \
      --side sell --pool "production-inference" --count 3 \
      --start "in 8d" --duration 3d \
      --min-rate 10.00 --sku your_sku_id \
      --allow-standing
    ```

    Use `--allow-standing` to keep the order open while it waits for a buyer. The order stays open until it fills, you cancel it, or the offered time ends. Save the order identifier (ID) to check or cancel the order later.
  </Step>
</Steps>

The chart shows the purchases that supply this example, followed by the sale. Each rectangle represents 1 node for 1 day; the shaded area shows the time you own. Select a step, then move the pointer over the chart to see the node count.

<CapacityChart title="production-inference" />

### How your pool tracks allocation

Your pool keeps one schedule for each SKU. This schedule adds time you buy and subtracts time you sell. Sell from that schedule, not from a single purchase.

You can sell any part of the time you own, including a period in the middle. Only the time a buyer purchases leaves your pool. The same rules apply to time bought through a [spot deployment](/preview/spot-deployments) or a firm reservation.

### How a sell order fills

By default, a sell order can fill partially. Buyers can purchase smaller parts of the offered nodes
or time, and the fills can cover separate periods with gaps between them. Pass
`--allow-partial=false` to require the order to fill completely — all offered nodes for the whole
window — or not at all. A complete fill can still consist of multiple fills from different buyers.

Fills use whole minutes, with a minimum of 1 node for 1 minute. You cannot set a larger minimum fill size. Use the order fields `fills` and `filled_allocation_schedule_delta` to check the exact nodes and time that sold.

### What happens to your instances when you sell

Each running instance needs enough compute time in its pool. If a sale leaves too little time, SF Compute terminates instances in this order:

1. Instances with the lowest [priority](/preview/instances#instance-priority)
2. The newest instances among those with the same priority

<Warning>
  Terminate unneeded instances before the sold time starts. Keep the rest.
</Warning>

Replace `your_instance_id` with the ID of an instance you want to terminate:

```bash theme={null}
sf instances terminate your_instance_id
```

The holiday sale leaves 2 nodes for 3 days, so SF Compute terminates the other 3 instances. Each bar below shows an instance; move the pointer over a bar to see its state.

<CapacityChart title="production-inference" />

## Choose time to sell

Sell a period when your jobs do not need the compute. Low use of graphics processing units (GPUs) alone does not mean the time is spare. An instance can still contain data or be necessary for a later job.

### Sell the end of a reservation

Sell the last hours of a reservation when work ends early. Here, you own 1 node for 12 hours but need only the first 8 hours.

Sell the last 4 hours:

```bash {3} theme={null}
sf orders create \
  --side sell --pool "production-inference" --count 1 \
  --start "in 8h" --duration 4h \
  --min-rate 8.00 --sku your_sku_id \
  --allow-standing
```

At \$8 per node-hour, this sale returns \$32 before fees. For a node with 8 GPUs, that rate equals \$1 per GPU-hour.

### Sell a gap between jobs

Offer a gap when work can stop and continue later. This example keeps the first 2 hours and last 4 hours of the same 12-hour reservation.

Choose this example or the one above. Both together leave only the first 2 hours; the first sale removes the last 4 hours you need here.

Sell the 6-hour gap:

```bash {3} theme={null}
sf orders create \
  --side sell --pool "production-inference" --count 1 \
  --start "in 2h" --duration 6h \
  --min-rate 8.00 --sku your_sku_id \
  --allow-standing
```

Save your work before the sold time starts. Leave time to terminate instances before the gap, then create new ones to resume work after it. Terminated instances do not restart when your compute time returns.

If you must move work to other nodes, compare the costs first. To reduce your costs, the sale value must cover these costs:

* Platform fees
* Replacement compute
* Moving the work

## How to make a sell order fill

Price and order size affect your chance of finding a buyer. Consider these options:

* Set `--min-rate` below current prices for the same SKU and period.
* Offer small amounts, such as 1 node for 1 hour, which can be easier to match.
* Keep partial fills enabled, which is the default, so buyers can take smaller parts of the offered nodes or time.
* Offer time early to give buyers more time to find your order.
* Keep an order open if some of its time has passed; a buyer can still purchase the remaining time.
* Use several sell orders for a pool when you need different prices or periods.

An order in the `standing` state waits for a buyer, and you still own the time. You might not find a buyer before the offered time ends.

### Reprice or cancel a listing

You can lower your price as the start time gets near. Do not go below the lowest price you will accept. Cancel the open order and check its fills before you place a new one.

<Steps>
  <Step title="Request cancellation">
    Replace `your_order_id` with your sell order ID. Run this command to ask SF Compute to cancel the order:

    ```bash theme={null}
    sf orders cancel your_order_id
    ```
  </Step>

  <Step title="Wait for the final result">
    Read the order fields as JavaScript Object Notation (JSON). Use the same order ID, and repeat until the state is `cancelled` or `filled`:

    ```bash theme={null}
    sf orders get your_order_id --json
    ```

    A buyer can purchase time while cancellation is in progress, and that time stays sold. Check `fills` and `filled_allocation_schedule_delta` before you sell or use the time again.
  </Step>

  <Step title="Use only the remaining time">
    Subtract all fills from the time you first offered. If 2 hours of a 6-hour sale fill before the order stops, only 4 hours become free again.

    Keep that time reserved until the order reaches its final state. See [Cancel an order](/preview/orders#cancel-an-order) for more details.
  </Step>
</Steps>

For sales through the application programming interface (API), save each request and its idempotency key first. This key identifies the request, so reuse it and the request body when you retry. Check orders and fills before each new sale to avoid selling the same time twice.

## Calculate your resale credits

Subtract the platform fee from the sale value to find the credits you receive. The sale value depends on the fill price and the number of node-hours sold.

### How the fill price is set

The order that reaches the orderbook first sets the fill price. Your `--min-rate` remains the minimum price you will accept:

| Order on the orderbook first | Fill price |
| - | - |
| Your sell order | Your sell price |
| The buy order | The buy price, which must equal or exceed your `--min-rate` |

### Platform fee

SF Compute subtracts a platform fee when your sale fills. The fee has two parts:

| Fee part | Calculation |
| - | - |
| Fixed amount | Fee per node-hour × node-hours sold |
| Percentage | Fee percentage × sale value |

The 3-node, 3-day holiday sale contains 216 node-hours: 3 × 3 × 24. Its fee includes the fixed amount for those node-hours plus the percentage of the sale value.

SF Compute sets both fee parts, and your fees can change. Fees can also differ between organizations. Check the fee estimate in the CLI before you confirm an order. The fee cannot exceed the sale value, so a sale cannot reduce your credit balance.

The buyer pays the fill price, and the `fills` array shows prices before fees. SF Compute subtracts the fee from your sale value and adds the remaining amount to your credits.

### Track your realized price

Your realized price is the cost per purchased GPU-hour after resale. Use the credits you receive after fees:

| Measure | Calculation |
| - | - |
| Net compute cost | Purchase cost − resale credits after fees |
| Realized price per purchased GPU-hour | Net compute cost ÷ purchased GPU-hours |
| Realized discount | Resale credits after fees ÷ purchase cost × 100% |

For example, a \$100,000 purchase with \$25,000 in resale credits gives these results. The original rate is \$4.50 per GPU-hour:

| Measure | Result |
| - | - |
| Net compute cost | \$75,000 |
| Realized discount | 25% |
| Realized price per purchased GPU-hour | \$3.375 |

This calculation uses all purchased GPU-hours. The cost per GPU-hour of completed work also depends on how much of the remaining time you use.

The [September 9, 2026 resale article](https://sfcompute.com/news/realized-discount) reported a 25% average realized discount for customers on the platform. Your results depend on the time you sell, demand, prices, and fees.

## Next steps

Use these guides to manage your compute after a sale:

* [Pools](/preview/pools): allocation schedules
* [Orders](/preview/orders): order states and fees
* [Instances](/preview/instances): creating and terminating instances


# Images
Source: https://docs.sfcompute.com/preview/images

Build, upload, and manage custom images

An image is the bootable disk template your instance runs from. Boot from an SF Compute base image
with common configurations, or upload your own custom image.

Every image has an `id` like `image_2KvMb9NpQs5` and a human-readable `name` like
`ubuntu-22.04-cuda-12.4` or `training-base`. Each image also has `is_public`, which is `true` for SF
Compute base images and `false` for images you upload.

A name identifies a sequence of immutable versions, starting at 1. The `id` always refers to one
exact build, and the bits behind an id never change. Uploading an existing name creates the next
version.

<Warning>
  Image versions, version pinning, and the deprecated lifecycle state are in
  [public preview](/preview/roadmap#feature-states) and live on the `/preview/v2` API only. The `/v2`
  image endpoints return no `version` or `deprecated_at` field, do not accept `all_versions`, and
  reject the `name@<version>` pin form. `sf` calls the preview endpoints, so every CLI example on
  this page works as written.
</Warning>

## Listing images

List all images available to you, including SF Compute's public images.

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

```text theme={null}
----------------------------------------------------------------------------------------
NAME                                               VISIBILITY  STATUS     CREATED
ubuntu-jammy-custom                                private     completed  Mar 27, 2:00pm
sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2  public      completed  Feb 23, 6:50pm
```

The CLI lists images outside the active workspace, including SF Compute's public images, by their
full resource path.

By default the list shows one entry per name: the latest active version. Pass `--all-versions` to
see every version with its lifecycle state, including a `VERSION` column.

## Using an image

Pass an image name, ID, or resource path when creating an instance.

```bash theme={null}
sf instances create --pool dev --image ubuntu-jammy-custom
```

If you omit `--image`, the CLI presents an interactive picker showing all completed images available
to you.

Referencing an image by name resolves to the latest active version at creation time, so new
instances automatically pick up updated builds. To pin one exact build, reference it by id, or
append `@<version>` to the name.

```bash theme={null}
sf instances create --pool dev --image ubuntu-jammy-custom@2
sf instances create --pool dev --image image_abc123
```

Both pin forms mean the same thing: exactly this build, even after newer versions appear. Both may
launch a version that has since been deprecated, while revoked versions never launch. Ids don't
take the suffix, since an id already names one exact build. `sf images get ubuntu-jammy-custom@2`
inspects a pinned version.

The instance stores the concrete image id it booted from either way, so `sf instances get` always
tells you exactly which build an instance is running.

[Instance templates](/preview/instance-templates) resolve the name once, when the template is
created, so every instance a [deployment](/preview/deployments) launches from a template boots the
same build.

## Uploading an image

Upload a raw disk image with `sf images upload`. The CLI uploads the image in parts, reports
progress as it goes, and verifies integrity with a SHA256 checksum. The maximum image size is 75
GiB. Custom images stay in your workspace.

```bash theme={null}
sf images upload \
  --name ubuntu-jammy-custom \
  --file output/ubuntu_jammy.raw
```

If you omit `--file` or `--name`, the CLI prompts you interactively.

Uploading a file under an existing name never overwrites anything. It creates the next version, and
the name starts resolving to it once the upload completes.

For large images, tune the number of parallel part uploads with `--concurrency`. The default is your
machine's CPU count.

```bash theme={null}
sf images upload \
  --name ubuntu-jammy-custom \
  --file output/ubuntu_jammy.raw \
  --concurrency 4
```

## Image requirements

SF Compute supports UEFI amd64 (x86\_64) raw images. We do not support qcow2.

Custom images should resize themselves at boot to fill the disk available to the instance. For an
example of building a compatible image with Packer, see our
[example GitHub repository](https://github.com/sfcompute/packer_example/).

Custom images must have drivers for both
<Tooltip>virtio-net</Tooltip> and
<Tooltip>mlx5Gen Virtual Function</Tooltip> for networking.
They must also have cloud-init installed with its network configuration step enabled so networking
comes up at boot.

## Image lifecycle

An upload moves through `started` → `uploading` → `completed` (or `failed`). Only completed images
can back instances.

Completed images additionally carry a catalog state.

An active image is the default state: listed, resolvable by name, and launchable. A deprecated
image is no longer the active version and will eventually be removed. It stops resolving by bare
name and leaves the default listing, but an explicit pin (image id or `name@<version>`) can still
launch it, and instances already running on it are unaffected. `sf images list --all-versions`
shows deprecated versions with status `deprecated`. A revoked image can no longer back new
instances, by name or by id, though instances already running on it are unaffected.

## Revoking an image

Revoke an image to stop new instances from using it. Existing instances keep running.

```bash theme={null}
sf images revoke ubuntu-jammy-custom
```

The command prompts for confirmation. Pass `--yes` to skip it.

Reinstate a revoked image to make it usable again.

```bash theme={null}
sf images reinstate ubuntu-jammy-custom
```

## Deleting an image

Delete an image to remove it permanently. Unlike a revoked image, a deleted image cannot be
reinstated. You cannot delete an image while an active instance uses it.

```bash theme={null}
sf images delete ubuntu-jammy-custom
```

The command prompts for confirmation. Pass `--yes` to skip it.

## SFC base images

SF Compute publishes base images named `ubuntu-<lts>-cuda-<major.minor>`, for example
`ubuntu-24.04-cuda-13.2`. The matrix covers Ubuntu 22.04 and 24.04 crossed with the two newest CUDA
minor versions, plus a back-catalog of older CUDA versions. A few older names carry the Ubuntu point
release, like `ubuntu-22.04.5-cuda-12.7`. `sf images list` shows every current name.

Each base image ships the NVIDIA server driver pinned to that CUDA version's compatibility floor,
the CUDA development libraries, and cloud-init.

Each name tracks its latest build. When NVIDIA ships a new CUDA patch release, or a driver or OS
point release lands, SF Compute republishes the same names, and each republish appears as a new
version. Instances created by name pick up the latest version automatically, while running
instances keep the exact image they booted from. If your workload needs one exact build, pin it by
image id or by version, like `ubuntu-24.04-cuda-13.2@3`.

Older versions of a base image are deprecated once superseded. A deprecated version leaves name
resolution and the default listing but still launches by pinned id or `name@<version>`. Versions
deprecated for a long time are eventually revoked, which blocks new launches without touching
running instances. Base image versions are never deleted.

## API reference

See the [Images API](/api-reference/images/list-images) for programmatic access.


# SKUs
Source: https://docs.sfcompute.com/preview/instance-skus

Pick the hardware your orders run on

A SKU (stock keeping unit) is a unique combination of [instance](/preview/instances) properties such
as `accelerator` and `rdma_type`.

Each SKU has a stable `id` and a human-readable `alias` that SF Compute assigns at registration.
Both the API and the CLI identify a SKU by its `sku_...` id.

A SKU is the boundary of fungibility. Two instances with the same SKU run on the same hardware and
are interchangeable. The market prices and allocates them as one supply, and you cannot pin a
specific machine within a SKU. Hardware differences that matter, such as the accelerator, the remote
direct memory access (RDMA) network, the zone, and the machine shape, place nodes in different SKUs.

Each SKU has its own [orderbook](/preview/orderbook) and its own allocation. An
[order](/preview/orders) fills only against orders on the same SKU. A [pool](/preview/pools) records
its allocation as a node-count schedule per SKU.

A SKU identifies hardware, not how you buy it, so spot and non-spot orders for the same hardware
share one SKU. Some guarantees depend on staying on the same hardware, such as buying more capacity
and keeping your instances running. These hold within one SKU, not across SKUs. An instance pins to
its SKU at create time and never moves to another.

## SKU properties

Every SKU has an `id` and an `alias`. Its other properties, such as `region`, `accelerator`, and
`memory_bytes`, describe the hardware, and the API omits any that are unset. For the full list, read
the [SKU API reference](https://docs.sfcompute.com/api-reference/skus/get-sku#response-id).

In the API, each property other than `id` and `alias` is an object with a machine-readable `value`
and a human-readable `display_value`, which the console and `sf` show. For example, a SKU with 2,016
GiB of memory returns:

```json theme={null}
"memory_bytes": { "value": 2164663517184, "display_value": "2,016 GiB" }
```

## List SKUs

List the registered SKUs and their ids.

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

```text theme={null}
  NAME         ACCELERATOR           MEMORY     STORAGE  VCPUS  ID
  sea-3-h100   8 x H100 80GB HBM3    2,016 GiB  1.5 TiB  56     sku_4UpxzQw7A8N
  iad-12-h200  8 x H200 141GB HBM3e  2,016 GiB  1.5 TiB  56     sku_NWhD6SrbjcXstGRvgl0eC
```

Add `--verbose` to include the region, zone, form factor, RDMA type, and public IPv4 columns.

## Get details for one SKU

Get the full property set for a single SKU.

```bash theme={null}
sf skus get sku_4UpxzQw7A8N
```

## Use a SKU

[Orders](/preview/orders), [pool transfers](/preview/pools), [deployments](/preview/deployments),
[procurements](/preview/procurements), and [instances](/preview/instances) each pin to a single SKU.
Pass its id with `--sku`.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h \
  --max-rate 20.00 \
  --sku sku_4UpxzQw7A8N
```

## Pick a SKU interactively

On commands that pin a SKU (for example, `sf orders create`), omit `--sku`. You then pick
from a list of registered SKUs and their properties.

## API reference

See the [SKUs API](/api-reference/skus/list-skus) for programmatic access.


# Instance templates
Source: https://docs.sfcompute.com/preview/instance-templates

Reusable instance configurations for deployments

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

An instance template defines the configuration for an [instance](/preview/instances): which
[image](/preview/images) to boot and an optional [cloud-init](https://cloudinit.readthedocs.io/)
script. [Deployments](/preview/deployments) use templates to create instances with a consistent
configuration.

Templates are immutable. To change a configuration, create a new template and update your deployment
to reference it. See [deployments](/preview/deployments#instance-templates) for how a deployment
picks up the change.

## Create an instance template

Create a template with a name and an image. Public images require the full
`sfc:image:sfcompute:public:...` name; SF Compute rejects the short trailing segment on its own.

```bash theme={null}
sf instance-templates create \
  --name prod-worker \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2
```

A template captures one exact image build. SF Compute resolves the image name when you create the
template and stores that build's id, so later [versions](/preview/images#using-an-image) of the same
name never reach an existing template. Pass an image id to name the build explicitly; templates take
a name or an id, not the `name@<version>` pin form.

## Cloud-init

Pass a startup script or cloud-config YAML file via `--cloud-init`. The template stores the file and
applies it to every instance you create from it. Maximum size is 64 KB.

Cloud-init data isn't parameterized per instance: every instance created from the template receives
the same bytes. For per-instance identity, use a deployment's
[instance name template](/preview/deployments#instance-name-templates). For example, this startup
script installs an SSH key.

```bash startup.sh theme={null}
#!/bin/bash

mkdir -p /root/.ssh
cat >>/root/.ssh/authorized_keys <<"EOF"
ssh-ed25519 AAAA... you@example.com
EOF
```

Create a template that uses the script.

```bash theme={null}
sf instance-templates create --name ssh-ready \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 --cloud-init ./startup.sh
```

## List templates

List the templates in your workspace.

```bash theme={null}
sf instance-templates list
```

```text theme={null}
----------------------------------------------------------------
NAME          IMAGE                   CLOUD-INIT  CREATED
prod-ubuntu   ubuntu-24.04-cuda-13.2  yes         Mar 23, 4:40pm
dev-debian    debian-12-cuda-12.7     -           Mar 26, 2:00pm
staging-base  ubuntu-24.04-cuda-13.2  yes         Mar 27, 2:00pm
```

## Get template details

Get a template by name or ID.

```bash theme={null}
sf instance-templates get prod-ubuntu
```

```text theme={null}
| ID             itmpl_Gw5rT8mKn2Pj4Lx9Qf7Y
| NAME           prod-ubuntu
| RESOURCE PATH  sfc:instance_template:acme:default:prod-ubuntu
| IMAGE          ubuntu-24.04-cuda-13.2 (image_Qb7dRk2mNp4Ls9Xf1Zt0)
| CLOUD-INIT     yes
| CREATED        Mar 23, 4:40pm PDT
```

<Note>
  Template IDs use the `itmpl_` prefix. You can still pass older IDs with the legacy `ntmpl_` prefix.
</Note>

## Delete a template

Delete a template by name or ID.

```bash theme={null}
sf instance-templates delete prod-ubuntu
```

You can't delete a template while a [deployment](/preview/deployments) or running instance uses it.
Update or delete the deployment, or terminate the instance, first.

## API reference

See the [Instance Templates API](/api-reference/instance-templates/list-instance-templates)
for programmatic access.


# Instances
Source: https://docs.sfcompute.com/preview/instances

Create, connect to, and manage GPU compute instances

An instance is a GPU-backed virtual machine. You create an instance, attach it to a
[pool](/preview/pools), 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](/preview/orders)) before starting.

## Create an instance

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

```bash theme={null}
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.

```bash theme={null}
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:

1. **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](/preview/orders)
   on the pool.
2. **The allocation starts in the future.** If the schedule's first segment starts later than now,
   the instance waits until then.
3. **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](/preview/pools#mixed-hardware).
4. **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.
5. **The buy order hasn't filled yet.** Orders add to the schedule only once they fill. Check the
   [order status](/preview/orders#order-statuses).

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](mailto: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](/preview/networking/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](/preview/spot-deployments) 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](#delete-an-instance) 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](/preview/spot-deployments#preemption). For everything else, build in a margin before
your pool's allocation ends instead of waiting for a signal. See
[Allocation schedule](/preview/pools#allocation-schedule).

## Images

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

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

```text theme={null}
----------------------------------------------------------------------------------------
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.

```bash theme={null}
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](/preview/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.

```bash theme={null}
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.

```yaml startup.yaml theme={null}
#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.

```bash theme={null}
sf instances create --pool dev --cloud-init ./startup.yaml
```

## Check instance status

List your instances and their statuses.

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

```text theme={null}
----------------------------------------------------------
NAME        STATUS   POOL  INSTANCE SKU     CREATED
gpu-worker  running  dev   sku_8FxR3pTzN6L  Mar 19, 4:40pm
```

Filter by time range.

```bash theme={null}
# 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.

```bash theme={null}
sf instances get gpu-worker
```

## SSH into an instance

Connect to a running instance over SSH.

```bash theme={null}
sf instances ssh gpu-worker
```

<Note>
  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.
</Note>

<Warning>
  `Permission denied (publickey)` means the instance has no matching key: either its cloud-init never
  added one (see [Cloud-init](#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>`.
</Warning>

## View logs

View an instance's logs.

```bash theme={null}
sf instances logs gpu-worker
```

Show more lines.

```bash theme={null}
sf instances logs gpu-worker --limit 500
```

Filter by time range.

```bash theme={null}
# 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.

```bash theme={null}
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).

```bash theme={null}
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.

<Note>
  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.
</Note>

Replace with a specific name.

```bash theme={null}
sf instances replace gpu-worker --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 --cloud-init ./new-startup.sh --name worker-2
```

<Warning>
  Instances have no persistent storage. Replacing an instance deletes all data on the original.
</Warning>

## Delete an instance

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

```bash theme={null}
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.

```bash theme={null}
sf instances set gpu-worker --priority critical
```

Set priority at create time.

```bash theme={null}
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.

```http theme={null}
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}`.

```http theme={null}
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.

```http theme={null}
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, the instance's disk is lost with it.
* Public IPv4 is available only on SKUs that support it, and only when enabled at create
  time. See [IP addresses](/preview/networking/ip-addresses).
* InfiniBand is in preview. See [InfiniBand partitions](/preview/networking/infiniband-partitions).
* 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](mailto:support@sfcompute.com).

## API reference

See the [Instances API](/api-reference/instances/list-instances) for programmatic access.


# Limits
Source: https://docs.sfcompute.com/preview/limits

Read the compute caps, resource limits, and credit line on your account, and your usage against them

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

A limit caps how much compute time your account can hold at once, how many of a resource it can hold, or how large a credit line it has. This page covers the limits `sf limits` shows, the units they use, and how to request a higher one.

```bash theme={null}
sf limits
```

```text theme={null}
NAME                                    LIMIT      USED  SCOPE
compute_max_total_node_hours            5760       1200  account
compute_max_total_node_hours            720        720   sku_4UpxzQw7A8N
compute_node_hours_free_window_seconds  3600       —     account
max_instances                           64         12    account
credits_max_credit                      unlimited  —     account
```

Each row is one limit in effect on your account:

* **NAME**: the limit’s identifier, covered in the sections below
* **LIMIT**: the cap, or `unlimited` when your account has no cap for that name
* **USED**: your usage against the cap, printed as `—` when there is no figure to report, and in red once it reaches the cap
* **SCOPE**: what the cap covers, either your whole account or the `sku_…` ID of one [SKU](/preview/instance-skus)

A limit with no row is unset, and an unset limit refuses nothing.

A compute limit counts the node-hours you hold plus the unfilled node-hours of your open buy orders. Some open sell orders subtract from that total, as described in [Compute limits](#compute-limits).

SF Compute refuses a buy order that would put you over the cap. An [interruptible buy order](/preview/orders#interruptible-buy-orders) with an interrupt rate below the [offset price ceiling](#compute-limits) is the exception. A compute limit never refuses a sell order, because a sell can't raise your usage. You can't cancel a sell order that lowered your usage if cancelling it would put you over the cap.

## Compute limits

`compute_max_total_node_hours` caps that total in node-hours across all pools, so a resting buy order counts against the cap before it fills. A node-hour is one node held for one hour, so the cap measures the area under the combined schedule. Buying further ahead spends it the same way a wider order does.

<CapacityChart title="node-hours held" />

Placing a [standing sell order](/preview/orders#sell-orders) offsets your usage for this limit, but only if it allows partial fills (`--allow-partial`) and its price is below the offset price ceiling. SF Compute sets this ceiling and can change it. See the current one in the `COMPUTE LIMIT OFFSET PRICE CEILING` row of `sf platform-constants`.

The offset lasts only while the sell order stands. For example, with a cap of 200 node-hours:

* You reserve 200 node-hours. You are at the cap and cannot buy more.
* You place a standing sell order for 100 node-hours, allowing partial fills and priced below the ceiling. You can now reserve another 100 node-hours.
* You can repeat this as many times as you like, as long as you keep placing sell orders.
* You cannot cancel those sell orders while doing so would put you back over the cap.

An [interruptible buy order](/preview/orders#interruptible-buy-orders) gets the same offset. SF Compute lists the compute the order buys as standing sell orders at the order's interrupt rate. When that rate is below the ceiling, the order stays out of your usage.

`compute_node_hours_free_window_seconds` sets how far ahead the cap starts counting, in seconds from now. An order that fits entirely inside the free window never counts. An order that starts inside the window counts from the edge of the window onward.

## Account-wide and per-SKU limits

A limit’s scope decides which part of your allocation it meters. A limit scoped to your account meters every pool you hold. A limit scoped to one SKU meters your allocation on that SKU alone. Both apply together rather than replacing each other, so an order for that SKU has to fit inside both. Resource limits are always account-wide.

## Resource limits

A resource limit caps how many of one kind of resource your account holds at once. **USED** is how many you hold now. SF Compute refuses a request that would create one more than the limit allows; delete one to make room.

| Name | Counts |
| - | - |
| `max_instances` | Instances that are not destroyed |
| `max_standing_orders` | Open orders: those on the book, plus any placed but not yet settled. An order placed without `--allow-standing` never rests, so this limit never refuses one. |
| `max_workspaces` | Workspaces, including your default workspace |
| `max_pools` | Pools |
| `max_images` | Images that are not deleted, including uploads still in progress and revoked images |
| `max_tokens` | API tokens that are neither deleted nor expired |
| `max_subnets` | Subnets that are not deleted |
| `max_infiniband_partitions` | InfiniBand partitions that are not deleted |

A request retried with the same `Idempotency-Key` as one that already created its order or pool isn't refused, because it creates nothing new.

## Credit line

`credits_max_credit` is the credit line on your account, in dollars. It comes from the same credit line as the overage limit in `sf billing balance`. It reads as `unlimited` for an account with no ceiling.

## Requesting a higher limit

SF Compute sets your limits. Verify your organization in the [SF Compute dashboard](https://sfcompute.com/dashboard/settings), then [contact us](https://sfcompute.com/contact) with the limit you need.


# Firewalls
Source: https://docs.sfcompute.com/preview/networking/firewalls

Control inbound traffic to an instance with ingress rules

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

A firewall is a set of rules controlling inbound traffic to an [instance](/preview/instances).
Firewalls are scoped to a [workspace](/preview/workspaces).

## Default firewall

Every workspace has a built-in `default` firewall with 2 ingress rules.

* Allow SSH (TCP port 22) from anywhere
* Allow ICMP (ping) from anywhere

SF Compute manages the `default` firewall. You cannot modify or delete it. Password authentication
is disabled on all SF Compute base images, so open SSH is safe by default. Only key holders can
connect.

## How firewalls apply

Firewall rules control traffic between instances and the public internet. Instances in the same
subnet communicate freely on all ports. Instances in different subnets are isolated and cannot
communicate.

Firewalls only apply to instances with a [public IP](/preview/networking/ip-addresses) (created with
`--public-ipv4`) and cannot be attached to an instance without one. The API requires the `firewall`
field whenever `enable_public_ipv4` is `true` and rejects the request with 422 when it is omitted.

The CLI fills it in for you. If you run `sf instances create --public-ipv4` interactively without
`--firewall`, it prompts you to pick a firewall. Otherwise, it uses the workspace's `default`
firewall.

## Creating a firewall

Create a firewall from a TOML file that defines the rules.

```bash theme={null}
sf firewalls create --name web --file firewall.toml
```

### Rule format

Each rule specifies a direction, protocol, port (or port range), and source CIDR (Classless
Inter-Domain Routing). The API accepts only `ingress` rules and rejects `egress`, which is reserved
for future use. Firewalls do not filter outbound traffic. The protocol is `tcp`, `udp`, or `icmp`;
ICMP rules take no port.

```toml theme={null}
[[rules]]
direction = "ingress"
protocol = "tcp"
port = "22"
source = "0.0.0.0/0"

[[rules]]
direction = "ingress"
protocol = "tcp"
port = "8080"
source = "0.0.0.0/0"
```

This creates a firewall that allows SSH and port 8080 from anywhere.

Source CIDRs must be publicly routable. The API rejects private, reserved, and other non-public
ranges (for example `10.0.0.0/8`, `192.168.0.0/16`). The wildcard `0.0.0.0/0` (allow from anywhere)
is the only exception.

### Restricting access

Restrict SSH to a specific network.

```toml theme={null}
[[rules]]
direction = "ingress"
protocol = "tcp"
port = "22"
source = "8.8.8.0/24"

[[rules]]
direction = "ingress"
protocol = "tcp"
port = "8080"
source = "0.0.0.0/0"
```

### Port ranges

Allow a range of ports.

```toml theme={null}
[[rules]]
direction = "ingress"
protocol = "tcp"
port = "22"
source = "0.0.0.0/0"

[[rules]]
direction = "ingress"
protocol = "tcp"
port = "8000-8999"
source = "0.0.0.0/0"
```

### Create via the API

To create a firewall via the API, send a `POST` request to `/preview/v2/firewalls`.

```json theme={null}
{
  "workspace": "sfc:workspace:acme:production",
  "name": "web",
  "rules": [
    { "direction": "ingress", "protocol": "tcp", "port": "22", "source": "0.0.0.0/0" },
    { "direction": "ingress", "protocol": "tcp", "port": "8080", "source": "0.0.0.0/0" }
  ]
}
```

## Attaching a firewall to an instance

Specify the firewall when creating an instance.

```bash theme={null}
sf instances create \
  --name worker-1 \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 \
  --cloud-init ./startup.sh \
  --public-ipv4 \
  --firewall web
```

## Replacing the firewall on an instance

Replace the attached firewall on an existing instance. The instance must have been created with
`--public-ipv4`. The new rules take effect without a reboot.

```bash theme={null}
sf instances set worker-1 --firewall restricted
```

You can replace the firewall but not detach it.

## Listing firewalls

List the firewalls in the active workspace.

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

```text theme={null}
NAME         RULES
default      2
web          2
restricted   2
```

## Getting firewall details

Fetch a firewall by name.

```bash theme={null}
sf firewalls get web
```

Add `--toml` to output the rule set as TOML, which round-trips with `sf firewalls set`.

```bash theme={null}
sf firewalls get web --toml > firewall.toml
```

## Updating a firewall

Replace a firewall's rule set from a TOML file. The replacement is atomic.

```bash theme={null}
sf firewalls set web --file firewall.toml
```

### Update via the API

`PUT /preview/v2/firewalls/{id}` replaces the full rule set.

```json theme={null}
{
  "rules": [
    { "direction": "ingress", "protocol": "tcp", "port": "22", "source": "0.0.0.0/0" }
  ]
}
```

## Deleting a firewall

Delete a firewall by name.

```bash theme={null}
sf firewalls delete web
```

Deleting a firewall fails if any instances still reference it.

## Limits

Firewalls enforce the following limits.

* 100 rules per firewall
* 100 firewalls per workspace, including the built-in `default`

## API reference

See the [Firewalls API](/api-reference/firewalls/list-firewalls) for programmatic access.


# InfiniBand partitions
Source: https://docs.sfcompute.com/preview/networking/infiniband-partitions

Connect instances over an isolated InfiniBand network for distributed training

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

InfiniBand is a high-bandwidth, low-latency network that lets GPUs on different instances exchange
data during multi-node training. It uses RDMA (remote direct memory access). With RDMA, one machine
reads and writes another machine's memory directly, including GPU memory, without involving either
operating system.

An InfiniBand partition is an isolated network for RDMA traffic between your instances. Instances in
the same partition can reach each other over InfiniBand. An instance created without a partition has
no InfiniBand connectivity, even when its SKU supports InfiniBand.

A fabric is a physical InfiniBand network in one availability zone, with a name such as
`europe-north1-a.fab2`. Separate fabrics are separate networks and cannot reach each other.

To connect instances over InfiniBand:

1. Create a partition.
2. Attach instances on the same fabric to that partition.

`sf infiniband-partitions` is also available as `sf ib-partitions` and `sf ibp`.

## Enroll in the InfiniBand preview

Enroll your account in the preview before you create a partition. Until you do, the
`sf infiniband-partitions` commands and the `--infiniband-partition` flag are hidden, and the API
returns a `403` error.

```bash theme={null}
sf preview set infiniband-preview=true
```

## Find a SKU that supports InfiniBand

A [SKU](/preview/instance-skus) supports InfiniBand when its RDMA type is `infiniband`. List the
SKUs that support it, with their availability.

```bash theme={null}
sf availability --rdma-type infiniband
```

## Create a partition

Create a partition on the fabric your SKU is on. The partition belongs to the current
[workspace](/preview/workspaces).

```bash theme={null}
sf infiniband-partitions create --name training --fabric europe-north1-a.fab2
```

You can also run `sf infiniband-partitions create` with no flags. It asks for a name, then lists
each fabric with the names of the SKUs on it. Pick the fabric of the SKU you plan to create
instances on.

In a zone with only one fabric, you can pass `--region` and `--zone` instead of `--fabric`.

A partition name must be unique within its workspace, across all fabrics.

## List partitions

List the partitions in the current workspace. Add `--all` to list across every workspace you can
read.

```bash theme={null}
sf infiniband-partitions list
```

```text theme={null}
  NAME      FABRIC                ZONE             CREATED
  training  europe-north1-a.fab2  europe-north1-a  Sep 28, 2:02pm
```

Filter by `--fabric` to see the partitions on one network.

```bash theme={null}
sf infiniband-partitions list --fabric europe-north1-a.fab2
```

## Get details for one partition

Get a partition by its name, its `ibpart_...` ID, or its resource path. A name resolves within the
current workspace.

```bash theme={null}
sf infiniband-partitions get training
```

```bash theme={null}
sf infiniband-partitions get sfc:infiniband_partition:acme:production:training
```

A resource path joins the account, the workspace, and the partition name, as in `acme`,
`production`, and `training` above. Anywhere a command or API field takes a partition, it accepts
the name, the ID, or the resource path.

## Attach an instance to a partition

Attach an instance by passing `--infiniband-partition` when you create it. The partition must be on
the same fabric as the instance's SKU. See [Instances](/preview/instances) for the other creation
flags and the [startup script](/preview/instances#cloud-init).

```bash theme={null}
sf instances create --pool training --sku sku_4UpxzQw7A8N \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 --cloud-init ./startup.sh \
  --infiniband-partition training
```

You can also run `sf instances create` without `--infiniband-partition`. On an InfiniBand SKU, it
lists the partitions on the SKU's fabric, so you can pick one, create one, or choose none.

An instance stays in its partition for its whole life. To move it to another partition, terminate it
and create a new instance.

## List the instances in a partition

List the instances attached to a partition. The output has the same columns as
[`sf instances list`](/preview/instances).

```bash theme={null}
sf infiniband-partitions instances training
```

A terminated instance drops out of this list once its node releases the partition.

## Delete a partition

Delete a partition by its name, ID, or resource path. Terminate every instance in the partition
first, since deletion fails while any instance is still attached.

```bash theme={null}
sf infiniband-partitions delete training
```

Two kinds of instance can block a deletion without showing up in
`sf infiniband-partitions instances`:

* An instance you don't have permission to read
* A terminated instance whose node hasn't released the partition yet

## Check InfiniBand from an instance

The current Ubuntu images with CUDA 13.1 or 13.2, such as `ubuntu-24.04-cuda-13.2`, ship the
InfiniBand stack. See [Images](/preview/images) for the full list. The stack includes:

* **Drivers**: NVIDIA DOCA-OFED, with IP over InfiniBand
* **Tools**: `ibverbs-utils` and `perftest`, for checking a link
* **GPUDirect RDMA**: `nvidia-peermem`, loaded at boot with the InfiniBand modules

An instance booted from one of these images needs no setup inside the guest. Other base images, and
older builds of these images, don't include the stack.

Run `ibv_devinfo` on the instance to confirm it sees an InfiniBand device.

```bash theme={null}
ibv_devinfo
```

A device with `state: PORT_ACTIVE` is connected to the fabric.

## API reference

See the
[InfiniBand Partitions API](/preview/api-reference/infiniband-partitions/list-infiniband-partitions)
for programmatic access.

## Next steps

To train across instances in a partition, follow
[Run a PyTorch job across multiple nodes](/preview/guides/multi-node-training).


# IP Addresses
Source: https://docs.sfcompute.com/preview/networking/ip-addresses

Give an instance a public IPv4 address for internet access

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

Instances can have a public IPv4 address for internet connectivity. You choose whether an instance
has a public IP when you create it; you cannot change it afterward. IPv6 is not yet supported.

## Enabling a public IP

Set `--public-ipv4` when [creating an instance](/preview/instances#create-an-instance) to assign a
public IP address.

```bash theme={null}
sf instances create --public-ipv4
```

SF Compute assigns the public IP automatically and releases it when you delete the instance. No two
instances share an IP.

Not every SKU supports public IPv4. The interactive SKU picker lists only SKUs that do. If
you pass a `--sku` that does not support it, the request fails with a 422 error.

Without `--public-ipv4`, the only inbound port open on the instance is SSH (TCP port 22); nothing
else is reachable from the internet. Connect with `sf instances ssh`.

## Internet connectivity

Instances reach the internet via IPv4 using TCP, UDP, and ICMP. SF Compute blocks all other layer 4
protocols. It also blocks outbound SMTP (TCP and UDP port 25).
[Contact us](https://sfcompute.com/contact) if you need this restriction removed.

[Firewall rules](/preview/networking/firewalls) govern inbound traffic. Source CIDRs must be public
IPv4 addresses. Internet source IPs are
[spoofable](https://en.wikipedia.org/wiki/IP_address_spoofing), so treat firewall rules as
[security hardening](https://en.wikipedia.org/wiki/Hardening_%28computing%29), not your primary
security control.

SF Compute blocks all traffic to an instance's UDP or TCP port 68 to prevent DHCP attacks.

## Finding an instance's IP

Run `sf instances get` with the instance name or ID to see its public IP.

```bash theme={null}
sf instances get worker-1
```

Instances created with `--public-ipv4` show a `PUBLIC IPV4` row, which reads `pending` until SF
Compute assigns the IP. In `--json` output, the `public_ip` field appears once SF Compute assigns
the IP, and only on instances created with `--public-ipv4`.


# Subnets
Source: https://docs.sfcompute.com/preview/networking/subnets

Create private networks so instances in the same zone can reach each other over private IPs.

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

A subnet is a private network in a zone. Instances in the same subnet can reach each other over private IPs; instances in different subnets are isolated. Create a subnet in the console, with the CLI, or through the API. Listing, inspecting, and deleting subnets need the console or the API.

## Create a subnet

Create subnets to allow instances to communicate with each other. A subnet lives in one availability zone, identified by its region and availability zone. Instances attached to the subnet must be in that same zone.

In the console, open **Networks** and select **Create Network**. While launching an instance, you can also select **Create network** under **Network**.

With the CLI, pass the workspace, a name, the region, the availability zone, and a CIDR (Classless Inter-Domain Routing) block.

```bash theme={null}
sf subnets create \
  --workspace production \
  --name training \
  --region europe-north1 \
  --zone a \
  --cidr 10.1.0.0/16
```

The API takes the same fields in a `POST` request to `/preview/v2/subnets`.

```http theme={null}
POST /preview/v2/subnets
{
  "workspace": "sfc:workspace:acme:production",
  "name": "training",
  "region": "europe-north1",
  "availability_zone": "a",
  "cidr": "10.1.0.0/16"
}
```

The `cidr` block must fall within one of the private address ranges, be a `/28` or larger, and have no host bits set (for example, `10.1.0.0/16`).

```text theme={null}
10.0.0.0/8
172.16.0.0/12
192.168.0.0/16
```

SF Compute reserves the first four addresses of every subnet and its broadcast address; these are never assigned to instances. Instance addresses begin at the fifth address: in a `10.1.0.0/24` subnet, the first instance receives `10.1.0.4`. The `/28` minimum leaves room for these reserved addresses. Each subnet supports up to 64 live instances.

## List subnets

List subnets with a `GET` request. Pass `workspace` to scope the list to one [workspace](/preview/workspaces); omit it to list every workspace where you can list subnets.

```http theme={null}
GET /preview/v2/subnets?workspace=sfc:workspace:acme:production
```

## Get subnet details

Fetch a subnet by ID or resource path. Subnet names are unique within a workspace, so the resource path identifies the subnet.

```http theme={null}
GET /preview/v2/subnets/sfc:subnet:acme:production:training
```

## Attach instances to a subnet

Specify the subnet when you create an instance. Pass its ID or resource path in the optional `subnet` field of the create request. See [Instances](/preview/instances) for the other creation fields. You cannot attach, detach, or move a running instance to another subnet.

In the console, choose a pool and SKU, then select the subnet from the **Network** menu. With the CLI, pass `--subnet`.

```bash theme={null}
sf instances create \
  --pool training \
  --sku sku_4UpxzQw7A8N \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 \
  --cloud-init ./startup.sh \
  --subnet training
```

The API takes the subnet as an ID or resource path.

```http theme={null}
POST /preview/v2/instances
{
  "pool": "sfc:pool:acme:production:training",
  "image": "sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2",
  "instance_sku": "sku_4UpxzQw7A8N",
  "subnet": "sfc:subnet:acme:production:training"
}
```

SF Compute assigns the lowest available address in the subnet. To request a specific address, use the console's **Private IP** field, the CLI's `--private-ip` option, or the API's `private_ip` field. An address stays reserved until the instance's host confirms teardown, so a terminated instance can hold its address for a short time after it stops.

## Delete a subnet

Delete a subnet by ID or resource path. Deletion fails while an instance is attached, including after termination is requested but before its host confirms teardown.

```http theme={null}
DELETE /preview/v2/subnets/sfc:subnet:acme:production:training
```

## Networking behavior

Each instance gets a private IP in its subnet's CIDR range. Instances in the same subnet can reach each other on all ports via private IPs using unicast only. Multicast and broadcast packets are unsupported.

Instances in different subnets cannot communicate with each other, even in the same zone. SF Compute blocks IP and MAC (Media Access Control) address spoofing. Each instance can only use its assigned private IP address.

Without a public IP, an instance can reach the internet through source Network Address Translation (NAT) but cannot receive inbound internet traffic. [Firewall rules](/preview/networking/firewalls) apply to traffic through a public IP; they do not filter traffic between instances in the same subnet.

For cross-zone communication, use [public IPs](/preview/networking/ip-addresses). Instances communicate over standard IPv4 only.

## Instances without a subnet

An instance created without a subnet gets its own isolated network. It has no private-IP path to any other instance.


# Object storage
Source: https://docs.sfcompute.com/preview/object-storage

Colocate datasets with your compute and save training checkpoints between runs

Keep datasets and checkpoints in SF Compute (SFC) object storage, close to your compute. Buckets
hold your files, and tools built for S3-compatible object stores, such as rclone and boto3, read
and write to them. Upload data from your laptop or another storage provider, then use it on SFC
[instances](/preview/instances). Uploaded data stays after an instance terminates.

## Create a bucket and access key

Create a bucket for your data and an access key that your tools use to reach it.

Creating buckets and access keys requires your organization to set up billing. Have a team member
with the [admin](/preview/roles#admin-role) or [billing](/preview/roles#billing-role) role complete
the following under [Billing](https://console.sfcompute.com/dashboard/billing) in the console:

* A billing profile
* A primary billing contact
* A card set as the default payment method

<Frame>
  <img alt="Billing page with the Payment Methods, Billing Profile, and Billing Contacts sections, and a card marked Default" />
</Frame>

The examples use the `europe-north1`
[region](https://docs.sfcompute.com/api-reference/skus/get-sku#response-region-one-of-1) and your
active [workspace](/preview/workspaces). Replace `acme-training-data` throughout with your own
bucket name.

<Info>
  Object storage isn't available in every region. The console and CLI list supported regions when you
  create a bucket. If you need storage in a region we don't support yet,
  [contact us](https://sfcompute.com/contact).
</Info>

<Tabs>
  <Tab title="CLI">
    [Install `sf` and log in](/preview/quick-start#install-the-cli), then create a bucket and key in
    the same region.

    ```bash theme={null}
    sf storage buckets create --name acme-training-data --region europe-north1
    sf storage access-key create --name training --region europe-north1
    ```

    Save the returned access key ID and secret in your secrets manager. `sf` shows the secret only
    once.
  </Tab>

  <Tab title="Console">
    <Steps>
      <Step title="Open the create form">
        Open [Storage → Buckets](https://console.sfcompute.com/dashboard/storage?tab=buckets) and
        click **Create Bucket**. Enter a name and region, and choose a workspace if offered.

        <Frame>
          <img alt="Storage page on the Buckets tab, with the Create Bucket button at the top right" />
        </Frame>
      </Step>

      <Step title="Create the bucket">
        If the workspace has no access keys in that region yet, the form shows **Also create an
        access key**. Select it and click **Create Bucket & Key**. If the workspace already has a
        key there, click **Create Bucket** and reuse that key.

        <Frame>
          <img alt="Create bucket form for acme-training-data in europe-north1, with Also create an access key selected" />
        </Frame>
      </Step>

      <Step title="Save the key">
        Save a new key's **Access key ID** and **Secret access key** in your secrets manager. The
        console shows the secret only once. To create another key, open [Access
        keys](https://console.sfcompute.com/dashboard/storage?tab=keys).

        <Frame>
          <img alt="Bucket created dialog showing an example access key ID and secret access key" />
        </Frame>
      </Step>
    </Steps>
  </Tab>
</Tabs>

You may reuse an existing access key if it's in the same workspace and region as the bucket.

<Note>
  An access key can read and write every bucket in its workspace and region. Use separate workspaces
  when you need separate access boundaries.
</Note>

### Set your storage credentials

Set these variables on your laptop and on each instance that uses the bucket. Find the endpoint in
the bucket's **Access bucket** panel or with `sf storage buckets get acme-training-data`.

<Frame>
  <img alt="Access bucket panel showing the rclone snippet with the bucket endpoint" />
</Frame>

`sf storage access-key create --format env` and the console's **Access bucket** snippets print
`AWS_*` names instead. Rename them as shown so they don't override your existing AWS credentials.

```bash theme={null}
export SFC_ACCESS_KEY_ID="your_access_key_id"
export SFC_SECRET_ACCESS_KEY="your_secret_access_key"
export SFC_ENDPOINT_URL="https://object.europe-north1.sfcompute.com"
export SFC_REGION="europe-north1"
```

## Bring your dataset to SFC

Copy your dataset into the bucket with rclone, then copy it onto each instance that trains on it.
Run these commands on your laptop or the machine doing the transfer. Install
[rclone](https://rclone.org/install/), then configure an SFC remote with your
[storage credentials](#set-your-storage-credentials).

```bash theme={null}
rclone config create sfc s3 \
  provider=Other \
  access_key_id="$SFC_ACCESS_KEY_ID" \
  secret_access_key="$SFC_SECRET_ACCESS_KEY" \
  endpoint="$SFC_ENDPOINT_URL" region="$SFC_REGION" \
  force_path_style=true
```

Choose your source:

<Tabs>
  <Tab title="From your laptop">
    Copy your dataset into a versioned directory in the bucket.

    ```bash theme={null}
    rclone copy ./dataset sfc:acme-training-data/datasets/v1 --progress
    ```
  </Tab>

  <Tab title="From another S3 provider">
    Use `rclone config` to add a remote named `source` with that provider's endpoint and its own
    credentials. Then copy between the two remotes.

    ```bash theme={null}
    rclone copy source:source-bucket/dataset \
      sfc:acme-training-data/datasets/v1 --progress
    ```

    Data passes through the machine running rclone. The transfer uses that machine's bandwidth, and
    your source provider may charge egress fees.
  </Tab>
</Tabs>

Rerun `copy` to transfer new or changed files. Use a new directory such as `datasets/v2` for a new
dataset version. To mirror the source exactly, use `rclone sync`; it also deletes destination files
absent from the source.

### Use the dataset on an instance

[Connect to your instance](/preview/instances#ssh-into-an-instance), set your
[storage credentials](#set-your-storage-credentials), and configure rclone as above. Copy the
dataset onto its local disk before starting training.

```bash theme={null}
mkdir -p ~/datasets/v1
rclone copy sfc:acme-training-data/datasets/v1 ~/datasets/v1 --progress
```

Point your training data loader at `~/datasets/v1`. Repeat on each instance that needs a local copy.

## Save and resume training checkpoints

From an SFC instance, save checkpoints to object storage in the same region as your training job.
Checkpoints in object storage stay available when you move to another instance or start another run.

With PyTorch already installed, run `python -m pip install boto3` in your training environment. Set
your [storage credentials](#set-your-storage-credentials) there. Add this to your training loop,
where `model`, `optimizer`, and `step` are your current training state:

```python theme={null}
import os
from pathlib import Path

import boto3
import torch
from botocore.config import Config

s3 = boto3.client(
    "s3",
    aws_access_key_id=os.environ["SFC_ACCESS_KEY_ID"],
    aws_secret_access_key=os.environ["SFC_SECRET_ACCESS_KEY"],
    endpoint_url=os.environ["SFC_ENDPOINT_URL"],
    region_name=os.environ["SFC_REGION"],
    config=Config(s3={"addressing_style": "path"}),
)

checkpoint = Path("checkpoints") / f"step-{step}.pt"
checkpoint.parent.mkdir(parents=True, exist_ok=True)
torch.save({
    "step": step,
    "model": model.state_dict(),
    "optimizer": optimizer.state_dict(),
}, checkpoint)
key = f"runs/run-42/step-{step}.pt"
s3.upload_file(str(checkpoint), "acme-training-data", key)
```

Use a different run directory for each job. Upload only completed checkpoints; for distributed
training, coordinate the writers so they don't overwrite each other. Wait for the upload to succeed
before terminating the instance.

On a fresh instance, recreate the model and optimizer, configure the S3 client as above, and restore
a completed checkpoint:

```python theme={null}
key = "runs/run-42/step-1000.pt"
s3.download_file("acme-training-data", key, "checkpoint.pt")
state = torch.load("checkpoint.pt", map_location="cpu", weights_only=True)
model.load_state_dict(state["model"])
optimizer.load_state_dict(state["optimizer"])
start_step = state["step"] + 1
```

Include any other state your job needs to resume, such as its learning-rate scheduler. See
[PyTorch checkpointing](https://docs.pytorch.org/tutorials/beginner/saving_loading_models.html#saving-loading-a-general-checkpoint-for-inference-and-or-resuming-training).

To retrieve a run on your own machine, use the same rclone remote:

```bash theme={null}
rclone copy sfc:acme-training-data/runs/run-42 ./run-42 --progress
```

## Manage buckets and access keys

List buckets and keys with `sf storage buckets list` and `sf storage access-key list`, or open
[Storage](https://console.sfcompute.com/dashboard/storage) in the console. Revoke a key with `sf
storage access-key delete training`, or open [Storage → Access
keys](https://console.sfcompute.com/dashboard/storage?tab=keys) and click **Revoke Key**.

<Frame>
  <img alt="Access keys tab with the actions menu open for the training key, showing Revoke Key" />
</Frame>

When you no longer need a bucket, run `sf storage buckets delete acme-training-data` or select
**Delete Bucket** in [Storage](https://console.sfcompute.com/dashboard/storage). Confirm the name
when prompted. Deletion removes the bucket and all its objects.

<Frame>
  <img alt="Buckets tab with the actions menu open for acme-training-data, showing Delete Bucket" />
</Frame>

<Warning>
  Deleting a bucket is permanent. Its name becomes available for anyone to claim.
</Warning>

## Bucket and access key limits

SF Compute enforces these limits on buckets and access keys:

| Resource | Limit |
| - | - |
| Bucket capacity | 100 TiB per bucket by default. [Contact us](https://sfcompute.com/contact) if you need a higher limit. |
| Access keys | 2 per workspace per region. Key names must be unique within a workspace. |
| Bucket names | Globally unique. 3 to 63 lowercase letters, numbers, or hyphens, starting with a letter or number. |

## Usage and billing

SF Compute measures the bytes stored in each bucket hourly. Storage costs \$0.14 per GiB-month,
prorated by amount stored and time kept. For example, 100 GiB for a full calendar month costs \$14,
and for half that month it costs \$7.

SF Compute invoices storage after each UTC calendar month and
charges your default card when the invoice is due, 7 days after sending it. Storage charges are
separate from prepaid compute credits.

Track usage and month-to-date cost under [Usage →
Storage](https://console.sfcompute.com/dashboard/usage?view=storage) in the console.

<Frame>
  <img alt="Usage page on the Storage tab, with stored bytes per bucket by day and month-to-date cost per bucket" />
</Frame>

View invoices on the [Billing](https://console.sfcompute.com/dashboard/billing) page.

<Frame>
  <img alt="Invoices section of the Billing page, listing each billing month with its status, total, and due date" />
</Frame>

## API reference

The SF Compute API doesn't manage buckets or access keys yet. Use `sf storage` to script them, or
[contact us](https://sfcompute.com/contact) if you need programmatic access.


# Orderbook
Source: https://docs.sfcompute.com/preview/orderbook

Read the public orderbook: orders, windows, quotes, depth, and fills

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

The orderbook is the public, anonymized record of buy and sell orders on the market. Each order
states its side, node count, SKU, delivery window, and limit price.

The diagram below shows 3 example open orders.

<img alt="Orderbook with three example open orders: a Buy for 8 H100s on Sep 1 9am to Sep 4 5pm at up to $17.42/node-hour, a Sell for 4 B200s on the same window at $17.38 minimum, and a Buy for 16 H200s on Oct 15 12am to Oct 22 12am at up to $16.95." />

The trading engine matches compatible buys and sells continuously. Open orders make up the live
book; filled orders and their executions provide market history. Orderbook responses never
expose participant, pool, or capacity identity.

Endpoints live under `/preview/v2/orderbook/` and require a Bearer token; see
[Using the API](/preview/using-the-api).

* [`/orders`](#orders) lists individual open and filled orders.
* [`/windows`](#windows) lists active SKU and delivery-window combinations in a time range.
* [`/quote`](#quote) returns the top of book (best bid and best ask) for one exact window.
* [`/depth`](#depth) returns the live book aggregated at every SKU and price level.
* [`/fills`](#fills) lists individual executions produced when orders match.

`/windows`, `/quote`, and `/depth` are derived views of open orders, while `/fills` is an
execution-level view. Use `/windows` when you don't yet know the exact window. The other endpoints
price or trace a window you've already picked. To create, cancel, or inspect your own workspace's
orders, see [Orders](/preview/orders).

The hardware filter is `?requirements=key:value`. Keys are SKU property names such as
`accelerator`, `region`, or `availability_zone`. Values are case-sensitive and match the property's
value spelling, as in `accelerator:h100`. Run `sf skus list` to see the properties a SKU
carries.

Each key takes exactly one value; combine keys with `;` to require all of them, as in
`accelerator:h100;availability_zone:a`. The reserved `instance_sku` key matches a single SKU by its
ID. The filter covers every SKU that satisfies these requirements.

All timestamps are Unix epoch seconds. Field names use the `_at` suffix. Delivery-window and range
boundaries (`start_at`, `end_at`, `range_start_at`, and `range_end_at`) must be aligned to whole
minutes.

## Orders

List individual open and filled orders created within the last 30 days whose delivery windows
match a time range. Results are anonymized and sorted newest first by `created_at`.

```http theme={null}
GET /preview/v2/orderbook/orders?requirements=accelerator:h100&range_start_at=1777507200&range_end_at=1780099200&window_relation=overlaps&status=open

{
  "object": "list",
  "requirements": { "accelerator": ["h100"] },
  "range_start_at": 1777507200,
  "range_end_at":   1780099200,
  "window_relation": "overlaps",
  "requested_at": 1777426010,
  "has_more": false,
  "data": [
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "side": "buy",
      "status": "open",
      "allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 8 }
      ],
      "filled_allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 3 }
      ],
      "limit_price_dollars_per_node_hour": "17.420000",
      "filled_average_price_dollars_per_node_hour": "17.400000",
      "created_at": 1777426010
    }
  ]
}
```

`open` includes standing and partially filled orders; `filled` means the order filled completely.
Pending, cancelled, and rejected orders are not returned. Omit `status` to include both public
statuses, or repeat it to select more than one. Use `side=buy` for buys or `side=sell` for sells.

Delivery windows are half-open ranges: `[start_at, end_at)`. `window_relation=overlaps` is the
default. `contained_within` requires the order's full window to be inside the requested range.
`exact` requires the windows to match.

The range is capped at 30 days. `limit` defaults to 50 and caps at 200; pass the returned `cursor`
as `starting_after` to fetch the next page. The cursor must reference an order created within the
last 30 days; older cursors return a 422 response.

## Windows

Enumerate every SKU and delivery window that currently has open orders matching the
requirements filter, within a time range.

<img alt="Three example delivery windows displayed as horizontal bars on a Sep 1 to Sep 29 time axis, each showing its bid and ask counts." />

```http theme={null}
GET /preview/v2/orderbook/windows?requirements=accelerator:h100&range_start_at=1777507200&range_end_at=1780099200

{
  "object": "list",
  "requirements": { "accelerator": ["h100"] },
  "range_start_at": 1777507200,
  "range_end_at":   1780099200,
  "has_more": false,
  "data": [
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "start_at": 1777507200,
      "end_at":   1778112000,
      "duration_hours": 168,
      "total_bid_order_count": 3,
      "total_ask_order_count": 5,
      "best_bid": {
        "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
        "dollars_per_node_hour": "17.380000",
        "allocation_schedule_delta": [
          { "start_at": 1777507200, "end_at": 1778112000, "node_count": 4 }
        ]
      },
      "best_ask": {
        "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
        "dollars_per_node_hour": "17.420000",
        "allocation_schedule_delta": [
          { "start_at": 1777507200, "end_at": 1778112000, "node_count": 2 }
        ]
      }
    },
    {
      "instance_sku": "sku_q7T-mB4cV9xL2pR6wN8sJ",
      "start_at": 1777593600,
      "end_at":   1778198400,
      "duration_hours": 168,
      "total_bid_order_count": 0,
      "total_ask_order_count": 1,
      "best_ask": {
        "instance_sku": "sku_q7T-mB4cV9xL2pR6wN8sJ",
        "dollars_per_node_hour": "16.950000",
        "allocation_schedule_delta": [
          { "start_at": 1777593600, "end_at": 1778198400, "node_count": 8 }
        ]
      }
    }
  ]
}
```

A window appears when it holds at least one matching open order and sits entirely within the range.
`best_bid` / `best_ask` are omitted when that side is empty. Results are sorted ascending by
`(start_at, end_at, instance_sku)` and cursor-paginated. `limit` defaults to 50 and caps at 200; the
range is capped at 365 days.

## Quote

Get the top of book for one exact window: the highest bid and lowest ask.

<img alt="A vertical price ladder showing best ask of $17.42 with 2 nodes above best bid of $17.38 with 4 nodes, with a vertical bracket between them labeled spread $0.04." />

```http theme={null}
GET /preview/v2/orderbook/quote?requirements=accelerator:h100&start_at=1777507200&end_at=1778112000

{
  "requirements": { "accelerator": ["h100"] },
  "start_at": 1777507200,
  "end_at":   1778112000,
  "requested_at": 1777426010,
  "best_bid": {
    "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
    "dollars_per_node_hour": "17.380000",
    "allocation_schedule_delta": [
      { "start_at": 1777507200, "end_at": 1778112000, "node_count": 4 }
    ]
  },
  "best_ask": {
    "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
    "dollars_per_node_hour": "17.420000",
    "allocation_schedule_delta": [
      { "start_at": 1777507200, "end_at": 1778112000, "node_count": 2 }
    ]
  }
}
```

Each side carries an `allocation_schedule_delta`: the unfilled nodes at that rate and SKU
over time. If multiple SKUs tie at the best price, the quote returns the SKU that sorts
first by ID. Use `/depth` to inspect every SKU at that price. The window's `end_at` must be in the
future; read past windows through [`/fills`](#fills).

## Depth

Get the depth of book aggregated by SKU and dollars-per-node-hour rate across the hardware
matching the requirements filter.

<img alt="Level II ladder showing two ask price levels above the spread and three bid price levels below, with horizontal bars whose lengths encode the node count at each price." />

```http theme={null}
GET /preview/v2/orderbook/depth?requirements=accelerator:h100&start_at=1777507200&end_at=1778112000&depth=20

{
  "requirements": { "accelerator": ["h100"] },
  "start_at": 1777507200,
  "end_at":   1778112000,
  "requested_at": 1777426010,
  "bids": [
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "dollars_per_node_hour": "17.380000",
      "allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 4 }
      ]
    },
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "dollars_per_node_hour": "17.370000",
      "allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 6 }
      ]
    }
  ],
  "asks": [
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "dollars_per_node_hour": "17.420000",
      "allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 2 }
      ]
    },
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "dollars_per_node_hour": "17.430000",
      "allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 5 }
      ]
    }
  ]
}
```

Bids are sorted by descending rate (best bid first); asks are ascending. Orders at the same
rate and SKU collapse into one level. `depth` defaults to 20 and caps at 100 per side. The
window's `end_at` must be in the future; read past windows through [`/fills`](#fills).

## Fills

List individual executions for one exact delivery window. A single order can produce multiple
fills, and each fill records the nodes and price that actually traded.

```http theme={null}
GET /preview/v2/orderbook/fills?requirements=accelerator:h100&start_at=1777507200&end_at=1778112000&since_at=1777420800

{
  "object": "list",
  "requirements": { "accelerator": ["h100"] },
  "start_at": 1777507200,
  "end_at":   1778112000,
  "requested_at": 1777426010,
  "has_more": false,
  "data": [
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "dollars_per_node_hour": "17.400000",
      "allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 3 }
      ],
      "filled_at": 1777424010
    }
  ]
}
```

`since_at` is a lower bound on when the fill was recorded. It defaults to 7 days before the request.
Values more than 30 days before the request return 422.

Results are sorted newest first and cursor-paginated. `limit` defaults to 50 and caps at 200.

## Allocation schedule deltas

`allocation_schedule_delta` describes how many nodes an order requests or offers during one or
more time intervals.

<img alt="An allocation_schedule_delta JSON entry mapped to eight nodes over a time interval. start_at supplies the time for vertices A and B, end_at supplies the time for C and D, and node_count supplies the value for B and C." />

Each object in the array is one schedule segment. `start_at` and `end_at` set the segment's time
bounds, while `node_count` specifies how many nodes apply during that interval. Multiple entries
can describe different node counts over adjacent intervals.

Schedule entries describe half-open intervals `[start_at, end_at)`: the node count applies at
`start_at`, but not at `end_at`. Adjacent entries therefore meet without overlapping. All segments
on an order refer to that order's single `instance_sku`.

In responses, a non-empty array always ends with a terminator entry whose `end_at` is `null` and
`node_count` is `0`, marking the schedule as open-ended and empty after the last segment. A schedule
with no capacity is returned as an empty array. Requests carry only the closed `[start_at, end_at)`
segments you submit and omit this terminator.

Orders are submitted with one node count over one delivery window, so
`allocation_schedule_delta` normally contains one segment. `filled_allocation_schedule_delta`
describes the portion that has executed so far and may contain multiple segments when different
parts of the order fill over different intervals. Subtract the filled node count from the
requested or offered node count at each instant to get the capacity that remains on the book.

For a buy, every filled segment adds to the destination pool's allocation schedule; for a sell, it
removes that segment. An orderbook fill reports the exact schedule segment that traded. To
calculate the compute represented by a schedule, sum `node_count × duration_hours` across its
entries.

## API reference

See the [Orderbook API reference](/api-reference/orderbook/list-market-windows) for full
request and response schemas.


# Orders
Source: https://docs.sfcompute.com/preview/orders

Buy and sell compute time

Orders are how you acquire and release compute time. A buy order increases your
[pool's](/preview/pools) allocation schedule. A sell order decreases it and returns credits to your
balance.

## Buy orders

Place a buy order to get compute time on a pool. `--max-rate` is the most you'll pay in dollars per
node-hour; 1 node is 8 GPUs. You can also use `--max-price` to set a maximum total for the order
instead.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h --max-rate 20.00
```

If the orderbook has availability at your rate, the order fills immediately. Otherwise, SF Compute
cancels the order by default (immediate-or-cancel).

To keep the order on the orderbook until it fills or you cancel it, use `--allow-standing`.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h \
  --max-rate 20.00 --allow-standing
```

A buy order fills completely or not at all by default. Pass `--allow-partial` to let it fill part of
the requested nodes or time window instead, which leaves the order `partially_filled`. A sell order
allows partial fills by default, since a seller usually wants any buyer for any part of the offered
supply. Pass `--allow-partial=false` to require an all-or-nothing fill on a sell.

## Pin to a SKU

You pin every order to a single SKU; the order fills only on that SKU. Pass
`--sku <id>` to pick one directly.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h \
  --max-rate 20.00 \
  --sku sku_4UpxzQw7A8N
```

Running `sf orders create` without `--sku` opens an interactive picker that shows every
registered SKU's name, ID, and properties. In non-interactive mode (`--no-input`), `--sku`
is required. Run `sf skus list` to browse them beforehand. See
[SKUs](/preview/instance-skus) for the full model.

## Sell orders

Sell back compute time you own.

```bash theme={null}
sf orders create --side sell --pool dev --count 1 \
  --start now --duration 1h --min-rate 8.00 --allow-standing
```

When a sell order fills, you receive credits and your pool's allocation decreases. Instances on that
pool that no longer have allocated time will terminate.

<Note>
  Sell orders are not guaranteed to fill. Use `--allow-standing` to keep the order on the orderbook
  until a buyer matches.
</Note>

## Sell fees

When a sell order executes, SF Compute deducts a variable
[platform fee](/preview/guides/reselling#platform-fee) from the fill price. You receive the fill
price minus the fee as credits. The CLI shows the estimated fee before you confirm an order.

Buy orders have no fees.

## Interruptible buy orders

<Warning>
  Interruptible buy orders are in [public preview](/preview/roadmap#feature-states).
</Warning>

When an interruptible buy order fills, SF Compute lists the compute it bought for sale at an
interrupt rate you set. These listings are sell orders on the same pool that allow partial fills.
While the interrupt rate is below the [offset price ceiling](/preview/limits#compute-limits), the
order doesn't count toward your compute limit.

If someone buys a listing, you lose that time. Instances left without allocated time terminate,
lowest [priority](/preview/instances#instance-priority) first.

Set the interrupt rate in dollars per node-hour with `--interrupt-rate`. It must be above your max
rate and below the ceiling. `sf platform-constants` shows the current ceiling.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h \
  --max-rate 20.00 --interrupt-rate 24.00
```

`sf pools extend` takes the same flag. If an interactive buy would go over your compute limit and
your max rate is below the ceiling, the CLI offers to make it interruptible.

If the ceiling drops to or below your interrupt rate, the order's unfilled node-hours and the
compute it bought start counting toward your limit.

See your listings with `sf orders list --side sell`. When a listing fills, you get the fill price
minus [sell fees](#sell-fees).

Cancelling the buy order doesn't cancel its listings. Cancel a listing with `sf orders cancel`. SF
Compute refuses the cancellation if it would put you over your compute limit.

## Holds

Placing an order reserves what a fill would need, so a match can always settle. A buy order holds
credits equal to its worst case, the limit price across the full requested window and node count.
Your available balance is what remains after open holds.

Placement fails with an insufficient-balance error when your available balance can't cover the hold.
A sell order instead reserves the pool allocation it offers, so the same compute can't be sold
twice.

When a fill executes, you pay the fill price and SF Compute releases the unused part of the hold.
Cancelling the order or letting its remaining window elapse releases the rest.

## Order statuses

| Status | Description |
| - | - |
| pending | Submitted, not yet processed |
| filled | Fully executed |
| partially\_filled | Partially executed; the unfilled remainder stays on the orderbook |
| standing | Waiting for a match on the orderbook |
| cancelled | No match found (immediate-or-cancel), manually cancelled, or the order's window fully elapsed |
| rejected | Validation or system error |

A standing order (buy or sell) rests until it fills, you cancel it, or its window fully elapses. As
the current time passes the order's start, it keeps matching only over the un-elapsed remainder of
its window. It matches at its original per-node-hour limit price. The order's total value shrinks as
time elapses.

Once the whole window has elapsed the order stops matching and moves to `cancelled`; there is no
separate expiry or time-to-live field. This lapse timing is current behavior, not a guarantee.

## Check an order

Look up a single order by ID.

```bash theme={null}
sf orders get ordr_JLBu4arl9nSLMfF2Ole
```

```text theme={null}
| ORDER ID                ordr_JLBu4arl9nSLMfF2Ole
| SIDE                    buy
| STATUS                  filled at Mar 19, 4:48pm
| FILLED                  100%
| POOL                    dev (pool_nuO4nVSM8O3NnsRE7udBe)
| SKU                     sku_4UpxzQw7A8N
| RATE (PER 8X GPU NODE)  $20.00/node/hr (Limit)
|
| SCHEDULE                Mar 19, 5:00pm → Mar 19, 6:00pm: 1 node
```

## List orders

List orders in the active workspace.

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

To list orders across your organization, use `--all`.

```bash theme={null}
sf orders list --all
```

```text theme={null}
-----------------------------------------------------------------------------------------------------------
SIDE  STATUS     PERIOD  NODES  RATE ($/NODE/HR, 8x GPU)  POOL  SKU              ID
sell  filled     Mar 19  1      ≥$8.00/node/hr            dev   sku_4UpxzQw7A8N  ordr_hYuOEmXWt3RqPd8KvA2Nc
buy   filled     Mar 19  1      ≤$20.00/node/hr           dev   sku_4UpxzQw7A8N  ordr_JLBu4arl9nSLMfF2Ole
buy   cancelled  Mar 12  1      ≤$20.00/node/hr           dev   sku_4UpxzQw7A8N  ordr_Qj69x65vLw4TmBn7RdEyS
```

Filter by side or status.

```bash theme={null}
sf orders list --side buy --status filled
```

Filter by time range.

```bash theme={null}
# Orders from the last 7 days
sf orders list --created-after 7d

# Orders within a specific window
sf orders list --created-after 2025-03-01 --created-before 2025-03-08

# Orders from a specific calendar month
sf orders list --month 2025-05
```

`--created-after` and `--created-before` accept a datetime, Unix timestamp, or a duration like `24h`
or `7d`. A duration means that long ago (24 hours or 7 days, respectively). You can also use
`--since` and `--until` as aliases.

## Cancel an order

Cancel an order that hasn't fully filled yet.

```bash theme={null}
sf orders cancel <order-id>
```

Cancellation is asynchronous. The request returns right away (`204 No Content` on the API). A
matching batch already in progress can still land a fill before the state flips to `cancelled`. Poll
`GET /v2/orders/{id}` until it does.

Cancellation removes only the unfilled remainder from the orderbook and keeps the fills that
executed before it. Once the order is `cancelled`, its `fills` and
`filled_allocation_schedule_delta` are final and remain readable on the order in both get and list
responses.

## Start and end times

Order start and end times must be on the
[allocation schedule grid](/api-reference/platform/get-platform-constants#response-allocation-schedule-grid).
An order can also start at the current time.

## Allocation schedule deltas

`allocation_schedule_delta` describes how many nodes an order requests or offers during one or
more time intervals.

<img alt="An allocation_schedule_delta JSON entry mapped to eight nodes over a time interval. start_at supplies the time for vertices A and B, end_at supplies the time for C and D, and node_count supplies the value for B and C." />

Each object in the array is one schedule segment. `start_at` and `end_at` set the segment's time
bounds, while `node_count` specifies how many nodes apply during that interval. Multiple entries
can describe different node counts over adjacent intervals.

Schedule entries describe half-open intervals `[start_at, end_at)`: the node count applies at
`start_at`, but not at `end_at`. Adjacent entries therefore meet without overlapping. All segments
on an order refer to that order's single `instance_sku`.

In responses, a non-empty array always ends with a terminator entry whose `end_at` is `null` and
`node_count` is `0`, marking the schedule as open-ended and empty after the last segment. A schedule
with no capacity is returned as an empty array. Requests carry only the closed `[start_at, end_at)`
segments you submit and omit this terminator.

Orders are submitted with one node count over one delivery window, so
`allocation_schedule_delta` normally contains one segment. `filled_allocation_schedule_delta`
describes the portion that has executed so far and may contain multiple segments when different
parts of the order fill over different intervals. Subtract the filled node count from the
requested or offered node count at each instant to get the capacity that remains on the book.

For a buy, every filled segment adds to the destination pool's allocation schedule; for a sell, it
removes that segment. An orderbook fill reports the exact schedule segment that traded. To
calculate the compute represented by a schedule, sum `node_count × duration_hours` across its
entries.

## API examples

These worked examples use the `/v2` order endpoints; see the
[Orders API reference](/api-reference/orders/list-orders) for the full request and response
schemas. Timestamps are Unix epoch seconds, and prices are strings in dollars per node-hour.

Create a buy order with `POST /v2/orders`. The request body includes the following fields.

* `side` is `buy` or `sell`.
* `pool` accepts a pool ID or resource path.
* `sku` takes a SKU ID.
* `allocation_schedule_delta` is a single time range.

```json theme={null}
{
  "pool": "pool_2m9Xk4Qw7A8N",
  "side": "buy",
  "allow_standing": true,
  "allow_partial": false,
  "sku": "sku_4UpxzQw7A8N",
  "allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 }
  ],
  "limit_price_dollars_per_node_hour": "18.000000"
}
```

The response returns the order in `pending` state; poll `GET /v2/orders/{id}` for the resolved
state. The trailing zero entry marks the end of the schedule.

```json theme={null}
{
  "object": "order",
  "id": "ordr_JLBu4arl9nSLMfF2Ole",
  "pool": { "object": "pool_summary", "id": "pool_2m9Xk4Qw7A8N", "name": "dev" },
  "workspace": { "object": "workspace_summary", "id": "wksp_7Ct3nR2xL9", "name": "acme" },
  "side": "buy",
  "allow_standing": true,
  "allow_partial": false,
  "sku": { "object": "sku", "id": "sku_4UpxzQw7A8N", "alias": "h100i" },
  "allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
    { "start_at": 1742407200, "end_at": null, "node_count": 0 }
  ],
  "filled_allocation_schedule_delta": [],
  "limit_price_dollars_per_node_hour": "18.000000",
  "state": "pending",
  "created_at": 1742402883
}
```

A sell order takes the same body with `side` set to `sell`, and its response has the same shape.

```json theme={null}
{
  "pool": "pool_2m9Xk4Qw7A8N",
  "side": "sell",
  "allow_standing": true,
  "allow_partial": true,
  "sku": "sku_4UpxzQw7A8N",
  "allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 }
  ],
  "limit_price_dollars_per_node_hour": "9.000000"
}
```

Fetch one order with `GET /v2/orders/{id}`. Once filled, `state` is `filled`, `filled_at` is set,
and `filled_allocation_schedule_delta` covers the filled portion. `fills` lists each execution with
the price actually paid (here below the buy's limit).

```json theme={null}
{
  "object": "order",
  "id": "ordr_JLBu4arl9nSLMfF2Ole",
  "pool": { "object": "pool_summary", "id": "pool_2m9Xk4Qw7A8N", "name": "dev" },
  "workspace": { "object": "workspace_summary", "id": "wksp_7Ct3nR2xL9", "name": "acme" },
  "side": "buy",
  "allow_standing": true,
  "allow_partial": false,
  "sku": { "object": "sku", "id": "sku_4UpxzQw7A8N", "alias": "h100i" },
  "allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
    { "start_at": 1742407200, "end_at": null, "node_count": 0 }
  ],
  "filled_allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
    { "start_at": 1742407200, "end_at": null, "node_count": 0 }
  ],
  "limit_price_dollars_per_node_hour": "18.000000",
  "state": "filled",
  "created_at": 1742402883,
  "filled_at": 1742402889,
  "fills": [
    {
      "filled_at": 1742402889,
      "allocation_schedule_delta": [
        { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
        { "start_at": 1742407200, "end_at": null, "node_count": 0 }
      ],
      "price_dollars_per_node_hour": "15.000000"
    }
  ]
}
```

List orders with `GET /v2/orders`. Each entry in `data` is a full order object; pass the returned
`cursor` as `starting_after` to page forward.

```json theme={null}
{
  "object": "list",
  "has_more": false,
  "cursor": "ordrc_kQ8Vd2wwpU1s2Wey",
  "data": [
    {
      "object": "order",
      "id": "ordr_hYuOEmXWt3RqPd8KvA2Nc",
      "pool": { "object": "pool_summary", "id": "pool_2m9Xk4Qw7A8N", "name": "dev" },
      "workspace": { "object": "workspace_summary", "id": "wksp_7Ct3nR2xL9", "name": "acme" },
      "side": "sell",
      "allow_standing": true,
      "allow_partial": true,
      "sku": { "object": "sku", "id": "sku_4UpxzQw7A8N", "alias": "h100i" },
      "allocation_schedule_delta": [
        { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
        { "start_at": 1742407200, "end_at": null, "node_count": 0 }
      ],
      "filled_allocation_schedule_delta": [],
      "limit_price_dollars_per_node_hour": "9.000000",
      "state": "standing",
      "created_at": 1742402883
    }
  ]
}
```

Cancel with `POST /v2/orders/{id}/cancel`, which returns `204 No Content`.

```http theme={null}
POST /v2/orders/ordr_hYuOEmXWt3RqPd8KvA2Nc/cancel
```


# Pools
Source: https://docs.sfcompute.com/preview/pools

Manage compute allocation

A pool records an allocation of compute time. You buy compute time into a pool with orders, and
[instances on the pool run during the scheduled time slots](/preview/guides/instances-and-pools).
You can also move compute between pools with [transfers](#transfers).

## Create a pool

A new pool starts with no allocation.

```bash theme={null}
sf pools create --name dev
```

## List pools

List the pools in your workspace.

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

```text theme={null}
─────────────────────────────────────────────────
NAME  KIND    NODES  PERIOD  NEXT 48H
dev   market  -      -       ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
```

## View a pool

Get a pool by name or ID.

```bash theme={null}
sf pools get dev
```

```text theme={null}
│ POOL ID         pool_nuO4nVSM8O3NnsRE7udBe
│ NAME            dev
│ RESOURCE PATH   sfc:pool:acme:default:dev
│ KIND            market
│ CREATED         Feb 17, 5:23pm PDT
└ TOTAL SCHEDULE  Today, 5:00pm → Aug 14, 5:00pm: 1 node
```

## Allocation schedule

The allocation schedule shows how many nodes you have over time on this pool. The schedule gains
time when a buy order fills and loses time when a sell order fills.

You can create instances on a pool before it has allocation. They start running when allocation
becomes available and stop when it runs out.

The schedule is a net node count over time, not a ledger of the orders that built it. Filled buy and
sell orders each add or remove a schedule segment (see [Orders](/preview/orders)), but the pool
keeps only the running total at each instant. There's no stable identifier for an individual
segment: 2 fills of the same SKU and time range are indistinguishable once merged into the total. To
track which order added or removed a given block of time, keep the order's own ID.

## Mixed hardware

A single pool can hold allocation across several [SKUs](/preview/instance-skus). Each order
fills against whatever SKU matches its requirements, and the schedule tracks each SKU's allocation
independently. Within a SKU, nodes are interchangeable, so the schedule tracks a node count, not
which physical machine is running it.

For example, a pool might hold 100 H100 nodes in `sea-3` from 9am to 5pm today. It could hold 50
more H100 nodes in `iad-12` from 5pm today to 9am tomorrow. The SKUs do not need to overlap in time;
the schedule records what was bought and when.

Run `sf pools get dev --verbose` to see a separate schedule block per SKU in addition to the
aggregate `TOTAL SCHEDULE`.

### Buy more on an existing SKU

To add allocation to a SKU you already have, pass its ID via `--sku` on the buy order. Each
SKU has a stable ID (`sku_...`) that pins the order to exactly that SKU.

```bash theme={null}
sf orders create --side buy --pool dev --nodes 1 --start now --duration 1h \
  --max-rate 20.00 \
  --sku sku_4UpxzQw7A8N
```

Run `sf pools get dev --verbose` or `sf skus list` to find the ID.

## Transfers

Transfers move nodes between 2 pools for a specified window of time.

### Create a transfer

Specify the source pool, destination pool, time window, node count, and SKU.

```bash theme={null}
sf pools transfers create \
  --from dev \
  --to prod \
  --start-at "tomorrow" \
  --duration 7d \
  --count 4 \
  --sku sku_4UpxzQw7A8N
```

Start and end times must be on the
[allocation schedule grid](/api-reference/platform/get-platform-constants#response-allocation-schedule-grid).
A transfer can also start at the current time.

Omitting a required flag opens an interactive picker to help you fill in the remaining values.

Specify the full resource path if the `--from` or `--to` pool is located in a
different workspace.

```bash theme={null}
sf pools transfers create \
  --from dev \
  --to sfc:pool:acme:prod_ws:prod \
  --start-at "tomorrow" \
  --duration 7d \
  --count 4 \
  --sku sku_4UpxzQw7A8N
```

### List transfers

List the transfers in your organization.

```bash theme={null}
sf pools transfers list
```

```text theme={null}
────────────────────────────────────────────────────────────────────
ID           CREATED AT      STATUS    FROM       TO    INSTANCE SKU
pxfr_abc123  Mar 19, 4:40pm  executed  dev        prod  -
pxfr_def456  Mar 18, 9:15am  pending   dev        prod  -
pxfr_ghi789  Mar 18, 9:02am  rejected  inference  prod  -
```

Filter by pool (repeatable) or status, or pass `--verbose` for the schedule details of each
transfer.

```bash theme={null}
sf pools transfers list --pool prod --status executed
```

```text theme={null}
───────────────────────────────────────────────────────────────
ID           CREATED AT      STATUS    FROM  TO    INSTANCE SKU
pxfr_abc123  Mar 19, 4:40pm  executed  dev   prod  -
```

### Get a transfer

Get a transfer by ID.

```bash theme={null}
sf pools transfers get pxfr_abc123
```

```text theme={null}
│ TRANSFER ID   pxfr_abc123
│ STATUS        executed
│ FROM POOL     dev
│ TO POOL       prod
│ INSTANCE SKU  sea-3-h100 (sku_4UpxzQw7A8N)
│ CREATED       Mar 19, 4:40pm PDT
│
└ SCHEDULE      Mar 20, 12:00am → Mar 27, 12:00am: 4 nodes
```

### Protect instances from termination

A pool's allocation can drop below the number of running instances when a sell order fills, a
[spot deployment](/preview/spot-deployments) scales down, or a transfer leaves. When that happens,
SF Compute terminates instances until the running count matches the schedule, lowest
[priority](/preview/instances#instance-priority) first, newest first within a priority.

To keep specific instances running when allocation shrinks, raise their priority. The system keeps
`critical` instances over everything else.

```bash theme={null}
sf instances set gpu-worker --priority critical
```

## Extend a pool

Extending places a buy order that continues the schedule's final node count to a new end time.

```bash theme={null}
sf pools extend dev
```

For example, consider the following pool.

```bash theme={null}
sf pools get dev
```

```text theme={null}
│ POOL ID         pool_nuO4nVSM8O3NnsRE7udBe
│ NAME            dev
│ RESOURCE PATH   sfc:pool:acme:default:dev
│ KIND            market
│ CREATED         Feb 17, 5:23pm PDT
└ TOTAL SCHEDULE  Today, 5:00pm → Aug 14, 5:00pm: 2 nodes
```

Extend it by 2 hours. The prompt asks for a duration and whether to leave a standing order. It then
quotes the current rate for the extension.

```bash theme={null}
sf pools extend dev
```

```text theme={null}
  note: extending from Aug 14, 5:00pm PDT

> Duration of compute time: 2h
> Allow as standing order until filled? No

│ ACTION                  extend pool
│ POOL                    dev (pool_nuO4nVSM8O3NnsRE7udBe)
│ NODES                   2
│ EXTENDING FROM          Aug 14, 5:00pm PDT
│ EXTENDING TO            Aug 14, 7:00pm PDT
│ INSTANCE SKU            sea-3-h100 (sku_4UpxzQw7A8N)
│ RATE (PER 8X GPU NODE)  $20.00/node/hr
│ TOTAL                   $80.00
│ ESTIMATED FEE           $4.00
│ FILL                    expected to fill at this rate
│ STANDING                false
└ to be placed
> Place this order? Yes
Order ordr_HV6cjCNfgs2y9HCIOJITO filled
```

Non-interactive runs require an end time and a price cap: pass `--duration` or `--stop`, plus
`--max-rate` or `--max-price`.

Fetch the pool again; the schedule now ends 2 hours later.

```bash theme={null}
sf pools get dev
```

```text theme={null}
│ POOL ID         pool_nuO4nVSM8O3NnsRE7udBe
│ NAME            dev
│ RESOURCE PATH   sfc:pool:acme:default:dev
│ KIND            market
│ CREATED         Feb 17, 5:23pm PDT
└ TOTAL SCHEDULE  Today, 5:00pm → Aug 14, 7:00pm: 2 nodes
```

Extension requires availability during the requested window.

## Rename a pool

Renaming a pool changes its resource path but not its ID.

```bash theme={null}
sf pools set dev --name production
```

## Delete a pool

A pool must have no active orders, future allocation, non-terminated instances, deployments,
procurements, or pending transfers before you can delete it.

```bash theme={null}
sf pools delete dev
```

## API reference

See the [Pools API](/api-reference/pools/list-pools) for programmatic access.


# Quickstart
Source: https://docs.sfcompute.com/preview/quick-start

Get your first GPU instance running

Create a pool, buy compute time into it, and start your first GPU instance on SF Compute.

## Install the CLI

Download and run the install script.

```bash theme={null}
curl -fsSL https://cli.sfcompute.com | bash
```

## Log in

Authenticate the CLI.

```bash theme={null}
sf login
```

This opens your browser to sign in and stores your credentials locally.

## Check what you can buy

[SKUs](/preview/instance-skus) describe the hardware you can buy. List them and when each
becomes available, 1 row per SKU.

```bash theme={null}
sf availability
```

```text theme={null}
  NAME        ID               NEXT AVAILABLE  NEXT 48H
  ams-1-h100  sku_7GtBqvXk2Nm  now (24)        ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▁▁▁▁▁  peak: 24
  iad-2-h100  sku_Wm5cRzJq8Ld  now (64)        ▇▇▇▇▇▇▇▇▇▇▁▁▁▁▁▁▁▁▁▁  peak: 64
  ord-1-a100  sku_2xPfVn6KwQh  now (96)        ▇▇▇▇▇▄▄▄▄▄▂▂▂▂▂▁▁▁▁▁  peak: 96
  sea-3-h100  sku_4UpxzQw7A8N  now (128)       ▇▇▇▇▇▇▇▇▇▇▁▁▁▁▁▁▁▁▁▁  peak: 128
  nrt-1-h100  sku_Ht9sLc3MvBn  now (48)        ▇▇▇▇▇▇▇▇▇▇▇▇▁▁▁▁▁▁▁▁  peak: 48
```

`NEXT AVAILABLE` is the soonest instances become available and how many. Values are `now (N)`, a
time like `Today, 8:00pm (4)`, or `—` when nothing is scheduled. `NEXT 48H` sparklines the schedule
with the peak shown to the right.

## Create an empty pool

A [pool](/preview/pools) tracks your compute allocation over time. You buy compute time into a pool
with orders, and instances on the pool run when there's allocated time. Create a pool named `dev`.

```bash theme={null}
sf pools create --name dev
```

## Buy compute time

<Note>
  Buying compute time charges your organization. Make sure you have credits: check with
  `sf billing balance` or [top up on the dashboard](https://sfcompute.com/dashboard).
</Note>

Place a buy [order](/preview/orders) for compute time on your pool. The command guides you through
each option interactively. You set the number of nodes (each node runs 1 instance), start time,
duration, rate, and the [SKU](/preview/instance-skus) the order pins to. For this guide,
choose a start time of `now`.

```bash theme={null}
sf orders create --pool dev --side buy
```

## Check your order

List your orders and check the status.

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

```text theme={null}
--------------------------------------------------------------------------------------------------------
SIDE  STATUS  PERIOD  NODES  RATE ($/NODE/HR, 8x GPU)  POOL  SKU              ID
buy   filled  Mar 23  1      ≤$20.00/node/hr           dev   sku_4UpxzQw7A8N  ordr_5KwQh2xPfVn6M3RtLcQw9
```

<Note>
  If the order shows `cancelled`, the price was too low or there was no availability. Try a higher
  rate, a later start time, or `--allow-standing`. A standing order stays open on the orderbook until
  it fills or you cancel it.
</Note>

## List images

An [image](/preview/images) is the bootable disk template an instance starts from. You need an image
name or ID to create an instance. List the images available to you.

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

```text theme={null}
----------------------------------------------------------------------------------------
NAME                                               VISIBILITY  STATUS     CREATED
sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2  public      completed  Feb 23, 6:50pm
```

SF Compute publishes public images with Ubuntu and CUDA pre-installed. You can also
[build and upload your own custom images](/preview/images).

## Create an instance

First, create a startup script that injects your SSH key so you can connect to the instance.

```bash theme={null}
# The $(cat ...) lines expand on your machine as startup.sh is written,
# embedding your public keys in the script.
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_ed25519.pub 2>/dev/null)
EOF
SCRIPT
```

Then create an [instance](/preview/instances) on your pool with the public image.

```bash theme={null}
sf instances create --pool dev --sku sku_4UpxzQw7A8N \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 --cloud-init ./startup.sh
```

Your pool already has compute time from the order you placed. Because you chose a start time of
`now`, your instance gets its allocation within about a minute and begins booting. Compute ownership
and instances are separate: you can terminate and recreate instances without losing your purchased
compute time.

## Watch your instance start

List your instances to watch the status. The `NAME` column shows the name you'll use to connect.

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

The image download and boot process takes up to 10 minutes before SSH is available.

## Connect via SSH

SSH in with the instance name from `sf instances list`.

```bash theme={null}
sf instances ssh <instance-name>
```

Verify the GPUs are available.

```bash theme={null}
nvidia-smi
```

## Next steps

You now have a running GPU instance. Here are some things to try.

### Sell back unused compute time

Place a sell order as a standing order. If someone buys it, you get credits back (minus a variable
[platform fee](/preview/guides/reselling#platform-fee)) and the instance loses its compute time.

```bash theme={null}
sf orders create --pool dev --side sell --count 1 --sku sku_4UpxzQw7A8N \
  --start now --duration 1h --min-rate 8.00 --allow-standing
```

### Check your pool's allocation schedule

See the compute time you own on the pool.

```bash theme={null}
sf pools get dev
```

### Learn more

* [Instances and Pools](/preview/guides/instances-and-pools) explains the core model.
* [Auto-scaling](/preview/guides/auto-scaling) shows how to scale a fleet up and down while buying
  and selling time automatically.
* [Pools](/preview/pools), [orders](/preview/orders), and [instances](/preview/instances) are the
  resource references for the commands used here.


# Resource paths
Source: https://docs.sfcompute.com/preview/resource-paths

Human-readable references for resources across the API and CLI

A resource path is a human-readable, colon-separated reference for a resource. Resource paths let
you reference resources across the API and CLI without memorizing IDs.

Not every resource has a resource path. You reference resources like [orders](/preview/orders),
which have no user-settable name, by ID only.

## Format

Most resource paths take 1 of 2 forms.

```text theme={null}
sfc:<type>:<organization>:<workspace>:<name>     # workspace-scoped
sfc:<type>:<organization>:<name>                 # organization-scoped
```

The `sfc:` prefix identifies the resource as belonging to SF Compute. The hierarchy moves from
broader scope (left) to narrower scope (right). Each segment contains only letters, numbers, and the
characters `.`, `_`, and `-`, so a colon always marks a segment boundary. Colons are URL-safe, so
resource paths can appear directly in URL path parameters without encoding.

## Examples by resource type

| Resource | Scope | Resource path |
| - | - | - |
| Pool | workspace | `sfc:pool:acme:production:training-pool` |
| Instance | workspace | `sfc:instance:acme:production:trainer-1` |
| Instance template | workspace | `sfc:instance_template:acme:production:gpu-worker` |
| Image | workspace | `sfc:image:acme:production:cuda-12-7` |
| Deployment | workspace | `sfc:deployment:acme:production:inference` |
| Workspace | organization | `sfc:workspace:acme:production` |

## IDs vs resource paths

Every resource has a stable ID (e.g., `pool_k3R-nX9vLm7Qp2Yw5Jd8F`). IDs never change for the
lifetime of the resource. The API derives resource paths from the resource's name, workspace, and
organization, so they change when any of those change. If you rename a pool from `training-pool` to
`inference-pool`, its ID stays the same but its resource path changes.

Use IDs for automation and integrations that need stable references. Use resource paths for
convenience in the CLI and ad-hoc API calls.

API responses include both.

```json theme={null}
{
  "object": "pool",
  "id": "pool_k3R-nX9vLm7Qp2Yw5Jd8F",
  "resource_path": "sfc:pool:acme:production:training-pool",
  "workspace": {
    "id": "wksp_7Yb-Ht2mNq4Rx8Wc1Ke5P",
    "name": "production"
  },
  "name": "training-pool"
}
```

## Using resource paths in the CLI

The CLI accepts resource paths wherever you would use a name.

```bash theme={null}
# Get an instance from another workspace by resource path
sf instances get sfc:instance:acme:staging:worker-1

# Transfer compute across workspaces using resource paths
sf pools transfers create \
  --from sfc:pool:acme:ml-team:unallocated \
  --to sfc:pool:acme:inference-team:unallocated \
  --count 10 \
  --start-at "tomorrow" \
  --duration 7d \
  --sku sku_4UpxzQw7A8N
```

## Using resource paths in the API

Anywhere the API accepts a resource ID, it also accepts a resource path. This includes path
parameters, request body fields, and query parameters. The API resolves a resource path to the
underlying ID before processing the request. These 2 requests are equivalent.

```http theme={null}
GET /v2/pools/pool_k3R-nX9vLm7Qp2Yw5Jd8F
GET /v2/pools/sfc:pool:acme:production:training-pool
```

Resource paths also work in request bodies that reference other resources. This is useful for
cross-workspace references, where you can target a resource in another workspace without switching
context. Fields that reference resources without user-settable names, like `sku`, take IDs only. For
example, this `POST /v2/instances` body references a pool and an image in another workspace by
resource path.

```json theme={null}
{
  "pool": "sfc:pool:acme:shared:training-pool",
  "image": "sfc:image:acme:shared:cuda-12-7",
  "sku": "sku_9Fd-Lz6pQw3Vn1Ay8Rk4T"
}
```

## Next steps

* [Workspaces](/preview/workspaces) explains the workspace layer that scopes most resource paths.
* [Pools](/preview/pools) covers the pools these examples reference.
* [Using the API](/preview/using-the-api) covers authentication and request basics.


# Roadmap
Source: https://docs.sfcompute.com/preview/roadmap

Development priorities, feature states, and the public preview support policy

See which features you can use today, how much support each state gets, and where the platform is
headed.

## Development priorities

1. Expanding our capabilities as a public cloud. We build core primitives for buying, managing,
   and orchestrating compute, then layer higher-level functionality on top.
2. Increasing liquidity. If you have unused compute, you should be able to resell it and recoup
   some of your compute costs.

## Feature states

Features move through the following states as they mature.

A feature starts in development: we are building it, and it is not yet available. It then enters
private preview. Selected customers get access, so we can validate the design with real usage before
opening it more broadly. Email [support@sfcompute.com](mailto:support@sfcompute.com) to request early access.

In public preview, the feature is available to everyone but may have rough edges. See
[Public preview support](#public-preview-support) for what that means in practice.

Generally available features are production-ready and fully supported under a stable API version
prefix (the versioned URL path; see [Using the API](/preview/using-the-api)). Our
[uptime SLA](https://sfcompute.com/legal/sla) covers them.

When we retire a feature, it reaches planned end of life first. It still works, but you should
migrate to the recommended alternative. At end of life, it is no longer available or supported.

## Public preview support

Preview features are available to everyone. Their API paths, response shapes, CLI flags, and error
codes may change while the design settles. We support preview features on a best-effort basis, and
our uptime SLA does not cover them.

## Public preview features

* [Instance templates](/preview/instance-templates) - define reusable instance configurations
* [Deployments](/preview/deployments) - automate instance creation and management
* [Orderbook](/preview/orderbook) - view market depth and pricing
* [Tags](/preview/tags) - organize resources with key-value pairs
* [Image versions](/preview/images#using-an-image) - pin an instance to one exact image build
* [Reselling](/preview/guides/reselling) - resell unused allocation on the orderbook
* [Interruptible buy orders](/preview/orders#interruptible-buy-orders) - buy past your compute limit
  by listing the compute for sale

## Generally available features

* [Pools](/preview/pools) - manage your compute allocation
* [Orders](/preview/orders) - buy and sell compute time
* [Instances](/preview/instances) - launch and operate GPU instances
* [SKUs](/preview/instance-skus) - pick the hardware your orders run on
* [Images](/preview/images) - build, upload, and manage custom images
* [Workspaces](/preview/workspaces) - group resources to isolate teams or environments
* [Resource paths](/preview/resource-paths) - reference resources by name across the API and CLI

## Feedback

If something is confusing, missing, or broken, reach out through your existing support channel or
email [support@sfcompute.com](mailto:support@sfcompute.com).


# Roles
Source: https://docs.sfcompute.com/preview/roles

Create and manage roles, named sets of permissions you assign with grants

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

SF Compute uses role-based access control (RBAC). A role is a named set of permissions that defines
what actions the holder can perform. A [grant](/preview/grants) assigns a role to a user or token
within a workspace or across the organization.

When a request arrives, SF Compute collects the caller's grants and evaluates every matched role's
rules. It allows the action only if a matched rule grants it. Otherwise SF Compute denies it.

A role name must start with a letter or number. After that, it can contain letters, numbers, dots,
hyphens, and underscores, up to 255 characters.

Role names are unique within the organization. Roles are organization-wide. The same role can be
granted across multiple workspaces.

## Built-in roles

Built-in roles cover common patterns, so you often don't need a custom role. List every role in the
organization with the CLI.

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

```text theme={null}
------------------------------------------------------------------------------------------
NAME               TYPE      DESCRIPTION
admin              built_in  Full access to all resources
viewer             built_in  Read-only access to all resources
operator           built_in  Infrastructure management, no IAM access
billing            built_in  Billing and orders only
workspace-admin    built_in  Full workspace management without purchasing
member             built_in  Standard org member: read-only across non-sensitive resources
training-operator  custom    Can manage instances and view pools
```

You cannot modify or delete built-in roles.

### Admin role

Full access to all resources. Use sparingly.

```toml theme={null}
api_version = "roles/v1"
description = "Full access to all resources"

[[rules]]
effect = "allow"

[rules.actions]
"*" = ["*"]
```

### Viewer role

Read-only access to all resources.

```toml theme={null}
api_version = "roles/v1"
description = "Read-only access to all resources"

[[rules]]
effect = "allow"

[rules.actions]
"*" = ["read", "list"]
```

### Operator role

Full access to infrastructure resources, with no access to identity and access management (IAM:
roles, grants, tokens), billing, or orders.

```toml theme={null}
api_version = "roles/v1"
description = "Infrastructure management, no IAM access"

[[rules]]
effect = "allow"

[rules.actions]
instance             = ["*"]
instance_template    = ["*"]
image                = ["*"]
pool                 = ["*"]
deployment           = ["*"]
procurement          = ["*"]
secret               = ["*"]
ssh_key              = ["*"]
firewall             = ["*"]
subnet               = ["*"]
infiniband_partition = ["*"]
```

### Billing role

Full access to billing and orders, plus read-only access to limits. No infrastructure access. Good
for finance teams.

```toml theme={null}
api_version = "roles/v1"
description = "Billing and orders only"

[[rules]]
effect = "allow"

[rules.actions]
billing = ["*"]
order   = ["*"]
limits  = ["read"]
```

### Workspace-admin role

Full management of a workspace and everything in it — including granting others access to it —
but no purchasing: orders, procurements, and deployments are read-only. Granted automatically,
scoped to the new workspace, to whoever creates a workspace.

```toml theme={null}
api_version = "roles/v1"
description = "Full workspace management without purchasing"

[[rules]]
effect = "allow"

[rules.actions]
workspace            = ["*"]
grant                = ["*"]
role                 = ["read", "list"]
instance             = ["*"]
instance_template    = ["*"]
image                = ["*"]
pool                 = ["*"]
secret               = ["*"]
ssh_key              = ["*"]
firewall             = ["*"]
subnet               = ["*"]
infiniband_partition = ["*"]
order                = ["read", "list"]
procurement          = ["read", "list"]
deployment           = ["read", "list"]
```

### Member role

Read and list access across non-sensitive resources, with no access to secrets, billing, tokens, or
SSH keys. This is the default role users hold when they join an organization.

```toml theme={null}
api_version = "roles/v1"
description = "Standard org member: read-only across non-sensitive resources"

[[rules]]
effect = "allow"

[rules.actions]
instance             = ["read", "list"]
instance_template    = ["read", "list"]
image                = ["read", "list"]
pool                 = ["read", "list"]
deployment           = ["read", "list"]
procurement          = ["read", "list"]
firewall             = ["read", "list"]
subnet               = ["read", "list"]
infiniband_partition = ["read", "list"]
role                 = ["read", "list"]
grant                = ["read", "list"]
order                = ["read", "list"]
limits               = ["read", "list"]
```

## Creating a role

Write a role definition in TOML and pass it to the CLI.

```bash theme={null}
sf roles create --name training-operator -f role.toml
```

In this example, `role.toml` contains the following definition.

```toml theme={null}
api_version = "roles/v1"
description = "Can manage instances and view pools"

[[rules]]
effect = "allow"

[rules.actions]
instance = ["*"]
pool     = ["read"]
ssh_key  = ["*"]
secret   = ["read"]
```

`api_version` must be `roles/v1`.

A role grants nothing on its own. [Create a grant](/preview/grants) to assign it to a user or
[token](/preview/tokens).

## Rule syntax

A rule says what a user or token is allowed to do. It has 2 pieces.

* An `actions` map, which pairs each resource (such as `instance` or `pool`) with a list of verbs
  (such as `read` or `write`).
* An `effect` sets what the rule grants for those actions. It takes one of these values.
  * `allow`: perform the action directly, request approval for it, and approve others' approval
    requests.
  * `require_approval`: request approval for the action, but not perform it directly or approve
    others' requests.
  * `approve_approval`: approve others' approval requests for the action, but not perform it
    directly or request approval.

A caller whose rules grant both `require_approval` and `approve_approval` for an action can perform
it directly, the same as `allow`.

For example, this role lets the holder read, update, delete, and list instances.

```toml theme={null}
api_version = "roles/v1"
description = "Instance management"

[[rules]]
effect = "allow"

[rules.actions]
instance = ["read", "write", "delete", "list"]
```

### Supported resources and verbs

The supported resources are `instance`, `instance_template`, `image`, `pool`, `deployment`,
`procurement`, `secret`, `ssh_key`, `firewall`, `subnet`, `infiniband_partition`, `role`, `grant`,
`token`, `approval`, `billing`, `order`, `limits`, `user`, `workspace`, and `*`.

The supported verbs are `read`, `write`, `delete`, `list`, `create`, and `*`.

Each rule covers every `(resource, verb)` pair you list. Use `"*"` as either the resource or the
verb for a wildcard.

These patterns cover common needs.

```toml theme={null}
instance = ["read"]           # Read instance details
instance = ["create"]         # Create instances
instance = ["write"]          # Update instances
instance = ["delete"]         # Delete instances
instance = ["*"]              # All instance actions
pool     = ["read"]           # View pool details
pool     = ["write"]          # Update pools
order    = ["read"]           # View orders
order    = ["create"]         # Place buy/sell orders
billing  = ["read"]           # View balance, usage, invoices, rates
billing  = ["write"]          # Update billing settings
limits   = ["read"]           # View hard and soft limits
secret   = ["read"]           # Read secrets from metadata service
firewall = ["*"]              # Manage firewalls
token    = ["*"]              # Manage tokens
ssh_key  = ["*"]              # Manage SSH keys
"*"      = ["*"]              # Everything (equivalent to admin)
```

If no rule matches, SF Compute denies the action.

## Listing and inspecting roles

List all roles, or fetch one by name.

```bash theme={null}
sf roles list
sf roles get training-operator
```

## Updating a role

Replace a role's definition from a TOML file.

```bash theme={null}
sf roles set training-operator -f role-v2.toml
```

Changes take effect immediately for all grants that reference this role. SF Compute re-evaluates
existing sessions on the next API call.

## Deleting a role

Deleting a role removes it from any grants that reference it. You cannot undo this.

```bash theme={null}
sf roles delete training-operator
```

## Example roles

These definitions cover common team setups; adapt them to your resources, and assign them with
[grants](/preview/grants).

### CI/CD deployer

For a CI/CD (continuous integration and delivery) pipeline. Full access to instances, read access to
pools, secrets, and SSH keys, and nothing else.

```toml theme={null}
api_version = "roles/v1"
description = "CI/CD pipeline - deploy and teardown training jobs"

[[rules]]
effect = "allow"

[rules.actions]
instance = ["*"]
pool     = ["read"]
secret   = ["read"]
ssh_key  = ["read"]
```

### Researcher

Can use existing infrastructure but not modify pools or access controls.

```toml theme={null}
api_version = "roles/v1"
description = "Researcher - run training jobs on allocated pools"

[[rules]]
effect = "allow"

[rules.actions]
instance = ["read", "write", "list"]
ssh_key  = ["*"]
secret   = ["read"]
```

### Finance

View billing data, update billing settings, and view orders. No infrastructure access.

```toml theme={null}
api_version = "roles/v1"
description = "Finance - view spending and invoices, update billing settings, view orders"

[[rules]]
effect = "allow"

[rules.actions]
billing = ["read", "write"]
order   = ["read"]
```

## API reference

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


# Tags
Source: https://docs.sfcompute.com/preview/tags

Track and organize resources with key-value pairs

Tags are `key=value` pairs that help you track and organize resources on SF Compute.

## Create tags

Set tags when you create a resource with the `--tag` flag.

```bash theme={null}
sf pools create --name root --tag model=cuda-crunch
```

## Edit tags

The `set` command replaces all existing tags on a resource. Pass every tag you want to keep.

```bash theme={null}
sf instances set prod --tag model=cuda-crunch --tag env=prod
```

## Delete tags

To delete all tags on a resource, set `--tag null`. You cannot recover deleted tags.

```bash theme={null}
sf pools set dev --tag null
```

To remove a single tag, re-run `set` with only the tags you want to keep.

## List resources by tags

Filter resources by tag with the `--tag` flag.

```bash theme={null}
sf instances list --tag model=cuda-crunch
```

```text theme={null}
-----------------------------------------------------------------------------
NAME  STATUS   POOL  INSTANCE SKU  CREATED        TAGS
prod  running  root  -             Mar 1, 9:00am  model=cuda-crunch, env=prod
```

To match any value for a key, filter with the `--tag-key` flag.

```bash theme={null}
sf instances list --tag-key env
```

```text theme={null}
-----------------------------------------------------------------------------
NAME  STATUS   POOL  INSTANCE SKU  CREATED        TAGS
prod  running  root  -             Mar 1, 9:00am  env=prod, model=cuda-crunch
```

## Constraints

Tag keys must not contain spaces, commas, or equals signs, and must not begin with an underscore
(`_`). Keys can be up to 128 characters.

Tag values must not contain commas or equals signs. Values may contain spaces and can be up to 256
characters.

Tags are case sensitive. You can add up to 50 tags to each resource.


# Tokens
Source: https://docs.sfcompute.com/preview/tokens

Create and manage bearer tokens that authenticate API and CLI requests

Tokens authenticate requests to the SF Compute API. Use tokens for CI/CD (continuous integration and
delivery) pipelines, automation, and service accounts. Tokens use the `sk_live_` prefix.

## Creating a token

A token applies to your whole organization, not to a single workspace. Creating or deleting a token
requires a role with `token` permissions. See [Roles](/preview/roles#supported-resources-and-verbs).

```bash theme={null}
sf tokens create --name deploy
```

The CLI prints the token value (`sk_live_...`) once, at creation. Store it somewhere safe. You can't
retrieve it again.

To set an expiry, pass a duration with `--expires`.

```bash theme={null}
sf tokens create --name ci-runner --expires 90d
```

Without `--expires`, interactive runs prompt for an expiration and non-interactive runs default to
90 days. Pass `--no-expire` to create a token that never expires.

## Attaching a role

A token with no role attached cannot do anything. Attach a role at creation time with `--role`, and
pass `--workspace` to limit it to 1 workspace or `--org` to apply it organization-wide.

```bash theme={null}
sf tokens create --name ci-deploy --role training-operator --workspace production
```

`training-operator` is a custom role you create yourself. To run this as-is, attach a built-in role
like `operator`. See [Roles](/preview/roles).

As with other commands, `-w` and `SF_WORKSPACE` also set the workspace. `--org` overrides
`SF_WORKSPACE`, and can't be combined with `-w` or `--workspace`. With no workspace and no `--org`,
interactive runs let you pick a workspace or organization-wide, and non-interactive runs exit with
an error, so scripts pass `--workspace` or `--org`.

Pass `--role` multiple times to attach more than one role. Every role gets the same scope. Running
`sf tokens create` without `--role` shows an interactive multi-select picker over your available
roles.

To grant a role to an existing token, use `sf grants create`. See
[Grants](/preview/grants#token-grants).

## Listing tokens

List every token in your organization.

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

```text theme={null}
-----------------------------------------------------------
NAME    SUFFIX   CREATED         LAST USED  EXPIRES
deploy  ...FHbI  Mar 1, 12:00pm  Never      May 30, 12:00pm
admin   ...XyZ1  Feb 15, 9:00am  Never      May 16, 9:00am
```

## Deleting a token

Delete a token by name.

```bash theme={null}
sf tokens delete deploy
```

Deleting a token revokes it immediately. In-flight requests authenticated with the token fail.

## Using a token

See [Using the API](/preview/using-the-api) to authenticate requests with your token.


# Using the API
Source: https://docs.sfcompute.com/preview/using-the-api

Authenticate and make your first API request

The API is available at `https://api.sfcompute.com/v2`. All requests require a
Bearer token.

The API exposes the same resource model as the CLI. Pools hold an allocation schedule, orders buy
and sell compute time, and instances run on pools. If that model is new, start with
[Instances and Pools](/preview/guides/instances-and-pools) before wiring the API into an
application.

## Create an API token

Create a token with the CLI.

```bash theme={null}
sf tokens create --name my-token
```

This prints a token starting with `sk_live_`. Save it somewhere safe. You can't retrieve it again.

## Grant permissions

Tokens start with no permissions. Grant access to the resources your token needs. These examples use
a workspace named `my-workspace`; every new organization starts with one named `default`.

```bash theme={null}
sf grants create --token my-token --role admin --workspace my-workspace
```

The `admin` role grants full access to the workspace; give production tokens a narrower role. See
[Roles](/preview/roles) and [Grants](/preview/grants) for how permissions work, and the
[Quickstart](/preview/quick-start) for more on workspaces.

## Make a request

Replace `my-account` with your organization name (shown by `sf me` or in the dashboard). Replace
`<token>` with the token you created above.

```bash theme={null}
curl 'https://api.sfcompute.com/v2/pools?workspace=sfc:workspace:my-account:my-workspace' \
  -H "Authorization: Bearer sk_live_..."
```

API workflows follow the same shape as the [Quickstart](/preview/quick-start).

1. Create or choose a pool.
2. Place a buy order to add allocation.
3. Create instances on the pool.
4. Read pool, order, and instance state to track what happened.

## API reference

Browse every endpoint, with request parameters and response shapes, in the sidebar. Start with the
[Pools API](/api-reference/pools/list-pools).


# Workspaces
Source: https://docs.sfcompute.com/preview/workspaces

Group resources to isolate teams or environments

A workspace groups resources within an organization. Pools, instances, instance templates,
deployments, images, subnets, and tags all belong to a workspace. Every new organization comes with
a workspace named `default`. It's not special: you can rename it through the
[API](/api-reference/workspaces/update-workspace) or delete it like any other workspace.

## Create a workspace

Workspace names are unique within your organization.

```bash theme={null}
sf workspaces create --name production
```

## List workspaces

The arrow in the leftmost column marks the active workspace.

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

```text theme={null}
-----------------------------
  NAME        CREATED
  default     Mar 1, 12:00am
→ production  Jun 15, 12:00am
  staging     Jun 15, 12:00am
```

## View a workspace

Get a workspace by name, or omit the name to get your active workspace.

```bash theme={null}
sf workspaces get production
```

```text theme={null}
| WORKSPACE      production
| ID             wksp_8fJq2LpXw4RkT7vY3mN5c
| RESOURCE PATH  sfc:workspace:acme:production
| CREATED        Jun 15, 12:00am PDT
```

## Set your active workspace

If you haven't set an active workspace, the CLI falls back to `default`. Set one with
`sf workspaces use <name>`. Override per-command with `--workspace <name>`.

```bash theme={null}
sf workspaces use production
sf instances list --workspace staging   # one-off override
```

## Every request targets a workspace

Every API request that creates, lists, or operates on workspace-scoped resources targets a
workspace. Not all resources are workspace-scoped; see [resource paths](/preview/resource-paths) for
which resources live at which scope.

* Creating resources: include `"workspace"` in the request body. Resources created on a pool
  (instances, deployments, and orders) are the exception. They inherit the pool's workspace, so you
  choose the workspace when you create the pool.
* Listing resources: pass `?workspace=` as a query parameter.
* Getting a single resource: use a [resource path](/preview/resource-paths) or an ID.

On the CLI, pass `--workspace`.

```bash theme={null}
# Create a pool in a specific workspace. Instances created on this pool
# inherit its workspace.
sf pools create --name training-cluster --workspace production

# List instances in a workspace
sf instances list --workspace production
```

## Cross-workspace references with resource paths

Every resource has a [resource path](/preview/resource-paths) that embeds the workspace. Use a
resource path anywhere you can pass a name or ID. It lets you reference resources in another
workspace without switching context.

```bash theme={null}
# Create an instance on a pool in the `shared` workspace without switching
# your active workspace. The instance is created in `shared`, since an
# instance inherits its pool's workspace.
sf instances create --pool sfc:pool:acme:shared:training-pool \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 \
  --cloud-init ./startup.sh \
  --sku sku_4UpxzQw7A8N
```

## Delete a workspace

Deletion fails if the workspace still contains pools, instance templates, images, subnets, or custom
firewalls. Move or delete them first.

```bash theme={null}
sf workspaces delete staging
```

## API reference

See the [Workspaces API](/api-reference/workspaces/list-workspaces) for programmatic
access.


# Delete workspace
Source: https://docs.sfcompute.com/api-reference/workspaces/delete-workspace

/openapi.json delete /v2/workspaces/{id}
Soft-delete a workspace by ID or resource path. Workspace must be empty.



# Update workspace
Source: https://docs.sfcompute.com/api-reference/workspaces/update-workspace

/openapi.json patch /v2/workspaces/{id}
Rename a workspace.



# Events
Source: https://docs.sfcompute.com/preview/events

Read an ordered log of what happened on your account, from instances starting to orders filling

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

Events form an append-only log of what happens on your account, such as [instances](/preview/instances) starting and terminating or [orders](/preview/orders) filling. Only events from the last 7 days are available. Authenticate with a bearer token, as described in [Using the API](/preview/using-the-api).

```bash theme={null}
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://api.sfcompute.com/preview/v2/events"
```

The response holds a page of events in `data`.

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "evt_x7Kp2mQhTv9rWq3s",
      "cursor": "evtc_...",
      "action": "instance.terminated",
      "occurred_at": 1755644312,
      "actor": { "type": "token", "id": "tokn_..." },
      "targets": [{ "type": "instance", "id": "inst_9dQpXk2LwZj" }]
    }
  ],
  "has_more": false,
  "cursor": "evtc_..."
}
```

`action` names what happened, and `occurred_at` records when, as a Unix timestamp in seconds. `actor` is the API token whose request caused the event, or `{ "type": "system" }` for automated actions, such as a preemption or a scheduled end. `targets` lists the resources the event is about as `{type, id}` pairs. Each `id` is the same ID the rest of the API uses for that resource.

## Event types

The table below lists each event type and its target type. To filter by resource, pass a target type as `target_type` or a single resource's ID as `target`.

| Action | Target type | Meaning |
| - | - | - |
| `instance.created` | `instance` | The instance was created and is [awaiting allocation](/preview/instances#instance-lifecycle). |
| `instance.running` | `instance` | The instance started running. SSH access becomes available once its image finishes booting. |
| `instance.termination_imminent` | `instance` | The instance will be terminated soon because its allocation is ending, whether from preemption or a scheduled end. |
| `instance.terminated` | `instance` | The instance was terminated, whether by user request, replacement, preemption, deployment teardown, or a scheduled end. |
| `instance.failed` | `instance` | The instance reported itself unhealthy. This does not terminate the instance, though work on it may be lost. [Replace](/preview/instances#replace-an-instance) or terminate it. |
| `instance.connection_lost` | `instance` | The instance stopped responding. |
| `order.created` | `order` | The order was placed. |
| `order.filled` | `order` | The order filled completely. |
| `order.cancelled` | `order` | The order was cancelled. |
| `image.revoked` | `image` | The image was [revoked](/preview/images#revoking-an-image) and can no longer back new instances. |
| `image.reinstated` | `image` | The image was reinstated and can back new instances again. |
| `trust_level.updated` | `account` | Your account's trust level changed. |
| `instance_sku_override.updated` | `instance_sku` | SF Compute set or changed property overrides on a [SKU](/preview/instance-skus) for your account. |
| `instance_sku_override.deleted` | `instance_sku` | SF Compute removed the property overrides on a SKU for your account. |

New event types are added over time, so if you don't filter by `action`, expect actions that aren't in this table. For a given instance, `instance.created`, `instance.running`, and `instance.terminated` appear in that order. An instance terminated while still awaiting allocation has no `instance.running` event.

## Consuming the stream

List events with `GET /preview/v2/events`. Events are returned oldest first, up to `limit` per request. `limit` defaults to 50 and is capped at 200. To fetch the next page, pass the response's `cursor` back as `starting_after`. `has_more` tells you whether more events are already available.

When `data` is empty and `has_more` is false, you have read everything so far. That response carries no `cursor`, so keep the one you sent and poll with it again later.

Filter with `action` for an exact event type, `target` for one resource, `target_type` for one type of resource, and `since` and `until` for inclusive bounds on `occurred_at`, given as Unix timestamps. Filters combine, so a single request can ask for one event type on one resource.

```bash theme={null}
# Everything that happened to one instance
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://api.sfcompute.com/preview/v2/events?target=inst_9dQpXk2LwZj&target_type=instance"

# All terminations since a point in time
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://api.sfcompute.com/preview/v2/events?action=instance.terminated&since=1755043200"

# When one order filled
curl -H "Authorization: Bearer $SF_API_KEY" \
  "https://api.sfcompute.com/preview/v2/events?action=order.filled&target=ordr_5Gh8kLm2Np4QwXz"
```

A cursor only works with the filters it was created with, and reusing it with different filters returns 400 Bad Request. If a saved cursor falls outside the 7-day retention window, requests with it return 410 Gone. In that case, start over without a cursor to read from the oldest available event.

## API reference

See the [Events API](/preview/api-reference/events/list-events) for every parameter and response field.


# Grants
Source: https://docs.sfcompute.com/preview/grants

Assign roles to users and tokens

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

A grant assigns a [role](/preview/roles) to a user or [token](/preview/tokens) within a
[workspace](/preview/workspaces) or across the organization.

## Granting access to a user

Grant a role directly to a user by their email.

```bash theme={null}
sf grants create \
  --workspace production \
  --user alice@acme.co \
  --role admin
```

Alice now has admin access to the `production` workspace.

As with other commands, `-w` and `SF_WORKSPACE` also set the workspace. `--org` overrides
`SF_WORKSPACE`, and can't be combined with `-w` or `--workspace`.

## Organization-wide grants

Use `--org` to grant a role across all workspaces in the organization.

```bash theme={null}
sf grants create \
  --org \
  --user alice@acme.co \
  --role admin
```

Alice now has admin access to every workspace in the organization.

## Listing grants

List all grants in the organization. With a workspace set by `-w` or `SF_WORKSPACE`, the list shows
only the grants scoped to that workspace, not organization-wide ones.

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

```text theme={null}
------------------------------------------------------------------------------------------------------------------
ID                          WORKSPACE   ROLE               TYPE   PRINCIPAL                   CREATED
grnt_k3RnX9vLm7Qp2Yw5JdA4f  (Org-wide)  admin              user   alice@acme.co               Feb 4, 2025, 12:00pm
grnt_8KvQ3mWxYpRtZn6Hb2C7j  production  training-operator  user   bob@acme.co                 Feb 3, 2025, 9:30am
grnt_9QwT4xNbVs2Lm7Cfj3W5d  production  viewer             token  tokn_5DhP2nLqWmKz8XvBt4Jc6  Feb 1, 2025, 8:15am
```

Filter by workspace or by user. Unlike `sf grants create`, which accepts an email, the `--user`
filter takes a user ID.

```bash theme={null}
sf grants list --workspace production
sf grants list --user usr_7d41c2a90b5f83e6
```

## Deleting a grant

Delete a grant by its ID, which `sf grants list` prints in the first column.

```bash theme={null}
sf grants delete grnt_k3RnX9vLm7Qp2Yw5JdA4f
```

You can also delete a workspace-scoped grant by its attributes. As with `sf grants list`, `--user`
takes a user ID.

```bash theme={null}
sf grants delete \
  --workspace production \
  --user usr_3e92f8b06c14da75 \
  --role training-operator
```

Delete an organization-wide grant.

```bash theme={null}
sf grants delete \
  --org \
  --user usr_7d41c2a90b5f83e6 \
  --role admin
```

## Multiple grants

A user or token can have multiple grants. SF Compute combines the permissions from every granted
role (a union).

```bash theme={null}
sf grants create --org --user bob@acme.co --role viewer
sf grants create --workspace production --user bob@acme.co --role training-operator
```

Bob has `viewer` access organization-wide and `training-operator` access in `production`.

## Token grants

Grant roles to tokens for CI/CD pipelines and other automation.

```bash theme={null}
sf grants create \
  --workspace production \
  --token ci-deploy \
  --role training-operator
```

Alternatively, assign a role when creating the token. `sf tokens create` takes the same
`--workspace` and `--org` flags and creates 1 grant per role.

```bash theme={null}
sf tokens create --name ci-deploy --role training-operator --workspace production
```

See [Tokens](/preview/tokens#attaching-a-role).

## How grants interact with roles

Grants bind users or tokens to roles. Roles define which actions a user or token can perform.

When a request arrives, SF Compute collects every grant the user or token holds on the target
workspace, including organization-wide grants. It then evaluates the rules from all matched roles.
See [Roles](/preview/roles) for the rule effects and evaluation semantics.

## API reference

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


# Instances and Pools
Source: https://docs.sfcompute.com/preview/guides/instances-and-pools

How instances and pools separate what you run from the compute time it runs on

You run workloads on instances and pay for the compute time they use from pools.

## Instances

An [instance](/preview/instances) is a GPU virtual machine booted from an [image](/preview/images).
Like instances on other clouds, it has hardware, an image, startup configuration, logs, SSH access,
and lifecycle state. You create it, connect to it, run your workload, and terminate it when you are
done.

The only difference is that an SF Compute instance consumes compute time when it runs. It won't
start until it has compute time allocated to it. That compute time comes from a pool.

## Pools

A [pool](/preview/pools) is a named container that holds an allocation of compute time. It
represents that allocation as a schedule. The schedule tracks how many nodes you own, on which
hardware, and for which windows of time. Each node runs 1 instance.

For example, a pool might have this schedule.

| Hardware | Window | Allocation |
| - | - | - |
| H100, EU North, InfiniBand, … | Mar 20, 09:00 → Mar 20, 17:00 | 4 nodes |
| H100, EU North, InfiniBand, … | Mar 20, 17:00 → Mar 21, 00:00 | 8 nodes |
| H200, US East, No RDMA, … | Mar 21, 09:00 → Mar 21, 17:00 | 2 nodes |

The pool's schedule changes as you buy, sell, or transfer compute time, or as it expires.

## SKUs

Each pool tracks a separate schedule for each stock-keeping unit (SKU). A
[SKU](/preview/instance-skus) represents a specific set of interchangeable hardware,
including the following.

* Accelerator type, such as H100 or H200
* Instance specs like number of CPUs, RAM, and local storage
* RDMA type, such as InfiniBand or RoCE
* Zone or location
* Other operator-defined hardware properties

You pin orders, transfers, and instances to a SKU. That tells SF Compute which hardware
the allocation comes from.

## Starting an instance

When you create an instance, you attach it to a pool. The instance starts in `awaiting_allocation`
if the pool does not currently have matching allocation for the hardware it will run on.

To add compute time, place a buy [order](/preview/orders) on the pool. When the order fills, it adds
compute time to the pool's allocation schedule for the order's SKU. Once the schedule
covers the current time and there is enough matching allocation, the instance starts booting.

```bash theme={null}
sf pools create --name dev

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

# --max-rate is the most you'll pay, in dollars per node-hour.
sf orders create \
  --side buy \
  --pool dev \
  --count 1 \
  --start now \
  --duration 2h \
  --max-rate 20.00 \
  --sku sku_4UpxzQw7A8N
```

You can create the instance before the order fills. It waits until matching allocation exists.

Instances define what should run. Pools define when there is compute time available to run it.

## Instance lifecycle

A pool's allocation determines whether attached instances can run.

| Pool state | Instance behavior |
| - | - |
| No matching allocation | Instance waits in `awaiting_allocation` |
| Allocation becomes available | Waiting instances start booting |
| Allocation covers the running instance | Instance stays `running` |
| Allocation shrinks below demand | SF Compute terminates instances until demand fits allocation |

Terminating an instance does not free its allocation. The allocation remains in the pool's
schedule until you sell it, transfer it, or let it expire.

When allocation grows, waiting instances can start. If you use a [deployment](/preview/deployments),
the deployment can also create more instances to match its target count. Those instances start when
allocation is available.

When allocation shrinks below the number of running instances, SF Compute terminates instances until
the running count fits the pool schedule. It terminates lower-priority instances first. Among
instances with the same priority, it terminates the newest first. If you need control over which
work survives a planned shrink, set [instance priority](/preview/instances) before selling,
transferring, or letting allocation expire.

Compute allocation stays separate from what you run. You can buy compute time before you launch
instances and recreate instances without losing reserved time. You can also sell unused time without
deleting the pool and move allocation between workloads.

Think of it like a power grid. Pools are the circuits.

Orders add compute time to those circuits. Transfers move it between circuits. Instances draw it
from the pool they are attached to.

If a circuit has enough scheduled compute time, the attached instances can run. If it does not, they
wait or terminate.

## One pool or many

You can attach multiple instances to a single pool, or create a separate pool for each instance or
workload.

Use a separate pool when you want to manage the instance independently.

* A personal dev box should usually have its own pool.
* A one-off debugging instance should usually have its own pool.
* A customer-isolated workload should use its own pool if selling or expiration should not affect
  other customers.

Use one shared pool when the instances are part of the same fleet and can share allocation
decisions.

* An inference fleet should usually use one pool and one deployment.
* Batch workers for the same queue can usually share one pool.
* A training job with many identical workers can usually share one pool.

As a rule of thumb, put instances in the same pool only when you can scale, interrupt, extend,
sell, or transfer them together.

## Transfers

You can transfer compute time between pools. This lets you manage allocation like any other
resource. Assign it to projects, teams, or workloads, then move it when it is not being used.

For example, a platform team might buy a large block of H100 time into a shared pool. It can then
transfer pieces of that allocation to separate pools for `training`, `inference`, and `experiments`.
If `experiments` does not need its allocation, the team can transfer it back or move it to another
project.

Transfers affect the same schedule that orders affect. If compute time leaves a pool, attached
instances may terminate if the remaining allocation no longer covers them. If compute time arrives,
waiting instances can start.

## Next steps

* [Orders](/preview/orders) covers buying and selling compute time.
* [Pools](/preview/pools) is the command reference for pool operations, including transfers.
* [Instances](/preview/instances) is the command reference for instance lifecycle operations.


# Run a PyTorch job across multiple nodes
Source: https://docs.sfcompute.com/preview/guides/multi-node-training

Create an InfiniBand partition, start instances in it, and launch torchrun on every node

This guide takes you from no instances to a `torchrun` job on 2 nodes with 8 GPUs each. The nodes find each other over a private [subnet](/preview/networking/subnets) and exchange training data over an isolated [InfiniBand partition](/preview/networking/infiniband-partitions). By the end, you'll have trained [nanoGPT](https://github.com/karpathy/nanoGPT) on a small corpus of Shakespeare and generated text from it.

## Before you start

Set up your account, a partition, a subnet, and a [pool](/preview/pools) before you create any instances. A pool holds the allocation your instances run on. You need the `sf` CLI, logged in to your account. See the [Quickstart](/preview/quick-start#install-the-cli) to install it.

The examples use landsend, a [SKU](/preview/instance-skus) with 8 H100 GPUs per node: ID `sku_4EzdPrHcTps`, region `europe-north1`, zone `a`, on the InfiniBand fabric `europe-north1-a.fab1`. A fabric is the physical InfiniBand network that a SKU's nodes connect to. To use another SKU with InfiniBand, replace these values with its own.

<Steps>
  <Step title="Enroll in the InfiniBand preview">
    Enroll your account so the `sf infiniband-partitions` commands and the `--infiniband-partition` flag become available.

    ```bash theme={null}
    sf preview set infiniband-preview=true
    ```
  </Step>

  <Step title="Create a partition on your SKU's fabric">
    Create a partition named `training` on your SKU's fabric.

    ```bash theme={null}
    sf infiniband-partitions create --name training --fabric europe-north1-a.fab1
    ```

    Only instances in the same partition can reach each other over InfiniBand. See [Create a partition](/preview/networking/infiniband-partitions#create-a-partition) for the other options.
  </Step>

  <Step title="Create a subnet in your SKU's zone">
    Create a subnet named `training` in your SKU's region and zone.

    ```bash theme={null}
    sf subnets create --name training --region europe-north1 --zone a \
      --cidr 10.1.0.0/24
    ```

    Note the subnet `id` in the output, which starts with `snet_`. You need it to delete the subnet later.

    Instances in the subnet reach each other over private IPv4 addresses. `torchrun` uses the subnet to start the job, and the NVIDIA Collective Communications Library (NCCL) sends the training traffic over InfiniBand.
  </Step>

  <Step title="Write a startup script">
    SF Compute public images ship with no SSH key. This script adds your public keys to the `root` user when the instance boots. The `$(cat ...)` lines run on your machine as you write the file. If you have none of these keys, create one with `ssh-keygen -t ed25519` first.

    To use a key stored elsewhere, see [SSH into an instance](/preview/instances#ssh-into-an-instance).

    ```bash theme={null}
    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_ed25519.pub 2>/dev/null)
    EOF
    SCRIPT
    ```

    See [Cloud-init](/preview/instances#cloud-init) for other ways to configure an instance.
  </Step>

  <Step title="Buy an allocation of 2 nodes">
    Create a [pool](/preview/pools) named `training` and buy an allocation of 2 nodes of your SKU for 4 hours. The 4 hours start as soon as the order fills, so buy last and start the next section right after. Your organization needs enough credits to cover the price.

    The `sf buy` command quotes the price and asks you to confirm before it charges your organization for the full 4 hours. To skip the prompt in a script, add `--max-rate` with the highest price per node-hour you accept, and `--yes`.

    ```bash theme={null}
    sf pools create --name training
    sf buy --pool training --sku sku_4EzdPrHcTps --count 2 --start now --duration 4h
    ```
  </Step>
</Steps>

## Launch the job

Each instance runs `torchrun` with a node rank, a number from 0 that identifies it in the job. The rank 0 instance coordinates the job, and the job needs only that instance's private subnet address.

<Steps>
  <Step title="Create one instance per node">
    Create 2 instances in the partition and the subnet. This loop names them `training-0` and `training-1` and gives them the private addresses `10.1.0.10` and `10.1.0.11`. `--public-ipv4` gives each instance a public address for `sf instances ssh` to connect to.

    ```bash theme={null}
    for i in 0 1; do
      sf instances create --name "training-$i" --pool training \
        --sku sku_4EzdPrHcTps \
        --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 \
        --cloud-init ./startup.sh --infiniband-partition training \
        --subnet training --private-ip "10.1.0.1$i" --public-ipv4 --yes
    done
    ```

    Wait until both instances show `running` in this list.

    ```bash theme={null}
    sf infiniband-partitions instances training
    ```

    SSH becomes available after the image downloads and the instance boots, which can take up to 10 minutes. See [Instances](/preview/instances#limitations). If `sf instances ssh` reports that SSH details aren't available yet, wait a minute and retry.
  </Step>

  <Step title="Find the subnet interface">
    Open one terminal per instance and connect as `root`, the user the startup script added your key to. Start with `training-0`.

    ```bash theme={null}
    sf instances ssh training-0 --login root
    ```

    On each instance, print the interface that holds the instance's subnet address.

    ```bash theme={null}
    ip -br -4 addr show to 10.1.0.0/24 | tr -s ' '
    ```

    ```text theme={null}
    ens1 UP 10.1.0.10/24
    ```

    The first field, `ens1` here, is the interface name, which can differ on each instance.
  </Step>

  <Step title="Set up nanoGPT on every instance">
    This guide trains [nanoGPT](https://github.com/karpathy/nanoGPT), a small GPT model, on 1 MB of Shakespeare. Install [uv](https://docs.astral.sh/uv/), clone nanoGPT, install its packages, and prepare the dataset. Run these commands on each instance.

    ```bash theme={null}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    source ~/.local/bin/env
    git clone https://github.com/karpathy/nanoGPT ~/nanoGPT
    uv venv ~/venv
    uv pip install --python ~/venv torch numpy tiktoken requests
    cd ~/nanoGPT && ~/venv/bin/python data/shakespeare_char/prepare.py
    ```

    `prepare.py` downloads the text and writes `train.bin` and `val.bin` to `data/shakespeare_char/`. Each instance reads its own copy.
  </Step>

  <Step title="Run torchrun on every instance">
    Start `torchrun` on each instance with its own node rank: `0` on `training-0` and `1` on `training-1`. Replace `ens1` with the instance's subnet interface.

    ```bash theme={null}
    cd ~/nanoGPT
    NCCL_SOCKET_IFNAME=ens1 NCCL_DEBUG=INFO ~/venv/bin/torchrun \
      --nnodes 2 --nproc-per-node 8 --node-rank 0 \
      --master-addr 10.1.0.10 --master-port 29500 \
      train.py config/train_shakespeare_char.py \
      --gradient_accumulation_steps=16 --max_iters=500 --lr_decay_iters=500 \
      --warmup_iters=50 --eval_interval=100 --eval_iters=20 --compile=False \
      2>&1 | grep -E "NET/IB|step "
    ```

    `NCCL_SOCKET_IFNAME` sets the interface that NCCL uses to connect the instances at startup. The subnet interface is the one the other instance can reach. NCCL then sends the training data over InfiniBand.

    The flags after the config file change nanoGPT's single-GPU defaults for 16 GPUs:

    * **`--gradient_accumulation_steps=16`**: nanoGPT splits this value across the GPUs, so it must be a multiple of the GPU count
    * **`--max_iters`, `--lr_decay_iters`, `--warmup_iters`**: shorten the run, since each step now covers 16 GPUs' worth of data
    * **`--eval_interval`, `--eval_iters`**: evaluate every 100 steps on 20 batches, so evaluation fits the short run

    Each instance waits until all `--nnodes` instances have joined, then training starts. Each GPU prints the NCCL network line, and `training-0` prints the loss every 100 steps.

    ```text theme={null}
    NCCL INFO NET/IB : Using [0]mlx5_4:1/IB … [RO]; OOB ens1:10.1.0.10<0>
    …
    step 0: train loss 4.2885, val loss 4.2831
    step 100: train loss 2.3385, val loss 2.3798
    …
    step 500: train loss 1.2817, val loss 1.5370
    ```

    The `NET/IB` line lists 1 InfiniBand device per GPU, so NCCL sends the job's traffic over InfiniBand. Device names and their order vary by node. `OOB` (out-of-band) names the subnet interface that NCCL used to connect the instances.

    On 2 landsend nodes, the run takes about 40 seconds.

    If the job exits or hangs with no output, run the command again without the final `grep` to see the full log.
  </Step>

  <Step title="Generate text from the model">
    `training-0` saves the checkpoint to `out-shakespeare-char/`. Generate 300 characters from it on `training-0`.

    ```bash theme={null}
    cd ~/nanoGPT
    ~/venv/bin/python sample.py --out_dir=out-shakespeare-char \
      --num_samples=1 --max_new_tokens=300
    ```

    ```text theme={null}
    GLOUCESTER:
    And will it there by the execution of your swell:
    There is the mark of your grieves hew you love.
    ```
  </Step>
</Steps>

## Clean up

Terminate the instances when the job ends, then delete the partition and the subnet. Run these commands on your machine, not on an instance.

```bash theme={null}
for i in 0 1; do sf instances terminate "training-$i" --yes; done
```

Delete the partition once `sf infiniband-partitions instances training` no longer lists the instances.

```bash theme={null}
sf infiniband-partitions delete training --yes
```

Deletion fails while an instance is still attached. See [Delete a partition](/preview/networking/infiniband-partitions#delete-a-partition) for the cases that block it.

Then delete the subnet. The `sf` CLI can't delete subnets, so open **Networks** in the console and delete `training`.

To use the API instead, create an [API token](/preview/using-the-api#create-an-api-token). [Grant it a role](/preview/using-the-api#grant-permissions) that can delete subnets, such as `admin`. Then send a `DELETE` request with the subnet ID:

```bash theme={null}
curl -X DELETE https://api.sfcompute.com/preview/v2/subnets/snet_1234567890123 \
  -H "Authorization: Bearer your_api_token_here"
```

If the delete fails because an instance is still attached, wait a minute for its host to finish teardown and retry.

SF Compute reserves instance names for about 5 minutes after termination. To rerun the guide sooner, use different instance names.

The `training` pool stays after cleanup, so skip `sf pools create` on a rerun.

Terminating an instance doesn't free its allocation. You paid for the 4 hours when the order filled, and the pool keeps the 2 nodes until they end.

To get credits back for allocation you don't use, place a [sell order](/preview/orders#sell-orders) on the pool. This example offers the 2 nodes for the next 2 hours at \$10.00 per node-hour or more:

```bash theme={null}
sf orders create --side sell --pool training --sku sku_4EzdPrHcTps \
  --count 2 --start now --duration 2h --min-rate 10.00 --allow-standing
```

## Next steps

Use these pages to manage the job's resources:

* [InfiniBand partitions](/preview/networking/infiniband-partitions): fabrics, partitions, and link checks
* [Subnets](/preview/networking/subnets): private networks and addresses
* [Instances](/preview/instances): instance states, priority, and termination
* [Object storage](/preview/object-storage): bring datasets to SFC and save training checkpoints
* [Pools](/preview/pools): the allocation for the nodes in your job


# Sell unused compute time
Source: https://docs.sfcompute.com/preview/guides/reselling

Choose time to sell, place an order, and check your credits after fees

Sell unused compute time through the SF Compute [orderbook](/preview/orderbook), where buyers and sellers place orders. Use this guide to choose time to sell and check the credits you receive. You receive credits only when a buyer buys the time.

## Before you sell

You need compute time that you own and access to the `sf` command-line interface (CLI). Follow the [quickstart](/preview/quick-start) to install the CLI and sign in.

Your [pool](/preview/pools) records the compute time that you own, called allocation. Each [stock keeping unit (SKU)](/preview/instance-skus) identifies a hardware configuration. Choose the pool and SKU whose time you want to sell.

The examples use the pool name `production-inference`. Replace it with your pool name, and replace `your_sku_id` with your SKU. Set the times and rates for your sale; the prices below are examples, not live quotes.

## How reselling works

Place a sell order for time that your work does not need. When a buyer purchases that time, the order fills and SF Compute removes the sold allocation from your pool.

<Steps>
  <Step title="Choose unused time">
    Keep enough allocation for planned work before you offer time for sale. Include these needs:

    * Jobs that are running
    * Jobs that are waiting to start
    * Spare nodes for new work

    Check the time held by other sell orders in your pool. A running [instance](/preview/instances) is a virtual machine that uses this time. Block new jobs on instances you plan to terminate, then check those instances for running jobs.
  </Step>

  <Step title="Check the market price">
    Check the [best bid and ask](/preview/orderbook#quote) for the SKU and exact period you want to sell. A bid is the price a buyer offers; an ask is the price a seller requests.

    Use [market depth](/preview/orderbook#depth) to check the number of nodes at each price. Set `--min-rate` to the lowest price you will accept, in dollars per node-hour.
  </Step>

  <Step title="Place the sell order">
    This example assumes you own 5 nodes for 14 days, with 2 extra nodes from day 3 to day 8. You need only 2 nodes during a 3-day holiday that starts on day 8.

    Offer 3 nodes for that holiday:

    ```bash {2,5} theme={null}
    sf orders create \
      --side sell --pool "production-inference" --count 3 \
      --start "in 8d" --duration 3d \
      --min-rate 10.00 --sku your_sku_id \
      --allow-standing
    ```

    Use `--allow-standing` to keep the order open while it waits for a buyer. The order stays open until it fills, you cancel it, or the offered time ends. Save the order identifier (ID) to check or cancel the order later.
  </Step>
</Steps>

The chart shows the purchases that supply this example, followed by the sale. Each rectangle represents 1 node for 1 day; the shaded area shows the time you own. Select a step, then move the pointer over the chart to see the node count.

<CapacityChart title="production-inference" />

### How your pool tracks allocation

Your pool keeps one schedule for each SKU. This schedule adds time you buy and subtracts time you sell. Sell from that schedule, not from a single purchase.

You can sell any part of the time you own, including a period in the middle. Only the time a buyer purchases leaves your pool. The same rules apply to time bought through a [spot deployment](/preview/spot-deployments) or a firm reservation.

### How a sell order fills

By default, a sell order can fill partially. Buyers can purchase smaller parts of the offered nodes
or time, and the fills can cover separate periods with gaps between them. Pass
`--allow-partial=false` to require the order to fill completely — all offered nodes for the whole
window — or not at all. A complete fill can still consist of multiple fills from different buyers.

Fills use whole minutes, with a minimum of 1 node for 1 minute. You cannot set a larger minimum fill size. Use the order fields `fills` and `filled_allocation_schedule_delta` to check the exact nodes and time that sold.

### What happens to your instances when you sell

Each running instance needs enough compute time in its pool. If a sale leaves too little time, SF Compute terminates instances in this order:

1. Instances with the lowest [priority](/preview/instances#instance-priority)
2. The newest instances among those with the same priority

<Warning>
  Terminate unneeded instances before the sold time starts. Keep the rest.
</Warning>

Replace `your_instance_id` with the ID of an instance you want to terminate:

```bash theme={null}
sf instances terminate your_instance_id
```

The holiday sale leaves 2 nodes for 3 days, so SF Compute terminates the other 3 instances. Each bar below shows an instance; move the pointer over a bar to see its state.

<CapacityChart title="production-inference" />

## Choose time to sell

Sell a period when your jobs do not need the compute. Low use of graphics processing units (GPUs) alone does not mean the time is spare. An instance can still contain data or be necessary for a later job.

### Sell the end of a reservation

Sell the last hours of a reservation when work ends early. Here, you own 1 node for 12 hours but need only the first 8 hours.

Sell the last 4 hours:

```bash {3} theme={null}
sf orders create \
  --side sell --pool "production-inference" --count 1 \
  --start "in 8h" --duration 4h \
  --min-rate 8.00 --sku your_sku_id \
  --allow-standing
```

At \$8 per node-hour, this sale returns \$32 before fees. For a node with 8 GPUs, that rate equals \$1 per GPU-hour.

### Sell a gap between jobs

Offer a gap when work can stop and continue later. This example keeps the first 2 hours and last 4 hours of the same 12-hour reservation.

Choose this example or the one above. Both together leave only the first 2 hours; the first sale removes the last 4 hours you need here.

Sell the 6-hour gap:

```bash {3} theme={null}
sf orders create \
  --side sell --pool "production-inference" --count 1 \
  --start "in 2h" --duration 6h \
  --min-rate 8.00 --sku your_sku_id \
  --allow-standing
```

Save your work before the sold time starts. Leave time to terminate instances before the gap, then create new ones to resume work after it. Terminated instances do not restart when your compute time returns.

If you must move work to other nodes, compare the costs first. To reduce your costs, the sale value must cover these costs:

* Platform fees
* Replacement compute
* Moving the work

## How to make a sell order fill

Price and order size affect your chance of finding a buyer. Consider these options:

* Set `--min-rate` below current prices for the same SKU and period.
* Offer small amounts, such as 1 node for 1 hour, which can be easier to match.
* Keep partial fills enabled, which is the default, so buyers can take smaller parts of the offered nodes or time.
* Offer time early to give buyers more time to find your order.
* Keep an order open if some of its time has passed; a buyer can still purchase the remaining time.
* Use several sell orders for a pool when you need different prices or periods.

An order in the `standing` state waits for a buyer, and you still own the time. You might not find a buyer before the offered time ends.

### Reprice or cancel a listing

You can lower your price as the start time gets near. Do not go below the lowest price you will accept. Cancel the open order and check its fills before you place a new one.

<Steps>
  <Step title="Request cancellation">
    Replace `your_order_id` with your sell order ID. Run this command to ask SF Compute to cancel the order:

    ```bash theme={null}
    sf orders cancel your_order_id
    ```
  </Step>

  <Step title="Wait for the final result">
    Read the order fields as JavaScript Object Notation (JSON). Use the same order ID, and repeat until the state is `cancelled` or `filled`:

    ```bash theme={null}
    sf orders get your_order_id --json
    ```

    A buyer can purchase time while cancellation is in progress, and that time stays sold. Check `fills` and `filled_allocation_schedule_delta` before you sell or use the time again.
  </Step>

  <Step title="Use only the remaining time">
    Subtract all fills from the time you first offered. If 2 hours of a 6-hour sale fill before the order stops, only 4 hours become free again.

    Keep that time reserved until the order reaches its final state. See [Cancel an order](/preview/orders#cancel-an-order) for more details.
  </Step>
</Steps>

For sales through the application programming interface (API), save each request and its idempotency key first. This key identifies the request, so reuse it and the request body when you retry. Check orders and fills before each new sale to avoid selling the same time twice.

## Calculate your resale credits

Subtract the platform fee from the sale value to find the credits you receive. The sale value depends on the fill price and the number of node-hours sold.

### How the fill price is set

The order that reaches the orderbook first sets the fill price. Your `--min-rate` remains the minimum price you will accept:

| Order on the orderbook first | Fill price |
| - | - |
| Your sell order | Your sell price |
| The buy order | The buy price, which must equal or exceed your `--min-rate` |

### Platform fee

SF Compute subtracts a platform fee when your sale fills. The fee has two parts:

| Fee part | Calculation |
| - | - |
| Fixed amount | Fee per node-hour × node-hours sold |
| Percentage | Fee percentage × sale value |

The 3-node, 3-day holiday sale contains 216 node-hours: 3 × 3 × 24. Its fee includes the fixed amount for those node-hours plus the percentage of the sale value.

SF Compute sets both fee parts, and your fees can change. Fees can also differ between organizations. Check the fee estimate in the CLI before you confirm an order. The fee cannot exceed the sale value, so a sale cannot reduce your credit balance.

The buyer pays the fill price, and the `fills` array shows prices before fees. SF Compute subtracts the fee from your sale value and adds the remaining amount to your credits.

### Track your realized price

Your realized price is the cost per purchased GPU-hour after resale. Use the credits you receive after fees:

| Measure | Calculation |
| - | - |
| Net compute cost | Purchase cost − resale credits after fees |
| Realized price per purchased GPU-hour | Net compute cost ÷ purchased GPU-hours |
| Realized discount | Resale credits after fees ÷ purchase cost × 100% |

For example, a \$100,000 purchase with \$25,000 in resale credits gives these results. The original rate is \$4.50 per GPU-hour:

| Measure | Result |
| - | - |
| Net compute cost | \$75,000 |
| Realized discount | 25% |
| Realized price per purchased GPU-hour | \$3.375 |

This calculation uses all purchased GPU-hours. The cost per GPU-hour of completed work also depends on how much of the remaining time you use.

The [September 9, 2026 resale article](https://sfcompute.com/news/realized-discount) reported a 25% average realized discount for customers on the platform. Your results depend on the time you sell, demand, prices, and fees.

## Next steps

Use these guides to manage your compute after a sale:

* [Pools](/preview/pools): allocation schedules
* [Orders](/preview/orders): order states and fees
* [Instances](/preview/instances): creating and terminating instances


# Images
Source: https://docs.sfcompute.com/preview/images

Build, upload, and manage custom images

An image is the bootable disk template your instance runs from. Boot from an SF Compute base image
with common configurations, or upload your own custom image.

Every image has an `id` like `image_2KvMb9NpQs5` and a human-readable `name` like
`ubuntu-22.04-cuda-12.4` or `training-base`. Each image also has `is_public`, which is `true` for SF
Compute base images and `false` for images you upload.

A name identifies a sequence of immutable versions, starting at 1. The `id` always refers to one
exact build, and the bits behind an id never change. Uploading an existing name creates the next
version.

<Warning>
  Image versions, version pinning, and the deprecated lifecycle state are in
  [public preview](/preview/roadmap#feature-states) and live on the `/preview/v2` API only. The `/v2`
  image endpoints return no `version` or `deprecated_at` field, do not accept `all_versions`, and
  reject the `name@<version>` pin form. `sf` calls the preview endpoints, so every CLI example on
  this page works as written.
</Warning>

## Listing images

List all images available to you, including SF Compute's public images.

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

```text theme={null}
----------------------------------------------------------------------------------------
NAME                                               VISIBILITY  STATUS     CREATED
ubuntu-jammy-custom                                private     completed  Mar 27, 2:00pm
sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2  public      completed  Feb 23, 6:50pm
```

The CLI lists images outside the active workspace, including SF Compute's public images, by their
full resource path.

By default the list shows one entry per name: the latest active version. Pass `--all-versions` to
see every version with its lifecycle state, including a `VERSION` column.

## Using an image

Pass an image name, ID, or resource path when creating an instance.

```bash theme={null}
sf instances create --pool dev --image ubuntu-jammy-custom
```

If you omit `--image`, the CLI presents an interactive picker showing all completed images available
to you.

Referencing an image by name resolves to the latest active version at creation time, so new
instances automatically pick up updated builds. To pin one exact build, reference it by id, or
append `@<version>` to the name.

```bash theme={null}
sf instances create --pool dev --image ubuntu-jammy-custom@2
sf instances create --pool dev --image image_abc123
```

Both pin forms mean the same thing: exactly this build, even after newer versions appear. Both may
launch a version that has since been deprecated, while revoked versions never launch. Ids don't
take the suffix, since an id already names one exact build. `sf images get ubuntu-jammy-custom@2`
inspects a pinned version.

The instance stores the concrete image id it booted from either way, so `sf instances get` always
tells you exactly which build an instance is running.

[Instance templates](/preview/instance-templates) resolve the name once, when the template is
created, so every instance a [deployment](/preview/deployments) launches from a template boots the
same build.

## Uploading an image

Upload a raw disk image with `sf images upload`. The CLI uploads the image in parts, reports
progress as it goes, and verifies integrity with a SHA256 checksum. The maximum image size is 75
GiB. Custom images stay in your workspace.

```bash theme={null}
sf images upload \
  --name ubuntu-jammy-custom \
  --file output/ubuntu_jammy.raw
```

If you omit `--file` or `--name`, the CLI prompts you interactively.

Uploading a file under an existing name never overwrites anything. It creates the next version, and
the name starts resolving to it once the upload completes.

For large images, tune the number of parallel part uploads with `--concurrency`. The default is your
machine's CPU count.

```bash theme={null}
sf images upload \
  --name ubuntu-jammy-custom \
  --file output/ubuntu_jammy.raw \
  --concurrency 4
```

## Image requirements

SF Compute supports UEFI amd64 (x86\_64) raw images. We do not support qcow2.

Custom images should resize themselves at boot to fill the disk available to the instance. For an
example of building a compatible image with Packer, see our
[example GitHub repository](https://github.com/sfcompute/packer_example/).

Custom images must have drivers for both
<Tooltip>virtio-net</Tooltip> and
<Tooltip>mlx5Gen Virtual Function</Tooltip> for networking.
They must also have cloud-init installed with its network configuration step enabled so networking
comes up at boot.

## Image lifecycle

An upload moves through `started` → `uploading` → `completed` (or `failed`). Only completed images
can back instances.

Completed images additionally carry a catalog state.

An active image is the default state: listed, resolvable by name, and launchable. A deprecated
image is no longer the active version and will eventually be removed. It stops resolving by bare
name and leaves the default listing, but an explicit pin (image id or `name@<version>`) can still
launch it, and instances already running on it are unaffected. `sf images list --all-versions`
shows deprecated versions with status `deprecated`. A revoked image can no longer back new
instances, by name or by id, though instances already running on it are unaffected.

## Revoking an image

Revoke an image to stop new instances from using it. Existing instances keep running.

```bash theme={null}
sf images revoke ubuntu-jammy-custom
```

The command prompts for confirmation. Pass `--yes` to skip it.

Reinstate a revoked image to make it usable again.

```bash theme={null}
sf images reinstate ubuntu-jammy-custom
```

## Deleting an image

Delete an image to remove it permanently. Unlike a revoked image, a deleted image cannot be
reinstated. You cannot delete an image while an active instance uses it.

```bash theme={null}
sf images delete ubuntu-jammy-custom
```

The command prompts for confirmation. Pass `--yes` to skip it.

## SFC base images

SF Compute publishes base images named `ubuntu-<lts>-cuda-<major.minor>`, for example
`ubuntu-24.04-cuda-13.2`. The matrix covers Ubuntu 22.04 and 24.04 crossed with the two newest CUDA
minor versions, plus a back-catalog of older CUDA versions. A few older names carry the Ubuntu point
release, like `ubuntu-22.04.5-cuda-12.7`. `sf images list` shows every current name.

Each base image ships the NVIDIA server driver pinned to that CUDA version's compatibility floor,
the CUDA development libraries, and cloud-init.

Each name tracks its latest build. When NVIDIA ships a new CUDA patch release, or a driver or OS
point release lands, SF Compute republishes the same names, and each republish appears as a new
version. Instances created by name pick up the latest version automatically, while running
instances keep the exact image they booted from. If your workload needs one exact build, pin it by
image id or by version, like `ubuntu-24.04-cuda-13.2@3`.

Older versions of a base image are deprecated once superseded. A deprecated version leaves name
resolution and the default listing but still launches by pinned id or `name@<version>`. Versions
deprecated for a long time are eventually revoked, which blocks new launches without touching
running instances. Base image versions are never deleted.

## API reference

See the [Images API](/api-reference/images/list-images) for programmatic access.


# SKUs
Source: https://docs.sfcompute.com/preview/instance-skus

Pick the hardware your orders run on

A SKU (stock keeping unit) is a unique combination of [instance](/preview/instances) properties such
as `accelerator` and `rdma_type`.

Each SKU has a stable `id` and a human-readable `alias` that SF Compute assigns at registration.
Both the API and the CLI identify a SKU by its `sku_...` id.

A SKU is the boundary of fungibility. Two instances with the same SKU run on the same hardware and
are interchangeable. The market prices and allocates them as one supply, and you cannot pin a
specific machine within a SKU. Hardware differences that matter, such as the accelerator, the remote
direct memory access (RDMA) network, the zone, and the machine shape, place nodes in different SKUs.

Each SKU has its own [orderbook](/preview/orderbook) and its own allocation. An
[order](/preview/orders) fills only against orders on the same SKU. A [pool](/preview/pools) records
its allocation as a node-count schedule per SKU.

A SKU identifies hardware, not how you buy it, so spot and non-spot orders for the same hardware
share one SKU. Some guarantees depend on staying on the same hardware, such as buying more capacity
and keeping your instances running. These hold within one SKU, not across SKUs. An instance pins to
its SKU at create time and never moves to another.

## SKU properties

Every SKU has an `id` and an `alias`. Its other properties, such as `region`, `accelerator`, and
`memory_bytes`, describe the hardware, and the API omits any that are unset. For the full list, read
the [SKU API reference](https://docs.sfcompute.com/api-reference/skus/get-sku#response-id).

In the API, each property other than `id` and `alias` is an object with a machine-readable `value`
and a human-readable `display_value`, which the console and `sf` show. For example, a SKU with 2,016
GiB of memory returns:

```json theme={null}
"memory_bytes": { "value": 2164663517184, "display_value": "2,016 GiB" }
```

## List SKUs

List the registered SKUs and their ids.

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

```text theme={null}
  NAME         ACCELERATOR           MEMORY     STORAGE  VCPUS  ID
  sea-3-h100   8 x H100 80GB HBM3    2,016 GiB  1.5 TiB  56     sku_4UpxzQw7A8N
  iad-12-h200  8 x H200 141GB HBM3e  2,016 GiB  1.5 TiB  56     sku_NWhD6SrbjcXstGRvgl0eC
```

Add `--verbose` to include the region, zone, form factor, RDMA type, and public IPv4 columns.

## Get details for one SKU

Get the full property set for a single SKU.

```bash theme={null}
sf skus get sku_4UpxzQw7A8N
```

## Use a SKU

[Orders](/preview/orders), [pool transfers](/preview/pools), [deployments](/preview/deployments),
[procurements](/preview/procurements), and [instances](/preview/instances) each pin to a single SKU.
Pass its id with `--sku`.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h \
  --max-rate 20.00 \
  --sku sku_4UpxzQw7A8N
```

## Pick a SKU interactively

On commands that pin a SKU (for example, `sf orders create`), omit `--sku`. You then pick
from a list of registered SKUs and their properties.

## API reference

See the [SKUs API](/api-reference/skus/list-skus) for programmatic access.


# Instance templates
Source: https://docs.sfcompute.com/preview/instance-templates

Reusable instance configurations for deployments

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

An instance template defines the configuration for an [instance](/preview/instances): which
[image](/preview/images) to boot and an optional [cloud-init](https://cloudinit.readthedocs.io/)
script. [Deployments](/preview/deployments) use templates to create instances with a consistent
configuration.

Templates are immutable. To change a configuration, create a new template and update your deployment
to reference it. See [deployments](/preview/deployments#instance-templates) for how a deployment
picks up the change.

## Create an instance template

Create a template with a name and an image. Public images require the full
`sfc:image:sfcompute:public:...` name; SF Compute rejects the short trailing segment on its own.

```bash theme={null}
sf instance-templates create \
  --name prod-worker \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2
```

A template captures one exact image build. SF Compute resolves the image name when you create the
template and stores that build's id, so later [versions](/preview/images#using-an-image) of the same
name never reach an existing template. Pass an image id to name the build explicitly; templates take
a name or an id, not the `name@<version>` pin form.

## Cloud-init

Pass a startup script or cloud-config YAML file via `--cloud-init`. The template stores the file and
applies it to every instance you create from it. Maximum size is 64 KB.

Cloud-init data isn't parameterized per instance: every instance created from the template receives
the same bytes. For per-instance identity, use a deployment's
[instance name template](/preview/deployments#instance-name-templates). For example, this startup
script installs an SSH key.

```bash startup.sh theme={null}
#!/bin/bash

mkdir -p /root/.ssh
cat >>/root/.ssh/authorized_keys <<"EOF"
ssh-ed25519 AAAA... you@example.com
EOF
```

Create a template that uses the script.

```bash theme={null}
sf instance-templates create --name ssh-ready \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 --cloud-init ./startup.sh
```

## List templates

List the templates in your workspace.

```bash theme={null}
sf instance-templates list
```

```text theme={null}
----------------------------------------------------------------
NAME          IMAGE                   CLOUD-INIT  CREATED
prod-ubuntu   ubuntu-24.04-cuda-13.2  yes         Mar 23, 4:40pm
dev-debian    debian-12-cuda-12.7     -           Mar 26, 2:00pm
staging-base  ubuntu-24.04-cuda-13.2  yes         Mar 27, 2:00pm
```

## Get template details

Get a template by name or ID.

```bash theme={null}
sf instance-templates get prod-ubuntu
```

```text theme={null}
| ID             itmpl_Gw5rT8mKn2Pj4Lx9Qf7Y
| NAME           prod-ubuntu
| RESOURCE PATH  sfc:instance_template:acme:default:prod-ubuntu
| IMAGE          ubuntu-24.04-cuda-13.2 (image_Qb7dRk2mNp4Ls9Xf1Zt0)
| CLOUD-INIT     yes
| CREATED        Mar 23, 4:40pm PDT
```

<Note>
  Template IDs use the `itmpl_` prefix. You can still pass older IDs with the legacy `ntmpl_` prefix.
</Note>

## Delete a template

Delete a template by name or ID.

```bash theme={null}
sf instance-templates delete prod-ubuntu
```

You can't delete a template while a [deployment](/preview/deployments) or running instance uses it.
Update or delete the deployment, or terminate the instance, first.

## API reference

See the [Instance Templates API](/api-reference/instance-templates/list-instance-templates)
for programmatic access.


# Instances
Source: https://docs.sfcompute.com/preview/instances

Create, connect to, and manage GPU compute instances

An instance is a GPU-backed virtual machine. You create an instance, attach it to a
[pool](/preview/pools), 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](/preview/orders)) before starting.

## Create an instance

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

```bash theme={null}
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.

```bash theme={null}
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:

1. **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](/preview/orders)
   on the pool.
2. **The allocation starts in the future.** If the schedule's first segment starts later than now,
   the instance waits until then.
3. **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](/preview/pools#mixed-hardware).
4. **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.
5. **The buy order hasn't filled yet.** Orders add to the schedule only once they fill. Check the
   [order status](/preview/orders#order-statuses).

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](mailto: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](/preview/networking/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](/preview/spot-deployments) 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](#delete-an-instance) 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](/preview/spot-deployments#preemption). For everything else, build in a margin before
your pool's allocation ends instead of waiting for a signal. See
[Allocation schedule](/preview/pools#allocation-schedule).

## Images

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

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

```text theme={null}
----------------------------------------------------------------------------------------
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.

```bash theme={null}
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](/preview/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.

```bash theme={null}
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.

```yaml startup.yaml theme={null}
#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.

```bash theme={null}
sf instances create --pool dev --cloud-init ./startup.yaml
```

## Check instance status

List your instances and their statuses.

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

```text theme={null}
----------------------------------------------------------
NAME        STATUS   POOL  INSTANCE SKU     CREATED
gpu-worker  running  dev   sku_8FxR3pTzN6L  Mar 19, 4:40pm
```

Filter by time range.

```bash theme={null}
# 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.

```bash theme={null}
sf instances get gpu-worker
```

## SSH into an instance

Connect to a running instance over SSH.

```bash theme={null}
sf instances ssh gpu-worker
```

<Note>
  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.
</Note>

<Warning>
  `Permission denied (publickey)` means the instance has no matching key: either its cloud-init never
  added one (see [Cloud-init](#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>`.
</Warning>

## View logs

View an instance's logs.

```bash theme={null}
sf instances logs gpu-worker
```

Show more lines.

```bash theme={null}
sf instances logs gpu-worker --limit 500
```

Filter by time range.

```bash theme={null}
# 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.

```bash theme={null}
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).

```bash theme={null}
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.

<Note>
  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.
</Note>

Replace with a specific name.

```bash theme={null}
sf instances replace gpu-worker --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 --cloud-init ./new-startup.sh --name worker-2
```

<Warning>
  Instances have no persistent storage. Replacing an instance deletes all data on the original.
</Warning>

## Delete an instance

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

```bash theme={null}
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.

```bash theme={null}
sf instances set gpu-worker --priority critical
```

Set priority at create time.

```bash theme={null}
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.

```http theme={null}
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}`.

```http theme={null}
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.

```http theme={null}
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, the instance's disk is lost with it.
* Public IPv4 is available only on SKUs that support it, and only when enabled at create
  time. See [IP addresses](/preview/networking/ip-addresses).
* InfiniBand is in preview. See [InfiniBand partitions](/preview/networking/infiniband-partitions).
* 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](mailto:support@sfcompute.com).

## API reference

See the [Instances API](/api-reference/instances/list-instances) for programmatic access.


# Limits
Source: https://docs.sfcompute.com/preview/limits

Read the compute caps, resource limits, and credit line on your account, and your usage against them

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

A limit caps how much compute time your account can hold at once, how many of a resource it can hold, or how large a credit line it has. This page covers the limits `sf limits` shows, the units they use, and how to request a higher one.

```bash theme={null}
sf limits
```

```text theme={null}
NAME                                    LIMIT      USED  SCOPE
compute_max_total_node_hours            5760       1200  account
compute_max_total_node_hours            720        720   sku_4UpxzQw7A8N
compute_node_hours_free_window_seconds  3600       —     account
max_instances                           64         12    account
credits_max_credit                      unlimited  —     account
```

Each row is one limit in effect on your account:

* **NAME**: the limit’s identifier, covered in the sections below
* **LIMIT**: the cap, or `unlimited` when your account has no cap for that name
* **USED**: your usage against the cap, printed as `—` when there is no figure to report, and in red once it reaches the cap
* **SCOPE**: what the cap covers, either your whole account or the `sku_…` ID of one [SKU](/preview/instance-skus)

A limit with no row is unset, and an unset limit refuses nothing.

A compute limit counts the node-hours you hold plus the unfilled node-hours of your open buy orders. Some open sell orders subtract from that total, as described in [Compute limits](#compute-limits).

SF Compute refuses a buy order that would put you over the cap. An [interruptible buy order](/preview/orders#interruptible-buy-orders) with an interrupt rate below the [offset price ceiling](#compute-limits) is the exception. A compute limit never refuses a sell order, because a sell can't raise your usage. You can't cancel a sell order that lowered your usage if cancelling it would put you over the cap.

## Compute limits

`compute_max_total_node_hours` caps that total in node-hours across all pools, so a resting buy order counts against the cap before it fills. A node-hour is one node held for one hour, so the cap measures the area under the combined schedule. Buying further ahead spends it the same way a wider order does.

<CapacityChart title="node-hours held" />

Placing a [standing sell order](/preview/orders#sell-orders) offsets your usage for this limit, but only if it allows partial fills (`--allow-partial`) and its price is below the offset price ceiling. SF Compute sets this ceiling and can change it. See the current one in the `COMPUTE LIMIT OFFSET PRICE CEILING` row of `sf platform-constants`.

The offset lasts only while the sell order stands. For example, with a cap of 200 node-hours:

* You reserve 200 node-hours. You are at the cap and cannot buy more.
* You place a standing sell order for 100 node-hours, allowing partial fills and priced below the ceiling. You can now reserve another 100 node-hours.
* You can repeat this as many times as you like, as long as you keep placing sell orders.
* You cannot cancel those sell orders while doing so would put you back over the cap.

An [interruptible buy order](/preview/orders#interruptible-buy-orders) gets the same offset. SF Compute lists the compute the order buys as standing sell orders at the order's interrupt rate. When that rate is below the ceiling, the order stays out of your usage.

`compute_node_hours_free_window_seconds` sets how far ahead the cap starts counting, in seconds from now. An order that fits entirely inside the free window never counts. An order that starts inside the window counts from the edge of the window onward.

## Account-wide and per-SKU limits

A limit’s scope decides which part of your allocation it meters. A limit scoped to your account meters every pool you hold. A limit scoped to one SKU meters your allocation on that SKU alone. Both apply together rather than replacing each other, so an order for that SKU has to fit inside both. Resource limits are always account-wide.

## Resource limits

A resource limit caps how many of one kind of resource your account holds at once. **USED** is how many you hold now. SF Compute refuses a request that would create one more than the limit allows; delete one to make room.

| Name | Counts |
| - | - |
| `max_instances` | Instances that are not destroyed |
| `max_standing_orders` | Open orders: those on the book, plus any placed but not yet settled. An order placed without `--allow-standing` never rests, so this limit never refuses one. |
| `max_workspaces` | Workspaces, including your default workspace |
| `max_pools` | Pools |
| `max_images` | Images that are not deleted, including uploads still in progress and revoked images |
| `max_tokens` | API tokens that are neither deleted nor expired |
| `max_subnets` | Subnets that are not deleted |
| `max_infiniband_partitions` | InfiniBand partitions that are not deleted |

A request retried with the same `Idempotency-Key` as one that already created its order or pool isn't refused, because it creates nothing new.

## Credit line

`credits_max_credit` is the credit line on your account, in dollars. It comes from the same credit line as the overage limit in `sf billing balance`. It reads as `unlimited` for an account with no ceiling.

## Requesting a higher limit

SF Compute sets your limits. Verify your organization in the [SF Compute dashboard](https://sfcompute.com/dashboard/settings), then [contact us](https://sfcompute.com/contact) with the limit you need.


# Firewalls
Source: https://docs.sfcompute.com/preview/networking/firewalls

Control inbound traffic to an instance with ingress rules

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

A firewall is a set of rules controlling inbound traffic to an [instance](/preview/instances).
Firewalls are scoped to a [workspace](/preview/workspaces).

## Default firewall

Every workspace has a built-in `default` firewall with 2 ingress rules.

* Allow SSH (TCP port 22) from anywhere
* Allow ICMP (ping) from anywhere

SF Compute manages the `default` firewall. You cannot modify or delete it. Password authentication
is disabled on all SF Compute base images, so open SSH is safe by default. Only key holders can
connect.

## How firewalls apply

Firewall rules control traffic between instances and the public internet. Instances in the same
subnet communicate freely on all ports. Instances in different subnets are isolated and cannot
communicate.

Firewalls only apply to instances with a [public IP](/preview/networking/ip-addresses) (created with
`--public-ipv4`) and cannot be attached to an instance without one. The API requires the `firewall`
field whenever `enable_public_ipv4` is `true` and rejects the request with 422 when it is omitted.

The CLI fills it in for you. If you run `sf instances create --public-ipv4` interactively without
`--firewall`, it prompts you to pick a firewall. Otherwise, it uses the workspace's `default`
firewall.

## Creating a firewall

Create a firewall from a TOML file that defines the rules.

```bash theme={null}
sf firewalls create --name web --file firewall.toml
```

### Rule format

Each rule specifies a direction, protocol, port (or port range), and source CIDR (Classless
Inter-Domain Routing). The API accepts only `ingress` rules and rejects `egress`, which is reserved
for future use. Firewalls do not filter outbound traffic. The protocol is `tcp`, `udp`, or `icmp`;
ICMP rules take no port.

```toml theme={null}
[[rules]]
direction = "ingress"
protocol = "tcp"
port = "22"
source = "0.0.0.0/0"

[[rules]]
direction = "ingress"
protocol = "tcp"
port = "8080"
source = "0.0.0.0/0"
```

This creates a firewall that allows SSH and port 8080 from anywhere.

Source CIDRs must be publicly routable. The API rejects private, reserved, and other non-public
ranges (for example `10.0.0.0/8`, `192.168.0.0/16`). The wildcard `0.0.0.0/0` (allow from anywhere)
is the only exception.

### Restricting access

Restrict SSH to a specific network.

```toml theme={null}
[[rules]]
direction = "ingress"
protocol = "tcp"
port = "22"
source = "8.8.8.0/24"

[[rules]]
direction = "ingress"
protocol = "tcp"
port = "8080"
source = "0.0.0.0/0"
```

### Port ranges

Allow a range of ports.

```toml theme={null}
[[rules]]
direction = "ingress"
protocol = "tcp"
port = "22"
source = "0.0.0.0/0"

[[rules]]
direction = "ingress"
protocol = "tcp"
port = "8000-8999"
source = "0.0.0.0/0"
```

### Create via the API

To create a firewall via the API, send a `POST` request to `/preview/v2/firewalls`.

```json theme={null}
{
  "workspace": "sfc:workspace:acme:production",
  "name": "web",
  "rules": [
    { "direction": "ingress", "protocol": "tcp", "port": "22", "source": "0.0.0.0/0" },
    { "direction": "ingress", "protocol": "tcp", "port": "8080", "source": "0.0.0.0/0" }
  ]
}
```

## Attaching a firewall to an instance

Specify the firewall when creating an instance.

```bash theme={null}
sf instances create \
  --name worker-1 \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 \
  --cloud-init ./startup.sh \
  --public-ipv4 \
  --firewall web
```

## Replacing the firewall on an instance

Replace the attached firewall on an existing instance. The instance must have been created with
`--public-ipv4`. The new rules take effect without a reboot.

```bash theme={null}
sf instances set worker-1 --firewall restricted
```

You can replace the firewall but not detach it.

## Listing firewalls

List the firewalls in the active workspace.

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

```text theme={null}
NAME         RULES
default      2
web          2
restricted   2
```

## Getting firewall details

Fetch a firewall by name.

```bash theme={null}
sf firewalls get web
```

Add `--toml` to output the rule set as TOML, which round-trips with `sf firewalls set`.

```bash theme={null}
sf firewalls get web --toml > firewall.toml
```

## Updating a firewall

Replace a firewall's rule set from a TOML file. The replacement is atomic.

```bash theme={null}
sf firewalls set web --file firewall.toml
```

### Update via the API

`PUT /preview/v2/firewalls/{id}` replaces the full rule set.

```json theme={null}
{
  "rules": [
    { "direction": "ingress", "protocol": "tcp", "port": "22", "source": "0.0.0.0/0" }
  ]
}
```

## Deleting a firewall

Delete a firewall by name.

```bash theme={null}
sf firewalls delete web
```

Deleting a firewall fails if any instances still reference it.

## Limits

Firewalls enforce the following limits.

* 100 rules per firewall
* 100 firewalls per workspace, including the built-in `default`

## API reference

See the [Firewalls API](/api-reference/firewalls/list-firewalls) for programmatic access.


# InfiniBand partitions
Source: https://docs.sfcompute.com/preview/networking/infiniband-partitions

Connect instances over an isolated InfiniBand network for distributed training

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

InfiniBand is a high-bandwidth, low-latency network that lets GPUs on different instances exchange
data during multi-node training. It uses RDMA (remote direct memory access). With RDMA, one machine
reads and writes another machine's memory directly, including GPU memory, without involving either
operating system.

An InfiniBand partition is an isolated network for RDMA traffic between your instances. Instances in
the same partition can reach each other over InfiniBand. An instance created without a partition has
no InfiniBand connectivity, even when its SKU supports InfiniBand.

A fabric is a physical InfiniBand network in one availability zone, with a name such as
`europe-north1-a.fab2`. Separate fabrics are separate networks and cannot reach each other.

To connect instances over InfiniBand:

1. Create a partition.
2. Attach instances on the same fabric to that partition.

`sf infiniband-partitions` is also available as `sf ib-partitions` and `sf ibp`.

## Enroll in the InfiniBand preview

Enroll your account in the preview before you create a partition. Until you do, the
`sf infiniband-partitions` commands and the `--infiniband-partition` flag are hidden, and the API
returns a `403` error.

```bash theme={null}
sf preview set infiniband-preview=true
```

## Find a SKU that supports InfiniBand

A [SKU](/preview/instance-skus) supports InfiniBand when its RDMA type is `infiniband`. List the
SKUs that support it, with their availability.

```bash theme={null}
sf availability --rdma-type infiniband
```

## Create a partition

Create a partition on the fabric your SKU is on. The partition belongs to the current
[workspace](/preview/workspaces).

```bash theme={null}
sf infiniband-partitions create --name training --fabric europe-north1-a.fab2
```

You can also run `sf infiniband-partitions create` with no flags. It asks for a name, then lists
each fabric with the names of the SKUs on it. Pick the fabric of the SKU you plan to create
instances on.

In a zone with only one fabric, you can pass `--region` and `--zone` instead of `--fabric`.

A partition name must be unique within its workspace, across all fabrics.

## List partitions

List the partitions in the current workspace. Add `--all` to list across every workspace you can
read.

```bash theme={null}
sf infiniband-partitions list
```

```text theme={null}
  NAME      FABRIC                ZONE             CREATED
  training  europe-north1-a.fab2  europe-north1-a  Sep 28, 2:02pm
```

Filter by `--fabric` to see the partitions on one network.

```bash theme={null}
sf infiniband-partitions list --fabric europe-north1-a.fab2
```

## Get details for one partition

Get a partition by its name, its `ibpart_...` ID, or its resource path. A name resolves within the
current workspace.

```bash theme={null}
sf infiniband-partitions get training
```

```bash theme={null}
sf infiniband-partitions get sfc:infiniband_partition:acme:production:training
```

A resource path joins the account, the workspace, and the partition name, as in `acme`,
`production`, and `training` above. Anywhere a command or API field takes a partition, it accepts
the name, the ID, or the resource path.

## Attach an instance to a partition

Attach an instance by passing `--infiniband-partition` when you create it. The partition must be on
the same fabric as the instance's SKU. See [Instances](/preview/instances) for the other creation
flags and the [startup script](/preview/instances#cloud-init).

```bash theme={null}
sf instances create --pool training --sku sku_4UpxzQw7A8N \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 --cloud-init ./startup.sh \
  --infiniband-partition training
```

You can also run `sf instances create` without `--infiniband-partition`. On an InfiniBand SKU, it
lists the partitions on the SKU's fabric, so you can pick one, create one, or choose none.

An instance stays in its partition for its whole life. To move it to another partition, terminate it
and create a new instance.

## List the instances in a partition

List the instances attached to a partition. The output has the same columns as
[`sf instances list`](/preview/instances).

```bash theme={null}
sf infiniband-partitions instances training
```

A terminated instance drops out of this list once its node releases the partition.

## Delete a partition

Delete a partition by its name, ID, or resource path. Terminate every instance in the partition
first, since deletion fails while any instance is still attached.

```bash theme={null}
sf infiniband-partitions delete training
```

Two kinds of instance can block a deletion without showing up in
`sf infiniband-partitions instances`:

* An instance you don't have permission to read
* A terminated instance whose node hasn't released the partition yet

## Check InfiniBand from an instance

The current Ubuntu images with CUDA 13.1 or 13.2, such as `ubuntu-24.04-cuda-13.2`, ship the
InfiniBand stack. See [Images](/preview/images) for the full list. The stack includes:

* **Drivers**: NVIDIA DOCA-OFED, with IP over InfiniBand
* **Tools**: `ibverbs-utils` and `perftest`, for checking a link
* **GPUDirect RDMA**: `nvidia-peermem`, loaded at boot with the InfiniBand modules

An instance booted from one of these images needs no setup inside the guest. Other base images, and
older builds of these images, don't include the stack.

Run `ibv_devinfo` on the instance to confirm it sees an InfiniBand device.

```bash theme={null}
ibv_devinfo
```

A device with `state: PORT_ACTIVE` is connected to the fabric.

## API reference

See the
[InfiniBand Partitions API](/preview/api-reference/infiniband-partitions/list-infiniband-partitions)
for programmatic access.

## Next steps

To train across instances in a partition, follow
[Run a PyTorch job across multiple nodes](/preview/guides/multi-node-training).


# IP Addresses
Source: https://docs.sfcompute.com/preview/networking/ip-addresses

Give an instance a public IPv4 address for internet access

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

Instances can have a public IPv4 address for internet connectivity. You choose whether an instance
has a public IP when you create it; you cannot change it afterward. IPv6 is not yet supported.

## Enabling a public IP

Set `--public-ipv4` when [creating an instance](/preview/instances#create-an-instance) to assign a
public IP address.

```bash theme={null}
sf instances create --public-ipv4
```

SF Compute assigns the public IP automatically and releases it when you delete the instance. No two
instances share an IP.

Not every SKU supports public IPv4. The interactive SKU picker lists only SKUs that do. If
you pass a `--sku` that does not support it, the request fails with a 422 error.

Without `--public-ipv4`, the only inbound port open on the instance is SSH (TCP port 22); nothing
else is reachable from the internet. Connect with `sf instances ssh`.

## Internet connectivity

Instances reach the internet via IPv4 using TCP, UDP, and ICMP. SF Compute blocks all other layer 4
protocols. It also blocks outbound SMTP (TCP and UDP port 25).
[Contact us](https://sfcompute.com/contact) if you need this restriction removed.

[Firewall rules](/preview/networking/firewalls) govern inbound traffic. Source CIDRs must be public
IPv4 addresses. Internet source IPs are
[spoofable](https://en.wikipedia.org/wiki/IP_address_spoofing), so treat firewall rules as
[security hardening](https://en.wikipedia.org/wiki/Hardening_%28computing%29), not your primary
security control.

SF Compute blocks all traffic to an instance's UDP or TCP port 68 to prevent DHCP attacks.

## Finding an instance's IP

Run `sf instances get` with the instance name or ID to see its public IP.

```bash theme={null}
sf instances get worker-1
```

Instances created with `--public-ipv4` show a `PUBLIC IPV4` row, which reads `pending` until SF
Compute assigns the IP. In `--json` output, the `public_ip` field appears once SF Compute assigns
the IP, and only on instances created with `--public-ipv4`.


# Subnets
Source: https://docs.sfcompute.com/preview/networking/subnets

Create private networks so instances in the same zone can reach each other over private IPs.

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

A subnet is a private network in a zone. Instances in the same subnet can reach each other over private IPs; instances in different subnets are isolated. Create a subnet in the console, with the CLI, or through the API. Listing, inspecting, and deleting subnets need the console or the API.

## Create a subnet

Create subnets to allow instances to communicate with each other. A subnet lives in one availability zone, identified by its region and availability zone. Instances attached to the subnet must be in that same zone.

In the console, open **Networks** and select **Create Network**. While launching an instance, you can also select **Create network** under **Network**.

With the CLI, pass the workspace, a name, the region, the availability zone, and a CIDR (Classless Inter-Domain Routing) block.

```bash theme={null}
sf subnets create \
  --workspace production \
  --name training \
  --region europe-north1 \
  --zone a \
  --cidr 10.1.0.0/16
```

The API takes the same fields in a `POST` request to `/preview/v2/subnets`.

```http theme={null}
POST /preview/v2/subnets
{
  "workspace": "sfc:workspace:acme:production",
  "name": "training",
  "region": "europe-north1",
  "availability_zone": "a",
  "cidr": "10.1.0.0/16"
}
```

The `cidr` block must fall within one of the private address ranges, be a `/28` or larger, and have no host bits set (for example, `10.1.0.0/16`).

```text theme={null}
10.0.0.0/8
172.16.0.0/12
192.168.0.0/16
```

SF Compute reserves the first four addresses of every subnet and its broadcast address; these are never assigned to instances. Instance addresses begin at the fifth address: in a `10.1.0.0/24` subnet, the first instance receives `10.1.0.4`. The `/28` minimum leaves room for these reserved addresses. Each subnet supports up to 64 live instances.

## List subnets

List subnets with a `GET` request. Pass `workspace` to scope the list to one [workspace](/preview/workspaces); omit it to list every workspace where you can list subnets.

```http theme={null}
GET /preview/v2/subnets?workspace=sfc:workspace:acme:production
```

## Get subnet details

Fetch a subnet by ID or resource path. Subnet names are unique within a workspace, so the resource path identifies the subnet.

```http theme={null}
GET /preview/v2/subnets/sfc:subnet:acme:production:training
```

## Attach instances to a subnet

Specify the subnet when you create an instance. Pass its ID or resource path in the optional `subnet` field of the create request. See [Instances](/preview/instances) for the other creation fields. You cannot attach, detach, or move a running instance to another subnet.

In the console, choose a pool and SKU, then select the subnet from the **Network** menu. With the CLI, pass `--subnet`.

```bash theme={null}
sf instances create \
  --pool training \
  --sku sku_4UpxzQw7A8N \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 \
  --cloud-init ./startup.sh \
  --subnet training
```

The API takes the subnet as an ID or resource path.

```http theme={null}
POST /preview/v2/instances
{
  "pool": "sfc:pool:acme:production:training",
  "image": "sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2",
  "instance_sku": "sku_4UpxzQw7A8N",
  "subnet": "sfc:subnet:acme:production:training"
}
```

SF Compute assigns the lowest available address in the subnet. To request a specific address, use the console's **Private IP** field, the CLI's `--private-ip` option, or the API's `private_ip` field. An address stays reserved until the instance's host confirms teardown, so a terminated instance can hold its address for a short time after it stops.

## Delete a subnet

Delete a subnet by ID or resource path. Deletion fails while an instance is attached, including after termination is requested but before its host confirms teardown.

```http theme={null}
DELETE /preview/v2/subnets/sfc:subnet:acme:production:training
```

## Networking behavior

Each instance gets a private IP in its subnet's CIDR range. Instances in the same subnet can reach each other on all ports via private IPs using unicast only. Multicast and broadcast packets are unsupported.

Instances in different subnets cannot communicate with each other, even in the same zone. SF Compute blocks IP and MAC (Media Access Control) address spoofing. Each instance can only use its assigned private IP address.

Without a public IP, an instance can reach the internet through source Network Address Translation (NAT) but cannot receive inbound internet traffic. [Firewall rules](/preview/networking/firewalls) apply to traffic through a public IP; they do not filter traffic between instances in the same subnet.

For cross-zone communication, use [public IPs](/preview/networking/ip-addresses). Instances communicate over standard IPv4 only.

## Instances without a subnet

An instance created without a subnet gets its own isolated network. It has no private-IP path to any other instance.


# Object storage
Source: https://docs.sfcompute.com/preview/object-storage

Colocate datasets with your compute and save training checkpoints between runs

Keep datasets and checkpoints in SF Compute (SFC) object storage, close to your compute. Buckets
hold your files, and tools built for S3-compatible object stores, such as rclone and boto3, read
and write to them. Upload data from your laptop or another storage provider, then use it on SFC
[instances](/preview/instances). Uploaded data stays after an instance terminates.

## Create a bucket and access key

Create a bucket for your data and an access key that your tools use to reach it.

Creating buckets and access keys requires your organization to set up billing. Have a team member
with the [admin](/preview/roles#admin-role) or [billing](/preview/roles#billing-role) role complete
the following under [Billing](https://console.sfcompute.com/dashboard/billing) in the console:

* A billing profile
* A primary billing contact
* A card set as the default payment method

<Frame>
  <img alt="Billing page with the Payment Methods, Billing Profile, and Billing Contacts sections, and a card marked Default" />
</Frame>

The examples use the `europe-north1`
[region](https://docs.sfcompute.com/api-reference/skus/get-sku#response-region-one-of-1) and your
active [workspace](/preview/workspaces). Replace `acme-training-data` throughout with your own
bucket name.

<Info>
  Object storage isn't available in every region. The console and CLI list supported regions when you
  create a bucket. If you need storage in a region we don't support yet,
  [contact us](https://sfcompute.com/contact).
</Info>

<Tabs>
  <Tab title="CLI">
    [Install `sf` and log in](/preview/quick-start#install-the-cli), then create a bucket and key in
    the same region.

    ```bash theme={null}
    sf storage buckets create --name acme-training-data --region europe-north1
    sf storage access-key create --name training --region europe-north1
    ```

    Save the returned access key ID and secret in your secrets manager. `sf` shows the secret only
    once.
  </Tab>

  <Tab title="Console">
    <Steps>
      <Step title="Open the create form">
        Open [Storage → Buckets](https://console.sfcompute.com/dashboard/storage?tab=buckets) and
        click **Create Bucket**. Enter a name and region, and choose a workspace if offered.

        <Frame>
          <img alt="Storage page on the Buckets tab, with the Create Bucket button at the top right" />
        </Frame>
      </Step>

      <Step title="Create the bucket">
        If the workspace has no access keys in that region yet, the form shows **Also create an
        access key**. Select it and click **Create Bucket & Key**. If the workspace already has a
        key there, click **Create Bucket** and reuse that key.

        <Frame>
          <img alt="Create bucket form for acme-training-data in europe-north1, with Also create an access key selected" />
        </Frame>
      </Step>

      <Step title="Save the key">
        Save a new key's **Access key ID** and **Secret access key** in your secrets manager. The
        console shows the secret only once. To create another key, open [Access
        keys](https://console.sfcompute.com/dashboard/storage?tab=keys).

        <Frame>
          <img alt="Bucket created dialog showing an example access key ID and secret access key" />
        </Frame>
      </Step>
    </Steps>
  </Tab>
</Tabs>

You may reuse an existing access key if it's in the same workspace and region as the bucket.

<Note>
  An access key can read and write every bucket in its workspace and region. Use separate workspaces
  when you need separate access boundaries.
</Note>

### Set your storage credentials

Set these variables on your laptop and on each instance that uses the bucket. Find the endpoint in
the bucket's **Access bucket** panel or with `sf storage buckets get acme-training-data`.

<Frame>
  <img alt="Access bucket panel showing the rclone snippet with the bucket endpoint" />
</Frame>

`sf storage access-key create --format env` and the console's **Access bucket** snippets print
`AWS_*` names instead. Rename them as shown so they don't override your existing AWS credentials.

```bash theme={null}
export SFC_ACCESS_KEY_ID="your_access_key_id"
export SFC_SECRET_ACCESS_KEY="your_secret_access_key"
export SFC_ENDPOINT_URL="https://object.europe-north1.sfcompute.com"
export SFC_REGION="europe-north1"
```

## Bring your dataset to SFC

Copy your dataset into the bucket with rclone, then copy it onto each instance that trains on it.
Run these commands on your laptop or the machine doing the transfer. Install
[rclone](https://rclone.org/install/), then configure an SFC remote with your
[storage credentials](#set-your-storage-credentials).

```bash theme={null}
rclone config create sfc s3 \
  provider=Other \
  access_key_id="$SFC_ACCESS_KEY_ID" \
  secret_access_key="$SFC_SECRET_ACCESS_KEY" \
  endpoint="$SFC_ENDPOINT_URL" region="$SFC_REGION" \
  force_path_style=true
```

Choose your source:

<Tabs>
  <Tab title="From your laptop">
    Copy your dataset into a versioned directory in the bucket.

    ```bash theme={null}
    rclone copy ./dataset sfc:acme-training-data/datasets/v1 --progress
    ```
  </Tab>

  <Tab title="From another S3 provider">
    Use `rclone config` to add a remote named `source` with that provider's endpoint and its own
    credentials. Then copy between the two remotes.

    ```bash theme={null}
    rclone copy source:source-bucket/dataset \
      sfc:acme-training-data/datasets/v1 --progress
    ```

    Data passes through the machine running rclone. The transfer uses that machine's bandwidth, and
    your source provider may charge egress fees.
  </Tab>
</Tabs>

Rerun `copy` to transfer new or changed files. Use a new directory such as `datasets/v2` for a new
dataset version. To mirror the source exactly, use `rclone sync`; it also deletes destination files
absent from the source.

### Use the dataset on an instance

[Connect to your instance](/preview/instances#ssh-into-an-instance), set your
[storage credentials](#set-your-storage-credentials), and configure rclone as above. Copy the
dataset onto its local disk before starting training.

```bash theme={null}
mkdir -p ~/datasets/v1
rclone copy sfc:acme-training-data/datasets/v1 ~/datasets/v1 --progress
```

Point your training data loader at `~/datasets/v1`. Repeat on each instance that needs a local copy.

## Save and resume training checkpoints

From an SFC instance, save checkpoints to object storage in the same region as your training job.
Checkpoints in object storage stay available when you move to another instance or start another run.

With PyTorch already installed, run `python -m pip install boto3` in your training environment. Set
your [storage credentials](#set-your-storage-credentials) there. Add this to your training loop,
where `model`, `optimizer`, and `step` are your current training state:

```python theme={null}
import os
from pathlib import Path

import boto3
import torch
from botocore.config import Config

s3 = boto3.client(
    "s3",
    aws_access_key_id=os.environ["SFC_ACCESS_KEY_ID"],
    aws_secret_access_key=os.environ["SFC_SECRET_ACCESS_KEY"],
    endpoint_url=os.environ["SFC_ENDPOINT_URL"],
    region_name=os.environ["SFC_REGION"],
    config=Config(s3={"addressing_style": "path"}),
)

checkpoint = Path("checkpoints") / f"step-{step}.pt"
checkpoint.parent.mkdir(parents=True, exist_ok=True)
torch.save({
    "step": step,
    "model": model.state_dict(),
    "optimizer": optimizer.state_dict(),
}, checkpoint)
key = f"runs/run-42/step-{step}.pt"
s3.upload_file(str(checkpoint), "acme-training-data", key)
```

Use a different run directory for each job. Upload only completed checkpoints; for distributed
training, coordinate the writers so they don't overwrite each other. Wait for the upload to succeed
before terminating the instance.

On a fresh instance, recreate the model and optimizer, configure the S3 client as above, and restore
a completed checkpoint:

```python theme={null}
key = "runs/run-42/step-1000.pt"
s3.download_file("acme-training-data", key, "checkpoint.pt")
state = torch.load("checkpoint.pt", map_location="cpu", weights_only=True)
model.load_state_dict(state["model"])
optimizer.load_state_dict(state["optimizer"])
start_step = state["step"] + 1
```

Include any other state your job needs to resume, such as its learning-rate scheduler. See
[PyTorch checkpointing](https://docs.pytorch.org/tutorials/beginner/saving_loading_models.html#saving-loading-a-general-checkpoint-for-inference-and-or-resuming-training).

To retrieve a run on your own machine, use the same rclone remote:

```bash theme={null}
rclone copy sfc:acme-training-data/runs/run-42 ./run-42 --progress
```

## Manage buckets and access keys

List buckets and keys with `sf storage buckets list` and `sf storage access-key list`, or open
[Storage](https://console.sfcompute.com/dashboard/storage) in the console. Revoke a key with `sf
storage access-key delete training`, or open [Storage → Access
keys](https://console.sfcompute.com/dashboard/storage?tab=keys) and click **Revoke Key**.

<Frame>
  <img alt="Access keys tab with the actions menu open for the training key, showing Revoke Key" />
</Frame>

When you no longer need a bucket, run `sf storage buckets delete acme-training-data` or select
**Delete Bucket** in [Storage](https://console.sfcompute.com/dashboard/storage). Confirm the name
when prompted. Deletion removes the bucket and all its objects.

<Frame>
  <img alt="Buckets tab with the actions menu open for acme-training-data, showing Delete Bucket" />
</Frame>

<Warning>
  Deleting a bucket is permanent. Its name becomes available for anyone to claim.
</Warning>

## Bucket and access key limits

SF Compute enforces these limits on buckets and access keys:

| Resource | Limit |
| - | - |
| Bucket capacity | 100 TiB per bucket by default. [Contact us](https://sfcompute.com/contact) if you need a higher limit. |
| Access keys | 2 per workspace per region. Key names must be unique within a workspace. |
| Bucket names | Globally unique. 3 to 63 lowercase letters, numbers, or hyphens, starting with a letter or number. |

## Usage and billing

SF Compute measures the bytes stored in each bucket hourly. Storage costs \$0.14 per GiB-month,
prorated by amount stored and time kept. For example, 100 GiB for a full calendar month costs \$14,
and for half that month it costs \$7.

SF Compute invoices storage after each UTC calendar month and
charges your default card when the invoice is due, 7 days after sending it. Storage charges are
separate from prepaid compute credits.

Track usage and month-to-date cost under [Usage →
Storage](https://console.sfcompute.com/dashboard/usage?view=storage) in the console.

<Frame>
  <img alt="Usage page on the Storage tab, with stored bytes per bucket by day and month-to-date cost per bucket" />
</Frame>

View invoices on the [Billing](https://console.sfcompute.com/dashboard/billing) page.

<Frame>
  <img alt="Invoices section of the Billing page, listing each billing month with its status, total, and due date" />
</Frame>

## API reference

The SF Compute API doesn't manage buckets or access keys yet. Use `sf storage` to script them, or
[contact us](https://sfcompute.com/contact) if you need programmatic access.


# Orderbook
Source: https://docs.sfcompute.com/preview/orderbook

Read the public orderbook: orders, windows, quotes, depth, and fills

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

The orderbook is the public, anonymized record of buy and sell orders on the market. Each order
states its side, node count, SKU, delivery window, and limit price.

The diagram below shows 3 example open orders.

<img alt="Orderbook with three example open orders: a Buy for 8 H100s on Sep 1 9am to Sep 4 5pm at up to $17.42/node-hour, a Sell for 4 B200s on the same window at $17.38 minimum, and a Buy for 16 H200s on Oct 15 12am to Oct 22 12am at up to $16.95." />

The trading engine matches compatible buys and sells continuously. Open orders make up the live
book; filled orders and their executions provide market history. Orderbook responses never
expose participant, pool, or capacity identity.

Endpoints live under `/preview/v2/orderbook/` and require a Bearer token; see
[Using the API](/preview/using-the-api).

* [`/orders`](#orders) lists individual open and filled orders.
* [`/windows`](#windows) lists active SKU and delivery-window combinations in a time range.
* [`/quote`](#quote) returns the top of book (best bid and best ask) for one exact window.
* [`/depth`](#depth) returns the live book aggregated at every SKU and price level.
* [`/fills`](#fills) lists individual executions produced when orders match.

`/windows`, `/quote`, and `/depth` are derived views of open orders, while `/fills` is an
execution-level view. Use `/windows` when you don't yet know the exact window. The other endpoints
price or trace a window you've already picked. To create, cancel, or inspect your own workspace's
orders, see [Orders](/preview/orders).

The hardware filter is `?requirements=key:value`. Keys are SKU property names such as
`accelerator`, `region`, or `availability_zone`. Values are case-sensitive and match the property's
value spelling, as in `accelerator:h100`. Run `sf skus list` to see the properties a SKU
carries.

Each key takes exactly one value; combine keys with `;` to require all of them, as in
`accelerator:h100;availability_zone:a`. The reserved `instance_sku` key matches a single SKU by its
ID. The filter covers every SKU that satisfies these requirements.

All timestamps are Unix epoch seconds. Field names use the `_at` suffix. Delivery-window and range
boundaries (`start_at`, `end_at`, `range_start_at`, and `range_end_at`) must be aligned to whole
minutes.

## Orders

List individual open and filled orders created within the last 30 days whose delivery windows
match a time range. Results are anonymized and sorted newest first by `created_at`.

```http theme={null}
GET /preview/v2/orderbook/orders?requirements=accelerator:h100&range_start_at=1777507200&range_end_at=1780099200&window_relation=overlaps&status=open

{
  "object": "list",
  "requirements": { "accelerator": ["h100"] },
  "range_start_at": 1777507200,
  "range_end_at":   1780099200,
  "window_relation": "overlaps",
  "requested_at": 1777426010,
  "has_more": false,
  "data": [
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "side": "buy",
      "status": "open",
      "allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 8 }
      ],
      "filled_allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 3 }
      ],
      "limit_price_dollars_per_node_hour": "17.420000",
      "filled_average_price_dollars_per_node_hour": "17.400000",
      "created_at": 1777426010
    }
  ]
}
```

`open` includes standing and partially filled orders; `filled` means the order filled completely.
Pending, cancelled, and rejected orders are not returned. Omit `status` to include both public
statuses, or repeat it to select more than one. Use `side=buy` for buys or `side=sell` for sells.

Delivery windows are half-open ranges: `[start_at, end_at)`. `window_relation=overlaps` is the
default. `contained_within` requires the order's full window to be inside the requested range.
`exact` requires the windows to match.

The range is capped at 30 days. `limit` defaults to 50 and caps at 200; pass the returned `cursor`
as `starting_after` to fetch the next page. The cursor must reference an order created within the
last 30 days; older cursors return a 422 response.

## Windows

Enumerate every SKU and delivery window that currently has open orders matching the
requirements filter, within a time range.

<img alt="Three example delivery windows displayed as horizontal bars on a Sep 1 to Sep 29 time axis, each showing its bid and ask counts." />

```http theme={null}
GET /preview/v2/orderbook/windows?requirements=accelerator:h100&range_start_at=1777507200&range_end_at=1780099200

{
  "object": "list",
  "requirements": { "accelerator": ["h100"] },
  "range_start_at": 1777507200,
  "range_end_at":   1780099200,
  "has_more": false,
  "data": [
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "start_at": 1777507200,
      "end_at":   1778112000,
      "duration_hours": 168,
      "total_bid_order_count": 3,
      "total_ask_order_count": 5,
      "best_bid": {
        "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
        "dollars_per_node_hour": "17.380000",
        "allocation_schedule_delta": [
          { "start_at": 1777507200, "end_at": 1778112000, "node_count": 4 }
        ]
      },
      "best_ask": {
        "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
        "dollars_per_node_hour": "17.420000",
        "allocation_schedule_delta": [
          { "start_at": 1777507200, "end_at": 1778112000, "node_count": 2 }
        ]
      }
    },
    {
      "instance_sku": "sku_q7T-mB4cV9xL2pR6wN8sJ",
      "start_at": 1777593600,
      "end_at":   1778198400,
      "duration_hours": 168,
      "total_bid_order_count": 0,
      "total_ask_order_count": 1,
      "best_ask": {
        "instance_sku": "sku_q7T-mB4cV9xL2pR6wN8sJ",
        "dollars_per_node_hour": "16.950000",
        "allocation_schedule_delta": [
          { "start_at": 1777593600, "end_at": 1778198400, "node_count": 8 }
        ]
      }
    }
  ]
}
```

A window appears when it holds at least one matching open order and sits entirely within the range.
`best_bid` / `best_ask` are omitted when that side is empty. Results are sorted ascending by
`(start_at, end_at, instance_sku)` and cursor-paginated. `limit` defaults to 50 and caps at 200; the
range is capped at 365 days.

## Quote

Get the top of book for one exact window: the highest bid and lowest ask.

<img alt="A vertical price ladder showing best ask of $17.42 with 2 nodes above best bid of $17.38 with 4 nodes, with a vertical bracket between them labeled spread $0.04." />

```http theme={null}
GET /preview/v2/orderbook/quote?requirements=accelerator:h100&start_at=1777507200&end_at=1778112000

{
  "requirements": { "accelerator": ["h100"] },
  "start_at": 1777507200,
  "end_at":   1778112000,
  "requested_at": 1777426010,
  "best_bid": {
    "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
    "dollars_per_node_hour": "17.380000",
    "allocation_schedule_delta": [
      { "start_at": 1777507200, "end_at": 1778112000, "node_count": 4 }
    ]
  },
  "best_ask": {
    "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
    "dollars_per_node_hour": "17.420000",
    "allocation_schedule_delta": [
      { "start_at": 1777507200, "end_at": 1778112000, "node_count": 2 }
    ]
  }
}
```

Each side carries an `allocation_schedule_delta`: the unfilled nodes at that rate and SKU
over time. If multiple SKUs tie at the best price, the quote returns the SKU that sorts
first by ID. Use `/depth` to inspect every SKU at that price. The window's `end_at` must be in the
future; read past windows through [`/fills`](#fills).

## Depth

Get the depth of book aggregated by SKU and dollars-per-node-hour rate across the hardware
matching the requirements filter.

<img alt="Level II ladder showing two ask price levels above the spread and three bid price levels below, with horizontal bars whose lengths encode the node count at each price." />

```http theme={null}
GET /preview/v2/orderbook/depth?requirements=accelerator:h100&start_at=1777507200&end_at=1778112000&depth=20

{
  "requirements": { "accelerator": ["h100"] },
  "start_at": 1777507200,
  "end_at":   1778112000,
  "requested_at": 1777426010,
  "bids": [
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "dollars_per_node_hour": "17.380000",
      "allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 4 }
      ]
    },
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "dollars_per_node_hour": "17.370000",
      "allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 6 }
      ]
    }
  ],
  "asks": [
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "dollars_per_node_hour": "17.420000",
      "allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 2 }
      ]
    },
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "dollars_per_node_hour": "17.430000",
      "allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 5 }
      ]
    }
  ]
}
```

Bids are sorted by descending rate (best bid first); asks are ascending. Orders at the same
rate and SKU collapse into one level. `depth` defaults to 20 and caps at 100 per side. The
window's `end_at` must be in the future; read past windows through [`/fills`](#fills).

## Fills

List individual executions for one exact delivery window. A single order can produce multiple
fills, and each fill records the nodes and price that actually traded.

```http theme={null}
GET /preview/v2/orderbook/fills?requirements=accelerator:h100&start_at=1777507200&end_at=1778112000&since_at=1777420800

{
  "object": "list",
  "requirements": { "accelerator": ["h100"] },
  "start_at": 1777507200,
  "end_at":   1778112000,
  "requested_at": 1777426010,
  "has_more": false,
  "data": [
    {
      "instance_sku": "sku_k3R-nX9vLm7Qp2Yw5Jd8F",
      "dollars_per_node_hour": "17.400000",
      "allocation_schedule_delta": [
        { "start_at": 1777507200, "end_at": 1778112000, "node_count": 3 }
      ],
      "filled_at": 1777424010
    }
  ]
}
```

`since_at` is a lower bound on when the fill was recorded. It defaults to 7 days before the request.
Values more than 30 days before the request return 422.

Results are sorted newest first and cursor-paginated. `limit` defaults to 50 and caps at 200.

## Allocation schedule deltas

`allocation_schedule_delta` describes how many nodes an order requests or offers during one or
more time intervals.

<img alt="An allocation_schedule_delta JSON entry mapped to eight nodes over a time interval. start_at supplies the time for vertices A and B, end_at supplies the time for C and D, and node_count supplies the value for B and C." />

Each object in the array is one schedule segment. `start_at` and `end_at` set the segment's time
bounds, while `node_count` specifies how many nodes apply during that interval. Multiple entries
can describe different node counts over adjacent intervals.

Schedule entries describe half-open intervals `[start_at, end_at)`: the node count applies at
`start_at`, but not at `end_at`. Adjacent entries therefore meet without overlapping. All segments
on an order refer to that order's single `instance_sku`.

In responses, a non-empty array always ends with a terminator entry whose `end_at` is `null` and
`node_count` is `0`, marking the schedule as open-ended and empty after the last segment. A schedule
with no capacity is returned as an empty array. Requests carry only the closed `[start_at, end_at)`
segments you submit and omit this terminator.

Orders are submitted with one node count over one delivery window, so
`allocation_schedule_delta` normally contains one segment. `filled_allocation_schedule_delta`
describes the portion that has executed so far and may contain multiple segments when different
parts of the order fill over different intervals. Subtract the filled node count from the
requested or offered node count at each instant to get the capacity that remains on the book.

For a buy, every filled segment adds to the destination pool's allocation schedule; for a sell, it
removes that segment. An orderbook fill reports the exact schedule segment that traded. To
calculate the compute represented by a schedule, sum `node_count × duration_hours` across its
entries.

## API reference

See the [Orderbook API reference](/api-reference/orderbook/list-market-windows) for full
request and response schemas.


# Orders
Source: https://docs.sfcompute.com/preview/orders

Buy and sell compute time

Orders are how you acquire and release compute time. A buy order increases your
[pool's](/preview/pools) allocation schedule. A sell order decreases it and returns credits to your
balance.

## Buy orders

Place a buy order to get compute time on a pool. `--max-rate` is the most you'll pay in dollars per
node-hour; 1 node is 8 GPUs. You can also use `--max-price` to set a maximum total for the order
instead.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h --max-rate 20.00
```

If the orderbook has availability at your rate, the order fills immediately. Otherwise, SF Compute
cancels the order by default (immediate-or-cancel).

To keep the order on the orderbook until it fills or you cancel it, use `--allow-standing`.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h \
  --max-rate 20.00 --allow-standing
```

A buy order fills completely or not at all by default. Pass `--allow-partial` to let it fill part of
the requested nodes or time window instead, which leaves the order `partially_filled`. A sell order
allows partial fills by default, since a seller usually wants any buyer for any part of the offered
supply. Pass `--allow-partial=false` to require an all-or-nothing fill on a sell.

## Pin to a SKU

You pin every order to a single SKU; the order fills only on that SKU. Pass
`--sku <id>` to pick one directly.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h \
  --max-rate 20.00 \
  --sku sku_4UpxzQw7A8N
```

Running `sf orders create` without `--sku` opens an interactive picker that shows every
registered SKU's name, ID, and properties. In non-interactive mode (`--no-input`), `--sku`
is required. Run `sf skus list` to browse them beforehand. See
[SKUs](/preview/instance-skus) for the full model.

## Sell orders

Sell back compute time you own.

```bash theme={null}
sf orders create --side sell --pool dev --count 1 \
  --start now --duration 1h --min-rate 8.00 --allow-standing
```

When a sell order fills, you receive credits and your pool's allocation decreases. Instances on that
pool that no longer have allocated time will terminate.

<Note>
  Sell orders are not guaranteed to fill. Use `--allow-standing` to keep the order on the orderbook
  until a buyer matches.
</Note>

## Sell fees

When a sell order executes, SF Compute deducts a variable
[platform fee](/preview/guides/reselling#platform-fee) from the fill price. You receive the fill
price minus the fee as credits. The CLI shows the estimated fee before you confirm an order.

Buy orders have no fees.

## Interruptible buy orders

<Warning>
  Interruptible buy orders are in [public preview](/preview/roadmap#feature-states).
</Warning>

When an interruptible buy order fills, SF Compute lists the compute it bought for sale at an
interrupt rate you set. These listings are sell orders on the same pool that allow partial fills.
While the interrupt rate is below the [offset price ceiling](/preview/limits#compute-limits), the
order doesn't count toward your compute limit.

If someone buys a listing, you lose that time. Instances left without allocated time terminate,
lowest [priority](/preview/instances#instance-priority) first.

Set the interrupt rate in dollars per node-hour with `--interrupt-rate`. It must be above your max
rate and below the ceiling. `sf platform-constants` shows the current ceiling.

```bash theme={null}
sf orders create --side buy --pool dev --count 1 --start now --duration 1h \
  --max-rate 20.00 --interrupt-rate 24.00
```

`sf pools extend` takes the same flag. If an interactive buy would go over your compute limit and
your max rate is below the ceiling, the CLI offers to make it interruptible.

If the ceiling drops to or below your interrupt rate, the order's unfilled node-hours and the
compute it bought start counting toward your limit.

See your listings with `sf orders list --side sell`. When a listing fills, you get the fill price
minus [sell fees](#sell-fees).

Cancelling the buy order doesn't cancel its listings. Cancel a listing with `sf orders cancel`. SF
Compute refuses the cancellation if it would put you over your compute limit.

## Holds

Placing an order reserves what a fill would need, so a match can always settle. A buy order holds
credits equal to its worst case, the limit price across the full requested window and node count.
Your available balance is what remains after open holds.

Placement fails with an insufficient-balance error when your available balance can't cover the hold.
A sell order instead reserves the pool allocation it offers, so the same compute can't be sold
twice.

When a fill executes, you pay the fill price and SF Compute releases the unused part of the hold.
Cancelling the order or letting its remaining window elapse releases the rest.

## Order statuses

| Status | Description |
| - | - |
| pending | Submitted, not yet processed |
| filled | Fully executed |
| partially\_filled | Partially executed; the unfilled remainder stays on the orderbook |
| standing | Waiting for a match on the orderbook |
| cancelled | No match found (immediate-or-cancel), manually cancelled, or the order's window fully elapsed |
| rejected | Validation or system error |

A standing order (buy or sell) rests until it fills, you cancel it, or its window fully elapses. As
the current time passes the order's start, it keeps matching only over the un-elapsed remainder of
its window. It matches at its original per-node-hour limit price. The order's total value shrinks as
time elapses.

Once the whole window has elapsed the order stops matching and moves to `cancelled`; there is no
separate expiry or time-to-live field. This lapse timing is current behavior, not a guarantee.

## Check an order

Look up a single order by ID.

```bash theme={null}
sf orders get ordr_JLBu4arl9nSLMfF2Ole
```

```text theme={null}
| ORDER ID                ordr_JLBu4arl9nSLMfF2Ole
| SIDE                    buy
| STATUS                  filled at Mar 19, 4:48pm
| FILLED                  100%
| POOL                    dev (pool_nuO4nVSM8O3NnsRE7udBe)
| SKU                     sku_4UpxzQw7A8N
| RATE (PER 8X GPU NODE)  $20.00/node/hr (Limit)
|
| SCHEDULE                Mar 19, 5:00pm → Mar 19, 6:00pm: 1 node
```

## List orders

List orders in the active workspace.

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

To list orders across your organization, use `--all`.

```bash theme={null}
sf orders list --all
```

```text theme={null}
-----------------------------------------------------------------------------------------------------------
SIDE  STATUS     PERIOD  NODES  RATE ($/NODE/HR, 8x GPU)  POOL  SKU              ID
sell  filled     Mar 19  1      ≥$8.00/node/hr            dev   sku_4UpxzQw7A8N  ordr_hYuOEmXWt3RqPd8KvA2Nc
buy   filled     Mar 19  1      ≤$20.00/node/hr           dev   sku_4UpxzQw7A8N  ordr_JLBu4arl9nSLMfF2Ole
buy   cancelled  Mar 12  1      ≤$20.00/node/hr           dev   sku_4UpxzQw7A8N  ordr_Qj69x65vLw4TmBn7RdEyS
```

Filter by side or status.

```bash theme={null}
sf orders list --side buy --status filled
```

Filter by time range.

```bash theme={null}
# Orders from the last 7 days
sf orders list --created-after 7d

# Orders within a specific window
sf orders list --created-after 2025-03-01 --created-before 2025-03-08

# Orders from a specific calendar month
sf orders list --month 2025-05
```

`--created-after` and `--created-before` accept a datetime, Unix timestamp, or a duration like `24h`
or `7d`. A duration means that long ago (24 hours or 7 days, respectively). You can also use
`--since` and `--until` as aliases.

## Cancel an order

Cancel an order that hasn't fully filled yet.

```bash theme={null}
sf orders cancel <order-id>
```

Cancellation is asynchronous. The request returns right away (`204 No Content` on the API). A
matching batch already in progress can still land a fill before the state flips to `cancelled`. Poll
`GET /v2/orders/{id}` until it does.

Cancellation removes only the unfilled remainder from the orderbook and keeps the fills that
executed before it. Once the order is `cancelled`, its `fills` and
`filled_allocation_schedule_delta` are final and remain readable on the order in both get and list
responses.

## Start and end times

Order start and end times must be on the
[allocation schedule grid](/api-reference/platform/get-platform-constants#response-allocation-schedule-grid).
An order can also start at the current time.

## Allocation schedule deltas

`allocation_schedule_delta` describes how many nodes an order requests or offers during one or
more time intervals.

<img alt="An allocation_schedule_delta JSON entry mapped to eight nodes over a time interval. start_at supplies the time for vertices A and B, end_at supplies the time for C and D, and node_count supplies the value for B and C." />

Each object in the array is one schedule segment. `start_at` and `end_at` set the segment's time
bounds, while `node_count` specifies how many nodes apply during that interval. Multiple entries
can describe different node counts over adjacent intervals.

Schedule entries describe half-open intervals `[start_at, end_at)`: the node count applies at
`start_at`, but not at `end_at`. Adjacent entries therefore meet without overlapping. All segments
on an order refer to that order's single `instance_sku`.

In responses, a non-empty array always ends with a terminator entry whose `end_at` is `null` and
`node_count` is `0`, marking the schedule as open-ended and empty after the last segment. A schedule
with no capacity is returned as an empty array. Requests carry only the closed `[start_at, end_at)`
segments you submit and omit this terminator.

Orders are submitted with one node count over one delivery window, so
`allocation_schedule_delta` normally contains one segment. `filled_allocation_schedule_delta`
describes the portion that has executed so far and may contain multiple segments when different
parts of the order fill over different intervals. Subtract the filled node count from the
requested or offered node count at each instant to get the capacity that remains on the book.

For a buy, every filled segment adds to the destination pool's allocation schedule; for a sell, it
removes that segment. An orderbook fill reports the exact schedule segment that traded. To
calculate the compute represented by a schedule, sum `node_count × duration_hours` across its
entries.

## API examples

These worked examples use the `/v2` order endpoints; see the
[Orders API reference](/api-reference/orders/list-orders) for the full request and response
schemas. Timestamps are Unix epoch seconds, and prices are strings in dollars per node-hour.

Create a buy order with `POST /v2/orders`. The request body includes the following fields.

* `side` is `buy` or `sell`.
* `pool` accepts a pool ID or resource path.
* `sku` takes a SKU ID.
* `allocation_schedule_delta` is a single time range.

```json theme={null}
{
  "pool": "pool_2m9Xk4Qw7A8N",
  "side": "buy",
  "allow_standing": true,
  "allow_partial": false,
  "sku": "sku_4UpxzQw7A8N",
  "allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 }
  ],
  "limit_price_dollars_per_node_hour": "18.000000"
}
```

The response returns the order in `pending` state; poll `GET /v2/orders/{id}` for the resolved
state. The trailing zero entry marks the end of the schedule.

```json theme={null}
{
  "object": "order",
  "id": "ordr_JLBu4arl9nSLMfF2Ole",
  "pool": { "object": "pool_summary", "id": "pool_2m9Xk4Qw7A8N", "name": "dev" },
  "workspace": { "object": "workspace_summary", "id": "wksp_7Ct3nR2xL9", "name": "acme" },
  "side": "buy",
  "allow_standing": true,
  "allow_partial": false,
  "sku": { "object": "sku", "id": "sku_4UpxzQw7A8N", "alias": "h100i" },
  "allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
    { "start_at": 1742407200, "end_at": null, "node_count": 0 }
  ],
  "filled_allocation_schedule_delta": [],
  "limit_price_dollars_per_node_hour": "18.000000",
  "state": "pending",
  "created_at": 1742402883
}
```

A sell order takes the same body with `side` set to `sell`, and its response has the same shape.

```json theme={null}
{
  "pool": "pool_2m9Xk4Qw7A8N",
  "side": "sell",
  "allow_standing": true,
  "allow_partial": true,
  "sku": "sku_4UpxzQw7A8N",
  "allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 }
  ],
  "limit_price_dollars_per_node_hour": "9.000000"
}
```

Fetch one order with `GET /v2/orders/{id}`. Once filled, `state` is `filled`, `filled_at` is set,
and `filled_allocation_schedule_delta` covers the filled portion. `fills` lists each execution with
the price actually paid (here below the buy's limit).

```json theme={null}
{
  "object": "order",
  "id": "ordr_JLBu4arl9nSLMfF2Ole",
  "pool": { "object": "pool_summary", "id": "pool_2m9Xk4Qw7A8N", "name": "dev" },
  "workspace": { "object": "workspace_summary", "id": "wksp_7Ct3nR2xL9", "name": "acme" },
  "side": "buy",
  "allow_standing": true,
  "allow_partial": false,
  "sku": { "object": "sku", "id": "sku_4UpxzQw7A8N", "alias": "h100i" },
  "allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
    { "start_at": 1742407200, "end_at": null, "node_count": 0 }
  ],
  "filled_allocation_schedule_delta": [
    { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
    { "start_at": 1742407200, "end_at": null, "node_count": 0 }
  ],
  "limit_price_dollars_per_node_hour": "18.000000",
  "state": "filled",
  "created_at": 1742402883,
  "filled_at": 1742402889,
  "fills": [
    {
      "filled_at": 1742402889,
      "allocation_schedule_delta": [
        { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
        { "start_at": 1742407200, "end_at": null, "node_count": 0 }
      ],
      "price_dollars_per_node_hour": "15.000000"
    }
  ]
}
```

List orders with `GET /v2/orders`. Each entry in `data` is a full order object; pass the returned
`cursor` as `starting_after` to page forward.

```json theme={null}
{
  "object": "list",
  "has_more": false,
  "cursor": "ordrc_kQ8Vd2wwpU1s2Wey",
  "data": [
    {
      "object": "order",
      "id": "ordr_hYuOEmXWt3RqPd8KvA2Nc",
      "pool": { "object": "pool_summary", "id": "pool_2m9Xk4Qw7A8N", "name": "dev" },
      "workspace": { "object": "workspace_summary", "id": "wksp_7Ct3nR2xL9", "name": "acme" },
      "side": "sell",
      "allow_standing": true,
      "allow_partial": true,
      "sku": { "object": "sku", "id": "sku_4UpxzQw7A8N", "alias": "h100i" },
      "allocation_schedule_delta": [
        { "start_at": 1742403600, "end_at": 1742407200, "node_count": 1 },
        { "start_at": 1742407200, "end_at": null, "node_count": 0 }
      ],
      "filled_allocation_schedule_delta": [],
      "limit_price_dollars_per_node_hour": "9.000000",
      "state": "standing",
      "created_at": 1742402883
    }
  ]
}
```

Cancel with `POST /v2/orders/{id}/cancel`, which returns `204 No Content`.

```http theme={null}
POST /v2/orders/ordr_hYuOEmXWt3RqPd8KvA2Nc/cancel
```


# Pools
Source: https://docs.sfcompute.com/preview/pools

Manage compute allocation

A pool records an allocation of compute time. You buy compute time into a pool with orders, and
[instances on the pool run during the scheduled time slots](/preview/guides/instances-and-pools).
You can also move compute between pools with [transfers](#transfers).

## Create a pool

A new pool starts with no allocation.

```bash theme={null}
sf pools create --name dev
```

## List pools

List the pools in your workspace.

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

```text theme={null}
─────────────────────────────────────────────────
NAME  KIND    NODES  PERIOD  NEXT 48H
dev   market  -      -       ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
```

## View a pool

Get a pool by name or ID.

```bash theme={null}
sf pools get dev
```

```text theme={null}
│ POOL ID         pool_nuO4nVSM8O3NnsRE7udBe
│ NAME            dev
│ RESOURCE PATH   sfc:pool:acme:default:dev
│ KIND            market
│ CREATED         Feb 17, 5:23pm PDT
└ TOTAL SCHEDULE  Today, 5:00pm → Aug 14, 5:00pm: 1 node
```

## Allocation schedule

The allocation schedule shows how many nodes you have over time on this pool. The schedule gains
time when a buy order fills and loses time when a sell order fills.

You can create instances on a pool before it has allocation. They start running when allocation
becomes available and stop when it runs out.

The schedule is a net node count over time, not a ledger of the orders that built it. Filled buy and
sell orders each add or remove a schedule segment (see [Orders](/preview/orders)), but the pool
keeps only the running total at each instant. There's no stable identifier for an individual
segment: 2 fills of the same SKU and time range are indistinguishable once merged into the total. To
track which order added or removed a given block of time, keep the order's own ID.

## Mixed hardware

A single pool can hold allocation across several [SKUs](/preview/instance-skus). Each order
fills against whatever SKU matches its requirements, and the schedule tracks each SKU's allocation
independently. Within a SKU, nodes are interchangeable, so the schedule tracks a node count, not
which physical machine is running it.

For example, a pool might hold 100 H100 nodes in `sea-3` from 9am to 5pm today. It could hold 50
more H100 nodes in `iad-12` from 5pm today to 9am tomorrow. The SKUs do not need to overlap in time;
the schedule records what was bought and when.

Run `sf pools get dev --verbose` to see a separate schedule block per SKU in addition to the
aggregate `TOTAL SCHEDULE`.

### Buy more on an existing SKU

To add allocation to a SKU you already have, pass its ID via `--sku` on the buy order. Each
SKU has a stable ID (`sku_...`) that pins the order to exactly that SKU.

```bash theme={null}
sf orders create --side buy --pool dev --nodes 1 --start now --duration 1h \
  --max-rate 20.00 \
  --sku sku_4UpxzQw7A8N
```

Run `sf pools get dev --verbose` or `sf skus list` to find the ID.

## Transfers

Transfers move nodes between 2 pools for a specified window of time.

### Create a transfer

Specify the source pool, destination pool, time window, node count, and SKU.

```bash theme={null}
sf pools transfers create \
  --from dev \
  --to prod \
  --start-at "tomorrow" \
  --duration 7d \
  --count 4 \
  --sku sku_4UpxzQw7A8N
```

Start and end times must be on the
[allocation schedule grid](/api-reference/platform/get-platform-constants#response-allocation-schedule-grid).
A transfer can also start at the current time.

Omitting a required flag opens an interactive picker to help you fill in the remaining values.

Specify the full resource path if the `--from` or `--to` pool is located in a
different workspace.

```bash theme={null}
sf pools transfers create \
  --from dev \
  --to sfc:pool:acme:prod_ws:prod \
  --start-at "tomorrow" \
  --duration 7d \
  --count 4 \
  --sku sku_4UpxzQw7A8N
```

### List transfers

List the transfers in your organization.

```bash theme={null}
sf pools transfers list
```

```text theme={null}
────────────────────────────────────────────────────────────────────
ID           CREATED AT      STATUS    FROM       TO    INSTANCE SKU
pxfr_abc123  Mar 19, 4:40pm  executed  dev        prod  -
pxfr_def456  Mar 18, 9:15am  pending   dev        prod  -
pxfr_ghi789  Mar 18, 9:02am  rejected  inference  prod  -
```

Filter by pool (repeatable) or status, or pass `--verbose` for the schedule details of each
transfer.

```bash theme={null}
sf pools transfers list --pool prod --status executed
```

```text theme={null}
───────────────────────────────────────────────────────────────
ID           CREATED AT      STATUS    FROM  TO    INSTANCE SKU
pxfr_abc123  Mar 19, 4:40pm  executed  dev   prod  -
```

### Get a transfer

Get a transfer by ID.

```bash theme={null}
sf pools transfers get pxfr_abc123
```

```text theme={null}
│ TRANSFER ID   pxfr_abc123
│ STATUS        executed
│ FROM POOL     dev
│ TO POOL       prod
│ INSTANCE SKU  sea-3-h100 (sku_4UpxzQw7A8N)
│ CREATED       Mar 19, 4:40pm PDT
│
└ SCHEDULE      Mar 20, 12:00am → Mar 27, 12:00am: 4 nodes
```

### Protect instances from termination

A pool's allocation can drop below the number of running instances when a sell order fills, a
[spot deployment](/preview/spot-deployments) scales down, or a transfer leaves. When that happens,
SF Compute terminates instances until the running count matches the schedule, lowest
[priority](/preview/instances#instance-priority) first, newest first within a priority.

To keep specific instances running when allocation shrinks, raise their priority. The system keeps
`critical` instances over everything else.

```bash theme={null}
sf instances set gpu-worker --priority critical
```

## Extend a pool

Extending places a buy order that continues the schedule's final node count to a new end time.

```bash theme={null}
sf pools extend dev
```

For example, consider the following pool.

```bash theme={null}
sf pools get dev
```

```text theme={null}
│ POOL ID         pool_nuO4nVSM8O3NnsRE7udBe
│ NAME            dev
│ RESOURCE PATH   sfc:pool:acme:default:dev
│ KIND            market
│ CREATED         Feb 17, 5:23pm PDT
└ TOTAL SCHEDULE  Today, 5:00pm → Aug 14, 5:00pm: 2 nodes
```

Extend it by 2 hours. The prompt asks for a duration and whether to leave a standing order. It then
quotes the current rate for the extension.

```bash theme={null}
sf pools extend dev
```

```text theme={null}
  note: extending from Aug 14, 5:00pm PDT

> Duration of compute time: 2h
> Allow as standing order until filled? No

│ ACTION                  extend pool
│ POOL                    dev (pool_nuO4nVSM8O3NnsRE7udBe)
│ NODES                   2
│ EXTENDING FROM          Aug 14, 5:00pm PDT
│ EXTENDING TO            Aug 14, 7:00pm PDT
│ INSTANCE SKU            sea-3-h100 (sku_4UpxzQw7A8N)
│ RATE (PER 8X GPU NODE)  $20.00/node/hr
│ TOTAL                   $80.00
│ ESTIMATED FEE           $4.00
│ FILL                    expected to fill at this rate
│ STANDING                false
└ to be placed
> Place this order? Yes
Order ordr_HV6cjCNfgs2y9HCIOJITO filled
```

Non-interactive runs require an end time and a price cap: pass `--duration` or `--stop`, plus
`--max-rate` or `--max-price`.

Fetch the pool again; the schedule now ends 2 hours later.

```bash theme={null}
sf pools get dev
```

```text theme={null}
│ POOL ID         pool_nuO4nVSM8O3NnsRE7udBe
│ NAME            dev
│ RESOURCE PATH   sfc:pool:acme:default:dev
│ KIND            market
│ CREATED         Feb 17, 5:23pm PDT
└ TOTAL SCHEDULE  Today, 5:00pm → Aug 14, 7:00pm: 2 nodes
```

Extension requires availability during the requested window.

## Rename a pool

Renaming a pool changes its resource path but not its ID.

```bash theme={null}
sf pools set dev --name production
```

## Delete a pool

A pool must have no active orders, future allocation, non-terminated instances, deployments,
procurements, or pending transfers before you can delete it.

```bash theme={null}
sf pools delete dev
```

## API reference

See the [Pools API](/api-reference/pools/list-pools) for programmatic access.


# Quickstart
Source: https://docs.sfcompute.com/preview/quick-start

Get your first GPU instance running

Create a pool, buy compute time into it, and start your first GPU instance on SF Compute.

## Install the CLI

Download and run the install script.

```bash theme={null}
curl -fsSL https://cli.sfcompute.com | bash
```

## Log in

Authenticate the CLI.

```bash theme={null}
sf login
```

This opens your browser to sign in and stores your credentials locally.

## Check what you can buy

[SKUs](/preview/instance-skus) describe the hardware you can buy. List them and when each
becomes available, 1 row per SKU.

```bash theme={null}
sf availability
```

```text theme={null}
  NAME        ID               NEXT AVAILABLE  NEXT 48H
  ams-1-h100  sku_7GtBqvXk2Nm  now (24)        ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▁▁▁▁▁  peak: 24
  iad-2-h100  sku_Wm5cRzJq8Ld  now (64)        ▇▇▇▇▇▇▇▇▇▇▁▁▁▁▁▁▁▁▁▁  peak: 64
  ord-1-a100  sku_2xPfVn6KwQh  now (96)        ▇▇▇▇▇▄▄▄▄▄▂▂▂▂▂▁▁▁▁▁  peak: 96
  sea-3-h100  sku_4UpxzQw7A8N  now (128)       ▇▇▇▇▇▇▇▇▇▇▁▁▁▁▁▁▁▁▁▁  peak: 128
  nrt-1-h100  sku_Ht9sLc3MvBn  now (48)        ▇▇▇▇▇▇▇▇▇▇▇▇▁▁▁▁▁▁▁▁  peak: 48
```

`NEXT AVAILABLE` is the soonest instances become available and how many. Values are `now (N)`, a
time like `Today, 8:00pm (4)`, or `—` when nothing is scheduled. `NEXT 48H` sparklines the schedule
with the peak shown to the right.

## Create an empty pool

A [pool](/preview/pools) tracks your compute allocation over time. You buy compute time into a pool
with orders, and instances on the pool run when there's allocated time. Create a pool named `dev`.

```bash theme={null}
sf pools create --name dev
```

## Buy compute time

<Note>
  Buying compute time charges your organization. Make sure you have credits: check with
  `sf billing balance` or [top up on the dashboard](https://sfcompute.com/dashboard).
</Note>

Place a buy [order](/preview/orders) for compute time on your pool. The command guides you through
each option interactively. You set the number of nodes (each node runs 1 instance), start time,
duration, rate, and the [SKU](/preview/instance-skus) the order pins to. For this guide,
choose a start time of `now`.

```bash theme={null}
sf orders create --pool dev --side buy
```

## Check your order

List your orders and check the status.

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

```text theme={null}
--------------------------------------------------------------------------------------------------------
SIDE  STATUS  PERIOD  NODES  RATE ($/NODE/HR, 8x GPU)  POOL  SKU              ID
buy   filled  Mar 23  1      ≤$20.00/node/hr           dev   sku_4UpxzQw7A8N  ordr_5KwQh2xPfVn6M3RtLcQw9
```

<Note>
  If the order shows `cancelled`, the price was too low or there was no availability. Try a higher
  rate, a later start time, or `--allow-standing`. A standing order stays open on the orderbook until
  it fills or you cancel it.
</Note>

## List images

An [image](/preview/images) is the bootable disk template an instance starts from. You need an image
name or ID to create an instance. List the images available to you.

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

```text theme={null}
----------------------------------------------------------------------------------------
NAME                                               VISIBILITY  STATUS     CREATED
sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2  public      completed  Feb 23, 6:50pm
```

SF Compute publishes public images with Ubuntu and CUDA pre-installed. You can also
[build and upload your own custom images](/preview/images).

## Create an instance

First, create a startup script that injects your SSH key so you can connect to the instance.

```bash theme={null}
# The $(cat ...) lines expand on your machine as startup.sh is written,
# embedding your public keys in the script.
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_ed25519.pub 2>/dev/null)
EOF
SCRIPT
```

Then create an [instance](/preview/instances) on your pool with the public image.

```bash theme={null}
sf instances create --pool dev --sku sku_4UpxzQw7A8N \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 --cloud-init ./startup.sh
```

Your pool already has compute time from the order you placed. Because you chose a start time of
`now`, your instance gets its allocation within about a minute and begins booting. Compute ownership
and instances are separate: you can terminate and recreate instances without losing your purchased
compute time.

## Watch your instance start

List your instances to watch the status. The `NAME` column shows the name you'll use to connect.

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

The image download and boot process takes up to 10 minutes before SSH is available.

## Connect via SSH

SSH in with the instance name from `sf instances list`.

```bash theme={null}
sf instances ssh <instance-name>
```

Verify the GPUs are available.

```bash theme={null}
nvidia-smi
```

## Next steps

You now have a running GPU instance. Here are some things to try.

### Sell back unused compute time

Place a sell order as a standing order. If someone buys it, you get credits back (minus a variable
[platform fee](/preview/guides/reselling#platform-fee)) and the instance loses its compute time.

```bash theme={null}
sf orders create --pool dev --side sell --count 1 --sku sku_4UpxzQw7A8N \
  --start now --duration 1h --min-rate 8.00 --allow-standing
```

### Check your pool's allocation schedule

See the compute time you own on the pool.

```bash theme={null}
sf pools get dev
```

### Learn more

* [Instances and Pools](/preview/guides/instances-and-pools) explains the core model.
* [Auto-scaling](/preview/guides/auto-scaling) shows how to scale a fleet up and down while buying
  and selling time automatically.
* [Pools](/preview/pools), [orders](/preview/orders), and [instances](/preview/instances) are the
  resource references for the commands used here.


# Resource paths
Source: https://docs.sfcompute.com/preview/resource-paths

Human-readable references for resources across the API and CLI

A resource path is a human-readable, colon-separated reference for a resource. Resource paths let
you reference resources across the API and CLI without memorizing IDs.

Not every resource has a resource path. You reference resources like [orders](/preview/orders),
which have no user-settable name, by ID only.

## Format

Most resource paths take 1 of 2 forms.

```text theme={null}
sfc:<type>:<organization>:<workspace>:<name>     # workspace-scoped
sfc:<type>:<organization>:<name>                 # organization-scoped
```

The `sfc:` prefix identifies the resource as belonging to SF Compute. The hierarchy moves from
broader scope (left) to narrower scope (right). Each segment contains only letters, numbers, and the
characters `.`, `_`, and `-`, so a colon always marks a segment boundary. Colons are URL-safe, so
resource paths can appear directly in URL path parameters without encoding.

## Examples by resource type

| Resource | Scope | Resource path |
| - | - | - |
| Pool | workspace | `sfc:pool:acme:production:training-pool` |
| Instance | workspace | `sfc:instance:acme:production:trainer-1` |
| Instance template | workspace | `sfc:instance_template:acme:production:gpu-worker` |
| Image | workspace | `sfc:image:acme:production:cuda-12-7` |
| Deployment | workspace | `sfc:deployment:acme:production:inference` |
| Workspace | organization | `sfc:workspace:acme:production` |

## IDs vs resource paths

Every resource has a stable ID (e.g., `pool_k3R-nX9vLm7Qp2Yw5Jd8F`). IDs never change for the
lifetime of the resource. The API derives resource paths from the resource's name, workspace, and
organization, so they change when any of those change. If you rename a pool from `training-pool` to
`inference-pool`, its ID stays the same but its resource path changes.

Use IDs for automation and integrations that need stable references. Use resource paths for
convenience in the CLI and ad-hoc API calls.

API responses include both.

```json theme={null}
{
  "object": "pool",
  "id": "pool_k3R-nX9vLm7Qp2Yw5Jd8F",
  "resource_path": "sfc:pool:acme:production:training-pool",
  "workspace": {
    "id": "wksp_7Yb-Ht2mNq4Rx8Wc1Ke5P",
    "name": "production"
  },
  "name": "training-pool"
}
```

## Using resource paths in the CLI

The CLI accepts resource paths wherever you would use a name.

```bash theme={null}
# Get an instance from another workspace by resource path
sf instances get sfc:instance:acme:staging:worker-1

# Transfer compute across workspaces using resource paths
sf pools transfers create \
  --from sfc:pool:acme:ml-team:unallocated \
  --to sfc:pool:acme:inference-team:unallocated \
  --count 10 \
  --start-at "tomorrow" \
  --duration 7d \
  --sku sku_4UpxzQw7A8N
```

## Using resource paths in the API

Anywhere the API accepts a resource ID, it also accepts a resource path. This includes path
parameters, request body fields, and query parameters. The API resolves a resource path to the
underlying ID before processing the request. These 2 requests are equivalent.

```http theme={null}
GET /v2/pools/pool_k3R-nX9vLm7Qp2Yw5Jd8F
GET /v2/pools/sfc:pool:acme:production:training-pool
```

Resource paths also work in request bodies that reference other resources. This is useful for
cross-workspace references, where you can target a resource in another workspace without switching
context. Fields that reference resources without user-settable names, like `sku`, take IDs only. For
example, this `POST /v2/instances` body references a pool and an image in another workspace by
resource path.

```json theme={null}
{
  "pool": "sfc:pool:acme:shared:training-pool",
  "image": "sfc:image:acme:shared:cuda-12-7",
  "sku": "sku_9Fd-Lz6pQw3Vn1Ay8Rk4T"
}
```

## Next steps

* [Workspaces](/preview/workspaces) explains the workspace layer that scopes most resource paths.
* [Pools](/preview/pools) covers the pools these examples reference.
* [Using the API](/preview/using-the-api) covers authentication and request basics.


# Roadmap
Source: https://docs.sfcompute.com/preview/roadmap

Development priorities, feature states, and the public preview support policy

See which features you can use today, how much support each state gets, and where the platform is
headed.

## Development priorities

1. Expanding our capabilities as a public cloud. We build core primitives for buying, managing,
   and orchestrating compute, then layer higher-level functionality on top.
2. Increasing liquidity. If you have unused compute, you should be able to resell it and recoup
   some of your compute costs.

## Feature states

Features move through the following states as they mature.

A feature starts in development: we are building it, and it is not yet available. It then enters
private preview. Selected customers get access, so we can validate the design with real usage before
opening it more broadly. Email [support@sfcompute.com](mailto:support@sfcompute.com) to request early access.

In public preview, the feature is available to everyone but may have rough edges. See
[Public preview support](#public-preview-support) for what that means in practice.

Generally available features are production-ready and fully supported under a stable API version
prefix (the versioned URL path; see [Using the API](/preview/using-the-api)). Our
[uptime SLA](https://sfcompute.com/legal/sla) covers them.

When we retire a feature, it reaches planned end of life first. It still works, but you should
migrate to the recommended alternative. At end of life, it is no longer available or supported.

## Public preview support

Preview features are available to everyone. Their API paths, response shapes, CLI flags, and error
codes may change while the design settles. We support preview features on a best-effort basis, and
our uptime SLA does not cover them.

## Public preview features

* [Instance templates](/preview/instance-templates) - define reusable instance configurations
* [Deployments](/preview/deployments) - automate instance creation and management
* [Orderbook](/preview/orderbook) - view market depth and pricing
* [Tags](/preview/tags) - organize resources with key-value pairs
* [Image versions](/preview/images#using-an-image) - pin an instance to one exact image build
* [Reselling](/preview/guides/reselling) - resell unused allocation on the orderbook
* [Interruptible buy orders](/preview/orders#interruptible-buy-orders) - buy past your compute limit
  by listing the compute for sale

## Generally available features

* [Pools](/preview/pools) - manage your compute allocation
* [Orders](/preview/orders) - buy and sell compute time
* [Instances](/preview/instances) - launch and operate GPU instances
* [SKUs](/preview/instance-skus) - pick the hardware your orders run on
* [Images](/preview/images) - build, upload, and manage custom images
* [Workspaces](/preview/workspaces) - group resources to isolate teams or environments
* [Resource paths](/preview/resource-paths) - reference resources by name across the API and CLI

## Feedback

If something is confusing, missing, or broken, reach out through your existing support channel or
email [support@sfcompute.com](mailto:support@sfcompute.com).


# Roles
Source: https://docs.sfcompute.com/preview/roles

Create and manage roles, named sets of permissions you assign with grants

<div>
  <Info>
    This feature is in [public preview](/preview/roadmap#feature-states).
  </Info>
</div>

SF Compute uses role-based access control (RBAC). A role is a named set of permissions that defines
what actions the holder can perform. A [grant](/preview/grants) assigns a role to a user or token
within a workspace or across the organization.

When a request arrives, SF Compute collects the caller's grants and evaluates every matched role's
rules. It allows the action only if a matched rule grants it. Otherwise SF Compute denies it.

A role name must start with a letter or number. After that, it can contain letters, numbers, dots,
hyphens, and underscores, up to 255 characters.

Role names are unique within the organization. Roles are organization-wide. The same role can be
granted across multiple workspaces.

## Built-in roles

Built-in roles cover common patterns, so you often don't need a custom role. List every role in the
organization with the CLI.

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

```text theme={null}
------------------------------------------------------------------------------------------
NAME               TYPE      DESCRIPTION
admin              built_in  Full access to all resources
viewer             built_in  Read-only access to all resources
operator           built_in  Infrastructure management, no IAM access
billing            built_in  Billing and orders only
workspace-admin    built_in  Full workspace management without purchasing
member             built_in  Standard org member: read-only across non-sensitive resources
training-operator  custom    Can manage instances and view pools
```

You cannot modify or delete built-in roles.

### Admin role

Full access to all resources. Use sparingly.

```toml theme={null}
api_version = "roles/v1"
description = "Full access to all resources"

[[rules]]
effect = "allow"

[rules.actions]
"*" = ["*"]
```

### Viewer role

Read-only access to all resources.

```toml theme={null}
api_version = "roles/v1"
description = "Read-only access to all resources"

[[rules]]
effect = "allow"

[rules.actions]
"*" = ["read", "list"]
```

### Operator role

Full access to infrastructure resources, with no access to identity and access management (IAM:
roles, grants, tokens), billing, or orders.

```toml theme={null}
api_version = "roles/v1"
description = "Infrastructure management, no IAM access"

[[rules]]
effect = "allow"

[rules.actions]
instance             = ["*"]
instance_template    = ["*"]
image                = ["*"]
pool                 = ["*"]
deployment           = ["*"]
procurement          = ["*"]
secret               = ["*"]
ssh_key              = ["*"]
firewall             = ["*"]
subnet               = ["*"]
infiniband_partition = ["*"]
```

### Billing role

Full access to billing and orders, plus read-only access to limits. No infrastructure access. Good
for finance teams.

```toml theme={null}
api_version = "roles/v1"
description = "Billing and orders only"

[[rules]]
effect = "allow"

[rules.actions]
billing = ["*"]
order   = ["*"]
limits  = ["read"]
```

### Workspace-admin role

Full management of a workspace and everything in it — including granting others access to it —
but no purchasing: orders, procurements, and deployments are read-only. Granted automatically,
scoped to the new workspace, to whoever creates a workspace.

```toml theme={null}
api_version = "roles/v1"
description = "Full workspace management without purchasing"

[[rules]]
effect = "allow"

[rules.actions]
workspace            = ["*"]
grant                = ["*"]
role                 = ["read", "list"]
instance             = ["*"]
instance_template    = ["*"]
image                = ["*"]
pool                 = ["*"]
secret               = ["*"]
ssh_key              = ["*"]
firewall             = ["*"]
subnet               = ["*"]
infiniband_partition = ["*"]
order                = ["read", "list"]
procurement          = ["read", "list"]
deployment           = ["read", "list"]
```

### Member role

Read and list access across non-sensitive resources, with no access to secrets, billing, tokens, or
SSH keys. This is the default role users hold when they join an organization.

```toml theme={null}
api_version = "roles/v1"
description = "Standard org member: read-only across non-sensitive resources"

[[rules]]
effect = "allow"

[rules.actions]
instance             = ["read", "list"]
instance_template    = ["read", "list"]
image                = ["read", "list"]
pool                 = ["read", "list"]
deployment           = ["read", "list"]
procurement          = ["read", "list"]
firewall             = ["read", "list"]
subnet               = ["read", "list"]
infiniband_partition = ["read", "list"]
role                 = ["read", "list"]
grant                = ["read", "list"]
order                = ["read", "list"]
limits               = ["read", "list"]
```

## Creating a role

Write a role definition in TOML and pass it to the CLI.

```bash theme={null}
sf roles create --name training-operator -f role.toml
```

In this example, `role.toml` contains the following definition.

```toml theme={null}
api_version = "roles/v1"
description = "Can manage instances and view pools"

[[rules]]
effect = "allow"

[rules.actions]
instance = ["*"]
pool     = ["read"]
ssh_key  = ["*"]
secret   = ["read"]
```

`api_version` must be `roles/v1`.

A role grants nothing on its own. [Create a grant](/preview/grants) to assign it to a user or
[token](/preview/tokens).

## Rule syntax

A rule says what a user or token is allowed to do. It has 2 pieces.

* An `actions` map, which pairs each resource (such as `instance` or `pool`) with a list of verbs
  (such as `read` or `write`).
* An `effect` sets what the rule grants for those actions. It takes one of these values.
  * `allow`: perform the action directly, request approval for it, and approve others' approval
    requests.
  * `require_approval`: request approval for the action, but not perform it directly or approve
    others' requests.
  * `approve_approval`: approve others' approval requests for the action, but not perform it
    directly or request approval.

A caller whose rules grant both `require_approval` and `approve_approval` for an action can perform
it directly, the same as `allow`.

For example, this role lets the holder read, update, delete, and list instances.

```toml theme={null}
api_version = "roles/v1"
description = "Instance management"

[[rules]]
effect = "allow"

[rules.actions]
instance = ["read", "write", "delete", "list"]
```

### Supported resources and verbs

The supported resources are `instance`, `instance_template`, `image`, `pool`, `deployment`,
`procurement`, `secret`, `ssh_key`, `firewall`, `subnet`, `infiniband_partition`, `role`, `grant`,
`token`, `approval`, `billing`, `order`, `limits`, `user`, `workspace`, and `*`.

The supported verbs are `read`, `write`, `delete`, `list`, `create`, and `*`.

Each rule covers every `(resource, verb)` pair you list. Use `"*"` as either the resource or the
verb for a wildcard.

These patterns cover common needs.

```toml theme={null}
instance = ["read"]           # Read instance details
instance = ["create"]         # Create instances
instance = ["write"]          # Update instances
instance = ["delete"]         # Delete instances
instance = ["*"]              # All instance actions
pool     = ["read"]           # View pool details
pool     = ["write"]          # Update pools
order    = ["read"]           # View orders
order    = ["create"]         # Place buy/sell orders
billing  = ["read"]           # View balance, usage, invoices, rates
billing  = ["write"]          # Update billing settings
limits   = ["read"]           # View hard and soft limits
secret   = ["read"]           # Read secrets from metadata service
firewall = ["*"]              # Manage firewalls
token    = ["*"]              # Manage tokens
ssh_key  = ["*"]              # Manage SSH keys
"*"      = ["*"]              # Everything (equivalent to admin)
```

If no rule matches, SF Compute denies the action.

## Listing and inspecting roles

List all roles, or fetch one by name.

```bash theme={null}
sf roles list
sf roles get training-operator
```

## Updating a role

Replace a role's definition from a TOML file.

```bash theme={null}
sf roles set training-operator -f role-v2.toml
```

Changes take effect immediately for all grants that reference this role. SF Compute re-evaluates
existing sessions on the next API call.

## Deleting a role

Deleting a role removes it from any grants that reference it. You cannot undo this.

```bash theme={null}
sf roles delete training-operator
```

## Example roles

These definitions cover common team setups; adapt them to your resources, and assign them with
[grants](/preview/grants).

### CI/CD deployer

For a CI/CD (continuous integration and delivery) pipeline. Full access to instances, read access to
pools, secrets, and SSH keys, and nothing else.

```toml theme={null}
api_version = "roles/v1"
description = "CI/CD pipeline - deploy and teardown training jobs"

[[rules]]
effect = "allow"

[rules.actions]
instance = ["*"]
pool     = ["read"]
secret   = ["read"]
ssh_key  = ["read"]
```

### Researcher

Can use existing infrastructure but not modify pools or access controls.

```toml theme={null}
api_version = "roles/v1"
description = "Researcher - run training jobs on allocated pools"

[[rules]]
effect = "allow"

[rules.actions]
instance = ["read", "write", "list"]
ssh_key  = ["*"]
secret   = ["read"]
```

### Finance

View billing data, update billing settings, and view orders. No infrastructure access.

```toml theme={null}
api_version = "roles/v1"
description = "Finance - view spending and invoices, update billing settings, view orders"

[[rules]]
effect = "allow"

[rules.actions]
billing = ["read", "write"]
order   = ["read"]
```

## API reference

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


# Tags
Source: https://docs.sfcompute.com/preview/tags

Track and organize resources with key-value pairs

Tags are `key=value` pairs that help you track and organize resources on SF Compute.

## Create tags

Set tags when you create a resource with the `--tag` flag.

```bash theme={null}
sf pools create --name root --tag model=cuda-crunch
```

## Edit tags

The `set` command replaces all existing tags on a resource. Pass every tag you want to keep.

```bash theme={null}
sf instances set prod --tag model=cuda-crunch --tag env=prod
```

## Delete tags

To delete all tags on a resource, set `--tag null`. You cannot recover deleted tags.

```bash theme={null}
sf pools set dev --tag null
```

To remove a single tag, re-run `set` with only the tags you want to keep.

## List resources by tags

Filter resources by tag with the `--tag` flag.

```bash theme={null}
sf instances list --tag model=cuda-crunch
```

```text theme={null}
-----------------------------------------------------------------------------
NAME  STATUS   POOL  INSTANCE SKU  CREATED        TAGS
prod  running  root  -             Mar 1, 9:00am  model=cuda-crunch, env=prod
```

To match any value for a key, filter with the `--tag-key` flag.

```bash theme={null}
sf instances list --tag-key env
```

```text theme={null}
-----------------------------------------------------------------------------
NAME  STATUS   POOL  INSTANCE SKU  CREATED        TAGS
prod  running  root  -             Mar 1, 9:00am  env=prod, model=cuda-crunch
```

## Constraints

Tag keys must not contain spaces, commas, or equals signs, and must not begin with an underscore
(`_`). Keys can be up to 128 characters.

Tag values must not contain commas or equals signs. Values may contain spaces and can be up to 256
characters.

Tags are case sensitive. You can add up to 50 tags to each resource.


# Tokens
Source: https://docs.sfcompute.com/preview/tokens

Create and manage bearer tokens that authenticate API and CLI requests

Tokens authenticate requests to the SF Compute API. Use tokens for CI/CD (continuous integration and
delivery) pipelines, automation, and service accounts. Tokens use the `sk_live_` prefix.

## Creating a token

A token applies to your whole organization, not to a single workspace. Creating or deleting a token
requires a role with `token` permissions. See [Roles](/preview/roles#supported-resources-and-verbs).

```bash theme={null}
sf tokens create --name deploy
```

The CLI prints the token value (`sk_live_...`) once, at creation. Store it somewhere safe. You can't
retrieve it again.

To set an expiry, pass a duration with `--expires`.

```bash theme={null}
sf tokens create --name ci-runner --expires 90d
```

Without `--expires`, interactive runs prompt for an expiration and non-interactive runs default to
90 days. Pass `--no-expire` to create a token that never expires.

## Attaching a role

A token with no role attached cannot do anything. Attach a role at creation time with `--role`, and
pass `--workspace` to limit it to 1 workspace or `--org` to apply it organization-wide.

```bash theme={null}
sf tokens create --name ci-deploy --role training-operator --workspace production
```

`training-operator` is a custom role you create yourself. To run this as-is, attach a built-in role
like `operator`. See [Roles](/preview/roles).

As with other commands, `-w` and `SF_WORKSPACE` also set the workspace. `--org` overrides
`SF_WORKSPACE`, and can't be combined with `-w` or `--workspace`. With no workspace and no `--org`,
interactive runs let you pick a workspace or organization-wide, and non-interactive runs exit with
an error, so scripts pass `--workspace` or `--org`.

Pass `--role` multiple times to attach more than one role. Every role gets the same scope. Running
`sf tokens create` without `--role` shows an interactive multi-select picker over your available
roles.

To grant a role to an existing token, use `sf grants create`. See
[Grants](/preview/grants#token-grants).

## Listing tokens

List every token in your organization.

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

```text theme={null}
-----------------------------------------------------------
NAME    SUFFIX   CREATED         LAST USED  EXPIRES
deploy  ...FHbI  Mar 1, 12:00pm  Never      May 30, 12:00pm
admin   ...XyZ1  Feb 15, 9:00am  Never      May 16, 9:00am
```

## Deleting a token

Delete a token by name.

```bash theme={null}
sf tokens delete deploy
```

Deleting a token revokes it immediately. In-flight requests authenticated with the token fail.

## Using a token

See [Using the API](/preview/using-the-api) to authenticate requests with your token.


# Using the API
Source: https://docs.sfcompute.com/preview/using-the-api

Authenticate and make your first API request

The API is available at `https://api.sfcompute.com/v2`. All requests require a
Bearer token.

The API exposes the same resource model as the CLI. Pools hold an allocation schedule, orders buy
and sell compute time, and instances run on pools. If that model is new, start with
[Instances and Pools](/preview/guides/instances-and-pools) before wiring the API into an
application.

## Create an API token

Create a token with the CLI.

```bash theme={null}
sf tokens create --name my-token
```

This prints a token starting with `sk_live_`. Save it somewhere safe. You can't retrieve it again.

## Grant permissions

Tokens start with no permissions. Grant access to the resources your token needs. These examples use
a workspace named `my-workspace`; every new organization starts with one named `default`.

```bash theme={null}
sf grants create --token my-token --role admin --workspace my-workspace
```

The `admin` role grants full access to the workspace; give production tokens a narrower role. See
[Roles](/preview/roles) and [Grants](/preview/grants) for how permissions work, and the
[Quickstart](/preview/quick-start) for more on workspaces.

## Make a request

Replace `my-account` with your organization name (shown by `sf me` or in the dashboard). Replace
`<token>` with the token you created above.

```bash theme={null}
curl 'https://api.sfcompute.com/v2/pools?workspace=sfc:workspace:my-account:my-workspace' \
  -H "Authorization: Bearer sk_live_..."
```

API workflows follow the same shape as the [Quickstart](/preview/quick-start).

1. Create or choose a pool.
2. Place a buy order to add allocation.
3. Create instances on the pool.
4. Read pool, order, and instance state to track what happened.

## API reference

Browse every endpoint, with request parameters and response shapes, in the sidebar. Start with the
[Pools API](/api-reference/pools/list-pools).


# Workspaces
Source: https://docs.sfcompute.com/preview/workspaces

Group resources to isolate teams or environments

A workspace groups resources within an organization. Pools, instances, instance templates,
deployments, images, subnets, and tags all belong to a workspace. Every new organization comes with
a workspace named `default`. It's not special: you can rename it through the
[API](/api-reference/workspaces/update-workspace) or delete it like any other workspace.

## Create a workspace

Workspace names are unique within your organization.

```bash theme={null}
sf workspaces create --name production
```

## List workspaces

The arrow in the leftmost column marks the active workspace.

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

```text theme={null}
-----------------------------
  NAME        CREATED
  default     Mar 1, 12:00am
→ production  Jun 15, 12:00am
  staging     Jun 15, 12:00am
```

## View a workspace

Get a workspace by name, or omit the name to get your active workspace.

```bash theme={null}
sf workspaces get production
```

```text theme={null}
| WORKSPACE      production
| ID             wksp_8fJq2LpXw4RkT7vY3mN5c
| RESOURCE PATH  sfc:workspace:acme:production
| CREATED        Jun 15, 12:00am PDT
```

## Set your active workspace

If you haven't set an active workspace, the CLI falls back to `default`. Set one with
`sf workspaces use <name>`. Override per-command with `--workspace <name>`.

```bash theme={null}
sf workspaces use production
sf instances list --workspace staging   # one-off override
```

## Every request targets a workspace

Every API request that creates, lists, or operates on workspace-scoped resources targets a
workspace. Not all resources are workspace-scoped; see [resource paths](/preview/resource-paths) for
which resources live at which scope.

* Creating resources: include `"workspace"` in the request body. Resources created on a pool
  (instances, deployments, and orders) are the exception. They inherit the pool's workspace, so you
  choose the workspace when you create the pool.
* Listing resources: pass `?workspace=` as a query parameter.
* Getting a single resource: use a [resource path](/preview/resource-paths) or an ID.

On the CLI, pass `--workspace`.

```bash theme={null}
# Create a pool in a specific workspace. Instances created on this pool
# inherit its workspace.
sf pools create --name training-cluster --workspace production

# List instances in a workspace
sf instances list --workspace production
```

## Cross-workspace references with resource paths

Every resource has a [resource path](/preview/resource-paths) that embeds the workspace. Use a
resource path anywhere you can pass a name or ID. It lets you reference resources in another
workspace without switching context.

```bash theme={null}
# Create an instance on a pool in the `shared` workspace without switching
# your active workspace. The instance is created in `shared`, since an
# instance inherits its pool's workspace.
sf instances create --pool sfc:pool:acme:shared:training-pool \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 \
  --cloud-init ./startup.sh \
  --sku sku_4UpxzQw7A8N
```

## Delete a workspace

Deletion fails if the workspace still contains pools, instance templates, images, subnets, or custom
firewalls. Move or delete them first.

```bash theme={null}
sf workspaces delete staging
```

## API reference

See the [Workspaces API](/api-reference/workspaces/list-workspaces) for programmatic
access.