Organization, Workspace & Project Hierarchy

The XpressAI Platform uses a three-level hierarchy to organize users, agents, and data. This page explains what each level is, why the hierarchy exists, and how it evolved from a simpler flat model. If you have ever wondered why "Workspace" means something different than you expected, or why personal projects behave differently from team projects, this is the page for you.

The Hierarchy

Organization

An organization is the top-level container. Every user gets one auto-created organization tied to their account (owner_user_id). Organizations exist to support future multi-org scenarios (e.g., a user belonging to both a personal org and a company org), but today the relationship is one-to-one.

Workspace

A workspace groups projects within an organization. One default workspace is auto-created for each organization. Workspaces serve two purposes:

1. Project grouping: logical separation of projects (e.g., "Client Work" vs. "Internal Tools").
2. Integration sharing: integrations (API keys, service connections) are stored at the workspace level and shared across all projects within that workspace.

Why Not Just Use Organizations?

Integrations need a scope narrower than the organization but broader than a single project. A team might want one set of API keys for production projects and a different set for experiments. Workspaces provide that middle layer.

Project

The project is the working unit of the platform. Everything that matters day-to-day lives here:

• Agents: created, configured, and deployed within a project.
• Tasks: assigned to agents within the project.
• Conversations: scoped to the project's participants.
• Files and knowledge: stored on NFS under the project's directory.
• Kubernetes namespace: each project gets its own namespace in the untrusted cluster.

Personal vs. Team Projects

There are two flavors of project, and they behave differently.

Aspect	Personal Project	Team Project
ID format	personal-{userId}	Any other string
Participants	Owner only	Multiple collaborators
NFS path	hdd/user/{userId}/	hdd/user/projects/{projectId}/
K8s namespace	User's personal namespace	Project-specific namespace
Auto-created	Yes, on first login	No, created explicitly

Personal projects are identified by the personal- prefix in their ID. The platform checks projectId.startsWith("personal-") to determine the project type, which affects file path resolution, namespace assignment, and access control.

The "personal" Gotcha

There is a legacy convention where the bare string "personal" (without the userId suffix) may appear as a project ID. The platform expects personal project IDs to follow the personal-{userId} format (e.g., personal-alice). If the bare "personal" string is used instead, the platform does not recognize it as a personal project, which causes files to resolve to the wrong path. The platform normalizes "personal" to "personal-{userId}" internally, but be aware of this if you encounter unexpected path resolution behavior.

How the Hierarchy Evolved

The platform did not always have this structure. Understanding the evolution explains some of the naming quirks you will encounter.

Phase 1: Flat (Just Projects)

Originally, the platform had only projects. Users created projects, added agents, and everything lived in a flat list. This was simple but did not support teams or shared configuration.

Phase 2: Adding Organizations and Workspaces

As the platform grew to support teams, the organization and workspace layers were added above projects. This introduced multi-tenancy (multiple users sharing a project) and integration sharing (API keys at the workspace level).

Phase 3: The "Workspace" Rename

Here is where it gets interesting. Before the organizational hierarchy existed, the term "Workspace" was already in use --- it referred to the agent runtime VMs (virtual machines where agents run desktop applications). When the organizational concept of "Workspace" was introduced, there was a name collision.

The solution: the agent runtime VMs were renamed from "Workspace" to "Desktop". This freed up the term "Workspace" for the organizational concept.

If you see "Desktop" in the codebase or UI, it refers to what used to be called "Workspace" in the runtime/VM sense. If you see "Workspace" in the organizational context, it refers to the project-grouping layer.

tip

If you are reading older code, documentation, or database columns, be aware that "workspace" might refer to either concept depending on when it was written. The rename was incremental, so some legacy references to the old meaning may still exist.

Integration Storage

Integrations (third-party API connections, credentials, webhooks) are stored at the workspace level. This means:

• All projects within a workspace share the same set of integrations.
• Adding a GitHub integration to a workspace makes it available to every project in that workspace.
• Agents in any project can use workspace-level integrations without per-project configuration.

This design avoids the overhead of configuring the same integration separately for each project while still allowing different workspaces to have different configurations.

Access Control

Access control follows the hierarchy:

• Organization owner: full control over everything in the org.
• Workspace member: access to all projects in the workspace.
• Project collaborator: access to a specific project.
• Personal project: only the owner has access (no collaboration).

When the platform checks whether a user can access a resource, it walks up the hierarchy: does the user have access to this project, or to the workspace containing this project, or to the organization containing that workspace?

For details on managing team membership, see Invite Team Members.

Key Takeaways

1. Projects are where the work happens. Agents, tasks, conversations, and files all live at the project level.
2. Workspaces group projects and share integrations. They are the middle layer for configuration sharing.
3. Organizations are the top-level container. Today they are one-per-user, but the data model supports multiple organizations per user if needed in the future.
4. "Desktop" means agent runtime VM. It was renamed from "Workspace" to avoid confusion with the organizational concept.
5. Personal projects use the personal-{userId} format. Always normalize the bare "personal" string before doing path resolution.