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

# Workspaces and organizations

> The boundary in which capabilities are owned and operated — workspace types, roles, access modes, and agent visibility.

A workspace is the organizational context in which capabilities are owned, operated, and shared. It contains people, agents, capabilities, deployments, runs, tickets, evidence, discussions, permissions, integrations, credentials, and shared knowledge.

Workspaces provide organizational boundaries, access control, collaboration, discoverability, shared ownership, and operational context. Capabilities should be visible within the appropriate boundary so good work can spread without losing governance.

## The hierarchy

```mermaid theme={null}
flowchart TD
    O["<b>Organization</b>"] --> W1["Org workspace"]
    O --> W2["Team workspace"]
    O --> W3["Team workspace"]
    P["<b>Personal workspace</b><br/>yours alone"]
    W1 --> C1["Capabilities, vaults,<br/>catalogs, members"]
    W2 --> C2["Capabilities, vaults,<br/>catalogs, members"]
```

There are three workspace types.

| Type       | Purpose                           | Notes                                                           |
| ---------- | --------------------------------- | --------------------------------------------------------------- |
| `PERSONAL` | Your own space, created for you   | Cannot be deleted                                               |
| `ORG`      | The organization's root workspace | Cannot be deleted while it has team workspaces                  |
| `TEAM`     | A team inside an organization     | Created with `jstm workspace create --type TEAM --org-id <org>` |

## Roles

Membership is per workspace, and each member holds one role.

| Role     | Can                                                                        |
| -------- | -------------------------------------------------------------------------- |
| `owner`  | Everything, including deleting the workspace                               |
| `admin`  | Manage members, credentials, and settings; audit and scope org credentials |
| `member` | Use the workspace — build, run, and operate agents                         |
| `viewer` | Read the workspace without changing it                                     |

Org-level administration — auditing credentials across every workspace in the org, or changing a credential's scope — requires `owner` or `admin` at the org.

## Access mode

Each workspace has an access mode that controls who can join.

| Mode         | Meaning                                           |
| ------------ | ------------------------------------------------- |
| `OPEN`       | Members of the organization can discover and join |
| `RESTRICTED` | Membership is by invitation only                  |

Set it with `jstm workspace update <workspace> --access-mode RESTRICTED`.

## Agent visibility

Separately from workspace membership, each agent carries a visibility that controls who can find it.

| Visibility    | Who can see it                                                |
| ------------- | ------------------------------------------------------------- |
| `PRIVATE`     | The owning workspace only                                     |
| `ORG_VISIBLE` | Any workspace in the organization can discover and install it |
| `PUBLIC`      | Discoverable beyond the organization                          |

`ORG_VISIBLE` is what makes a good capability spread. Another team finds it with `jstm agent search`, installs it into their own workspace, and runs it with their own credentials — while the original stays owned where it was built.

## Addressing

Almost every identifier accepts three forms: a friendly handle, a UUID, or a fully qualified name like `acme-corp/finance/month-end-close`. Handles can repeat across organizations, so `jstm workspace resolve <handle>` returns every match when a name is ambiguous.

See [Addressing](/cli/addressing) for the full rules.

## Vaults follow the hierarchy

Credentials live in personal, workspace, and org vaults, and resolve from the most specific outward. See [Credentials and vaults](/features/credentials-and-vaults).

## Next

<Columns cols={2}>
  <Card title="Set up your organization" href="/guides/set-up-your-organization" icon="building">
    Create an org, add team workspaces, switch context.
  </Card>

  <Card title="Invite and manage members" href="/guides/invite-and-manage-members" icon="user-plus">
    Roles, invitations, and removal.
  </Card>
</Columns>