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

# run

> Bootstrap your local Zmeel setup and start the server in one command.

`zmeel run` is the single command to get a Zmeel instance running. It runs `onboard` (if no config exists), then `doctor`, and finally starts the server. Once the server is healthy, it opens the dashboard in your browser.

## Usage

```bash theme={null}
zmeel run
```

If no config file exists and your terminal is interactive, `run` starts the onboarding wizard automatically. If the terminal is non-interactive and no config exists, the command exits with an error and directs you to run `zmeel onboard` first.

## Options

<ParamField query="-i, --instance" type="string">
  Local instance ID to use. Defaults to `default`. Use this to run multiple isolated instances side by side (for example `--instance dev` and `--instance staging`).
</ParamField>

<ParamField query="--repair" type="boolean" default="true">
  Attempt automatic repairs when `doctor` finds fixable issues. Enabled by default.
</ParamField>

<ParamField query="--no-repair" type="boolean">
  Disable automatic repairs during the doctor check. Issues are reported but not fixed.
</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`.
</ParamField>

## Examples

```bash theme={null}
# Start the default instance
zmeel run

# Start a named instance
zmeel run --instance dev

# Start with a custom data directory
zmeel run --data-dir ./tmp/zmeel-dev

# Start without automatic repairs
zmeel run --no-repair
```

## What happens when you run it

1. **Resolves the instance** — sets the instance ID from `--instance` or the `ZMEEL_INSTANCE_ID` environment variable (default: `default`).
2. **Checks for a config file** — if none exists and the terminal is interactive, starts `zmeel onboard`.
3. **Runs doctor** — checks configuration, database connectivity, storage, secrets, and port availability. Repairs fixable issues automatically (unless `--no-repair` is set). If any checks fail, the server does not start.
4. **Starts the server** — the Zmeel server and web UI become available at `http://localhost:3100` (or the port set in your config).
5. **Generates a bootstrap invite** (if needed) — if your deployment mode is `authenticated` and you are using embedded PostgreSQL, `run` generates a one-time admin invite URL after the server starts.

<Warning>
  If `doctor` reports blocking failures, `zmeel run` exits without starting the server. Run `zmeel doctor --repair` to fix issues, then retry.
</Warning>

## Server URL

The server starts at `http://localhost:3100` by default. The port and host are set during `zmeel onboard` or with `zmeel configure --section server`.