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

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:

// 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.