Setup and Onboarding

create-zhin-app only creates a minimal project (ADR 0053). The database, owner account, AI and adapters are set up in the Console after the Host starts. Onboarding is served by the management gateway, so it works before the instance is up.

Opening onboarding

npm create zhin-app my-bot     # asks only: language, project name, bootstrap token
cd my-bot
pnpm dev                       # = zhin start --foreground --watch source config

At the end of creation (and after zhin start starts) the terminal prints a Console link:

https://console.zhin.dev/?apiBaseUrl=http%3A%2F%2F127.0.0.1%3A8068#token=<bootstrap token>

• The token sits after #, so it is never sent to console.zhin.dev's server; the Console removes it from the address bar as soon as it reads it, and asks you to confirm the first connection to an unknown Host.
• Non-interactive terminals (CI logs) print the link without the token; the token is HTTP_TOKEN in .env.
• Lost the link? Open console.zhin.dev, set API Base to http://127.0.0.1:8068 (per http.port) and use HTTP_TOKEN as the token.

The five steps

Step	Credential	What happens	Permissions
1. Database	Bootstrap token	Pick a driver (SQLite / MySQL / PostgreSQL / MongoDB), install the driver package online if needed, fill in the connection, test, save	—
2. Owner	Bootstrap token	Create the first owner and sign in; the bootstrap token is refused everywhere afterwards	—
3. AI	Owner session	Enable AI or not; install AI dependencies; add and test the first model provider	plugin.manage + agent.configure
4. Chat platforms	Owner session	Pick platforms (several allowed), install adapter packages, add and test the first account of each	plugin.manage + endpoint.manage
5. Finish	—	Summary, then Home	plugin.manage

• Steps 3–5 are on the Console's Get started page (/onboarding); while onboarding is unfinished, every page shows a banner to continue it.
• Every step can be skipped and revisited. After onboarding, set up AI under AI & models in the sidebar (/features/ai); for chat platforms, install the adapter from the Plugin store, then use Connect platform account in Accounts and conversations (/scope) to open the adapter page and add an account (see Connect an account). The same APIs are used.
• If you are not connecting a platform yet, talk to the bot in Try a conversation in the sidebar.
• Database: keeping the default SQLite (.zhin/data.sqlite) is enough to continue. When the configuration already declares database, the step is skipped by default. The connection is always tested before saving; secret fields go to .env and the configuration keeps only ${…} references. After a switch the gateway reconnects to the new database and restarts the instance; plugin data in the old database is not migrated.
• Online installs are limited to packages in the official catalog: database drivers (mysql2, pg, mongodb), adapter packages, AI dependencies and marketplace entries. The bootstrap token can only install database drivers; every other install goes through the gateway's dependency transaction (stop instance → install → start instance, rollback on failure), see Dependency installs and rollback.
• A local Host without http.token is open to everyone until setup (fine for local development only); always configure http.token before exposing a Host.

Onboarding state

Progress is kept in .zhin/onboarding.json (not in the database, because the database is not decided before step 1):

{ "version": 1, "steps": { "database": "done", "owner": "done", "ai": "skipped", "adapters": "pending" } }

Endpoint	Purpose
GET {base}/auth/setup	Setup status with the onboarding field (bootstrap token)
GET {base}/auth/me	Callers holding plugin.manage also receive onboarding
RPC onboarding.update	{ step: 'ai' | 'adapters' | 'finish', status: 'done' | 'skipped' }; needs plugin.manage, plus agent.configure for ai and endpoint.manage for adapters

After an existing project upgrades, steps already present in its configuration (database / adapters / AI) are marked done automatically; only the owner remains to be created.

CLI equivalents

Every onboarding step is a method of the same service; the CLI and the Web are two shells with identical validation and writes:

Step	Command
1, 2	zhin console init; non-interactive: printf '%s\n' "$PASSWORD" | zhin console init --yes --owner admin --password-stdin (optionally --database <dialect> --database-<field> <value>)
3	zhin setup --ai
4	zhin setup --adapters
Status	zhin console init --status

Related

• Quick Start
• Access control: adding users and issuing API tokens after onboarding