Roles - San Francisco Compute Docs

This feature is in public preview.

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

sf roles list

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

api_version = "roles/v1"
description = "Full access to all resources"

[[rules]]
effect = "allow"

[rules.actions]
"*" = ["*"]

Viewer role

Read-only access to all resources.

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.

api_version = "roles/v1"
description = "Infrastructure management, no IAM access"

[[rules]]
effect = "allow"

[rules.actions]
instance             = ["*"]
instance_template    = ["*"]
image                = ["*"]
node                 = ["*"]
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.

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.

api_version = "roles/v1"
description = "Full workspace management without purchasing"

[[rules]]
effect = "allow"

[rules.actions]
workspace            = ["*"]
grant                = ["*"]
role                 = ["read", "list"]
instance             = ["*"]
instance_template    = ["*"]
image                = ["*"]
node                 = ["*"]
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.

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"]
node              = ["read", "list"]
pool              = ["read", "list"]
deployment        = ["read", "list"]
procurement       = ["read", "list"]
firewall          = ["read", "list"]
subnet            = ["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.

sf roles create --name training-operator -f role.toml

In this example, role.toml contains the following definition.

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 to assign it to a user or token.

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.

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, node, 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.

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.

sf roles list
sf roles get training-operator

Updating a role

Replace a role’s definition from a TOML file.

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.

sf roles delete training-operator

Example roles

These definitions cover common team setups; adapt them to your resources, and assign them with 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.

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.

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.

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 for programmatic access.

​Built-in roles

​Admin role

​Viewer role

​Operator role

​Billing role

​Workspace-admin role

​Member role

​Creating a role

​Rule syntax

​Supported resources and verbs

​Listing and inspecting roles

​Updating a role

​Deleting a role

​Example roles

​CI/CD deployer

​Researcher

​Finance

​API reference

Built-in roles

Admin role

Viewer role

Operator role

Billing role

Workspace-admin role

Member role

Creating a role

Rule syntax

Supported resources and verbs

Listing and inspecting roles

Updating a role

Deleting a role

Example roles

CI/CD deployer

Researcher

Finance

API reference