# Projects and workspaces

> How Helix is organized: organizations contain workspaces, workspaces contain projects, and permissions are granted at the workspace level.

Helix organizes everything in a three-level hierarchy: an organization contains workspaces, and each workspace contains projects. Permissions are granted at the workspace level and apply to every project in that workspace; there are no project-level permissions. A project is a deploy target: the unit that owns a production URL and the resources a deploy provisions.

## The hierarchy

```
Organization (Acme)
  Workspace: engineering
    Project: customer-health
    Project: deal-pipeline
  Workspace: finance
    Project: invoice-tracker
```

- The **organization** is your company's account. Org admins operate across all workspaces: they manage membership, define org-wide policies, configure SSO, set AI gateway budgets, inject org-level middleware, and read audit logs.
- A **workspace** groups related projects, typically per team or department. Membership and roles are set here, and the workspace determines billing, region, and infrastructure settings for its projects.
- A **project** is one codebase: functions, an optional SPA, a database schema, and a config file. Deploying a project provisions its resources and publishes it at `https://{project-id}.helix-app.ai`.

## Permissions attach to the workspace

Access to a workspace grants access to all projects in it, at whichever role you hold. There is no per-project grant, so the way to isolate a sensitive project is to give it its own workspace.

| Role | Scope | What it can do |
|---|---|---|
| Org admin | All workspaces | Everything: manage workspaces and members, define org policies, configure SSO and the AI gateway, inject org middleware, view all audit logs, manage billing |
| Workspace admin | One workspace | Full control of its projects: manage members and roles, create and delete projects, deploy and roll back, manage authentications, override project settings |
| Workspace editor | One workspace | Create and deploy projects, edit code and settings, manage authentications, view project data, logs, and metrics |
| Workspace reader | One workspace | Read only: view code, configuration, data, logs, and deployment history. Sees which credentials are configured, never their values |

:::note{title="Workspace roles are not app roles"}
These roles govern who can build and operate projects. Who can use a deployed app, and what they can do inside it, is a separate system: Helix Identity handles end-user SSO and per-function access rules. See [governance](/documentation/governance/).
:::

## What lives where

The split follows one rule: workspaces hold what projects share, projects hold what a deploy provisions.

In the workspace:

- **Authentications.** Credential records are created and managed at the workspace level and shared across its projects. `ctx.http.authed('alias')` resolves against the workspace's auth service even during local development, and agent tooling discovers which authentications are available by asking the workspace.
- **Workspace-scoped KV.** A key-value scope available to every project in the workspace.
- **Billing, region, and infrastructure.** The workspace ties projects to a Helix account and determines region, runtime, and memory settings. None of this is configured per project.

In the project:

- **The deploy target.** The project UUID names the production subdomain and the platform resources a deploy provisions: database, KV, file storage, queues.
- **Variables and secrets.** Set per project with `helix vars` and read by the config file's `requireEnv` thunks when the CLI loads it.
- **The code itself.** Functions, SPA, schema, and configuration, all in one repository.

## How config ties the two together

The config file names its workspace, and optionally its project:

```typescript
// helix.config.ts
import { defineConfig } from '@trayai/helix-sdk';

export default defineConfig({
  name: 'customer-health',
  workspaceId: 'f8e7d6c5-4b3a-2190-8765-abcdef012345', // required: resolves auths
  projectId: 'a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d',   // set once the project exists
});
```

`workspaceId` is required because auth resolution needs it both locally and in production. `projectId` matters only when you deploy, and the first `helix deploy` provisions the project and fills it in. The full model is covered in [the configuration model](/documentation/concepts/configuration/).

---

Canonical: https://helix.tray.ai/documentation/concepts/projects-and-workspaces/
Any link on this page is available as markdown by appending .md to its URL.
Full corpus: https://helix.tray.ai/documentation/llms-full.txt