Skip to main content
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

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

​
-i, --instance
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).
​
--repair
boolean
default:"true"
Attempt automatic repairs when doctor finds fixable issues. Enabled by default.
​
--no-repair
boolean
Disable automatic repairs during the doctor check. Issues are reported but not fixed.
​
-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.

​
Examples

# 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.
If doctor reports blocking failures, zmeel run exits without starting the server. Run zmeel doctor --repair to fix issues, then retry.

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