Self-Host

Self-hosting is free under AGPL-3.0. You run the Piyaz server yourself and point the plugin's piyaz-local server at it. No env vars are required in your agent config: the piyaz-local server already targets http://localhost:3000/api/mcp.

Prerequisites

Bun v1.0+
Docker for PostgreSQL
Linux, macOS, or Windows with WSL2

Setup

Clone and install

git clone git@github.com:FrkAk/piyaz.git
cd piyaz
bun install --production
cp .env.local.example .env.local

Configure `.env.local`

Follow the numbered steps at the top of .env.local.example. Piyaz connects to Postgres with three separate roles, each with its own password and connection URL:

APP_USER_PASSWORD=...
SERVICE_ROLE_PASSWORD=...
AUTH_ROLE_PASSWORD=...

DATABASE_URL=postgresql://app_user:...@localhost:5432/piyaz
DATABASE_SERVICE_ROLE_URL=postgresql://service_role:...@localhost:5432/piyaz
DATABASE_AUTH_URL=postgresql://auth_role:...@localhost:5432/piyaz

BETTER_AUTH_SECRET=...
BETTER_AUTH_URL=http://localhost:3000

Generate one URL-safe password per role and paste each into both its *_PASSWORD var and the matching DATABASE_*_URL:

openssl rand -hex 32     # run once per role password
openssl rand -base64 32  # BETTER_AUTH_SECRET

The three roles plus row-level security scope access inside Postgres. Do not point every URL at the same superuser. See self-host operations for the security rationale.

Bring up the database

bun run db:setup

This brings up Postgres in Docker, bootstraps the auth and row-level-security objects, and pushes the Drizzle schema in one command.

Build and start

bun run build
bun run start

Open http://localhost:3000, sign up, and you are in.

Connect your agent

Install the Piyaz plugin for your agent as you would for the hosted version, but select the piyaz-local server instead of piyaz. It points at http://localhost:3000/api/mcp, so your data stays on your own machine.

Advanced self-hosters on a custom domain can set PIYAZ_URL to repoint the default piyaz server in Claude Code. Codex and Cursor read a hardcoded hosted URL, so edit their mcp.json directly if you need a custom domain.

Day-2 operations

Upgrades, backups, restores, and security hardening live in self-host operations.

Self-Host

On this page