Self-Hosting

Meridian is designed to run on Vercel's free tier with Neon Serverless Postgres. This guide walks you through deploying your own instance.

Prerequisites

A GitHub account
A Vercel account (free tier works)
A Neon account (free tier works)

Step 1: Set up Neon Postgres

Create a new project at console.neon.tech.
Choose a region close to your Vercel deployment (typically us-east-1).
Copy the connection string from the dashboard. It looks like:
Connection string format
```
postgresql://user:password@ep-xxx.us-east-1.aws.neon.tech/meridian?sslmode=require
```
This becomes your DATABASE_URL environment variable.

Step 2: Fork and deploy to Vercel

Fork the repository at github.com/aurelius51/meridian.
Go to vercel.com/new and import your fork.
Add the environment variables listed below before deploying.
Click Deploy. Vercel will build and deploy the project.

Step 3: Run database migrations

After the first deploy, run Prisma migrations against your Neon database. You can do this from your local machine:

Terminal

git clone https://github.com/YOUR_USERNAME/meridian
cd meridian
pnpm install
cp .env.example .env
# Edit .env with your Neon DATABASE_URL and other values
pnpm prisma migrate deploy

Environment variables reference

Configure these in your Vercel project settings under Settings → Environment Variables.

Variable	Required	Description	How to generate
`DATABASE_URL`	Yes	Neon Postgres connection string	Copy from Neon dashboard
`NEXTAUTH_SECRET`	Yes	Random secret for signing session tokens	`openssl rand -base64 32`
`NEXTAUTH_URL`	Yes	Your deployment URL (including https://)	e.g., `https://meridian-xyz.vercel.app`
`ENCRYPTION_MASTER_KEY`	Yes	64-character hex string (32 bytes) for AES-256-GCM encryption of provider keys	`openssl rand -hex 32`

Security warning

Never commit .env files or raw secret values to version control. The ENCRYPTION_MASTER_KEY is used to encrypt all provider API keys — if it's lost, stored provider keys become unrecoverable. Store a backup securely.

Step 4: Verify the deployment

Navigate to your deployment URL. You should see the Meridian landing page.
Sign up for an account at /auth/signup.
Add a provider key and create a proxy key.

Test with a curl request:

Verification

curl -X POST https://your-meridian.vercel.app/api/v1/chat/completions \
  -H "Authorization: Bearer sk-mrd-your-new-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

Local development

To run Meridian locally for development:

Terminal

git clone https://github.com/aurelius51/meridian
cd meridian
pnpm install
cp .env.example .env    # Fill in your values
pnpm prisma migrate dev # Create/update local schema
pnpm dev                # Start at http://localhost:3000

For local development, set NEXTAUTH_URL=http://localhost:3000. You can use a Neon database branch or your production database connection string.

Updating

To update your self-hosted instance, sync your fork with the upstream repository and redeploy. Vercel will automatically rebuild on push. Run any new migrations:

Terminal

git fetch upstream
git merge upstream/main
pnpm prisma migrate deploy
git push origin main