Install

There are two ways to run Piyaz.

Hosted (recommended). Piyaz runs at app.piyaz.ai. You install only the plugin for your agent and sign in. No clone, no database. See the Quickstart.
Self-host. You run the Piyaz server yourself and point the plugin's piyaz-local server at it. This page covers the database setup; the full flow is in Self-host.

Self-host prerequisites

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

Clone

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

Configure the database

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

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

See Environment variables for a per-field reference.

Bring up the database

bun run db:setup

This brings up postgres:17 in Docker on port 5432, bootstraps the auth and row-level-security objects, and pushes the Drizzle schema in one command.

Data persists in the pgdata Docker volume. To wipe and start fresh: docker compose down -v.

db:setup drives the bootstrap through the piyaz-db-1 Docker container. Running against an external or cloud Postgres means replicating those SQL steps yourself (docker/init-auth.sql, the RLS scripts, docker/grants.sql) against your instance. The Docker Compose path above is the supported route.

Build and start

bun run build
bun run start

Open http://localhost:3000.

Connect your agent

Install the plugin for your agent, but select the piyaz-local server, which points at http://localhost:3000/api/mcp:

Troubleshooting

Common install issues are covered in Troubleshooting. The usual suspects:

Port 3000 or 5432 already in use.
BETTER_AUTH_SECRET shorter than 32 characters.
A role password that does not match between its *_PASSWORD var and its DATABASE_*_URL.

Install

On this page