PrivOS Onboarding MCP App

The v4 app uses PrivOS Lists for positions, hire records, templates, progress and scores, and PrivOS Files for shared learning materials. HR builds a template per position; each onboarding run gets its own isolated List. Learning days can be opened in any order, and the first quiz score is official.

Current Hub evidence (2026-09-24): the two room registries were created and read back through mcpapp.lists.*. A Ready template containing one week, one day and one lesson saved successfully; after reload, Open displayed the complete tree. One provision case also passed: the current admin account was onboarded from Ready template Kiểm thử Cha P8 2026-09-24 for 2026-09-29; People showed Learning 0/1 day and its drawer showed the correct position, date and status. A/B/C access, file open/download, quiz, cancellation, importer and full P8 manual acceptance remain unrun. A full template copy saved as a new Ready position (1/1/1); disabling that copy removed it from the new-onboarding position picker. See the v4 design, implementation plan and acceptance record.

What it stores

The app creates isolated Lists in the current room through the signed-in user's Hub session:

Hub may rewrite a requested List key, so the app discovers Lists by room and verified name/ID rather than treating the key as authoritative. A template or run List has one physical Stage, Nội dung. All content items are physically flat: Cha:TEXT stores the parent item ID and Thứ tự:NUMBER stores display order. The app reconstructs Tuần → Ngày → Bài học/Câu hỏi for templates and Tổng quan → Tuần → Ngày → Bài học/Câu hỏi for runs. Hub createItem was observed ignoring native parentId; do not use native parentId filters to load this tree. A missing, invalid or cyclic Cha is a data error. Each run item a hire needs must be assigned directly with ASSIGNEE, since the logical tree does not create Hub ACL inheritance.

Shared files belong under the room's Onboarding/<positionItemId>/ folder. Lesson items store a full file object in FILE_MULTIPLE plus a [fileId:...] description marker. Opening or downloading uses fresh file metadata; a temporary signed URL is not stored in Lists.

Related MCP server: HRizzle-HR-Assist

Who sees what

• Room owner/admin — Admin/HR screens for positions, templates, hires and provisioning.

• Assigned hire — "Lộ trình của tôi" for the hire's own run once item grants and discovery are verified on Hub.

Real access enforcement belongs to Hub isolated List ACL, with Isolated_Item_Write_ACL_Enforce enabled by a workspace administrator. The current A/B/C read and write matrix has not been verified on Hub; UI role checks alone are not acceptance evidence.

Member learning flow

The member service exposes listMine() to list the signed-in member's active onboarding runs, load(hireId?) to open the selected run, and resume(hireId) to continue a persisted quiz submission after a reload or interrupted write. The UI selects the newest run by default and lets the member switch to an older active run.

Provisioning writes ASSIGNEE directly to the hire, overview, week, day, lesson and question items. It reads the entire run back and verifies the exact item set and assignee before moving the hire to Đang học. A member can read their roadmap and files, mark lessons read, submit or retake quizzes, and resume a pending submission. The first completed quiz score remains the official score.

The submission journal makes retries of the same operation idempotent and detects conflicting score state before overwriting it. PrivOS Lists currently provide no proven compare-and-swap or atomic append contract, so concurrent submissions from two devices are not claimed as exactly-once. Local typecheck, automated tests, production build and artifact inspection passed on 2026-09-29. Live Hub A/B/C authorization, file download, recovery and full P8 acceptance remain unrun.

Current-room member IDs

For a connected PrivOS SDK instance, read the current room and its member IDs without configuring a room ID:

import { getCurrentRoomMemberIds } from './src/ui/onboarding/data/room-members';

const { roomId, memberIds } = await getCurrentRoomMemberIds(app);

The function reads mcpapp.context.get on each call, selects channels.members for a public room (c) or groups.members for a private room (p), reads all pages, and checks room identity again before returning. Other room types raise ROOM_TYPE_UNSUPPORTED. Denied or unavailable member routes raise ROOM_MEMBERS_UNAVAILABLE; malformed or incomplete member pages also raise errors. The function does not read or create onboarding Lists. rooms:read is a required installation permission because the onboarding form must provide a member selector. The current user must also have access to the room; a manifest declaration alone does not grant access to a stale installation.

Code layout

src/ui/onboarding/ has domain/ models and validation, ports/ typed capabilities, flows/ multi-call operations, data/ Hub adapters and views/ React screens. Lists/Items use mediated mcpapp.* tools through the Hub bridge; Files use the documented tool, REST and upload channels. The server serves the UI and MCP entrypoint; it holds no onboarding data store.

Dependency injection

The browser composition root is src/ui/composition/PrivosOnboardingRoot.tsx; it creates one actor/room session scope, browser effects and PrivOS adapters, then passes typed services to views. src/server.ts composes the MCP handler, assets and runtime lifecycle. Script entries in scripts/ compose Node filesystem, process, prompt and pairing adapters with scripts/core/. Pure modules do not construct default adapters. The compatibility functions in data/privos/ support integration fixtures; production views use the session services.

For a fixed-time test, inject the same port shape used in production:

import { createRequestBudget } from './src/ui/onboarding/data/request-budget';

const budget = createRequestBudget({
  clock: { now: () => new Date('2026-09-25T09:00:00Z') },
  scheduler: { after: () => () => {} },
  isRetryableReadError: () => false,
});

To add another backend, implement the existing port in a new adapter and select it in the relevant composition root. Do not change a flow to import that adapter. Run the local gates from this app directory:

npm run typecheck:all
npm run architecture:check
npx vitest run --exclude tests/packaging.spec.ts --exclude tests/di/bundle-boundaries.spec.ts
npm run build
npx vitest run tests/di/bundle-boundaries.spec.ts

The migration changes source wiring only. It does not change Hub schema, manifest scopes, tool name or UI resource identity. Local gates and live Hub/P8 outcomes are recorded separately in the DI acceptance ledger.

The v1/v2 plans remain in the parent workspace as historical records. Follow the v4 design and acceptance links above for current behavior and test status.

Runtime trust model

@privos_ai/app-server's resolveRuntimeMode() picks exactly one of three modes, in this precedence, and never guesses:

1. managed — a workload identity socket is present (App Cluster mounts one per installation). No pair URL, OAuth client secret, or browser user token is ever used.

2. standalone-production — a paired standalone identity file is present (see Standalone production below).

3. development — neither is present, and NODE_ENV is not production.

Both a workload socket and a paired identity file present is a fatal startup error (stale state from a prior deployment mode, or a misconfigured host — never silently picked). NODE_ENV=production with neither is also a fatal startup error: there is no unsigned-production fallback in any mode.

In managed mode, App Cluster mounts a per-installation Unix socket. @privos_ai/app-server creates an ephemeral P-256 DPoP key in memory, obtains short-lived sender-constrained workload tokens through the socket, and refreshes them without writing credentials to disk or environment variables. Hub-to-app /mcp requests travel through private Cluster dispatch and carry a short-lived signed assertion bound to the request body, installation, replica, receipt hash, and permission epoch. The backend actor passed to handleMcpMessage comes from that verified assertion. The iframe receives only non-secret host context and uses app.rest(), app.uploadFile(), and MCP tools through the Hub bridge as the current user.

Production accepts these non-secret values from the platform:

• PRIVOS_HUB_ORIGIN

• PRIVOS_APP_ID

• PRIVOS_INSTALLATION_ID

• PRIVOS_WORKLOAD_SOCKET (normally /run/privos/identity.sock)

Local development

Requirements: Node.js 22+, npm, Git, and Docker.

git clone https://github.com/PrivOS-AI/privos-mcp-app-demo
cd privos-mcp-app-demo
npm ci
cp .env.example .env
npm run dev

npm run dev resolves to development mode (no workload socket, no paired identity file) and connects over the Relay WebSocket. Obtain a pairing URL from PrivOS Admin and paste it into the prompt; credentials are cached to .env for the next run. This relaxed-compatibility path — no verified backend actor, credentials cached to disk — is only ever reachable when NODE_ENV is not production; the SDK's mode resolver refuses development outright otherwise.

The Vite UI defaults to http://localhost:5179. DEV_TUNNEL=cloudflared is optional when the browser displaying Hub is on another machine.

V4 review in a Hub test room

With the paired Relay configured, start the app from WSL in this app directory:

npm start

prestart builds the production UI automatically. A paired standalone session serves dist/standalone-ui.html, with JS/CSS embedded so Hub does not fetch separate assets. The normal split bundle remains in dist/ui for managed/runtime-v3 installations. For P0 diagnostics only, use NODE_ENV=development PRIVOS_DEV_UI=1 npm start.

Open the app inside the test room as owner/admin. On a room without onboarding registries, first open creates Onboarding positions and Onboarding hires; reload should reuse their IDs. In Templates, create a position with one week, one day and one lesson, choose Sẵn sàng, reload and use Open to inspect the tree. This exact Ready save/reload/Open path has been observed on Hub. The List stores flat items; inspect Cha:TEXT and Thứ tự on each item if comparing native Lists with the v4 UI. The single observed provision case used the current admin account and the Ready template Kiểm thử Cha P8 2026-09-24, with start date 2026-09-29; People showed Learning 0/1 day, and the drawer showed the correct position, date and status. Account B/C, Files, other provision cases, quiz and cancellation require their separate acceptance cases in the linked record.

For local verification from this app directory:

npm run typecheck:strict-unused
npx vitest run --exclude tests/packaging.spec.ts
npm run build

Local verification on 2026-09-24: strict-unused PASS; 68 files/430 tests PASS with --exclude tests/packaging.spec.ts; npm run build PASS; manifest lint valid; the production bundle contains no P0, role-switch or demoPositions labels. These results are separate from Hub manual acceptance; P8 manual acceptance remains unrun.

Managed direct runtime

The Marketplace image starts Direct HTTP transport by default (managed mode once the platform mounts PRIVOS_WORKLOAD_SOCKET; falls back to development mode locally when it isn't mounted):

npm run build
PORT=3000 npm start
curl http://127.0.0.1:3000/health
curl http://127.0.0.1:3000/ready
curl http://127.0.0.1:3000/.well-known/mcp/manifest.json

Development compatibility reports manifest-verified readiness without a broker. In production, /health only proves the process is alive; /ready returns 200 only after the manifest is valid, workload identity is paired, and the current receipt/epoch is active. A public or unsigned production POST /mcp returns 403.

Standalone production (self-hosted against a standalone hub)

A publisher can also run this exact app against a portal-less, self-hosted Hub — same manifest, same tools, same permission contract as a Marketplace install, but the app pairs directly with the Hub over the Relay WebSocket instead of App Cluster mounting a socket. Direct HTTP /mcp has no trust source in this mode and always returns 403 (DISPATCH_ASSERTION_INVALID); every MCP dispatch rides the Relay connection with a mandatory Hub-signed assertion.

Pair, twice

npm run pair     # or: pnpm pair

The command asks for the one-time pairing URL the Hub operator gives you — it takes no arguments, so the URL never lands in your shell history. It then announces privos-app.json over the pairing socket, which means no admin ever handles the manifest file: the app states what it wants, and an admin decides what it gets.

Run it twice, because the two runs mean different things:

1. The first run REGISTERS the app. The Hub stores the announced contract, grants nothing, and reports awaitingApproval. No identity file is written and the app does not start — dispatch trust belongs to the generation an approved permission ceiling creates, and there is nothing to run until then. Approve the declared permissions in Hub Admin > Apps.

2. Run it again with a fresh pairing URL from that app's own settings. The Hub re-hands the same credentials plus its dispatch trust, the identity file is written, and the app starts automatically — pair continues into start:standalone through whichever package manager you invoked it with, so there is no second command to remember.

The identity file lands at ./privos-standalone-identity.json (override with PRIVOS_STANDALONE_IDENTITY_FILE) at mode 0600, and the Hub's fingerprint is printed:

PrivOS Hub fingerprint: SHA256:<43-char base64url> — verify this out-of-band before trusting dispatch from this Hub.

Verify this fingerprint out-of-band — over a channel other than the one that gave you the pairing URL (a phone call, a separately-verified chat, the operator's own documentation). The fingerprint is the same SSH-host-key-style trust-on-first-use model as ssh printing a host key: a compromised pairing URL could otherwise hand you a Hub that signs dispatch you'd wrongly trust. Because the second pair run starts the app for itself, verify the fingerprint the moment it is printed and stop the process if it does not match.

Identity file handling

The identity file is the sole source of Relay OAuth credentials and Hub dispatch trust for this mode — treat it like an SSH private key:

• Back it up. Losing it means re-pairing (a new pairing URL from the Hub operator); there is no recovery path from the file alone.

• Never commit it, docker cp it into an image, or log its contents. scripts/package-source.sh already refuses to package any .env* / credential-like file; keep this file out of the Marketplace source archive the same way.

• A re-pair attempt over an existing file refuses (IDENTITY_FILE_ALREADY_EXISTS) rather than silently overwriting it — remove the file first if you intend to re-pair from scratch.

Run

The second pair run already started the app. Every later start — after a reboot, a redeploy, or any ordinary restart — uses the identity file that pairing wrote, and needs no pairing URL:

npm run start:standalone
curl http://127.0.0.1:3000/health
curl http://127.0.0.1:3000/ready

/ready reports not_ready (503) with a specific reason — IDENTITY_NOT_LOADED, RELAY_NOT_AUTHENTICATED, MANIFEST_LINT_INVALID, or MANIFEST_DRIFT — until the identity loads, the Relay connection authenticates, and the locally-built manifest's canonical digest still matches the digest pinned at pairing time.

Verified caller identity over Relay

The Relay runtime-dispatch assertion (SELF_HOSTED_LOCAL / PUBLISHER_HOSTED) proves which installation dispatched a call, but — unlike the managed Cluster assertion — carries no embedded actor claim. connectRelay independently verifies a SEPARATE Hub-signed RS256 user token (_meta.privosUser.userToken) against the Hub's published JWKS (/.well-known/mcp-apps/jwks.json) and cross-binds its room claim to the already-verified dispatch roomId. This is wired in automatically (hubUserTokenAuth: 'auto', the default) whenever a Hub dispatch trust is configured — true here, since start:standalone pins the paired identity's trust — so the backend receives a verified actor for standalone-production exactly like it does for managed, with provenance: 'user-token' distinguishing it from the managed path's 'dispatch-assertion'.

This verification requires the app host to reach the Hub's JWKS endpoint over the network. A fetch failure or timeout degrades that request's actor to unavailable (no actor is forwarded) — it never crashes dispatch and never falls back to the plain, unverified _meta.privosUser.userId / username fields that ride alongside the token.

npm run dev / npm run start:relay (development mode) intentionally configure no Hub dispatch trust at all (see Local development above), so this auto-wiring does not apply there and no verified actor is forwarded for any relay-transported call in that mode — by design, not a gap.

Rotation

The Hub can push secret rotation, trust rotation (re-key or a generation/manifest update), and capability changes over the same authenticated Relay connection, each as an ES256-signed control notification verified against the identity file's currently pinned Hub key before it is applied. No operator action is required; the identity file is rewritten atomically (temp file + rename) in place.

Upgrade path (manifest changes)

/ready returns MANIFEST_DRIFT when the locally-built privos-app.json no longer matches the canonical manifest digest pinned at pairing — this is the standalone analogue of the managed image-label digest check. A manifest change (new tool, new permission, new env declaration) needs re-approval: the Hub operator re-reviews the new manifest and pushes a trust rotation carrying the new digest before /ready goes green again. There is no way to silently start serving traffic under a manifest the Hub never approved.

The operator's side of that re-approval is Hub Admin → Apps → this app → Settings → Refresh (see the Hub's "Install and operate your own MCP app" doc). Re-pairing this app while it is live is refused and points back to Refresh — it is never needed for a manifest change.

Every signed exchange in this mode — dispatch assertions and control notifications alike — is capped at a 30-second signature lifetime with zero verifier headroom (exp - iat <= 30, hard capped even if the Hub asked for more). NTP-synchronized clocks on both the Hub and this app are a hard requirement, not an optimization; /ready's RELAY_NOT_AUTHENTICATED reason is the observable symptom of clock skew large enough to fail verification.

Permission contract

privos-app.json is the canonical reviewed manifest. Each permission declares:

• required or optional;

• workspace/room context and user/background execution context;

• a stable feature identifier and publisher reason;

• deterministic degraded behavior for every optional permission.

Required permissions are locked during approval. Optional permissions start from the exact approved subset and may be disabled later; Hub enforces the new epoch immediately. UI capability checks only hide or explain features and are never the authorization boundary. See SCOPES.md for the declaration-to-call-site map.

Run the shared linter to print the deterministic canonical manifest and publisher permission hashes:

npm run manifest:lint

Portal and Hub add the versioned authoritative permission catalog, data policy, and immutable image digest when computing the final permission-contract hash.

UI build and asset delivery

npm start runs npm run build:ui before starting the server. This produces both the split bundle below and dist/standalone-ui.html, a production HTML resource with all JS/CSS embedded. Paired standalone sessions use the inline resource by default; managed/runtime-v3 sessions use the split bundle. npm run build prepares both formats for the Docker image, whose runtime starts the server directly without rebuilding.

npm run build compiles src/ui with Vite (vite.config.ts: base: './', code-split manualChunks, build.manifest: true, build.sourcemap: false, build.assetsInlineLimit: 0) into a small shell (dist/ui/index.html) plus hashed, content-addressed files under dist/ui/assets/. @privos_ai/app-server's serveBuiltUi helper (src/mcp-message-handlers.ts) reads that build output once and answers three kinds of resources/read request: the shell (ui://ai.privos.mcp-app-demo/form.html, meta-tagged for relay delivery, with an inline boot watchdog), the assets manifest (ui://ai.privos.mcp-app-demo/assets-manifest.json), and each individual asset (ui://ai.privos.mcp-app-demo/assets/<file>). Any other URI is refused with JSON-RPC -32602.

The Hub fetches the shell once per open and the hashed assets once per installation generation, caches them, and re-serves everyone from its own origin behind a short-lived per-user token — this app's built bundle is never served to end users unmodified from this container, and it must never embed a secret (no VITE_* build-time env values; the platform's own non-secret values are read at runtime instead, see Environment configuration). Two build constraints follow directly from that: no sourcemaps are ever produced, and nothing may be served from a Vite publicDir — every asset the UI references (including the bundled sample agent-set archive) must be a real hashed file under dist/ui/assets/, which the build enforces at construction time (serveBuiltUi throws on an unhashed, oversized, or .map file, or on a shell with a non-relative asset reference).

This build requires the installing Hub to be at tenant.N or later — an older Hub has no route to fetch the split-out asset files, and the shell's boot watchdog shows a "App assets unavailable — Retry" panel instead of a blank frame until the tenant is upgraded.

Signed bundle at publish time

ui.distDir in privos-app.json is set to "dist/ui" — it must match wherever npm run build actually writes the UI, since this is what privos-app bundle-ui (npm run bundle:ui) packages into the tar the marketplace build node produces and the Portal signs. At install and upgrade, a capable Hub pulls that signed bundle, verifies its digest, and preloads the UI into the workspace's own storage before the app is allowed to go active — this is on top of, not instead of, the resources/read contract serveBuiltUi implements above. A version whose UI build output didn't change reuses the already-stored bundle rather than re-shipping it, so a manifest- or backend-only version bump does not by itself ship a UI change. See privos-dev-docs: mcp-app-platform/ui-bundle.md for the full mechanism and its refusal codes.

Ubuntu Docker Compose

See Ubuntu deployment instructions. The server needs Docker and Compose; no host Node/npm is required.

cp compose.env.example .env  # set APP_PORT if host port 3000 is occupied
bash scripts/build-compose.sh
docker compose run --rm --no-deps pair
docker compose up -d --no-build

Pairing waits for Hub approval and writes a persistent identity volume. Use /ready to verify readiness. Create the transferable Ubuntu source bundle with bash scripts/package-ubuntu.sh.

Verification

npm run typecheck
npm test
npm run build
npm run preflight
npm run docker:build

Preflight validates schema v2, canonical hashes, documented call sites, Docker inputs, license guards (when a license block is declared), safe source packaging, and the served manifest. Its versioned rules mirror Portal until the Marketplace validation package is published.

Safe source packaging

npm run package

This creates dist-source/ai.privos.mcp-app-demo-2.0.0.zip plus a SHA-256 provenance file from Git-tracked source. It rejects dirty trees by default, credential-like files, .env, dependencies, build output, and archives over 200 MiB. --allow-dirty is for local inspection only.

The multi-stage image installs only lockfile-pinned package inputs, runs as node, supports a read-only root filesystem, and needs no production credential environment variables.

Privacy, support, and release

Marketplace review/build source remains publisher-confidential; buyer workspaces receive the digest-pinned image. See PRIVACY.md, TERMS.md, and CHANGELOG.md. Support is available at dev@privos.ai.