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

# Self-Hosting

> Run Zmeel on your own machine or server. One command gets you started; the full source is available if you need more control.

Zmeel can run entirely on your own infrastructure. You get the full platform — web UI, embedded database, file storage, and all employee features — with your data staying local.

<Note>
  The hosted platform at [app.zmeel.ai](https://app.zmeel.ai) includes a free tier with no Node.js requirement, managed infrastructure, and automatic updates. Self-hosting is the right choice when you need full data control, private network deployment, or want to run from source.
</Note>

## Requirements

* Node.js 20+
* pnpm 9.15+ (required only when running from source)

## Quickstart

The fastest way to get Zmeel running locally is the `npx` onboard command:

<Steps>
  <Step title="Run onboard">
    ```bash theme={null}
    npx zmeel@latest onboard --yes
    ```

    The `--yes` flag uses quickstart defaults without any interactive prompts:

    * **Database:** embedded PostgreSQL (no separate database server needed)
    * **Storage:** local file storage
    * **Deployment mode:** `local_trusted` — loopback-only, no login required
    * **Data location:** `~/.zmeel/instances/default/`
  </Step>

  <Step title="Start the server">
    After onboarding completes, start Zmeel:

    ```bash theme={null}
    npx zmeel@latest run
    ```

    <Tip>
      If you ran `onboard --yes`, Zmeel offers to start the server immediately — you can skip this step.
    </Tip>
  </Step>

  <Step title="Open the web UI">
    Go to [http://localhost:3100](http://localhost:3100) in your browser. In `local_trusted` mode, you land directly in the board with no login required.
  </Step>
</Steps>

## Install from source

Use this path if you want to modify the platform, contribute, or run a development build.

**Requirements:** Node.js 20+, pnpm 9.15+

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/samskipsai/zmeel-platform.git
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm install
    ```
  </Step>

  <Step title="Start the development server">
    ```bash theme={null}
    pnpm dev
    ```

    This starts both the API and the UI in watch mode. The server is available at [http://localhost:3100](http://localhost:3100).
  </Step>
</Steps>

## What onboard sets up

When you run `npx zmeel@latest onboard --yes`, Zmeel creates an instance at `~/.zmeel/instances/default/` with the following:

| Component               | Details                                                                |
| ----------------------- | ---------------------------------------------------------------------- |
| **Embedded PostgreSQL** | A self-contained database. No separate PostgreSQL installation needed. |
| **File storage**        | Local disk storage for employee files and outputs.                     |
| **Web UI**              | Served directly at `http://localhost:3100`.                            |
| **Config file**         | Saved to your instance directory. Edit later with `zmeel configure`.   |
| **Agent JWT secret**    | Generated automatically for secure agent communication.                |

## Reconfiguring after setup

Use the CLI to change settings after the initial onboard:

```bash theme={null}
npx zmeel@latest configure
```

To check that your setup is healthy:

```bash theme={null}
npx zmeel@latest doctor
```

## Deployment modes

Zmeel supports two runtime modes:

| Mode            | Login required | Best for                                      |
| --------------- | -------------- | --------------------------------------------- |
| `local_trusted` | No             | Single-operator local machine use             |
| `authenticated` | Yes            | Private network or internet-facing deployment |

The quickstart (`--yes`) uses `local_trusted`. To set up an `authenticated` instance for a private network or public deployment, run `npx zmeel@latest onboard` without `--yes` and choose **Advanced setup** when prompted.

<Warning>
  `local_trusted` mode binds to loopback only (`127.0.0.1`) and has no login protection. Do not expose it to a public network.
</Warning>

For full details on deployment modes, exposure policies, and authenticated setup, see [Deployment Modes](/self-host/deployment-modes).