Workspaces - San Francisco Compute Docs

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 or delete it like any other workspace.

Create a workspace

Workspace names are unique within your organization.

sf workspaces create --name production

List workspaces

The arrow in the leftmost column marks the active workspace.

sf workspaces list

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

sf workspaces get production

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

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 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 or an ID.

On the CLI, pass --workspace.

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

# 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-22.04.5-cuda-12.7 \
  --instance-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.

sf workspaces delete staging

API reference

See the Workspaces API for programmatic access.

​Create a workspace

​List workspaces

​View a workspace

​Set your active workspace

​Every request targets a workspace

​Cross-workspace references with resource paths

​Delete a workspace

​API reference