> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zmeel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# onboard

> Run the interactive first-run setup wizard to configure your Zmeel instance.

`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`](/cli/configure) to change individual sections on an existing install.

## Quick start

```bash theme={null}
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

<ParamField query="-y, --yes" type="boolean">
  Accept all defaults without prompting. Equivalent to choosing the **Quickstart** path and immediately saving config. Also starts Zmeel right away.
</ParamField>

<ParamField query="--run" type="boolean">
  Start Zmeel immediately after saving config, without the interactive "Start now?" prompt.
</ParamField>

<ParamField query="-c, --config" type="string">
  Path to the config file. Defaults to `~/.zmeel/instances/default/config.json`.
</ParamField>

<ParamField query="-d, --data-dir" type="string">
  Data directory root. Isolates all state from `~/.zmeel`. Use this to set up a separate instance in a custom location.
</ParamField>

## Onboarding flow

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

<Steps>
  <Step title="Choose a setup path">
    Select **Quickstart** to accept recommended local defaults, or **Advanced setup** to customize each section.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Configure your LLM provider (advanced only)">
    Choose Claude or OpenAI and enter your API key. Onboard validates the key against the provider's API.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Save config and start">
    Zmeel writes your config to `~/.zmeel/instances/default/config.json`. You are prompted whether to start the server now.
  </Step>
</Steps>

<Note>
  After onboarding completes, use `zmeel run` to start the server, `zmeel configure` to change settings, and `zmeel doctor` to verify your setup.
</Note>

## 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`.