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

# Workspaces

> Give every user a private workspace and let teams share one, with role-based access and full isolation of files, chats and skills.

Multi-workspace mode gives every user a private personal workspace and lets
members of an organization share team workspaces. Each workspace is a complete
context: its own files, chats, `AGENT.md`, skills and key-value store.

```python theme={null}
web = (
    cycls.Web()
    .auth(cycls.Clerk())
    .workspaces()                  # anyone in the org can create teams
)

web = cycls.Web().auth(cycls.Clerk()).workspaces(create="admin")
```

It requires auth, since workspaces are keyed on the authenticated user.

## The model

| Workspace | Id            | Who can enter                                           | Managed by                         |
| --------- | ------------- | ------------------------------------------------------- | ---------------------------------- |
| Personal  | `u-{user_id}` | the owner only. Org admins get lifecycle, never content | the owner                          |
| Team      | `t-{id}`      | members on the ACL, plus org admins implicitly          | the creator and any `admin` member |
| General   | `t-shared`    | every org member as editor, minus anyone excluded       | org admins                         |

Every organization gets **General** on its first request. Solo users without an
organization get a personal workspace only.

Team roles are `owner`, who created it and can delete it, `admin`, who manages
members and renaming, and `editor`, who works in the workspace. The owner row
cannot be changed, and members can always remove themselves.

## Selecting one

The client sends the active workspace in an `X-Workspace` header on every
request. No header means the personal workspace, so existing API clients keep
working unchanged.

```bash theme={null}
curl https://my-agent.cycls.ai/files \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace: t-abc123"
```

Unknown or unauthorized ids return 404 rather than 403, so ids do not leak
existence.

## Inside the agent

`context.workspace` resolves to the active workspace. The bash sandbox binds only
that workspace's directory at `/workspace`, and uploads, the canvas, `AGENT.md`
and skills all follow it.

Chats and the `database` tool stay per user within a workspace. Teammates share
files, not each other's conversations.

## HTTP API

Mounted only when workspaces are enabled. All routes require auth.

| Method   | Path                                 | Purpose                                                                |
| -------- | ------------------------------------ | ---------------------------------------------------------------------- |
| `GET`    | `/workspaces`                        | personal plus your teams. `?all=1` gives org admins the lifecycle view |
| `POST`   | `/workspaces`                        | create a team, body `{"name": ..., "icon"?: "🚀"}`                     |
| `PATCH`  | `/workspaces/{id}`                   | rename or set the icon, one emoji, owner or admin                      |
| `DELETE` | `/workspaces/{id}`                   | owner or org admin                                                     |
| `GET`    | `/workspaces/{id}/members`           | members, or exclusions on General                                      |
| `PUT`    | `/workspaces/{id}/members/{user_id}` | body `{"role": "editor" \| "admin"}`                                   |
| `DELETE` | `/workspaces/{id}/members/{user_id}` | managers, or yourself to leave                                         |

Adding a member takes their user id from the identity provider. The row alone
grants nothing: access also needs a valid token for the same organization, so a
stray id is inert.

## Turning it on for an existing deployment

The SDK moves no data. On an organization's first request it creates General's
registry row and nothing else. Existing content under the organization root stays
where it is and is invisible in workspace mode until an operator migrates it.
Solo accounts need no migration at all, because their personal workspace is the
account root.

## Security notes

<AccordionGroup>
  <Accordion title="Sandbox isolation">
    The bash sandbox binds only the active workspace at `/workspace`. Sibling
    workspaces are not mounted. Registry and ACL rows live outside every workspace
    root, out of reach of both the sandbox and the path-validated file tools.
  </Accordion>

  <Accordion title="Shared instructions are shared trust">
    `AGENT.md` and `skills/` are per workspace, so in a team any editor's
    instructions run in teammates' sessions. It is the same trust boundary as a
    shared repository, and worth saying out loud to your users.
  </Accordion>

  <Accordion title="Network-enabled bash">
    A deliberately adversarial user with network-enabled bash can reach the
    deployment's own credentials. `.sandbox(network=False)` closes that path.
  </Accordion>
</AccordionGroup>

## Next

<Card title="Monetization" icon="credit-card" href="/web/monetization">
  Plans, quotas, and in-app purchase entitlements.
</Card>