> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sfcompute.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> Group resources to isolate teams or environments

<Warning>
  This feature is in [public preview](/preview/roadmap).
</Warning>

A workspace groups resources within an account. Pools, instances, instance templates,
deployments, procurements, images, subnets, and tags all belong to a workspace. Every new account
comes with a workspace named `default`. It's not special — it can be renamed or deleted like any
other workspace.

## Workspaces have to be specified

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
* Listing resources: pass `?workspace=` as a query parameter
* Getting a single resource: use a [resource path](/preview/resource-paths) or an ID

```bash theme={null}
# Create an instance in a specific workspace
sf instances create --pool training-cluster --workspace production

# List instances in a workspace
sf instances list --workspace production
```

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

## Create a workspace

```bash theme={null}
sf workspaces create --name production
```

## List workspaces

The active workspace is marked with an arrow in the leftmost column.

```bash theme={null}
sf workspaces list
    NAME         CREATED
    default      Mar 1, 2025, 12:00am
  → production   Jun 15, 2025, 12:00am
    staging      Jun 15, 2025, 12:00am
```

## View a workspace

```bash theme={null}
sf workspaces get production
│ WORKSPACE      production
│ ID             ws_4UpxzQw7A8N
│ RESOURCE PATH  sfc:workspace:acme:production
└ CREATED        Jun 15, 2025, 12:00am
```

## Cross-workspace references with resource paths

Every resource has a [resource path](/preview/resource-paths) that embeds the workspace. Resource
paths can be used anywhere a name or ID is accepted, enabling cross-workspace references without
switching context.

```bash theme={null}
# Create an instance in `production` on a pool owned by the `shared` workspace
sf instances create \
  --workspace production \
  --pool sfc:pool:acme:shared:training-pool
```

## Delete a workspace

```bash theme={null}
sf workspaces delete staging
```

Deletion fails if the workspace still contains pools, instance templates, images, or subnets.
Move or delete them first.