Workspaces

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.

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.

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

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.

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.

Network-enabled bash

A deliberately adversarial user with network-enabled bash can reach the deployment’s own credentials. .sandbox(network=False) closes that path.

Monetization

Plans, quotas, and in-app purchase entitlements.

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

The model

Selecting one

Inside the agent

HTTP API

Turning it on for an existing deployment

Security notes

Next

Monetization

​The model

​Selecting one

​Inside the agent

​HTTP API

​Turning it on for an existing deployment

​Security notes

​Next

Monetization

The model

Selecting one

Inside the agent

HTTP API

Turning it on for an existing deployment

Security notes

Next