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

# Self-host

> Run the open-source Watahub gateway yourself, with your own Meta app.

Use Self-host when you want to run the open-source gateway on your own infrastructure. You operate one Meta app, one API key and one subscriber webhook, and you can connect the phone lines that app allows.

This is not the Cloud account. Cloud lives at [app.watahub.dev](https://app.watahub.dev/) and is documented in the rest of this site. If you only want a Watahub API key and a hosted connect page, go back to the [introduction](https://docs.watahub.dev/en/overview.md) and follow Cloud.

## What you run

The core is the public [Hub-Ventures/watahub](https://github.com/Hub-Ventures/watahub) repository, also published as `watahub` on npm (0.2.0). It runs on Cloudflare Workers or Node.js 20+. The license is MIT.

You configure your Meta app secret, a webhook verify token and a Watahub API key of 32 or more characters. The gateway stores each line's Meta token and never returns it. Your agent receives each normalized event at `SUBSCRIBER_WEBHOOK_URL` and replies with `POST /v1/messages` against **your** gateway host, not `https://cloud.watahub.dev`.

## First run locally

You need Node.js 20 or later, pnpm (`corepack enable` uses the version pinned in the repository) and a Meta app with the WhatsApp product.

```bash theme={null}
git clone https://github.com/Hub-Ventures/watahub.git
cd watahub
pnpm install
cp .env.example .env
```

Generate `WATAHUB_API_KEY` and `SUBSCRIBER_WEBHOOK_SECRET`:

```bash theme={null}
openssl rand -hex 32
```

Fill in `.env`. The gateway reads `process.env` and does not load `.env` by itself, so start it with Node's `--env-file`:

```bash theme={null}
pnpm exec tsx watch --env-file=.env src/node.ts
curl http://localhost:3000/health
```

A healthy process returns JSON with `status` `ok`, `service` `watahub` and `version` `0.2.0`.

The full walkthrough — Meta app, first send, first inbound webhook and Embedded Signup — is in the core [Getting started](https://github.com/Hub-Ventures/watahub/blob/main/docs/GETTING_STARTED.md) guide. For Cloudflare Workers, Node, Docker or a reverse proxy, use [Deployment](https://github.com/Hub-Ventures/watahub/blob/main/docs/DEPLOYMENT.md).

## Connect a line

On Self-host you finish a line with `POST /v1/onboarding/connect` (the Embedded Signup code, WABA id, phone number id and PIN) or with a system user token in `META_SYSTEM_USER_TOKEN`. See Getting started.

Cloud customers instead use [hosted setup links](https://docs.watahub.dev/en/connect.md). Those pages do not apply here.

## Webhooks

The core forwards one signed POST per Meta delivery to your single subscriber URL.

The headers are `x-watahub-signature` (`sha256=` plus the lowercase hex HMAC-SHA256 of the exact body, keyed with `SUBSCRIBER_WEBHOOK_SECRET`), `x-watahub-delivery-id`, and `Idempotency-Key` (the same value as the delivery id). Deduplicate on `x-watahub-delivery-id`. The event catalog is in [Webhooks and events](https://github.com/Hub-Ventures/watahub/blob/main/docs/WEBHOOKS_AND_EVENTS.md).

Do not follow the Cloud [webhooks](https://docs.watahub.dev/en/webhooks.md) page for this. That page documents developer webhooks on `cloud.watahub.dev`: `X-Webhook-Event`, `X-Webhook-Signature` without a `sha256=` prefix, and `X-Idempotency-Key`. An older administrative destination on Cloud can look similar to the core subscriber; it is not the Self-host guide.

## What stays on Cloud

The hosted Inbox, seven-day logs, token custody for many tenants, hosted setup links, developer webhooks, the [CLI](https://docs.watahub.dev/en/cli.md) and [MCP](https://docs.watahub.dev/en/mcp.md) ship with Cloud / Enterprise Edition, not with the open-source core.

## Official core guides

* [Getting started](https://github.com/Hub-Ventures/watahub/blob/main/docs/GETTING_STARTED.md)
* [API reference](https://github.com/Hub-Ventures/watahub/blob/main/docs/API_REFERENCE.md)
* [Webhooks and events](https://github.com/Hub-Ventures/watahub/blob/main/docs/WEBHOOKS_AND_EVENTS.md)
* [Deployment](https://github.com/Hub-Ventures/watahub/blob/main/docs/DEPLOYMENT.md)
* [Extensions and Enterprise Edition](https://github.com/Hub-Ventures/watahub/blob/main/docs/MULTI_TENANCY_AND_EXTENSIONS.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.