Installation

Getting processOS running locally.

No Auth0? Run it offline

npm install
npm run qa:local

One command starts Main, the worker, Spell review and Allocation risk on loopback ports with a local identity provider, synthetic seats and seeded data. No Auth0, no .env, no network. See offline local development and acceptance.

The steps below are the Auth0 path, for working against a real tenant.

1. Install

npm install

2. Create `.env`

APP_BASE_URL=http://localhost:3000
NEXT_PUBLIC_APP_BASE_URL=http://localhost:3000

# Auth0 — required (see operations/auth0-setup.md)
AUTH0_DOMAIN=
AUTH0_AUDIENCE=
AUTH0_CLIENT_ID=
AUTH0_CLIENT_SECRET=
AUTH0_SECRET=
AUTH0_MGMT_CLIENT_ID=
AUTH0_MGMT_CLIENT_SECRET=

Copy the rest from applications/main/.env.example as needed. Leave MONGO_URL unset to use file storage in .process-platform/.

Full Auth0 steps: auth0 setup.

3. Run

npm run dev

Open http://localhost:3000 and sign in with Google (Auth0).

The run commands

Command	Starts	Use when
`npm run dev`	Next only	Learning, UI work. Only `input` steps advance.
`npm run dev:all`	Next + worker	You need automated steps to actually run.
`npm run dev-risk`	Next with `NEXT_PUBLIC_FRONTEND_ID=allocation-risk`	Working on the whitelabel skin.
`npm run qa:local`	Identity provider, Main, worker, Spell review and Allocation risk, offline	No Auth0, multi-role walks, agent acceptance. See the guide.

⚠️ npm run dev does not start the worker. If a process reaches a condition, slack_notify, or any non-input step it will sit there forever. That is not a bug — switch to dev:all.

Storage

Selection happens once at startup, in services/storage/index.ts:

`MONGO_URL`	Result
unset	JSON files in `.process-platform/` (gitignored)
set	MongoDB

Missing shipped templates from applications/main/src/templates/registry.ts are gap-filled on read; keys already in storage are left alone. See manage templates and storage.

Switching to MongoDB

Only needed to work against production-shaped data. Requires a mongod on :27017.

MONGO_URL=mongodb://localhost:27017

Restart after changing it — there is no runtime switch. If Mongo is not actually running, every API call returns ECONNREFUSED while the UI loads normally, which reads as a broken app rather than a missing database.