Run locally

The hosted app at app.piyaz.ai is the recommended way to use Piyaz. Running your own instance is for people who want their data on their own machine and are comfortable with Docker and Postgres.

Self-hosting is free under AGPL-3.0. You run the Piyaz server on your machine and point the plugin's piyaz-local server at it. No agent config is needed: piyaz-local 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

Fill in `.env.local`

.env.local.example is numbered and self-documenting. Work through it top to bottom: it sets three Postgres roles (each with its own password and connection URL) and the auth secret. Generate secrets with openssl rand as the file describes:

openssl rand -hex 32     # role passwords
openssl rand -base64 32  # auth secret

The three roles plus row-level security scope access inside Postgres. Do not point every URL at one superuser.

Bring up the database

bun run db:setup

This starts Postgres in Docker, bootstraps the auth and row-level-security objects, and pushes the 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 as you would for the hosted app, but select the piyaz-local server instead of piyaz. It points at http://localhost:3000/api/mcp, so your data stays on your machine.

Run locally

On this page