Getting Started

Prerequisites

• Node.js >= 22
• pnpm 9.x (workspace-aware package manager — corepack enable will pick up the version pinned in package.json)
• Docker (for the local Supabase stack — Postgres, Auth, Storage)

Get the code

Pick whichever fits your situation:

# Clone directly
git clone https://github.com/catesandrew/client-os.git my-app
cd my-app

# Or use it as a GitHub template (click "Use this template" on GitHub),
# then clone your new repo

# Or grab a snapshot without git history, via degit
npx degit catesandrew/client-os my-app
cd my-app

Install dependencies

pnpm install

This installs every workspace package under apps/* and packages/* in one pass.

Run the local stack

pnpm dev uses process-compose to boot the whole stack in dependency order — local Supabase, then schema migration, demo data, demo auth accounts, then the API and web servers:

pnpm dev

If you'd rather run pieces individually (for example, iterating on the API without restarting Supabase each time):

pnpm supabase:start
pnpm db:migrate
pnpm db:seed
pnpm --filter @client/api seed:auth   # creates real auth.users for the demo accounts
ENV=dev pnpm --filter @client/api dev
ENV=dev pnpm --filter apps-web dev

ENV=dev tells @cogs/config to load each app's .env.dev + .env.dev.local files.

Where things run

Service	URL
Web	http://localhost:3010
API	http://localhost:4010
Supabase Auth	http://127.0.0.1:55621/auth/v1
Supabase Studio	http://127.0.0.1:55623

Demo accounts

Seeded by seed:auth (password password123 for all three — see DEV_SEED_ACCOUNTS/DEV_SEED_PASSWORD in apps/api/.env.dev):

Email	Role
admin@client-os.local	org:admin
contributor@client-os.local	org:contributor
viewer@client-os.local	org:viewer

Log in at http://localhost:3010 with any of these to see the authed shell and the seeded clientos CRM demo data (acme-corp).

Next steps

• Read Architecture to understand how the pieces fit together.
• Walk through Usage Examples to see how to extend the CRM domain, use the CLI, and use the clientos-context skill.