← All docs

Tenant onboarding

How Twentyfirst provisions a new client workspace using the control plane + on-prem workspace model.

Roles

RoleResponsibility
Platform operatorCustomers, instances, config, licenses (control app)
Tenant adminUsers, local branding review (workspace /admin)
Client ITInstall workspace, DNS/TLS, model endpoint, firewall rules
End usersChat, library, RAG

Checklist

1. Gather client inputs

  • Legal entity name and workspace display name
  • RAG required? TTS/STT?
  • Model endpoint URL, API key, default model IDs
  • Auth: credentials, Google Workspace, Microsoft Entra ID, or combination
  • Connected (outbound HTTPS to control) or air-gapped?
  • Data residency and retention requirements

2. Provision in control (/ops)

  1. Create customer — name, billing email.
  2. Create instance — name, initial config (branding, model profile, entitlements).
  3. Copy pairing token (connected) or license + config bundle (air-gapped).

3. Client installs workspace

  1. Deploy apps/chat.twentyfirst.ai (Docker or Node on client infra).
  2. Configure DATABASE_URL, MODEL_*, NEXTAUTH_*.
  3. Connected: set CONTROL_PLANE_URL, INSTANCE_PAIRING_TOKEN, matching CONTROL_PLANE_SIGNING_KEY.
  4. Air-gapped: set LICENSE_FILE_PATH, import config bundle in Admin.
  5. Run npm run db:push and create initial admin user (or use seed in dev only).

4. Pair and verify

Connected

  1. Admin → Sync now (or cron hit /api/cron/sync).
  2. Confirm instance shows last seen in control.
  3. Client admin logs in; send a test chat message.

Air-gapped

  1. Import config bundle in workspace Admin.
  2. Verify license expiry in Admin panel.
  3. Re-import config bundles when operators publish updates.

5. Authentication

Email / password

Create users with bcrypt password_hash and memberships rows, or use workspace seed in dev:

npm run db:seed -w @repo/chat.twentyfirst.ai

Default dev admin: admin@demo.local / ChangeMe!123

Google / Microsoft OAuth

Configure AUTH_GOOGLE_* or AUTH_MICROSOFT_* on the workspace deployment. Redirect URI: https://<workspace-host>/api/auth/callback/...

6. Handoff

  • Tenant admin credentials or SSO instructions
  • Model endpoint documentation (client-owned)
  • Support contact and instance ID for control lookups
  • Usage/billing review cadence (control /ops/usage, /ops/billing)

Ongoing operations

TaskWhere
Change branding / model configControl → publish config revision → workspace syncs
Suspend clientControl → instance status → workspace blocks on next sync
Usage / billingControl usage ingest from workspace sync
Add usersWorkspace tenant admin

See deployment.md for production hardening.