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, evaluates the rules from every matched role, and allows the action only if a rule matches. Otherwise it is denied. Role names are slugs, unique within the organization. Roles are organization-wide. The same role can be granted across multiple workspaces.

Creating a role

Write a role definition in TOML and pass it to the CLI.

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

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. actions is a map from resource name to a list of verbs. Use "*" as either the verb or the resource for a wildcard. 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 two 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 that says what to do about those actions. Only allow is currently supported.

api_version = "roles/v1"
description = "Instance management"

[[rules]]
effect = "allow"

[rules.actions]
instance = ["read", "write", "delete", "list"]

Supported resources and verbs

Resources: instance, instance_template, image, pool, secret, ssh_key, firewall, role, grant, token, billing, order, limits, user, * Verbs: read, write, delete, list, create, * Each rule covers every (resource, verb) pair you list. Use "*" as either the resource or the verb for a wildcard. Common patterns:

instance = ["read"]           # Read instance details
instance = ["write"]          # Create or update instances
instance = ["delete"]         # Delete instances
instance = ["*"]              # All instance actions
pool     = ["read"]           # View pool details
pool     = ["write"]          # Create pools, attach schedulers
order    = ["read"]           # View orders
order    = ["write"]          # Place buy/sell orders
billing  = ["read"]           # View balance, usage, invoices, rates
billing  = ["write"]          # Create and manage budgets
limits   = ["read"]           # View hard and soft limits
limits   = ["write"]          # Set and remove 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, the action is denied.

Built-in roles

SF Compute provides built-in roles that cover common patterns.

sf roles list

NAME                  TYPE       DESCRIPTION
admin                 built-in   Full access to all resources in the workspace
viewer                built-in   Read-only access to all resources
operator              built-in   Infrastructure management, no IAM access
billing               built-in   Billing and orders only, no infrastructure
member                built-in   Standard org member: read-only across non-sensitive resources
training-operator     custom     Can manage instances and view pools

Built-in roles cannot be modified or deleted.

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. Cannot make any changes.

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 — instances, instance templates, images, pools, secrets, firewalls, SSH keys, and more — with no access to IAM (roles, grants, tokens) and no broader read access.

Billing role

Access to billing and orders only. 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"]

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.

Listing and inspecting roles

sf roles list
sf roles get training-operator

Updating a role

sf roles set training-operator -f role-v2.toml

Changes take effect immediately for all grants that reference this role. Existing sessions are re-evaluated on the next API call.

Deleting a role

Deleting a role removes it from any grants that reference it. This cannot be undone.

sf roles delete training-operator

Example roles

CI/CD deployer

Can create and delete instances, read pools, manage no other resources.

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, manage budgets, and view orders. No infrastructure access.

api_version = "roles/v1"
description = "Finance - view spending and invoices, manage budgets, view orders"

[[rules]]
effect = "allow"

[rules.actions]
billing = ["read", "write"]
order   = ["read"]

​Creating a role

​Rule syntax

​Supported resources and verbs

​Built-in roles

​Admin role

​Viewer role

​Operator role

​Billing role

​Member role

​Listing and inspecting roles

​Updating a role

​Deleting a role

​Example roles

​CI/CD deployer

​Researcher

​Finance

Creating a role

Rule syntax

Supported resources and verbs

Built-in roles

Admin role

Viewer role

Operator role

Billing role

Member role

Listing and inspecting roles

Updating a role

Deleting a role

Example roles

CI/CD deployer

Researcher

Finance