Skip to main content
zmeel onboard walks you through configuring a new Zmeel instance. It prompts you to choose a deployment mode, LLM provider, database, storage, and secrets settings, then writes a config file so you are ready to run. If a config file already exists, onboard preserves it and shows you its current settings. Use zmeel configure to change individual sections on an existing install.

​
Quick start

npx zmeel@latest onboard --yes
This accepts all defaults and writes a config immediately — no prompts. It sets up:
  • Embedded PostgreSQL — no external database required
  • Local file storage — stored under ~/.zmeel/instances/default/data/storage
  • Web UI — served at http://localhost:3100
After running, open http://localhost:3100 in your browser to access the Zmeel dashboard.

​
Options

​
-y, --yes
boolean
Accept all defaults without prompting. Equivalent to choosing the Quickstart path and immediately saving config. Also starts Zmeel right away.
​
--run
boolean
Start Zmeel immediately after saving config, without the interactive “Start now?” prompt.
​
-c, --config
string
Path to the config file. Defaults to ~/.zmeel/instances/default/config.json.
​
-d, --data-dir
string
Data directory root. Isolates all state from ~/.zmeel. Use this to set up a separate instance in a custom location.

​
Onboarding flow

When you run zmeel onboard interactively (without --yes), you choose between two setup paths:
1

Choose a setup path

Select Quickstart to accept recommended local defaults, or Advanced setup to customize each section.
2

Configure your database (advanced only)

Choose between embedded PostgreSQL (no external dependency) or an external PostgreSQL connection string. Onboard tests the connection immediately and warns you if it cannot connect.
3

Configure your LLM provider (advanced only)

Choose Claude or OpenAI and enter your API key. Onboard validates the key against the provider’s API.
4

Configure logging, server, storage, and secrets (advanced only)

Set log output mode, server deployment mode and port, storage provider (local_disk or s3), and secrets encryption settings.
5

Save config and start

Zmeel writes your config to ~/.zmeel/instances/default/config.json. You are prompted whether to start the server now.
After onboarding completes, use zmeel run to start the server, zmeel configure to change settings, and zmeel doctor to verify your setup.

​
After onboarding

Once onboarding finishes, the dashboard is available at http://localhost:3100. If you chose authenticated deployment mode with an external PostgreSQL database, zmeel onboard generates a one-time bootstrap invite URL so you can create the first admin account. For all other configurations, the invite is generated when you first run zmeel run.