Skip to content
AlumiaDocs

Search docs

Find pages, headings, and concepts. Press ⌘K or Ctrl+K to toggle.

Workspaces

Optional sub-org grouping for agents, projects, and members. Ala stays visible everywhere.

Open in ChatGPTOpen in Claude

Workspaces partition an org into smaller groups — typically one per team or department. They are opt-in: an org has them only if workspacesEnabled is set, and most orgs run fine with the implicit default.

When workspaces are enabled

Once enabled, almost every read and write carries a workspace condition. The runtime resolves a WorkspaceScope from the authenticated user:

FieldMeaning
enabledWhether the org has workspaces on.
workspaceIdThe active workspace for this request, or null if the user has no access.

A null workspace ID with enabled: true denies access — queries add false to the condition. With workspaces off, rows are visible to org members according to normal org-scoped application checks and role permissions.

Org-wide vs project-scoped

ResourceScope
Workspaces themselvesOrg-wide table; one row per workspace.
AgentsA primary workspaceId plus optional shares via agent_workspaces; Ala is visible everywhere.
ProjectsA primary workspaceId plus optional shares via project_workspaces.
SessionsInherit workspaceId from the project or agent.
MemoriesFiltered through the workspace scope when enabled.

A project can be shared into multiple workspaces through the project_workspaces join table — useful when one project genuinely belongs to two teams.

Sharing agents across workspaces

A created agent starts in the workspace it was made in, but it can be shared into additional workspaces through the agent_workspaces join table — so one well-tuned agent serves several teams without being duplicated.

  • Manage shares on the agent detail page, or through GET / PATCH /api/v1/agents/:id/workspaces. GET lists the workspaces the agent reaches (you only see workspaces you can access); PATCH sets the full list of workspaceIds.
  • The agent's primary workspaceId is always included — sharing widens reach, it never removes the home workspace.
  • Changing workspace access is a privileged mutation: it needs a browser session with step-up, and the caller must belong to every workspace in the list.
  • Ala can't be reshared (it's already visible everywhere) and managed agents can't change workspace access — both return 403.

Why Ala is special

Ala is the org's default agent. It's intentionally workspace-agnostic:

  • workspaceId is null.
  • The runtime adds an OR slug = 'ala' to every workspace agent filter, so Ala always shows up.
  • It's active by default and can't be deleted.
  • One row per org, deduped on creation.

This means every member, in every workspace, can talk to the same agent and share memories with it. Use Ala when you want one collaborator that knows the whole org; create new agents when you want behavior or tools scoped to specific workspaces — and share those agents into more workspaces as the need grows (below).

Defaults

A new org has one workspace marked isDefault: true. Members join workspaces with a role (owner, admin, member); the role gates membership listings while org-scoped query predicates and ownership checks protect tenant data.

Creating, updating, or deleting workspaces — and adding or removing members — requires a browser session with fresh step-up. API keys cannot perform workspace mutations even for org owners.

POST /api/v1/workspaces/switch sets the active workspace for the session. Deleting the default workspace returns 400; deleting a workspace that still holds projects or agents returns 409.