Skip to content

An AI-powered search engine with a generative UI

docs: lead self-hosting auth docs with Better Auth (#1068)

Yoshiki Miura7f680a0d98cf
diff --git a/.env.local.example b/.env.local.example
index 5f13f670..f3af581d 100644
--- a/.env.local.example
+++ b/.env.local.example
@@ -105,7 +105,7 @@ ANONYMOUS_USER_ID=anonymous-user
# SUPABASE_SECRET_KEY=[YOUR_SUPABASE_SECRET_KEY]
# Local multi-user accounts in Morphic's own Postgres (no Supabase needed).
-# See the "Local Authentication" section in README.md for the full walkthrough.
+# See the "Better Auth" section in docs/CONFIGURATION.md for the full walkthrough.
# AUTH_PROVIDER=better-auth
# BETTER_AUTH_SECRET=[RUN: openssl rand -hex 32]
# Only this email may sign up while the user table is empty (recommended):
diff --git a/README.md b/README.md
index 4647af26..a07ad504 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,7 @@ An AI-powered search engine with a generative UI.
- Chat history stored in PostgreSQL
- Share search results with unique URLs
- File upload support
-- User authentication with Supabase Auth
+- User authentication with built-in accounts (Better Auth) or Supabase Auth
- Guest mode for anonymous usage
- Docker deployment ready
@@ -98,7 +98,7 @@ TAVILY_API_KEY=your_tavily_key
To enable chat history, authentication, file upload, and other features, see [CONFIGURATION.md](./docs/CONFIGURATION.md).
-Auth is provided by `AUTH_PROVIDER` (`supabase | better-auth | none`). When unset it is derived from the existing environment: `ENABLE_AUTH=false` selects anonymous mode (`none`), otherwise Supabase auth is used — so existing deployments need no change. See [Authentication](./docs/CONFIGURATION.md#authentication).
+Auth is provided by `AUTH_PROVIDER` (`supabase | better-auth | none`). When unset it is derived from the existing environment: `ENABLE_AUTH=false` selects anonymous mode (`none`), otherwise Supabase auth is used. Existing deployments need no change. See [Authentication](./docs/CONFIGURATION.md#authentication).
For what a self-hosted instance sends outbound, and what is off by default, see [PRIVACY.md](./docs/PRIVACY.md).
@@ -112,47 +112,14 @@ Visit http://localhost:3000.
### Local Authentication (better-auth)
-To run a multi-user Morphic on your own machine or LAN without Supabase, use the built-in `better-auth` provider. Accounts live in Morphic's own Postgres database.
-
-1. Configure `.env.local`:
+To run a multi-user Morphic without Supabase, use the built-in `better-auth` provider. Accounts live in Morphic's own Postgres database. It is opt-in: set these in `.env.local`, then run `bun migrate` (Docker runs migrations at container start).
```bash
AUTH_PROVIDER=better-auth
BETTER_AUTH_SECRET=run-openssl-rand-hex-32-for-a-stable-value
-# Recommended whenever the instance is reachable by anyone but you:
```
-2. Start Morphic. With Docker (`docker compose up -d`), database migrations run automatically at container start and create the auth tables. For local development (`bun dev` with a local Postgres), run `bun migrate` once before starting the dev server.
-
-3. First boot: open http://localhost:3000/auth/sign-up and create your account. The first account becomes the instance admin; the bootstrap window then closes. Note that the window is tied to the user table being empty: if the last account is ever deleted, the window reopens and the gated address (or, without SMTP, whoever signs up first) can claim admin again. Keep at least one account, or unset `BOOTSTRAP_ADMIN_EMAIL` before deleting the last one. When `BOOTSTRAP_ADMIN_EMAIL` is set, only that address can sign up during the window. If SMTP is configured, the bootstrap sign-up emails a one-time link to that address, so only someone who controls the mailbox can complete it — this requires `BETTER_AUTH_URL` (the link origin); without SMTP the first person to submit the gated address wins the window, so finish first boot before exposing the instance to others.
-
-#### Invite-only sign-up
-
-Set `AUTH_SIGNUP_MODE=invite` to require an invitation for new accounts:
-
-- On a fresh instance there are no invitations yet: set `BOOTSTRAP_ADMIN_EMAIL` and the first account for that address can sign up without an invitation (with SMTP configured, the bootstrap link is emailed to that address first), then create invitations from the admin page.
-- As admin, open the admin page (user menu → **Admin**) and create an invitation link for an email address. Each link is bound to that address, valid for one sign-up for 7 days, and can be revoked until used.
-- The invitee opens the link and completes sign-up; the token is consumed automatically.
-
-#### Password reset and SMTP
-
-Password reset requires SMTP and `BETTER_AUTH_URL`; without them the forgot-password flow is hidden and the admin can set member passwords from the admin page instead. `BETTER_AUTH_URL` is the canonical origin embedded in emailed links (password resets, invitations, bootstrap) — it is never derived from request headers, so a spoofed `Host` cannot redirect a live credential to an attacker domain.
-
-```bash
-SMTP_HOST=smtp.example.com
-SMTP_PORT=587
-SMTP_USER=smtp-user
-SMTP_PASSWORD=smtp-password
-EMAIL_FROM="Morphic <[email protected]>"
-BETTER_AUTH_URL=https://morphic.example.com
-```
-
-With SMTP configured, password-reset emails are sent and invitation links are additionally emailed to invitees.
-
-#### HTTPS and secure cookies
-
-In production builds (Docker), session cookies carry the `__Secure-` prefix, so browsers only store and send them over HTTPS or on `localhost`. An instance reached via `http://<LAN-IP>:3000` will not stay logged in; serve it over HTTPS (reverse proxy, Tailscale Serve, etc.). Development mode (`bun dev`) is not affected.
+The first account to sign up becomes the admin. For first boot, invite-only sign-up, password reset, and HTTPS, see [Authentication](./docs/CONFIGURATION.md#better-auth) in the configuration guide.
## Deploy
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 114dd034..ad1621be 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -8,6 +8,10 @@ This guide covers the optional features and their configuration in Morphic.
- [AI Providers](#ai-providers)
- [Search Providers](#search-providers)
- [Authentication](#authentication)
+ - [Auth Provider](#auth-provider-auth_provider)
+ - [Anonymous Mode](#anonymous-mode-default)
+ - [Better Auth](#better-auth)
+ - [Supabase](#supabase)
- [Guest Mode](#guest-mode)
- [Other Features](#other-features)
- [Privacy and Telemetry](./PRIVACY.md)
@@ -188,31 +192,43 @@ If not configured, `type="general"` searches fall back to your configured search
## Authentication
-By default, Morphic runs in **anonymous mode** (`ENABLE_AUTH=false`). This is ideal for personal, single-user environments.
+Morphic has three auth providers. Pick the one that matches how the instance is used:
+
+| Use case | Provider |
+| ---------------------------------- | ----------------------------------------- |
+| Personal, single user | [Anonymous mode](#anonymous-mode-default) |
+| Self-hosted, multiple users | [Better Auth](#better-auth) |
+| You already run a Supabase project | [Supabase](#supabase) |
### Auth Provider (`AUTH_PROVIDER`)
-Auth behavior is controlled by an auth provider. Set `AUTH_PROVIDER` explicitly to one of:
+Set `AUTH_PROVIDER` explicitly to one of:
-| Value | Description |
-| ------------- | ----------------------------------------------------------------------------------- |
-| `supabase` | Supabase cloud authentication (multi-user) |
-| `none` | Anonymous mode: all users share one user ID |
-| `better-auth` | Local accounts in Morphic's own Postgres (see "Local Authentication" in the README) |
+| Value | Description |
+| ------------- | --------------------------------------------------------------- |
+| `none` | Anonymous mode: all users share one user ID |
+| `better-auth` | Built-in accounts stored in Morphic's own Postgres (multi-user) |
+| `supabase` | Supabase cloud authentication (multi-user) |
When `AUTH_PROVIDER` is **unset**, the provider is derived from the existing
environment so current deployments keep working unchanged:
-- `ENABLE_AUTH=false` → `none` (anonymous mode, shared `ANONYMOUS_USER_ID`)
+- `ENABLE_AUTH=false` → `none` (anonymous mode, shared `ANONYMOUS_USER_ID`).
+ This is what `.env.local.example` and Docker Compose set.
- otherwise → `supabase` (when Supabase is not configured, no user is resolved
and the app behaves as before: guest/anonymous access without a shared ID)
+Better Auth is never selected implicitly. An explicit `AUTH_PROVIDER` takes
+precedence over `ENABLE_AUTH`.
+
`MORPHIC_CLOUD_DEPLOYMENT=true` requires Supabase-backed auth: requests fail
with a clear error when the resolved provider is `none` or any non-Supabase
provider.
### Anonymous Mode (Default)
+For personal, single-user environments.
+
```bash
ENABLE_AUTH=false
ANONYMOUS_USER_ID=anonymous-user
@@ -222,9 +238,74 @@ All users share a single anonymous user ID. No additional configuration needed.
Anyone who can reach the instance can send prompts, and a prompt is what decides which addresses the server requests on the sender's behalf.
-### Enabling Supabase Authentication
+### Better Auth
+
+For multi-user self-hosting, this is the recommended provider. Accounts live in Morphic's own Postgres database, so no external auth service is needed.
+
+> **Note**: This provider is new. Its built-in rate limiting for sign-in, sign-up, and password reset is basic and in-process. If the instance is reachable from the internet, put it behind a reverse proxy that enforces its own rate limits and terminates HTTPS.
+
+#### Setup
+
+1. Configure `.env.local`:
+
+```bash
+AUTH_PROVIDER=better-auth
+BETTER_AUTH_SECRET=run-openssl-rand-hex-32-for-a-stable-value
+# Recommended whenever the instance is reachable by anyone but you:
+```
+
+`BETTER_AUTH_SECRET` is required in production builds. Keep it stable across restarts.
+
+2. Start Morphic. The auth tables are created by the database migration. With Docker (`docker compose up -d`), migrations run automatically at container start. For local development (`bun dev` with a local Postgres), run `bun migrate` once before starting the dev server.
+
+3. Open http://localhost:3000/auth/sign-up and create your account. The first account becomes the instance admin, and the bootstrap window then closes.
+
+#### First boot and `BOOTSTRAP_ADMIN_EMAIL`
+
+When `BOOTSTRAP_ADMIN_EMAIL` is set, only that address can sign up while the user table is empty.
+
+- With SMTP configured, the bootstrap sign-up emails a one-time link to that address, so only someone who controls the mailbox can complete it. This requires `BETTER_AUTH_URL` (the link origin).
+- Without SMTP, the first person to submit the gated address wins the window, so finish first boot before exposing the instance to others.
+
+The window is tied to the user table being empty. If the last account is ever deleted, the window reopens and the gated address (or, without SMTP, whoever signs up first) can claim admin again. Keep at least one account, or unset `BOOTSTRAP_ADMIN_EMAIL` before deleting the last one.
-For multi-user deployments:
+#### Invite-only sign-up
+
+`AUTH_SIGNUP_MODE` is `open` (default) or `invite`. Set `AUTH_SIGNUP_MODE=invite` to require an invitation for new accounts:
+
+- On a fresh instance there are no invitations yet: set `BOOTSTRAP_ADMIN_EMAIL` and the first account for that address can sign up without an invitation (with SMTP configured, the bootstrap link is emailed to that address first), then create invitations from the admin page.
+- As admin, open the admin page (user menu → **Admin**) and create an invitation link for an email address. Each link is bound to that address, valid for one sign-up for 7 days, and can be revoked until used.
+- The invitee opens the link and completes sign-up. The token is consumed automatically.
+
+#### Password reset and SMTP
+
+Password reset requires SMTP and `BETTER_AUTH_URL`. Without them the forgot-password flow is hidden and the admin can set member passwords from the admin page instead.
+
+```bash
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USER=smtp-user
+SMTP_PASSWORD=smtp-password
+EMAIL_FROM="Morphic <[email protected]>"
+BETTER_AUTH_URL=https://morphic.example.com
+```
+
+With SMTP configured, password-reset emails are sent and invitation links are additionally emailed to invitees.
+
+`BETTER_AUTH_URL` is the canonical origin embedded in emailed links (password resets, invitations, bootstrap). It is never derived from request headers, so a spoofed `Host` cannot redirect a live credential to an attacker domain.
+
+#### HTTPS and secure cookies
+
+In production builds (Docker), session cookies carry the `__Secure-` prefix, so browsers only store and send them over HTTPS or on `localhost`. An instance reached via `http://<LAN-IP>:3000` will not stay logged in. Serve it over HTTPS (reverse proxy, Tailscale Serve, etc.). Development mode (`bun dev`) is not affected.
+
+#### Chat sharing
+
+With Better Auth, sharing chats is off until you set `ENABLE_SHARE=true`. See [Chat Sharing](#chat-sharing).
+
+### Supabase
+
+For deployments that already use Supabase, or that prefer a hosted auth service.
1. Create a Supabase project at [supabase.com](https://supabase.com)
@@ -286,11 +367,12 @@ Rate limiting only applies when `MORPHIC_CLOUD_DEPLOYMENT=true`.
### Recommended Setup
-| Environment | Configuration |
-| -------------- | -------------------------------------------- |
-| Personal/Local | `ENABLE_AUTH=false` (anonymous mode) |
-| Public Demo | `ENABLE_GUEST_CHAT=true` with rate limiting |
-| Production | `ENABLE_AUTH=true` (Supabase authentication) |
+| Environment | Configuration |
+| ----------------------- | ----------------------------------------------- |
+| Personal/Local | `ENABLE_AUTH=false` (anonymous mode) |
+| Self-hosted, multi-user | `AUTH_PROVIDER=better-auth` (built-in accounts) |
+| Public Demo | `ENABLE_GUEST_CHAT=true` with rate limiting |
+| Production | `ENABLE_AUTH=true` (Supabase authentication) |
## Other Features
@@ -309,7 +391,7 @@ Off by default. Traces include full prompts and completions, so point `LANGFUSE_
### Chat Sharing
-Sharing chats is opt-in:
+With Supabase, signed-in users can share chats without extra configuration. With Better Auth, sharing is opt-in:
```bash
ENABLE_SHARE=true # runtime flag; works with prebuilt Docker images
@@ -317,6 +399,8 @@ ENABLE_SHARE=true # runtime flag; works with prebuilt Docker images
`NEXT_PUBLIC_ENABLE_SHARE=true` also works when building from source, but Next.js inlines `NEXT_PUBLIC_*` values at build time, so setting it at runtime has no effect in a published image.
+Sharing is not available in anonymous mode.
+
### Outbound Fetch
The `fetch` tool and the advanced-search crawler refuse private address space: loopback, RFC1918, link-local (which carries the cloud metadata endpoint), and the other non-global ranges. To let them read a service on the host's own network:
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index ba0e41ab..e61f8e39 100644
--- a/docs/DOCKER.md
+++ b/docs/DOCKER.md
@@ -98,9 +98,22 @@ docker compose down -v # Deletes all data
## Enabling Authentication
-By default, Docker runs in anonymous mode — all users share a single anonymous user ID. This is intended for **personal, single-user local environments only**.
+By default, Docker runs in anonymous mode: all users share a single anonymous user ID. This is intended for **personal, single-user local environments only**.
-To enable Supabase authentication for multi-user deployments:
+### Better Auth (built-in accounts)
+
+For a multi-user instance, use the built-in Better Auth provider. Accounts live in the bundled PostgreSQL database, and it works with the prebuilt image. Add to `.env.local`:
+
+```bash
+AUTH_PROVIDER=better-auth
+BETTER_AUTH_SECRET=run-openssl-rand-hex-32-for-a-stable-value
+```
+
+Then restart with `docker compose up -d`. See [Better Auth](./CONFIGURATION.md#better-auth) for sign-up modes, the first admin account, SMTP, and HTTPS.
+
+### Supabase
+
+To use Supabase authentication instead:
1. Set up a [Supabase](https://supabase.com/) project
2. Build from source with the Supabase environment variables:
@@ -118,7 +131,7 @@ ENABLE_AUTH=true
docker compose up -d --build
```
-**Note**: The prebuilt image does not support authentication because `NEXT_PUBLIC_*` variables are embedded at build time by Next.js. You must build from source to enable authentication.
+**Note**: The prebuilt image does not support Supabase authentication because `NEXT_PUBLIC_*` variables are embedded at build time by Next.js. You must build from source to use Supabase.
## Useful Commands