Run locally

Self-hosting is free under AGPL-3.0. You run the Piyaz server yourself and register an MCP server in your editor that points at it. The plugins ship pointing at the hosted app, so this is one command or one config entry after install.

Prerequisites

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

Setup

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

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

bun run db:setup

bun run build
bun run start

Connect your agent

Install the Piyaz plugin as you would for the hosted app. It ships one MCP server, piyaz, pointing at https://app.piyaz.ai/api/mcp. Your own instance is a second server that you register and name yourself.

claude mcp add -s user --transport http piyaz-self-hosted http://localhost:3000/api/mcp

claude mcp login piyaz-self-hosted

codex mcp add piyaz-self-hosted --url http://localhost:3000/api/mcp

codex mcp login piyaz-self-hosted

{
  "mcpServers": {
    "piyaz": { "url": "https://app.piyaz.ai/api/mcp" },
    "piyaz-self-hosted": { "url": "http://localhost:3000/api/mcp" }
  }
}

{
  "mcpServers": {
    "piyaz-self-hosted": { "serverUrl": "http://localhost:3000/api/mcp" }
  }
}

List my projects.

The bundled piyaz server stays pointed at the hosted app. Leave it signed out, or disable it in your editor's MCP settings so the two never mix.

• Connect Claude Code
• Connect Codex
• Connect Cursor
• Connect Antigravity

Running behind a proxy

Piyaz identifies a caller by IP address to throttle sign-in, password reset and email verification, and to record the IP on legal acceptance. Anyone can send an X-Forwarded-For header, so that address is only trustworthy when something in front of the app overwrites it. TRUSTED_PROXY_HEADER names the single header yours sets, and nothing else is ever read.

Set it to the header your proxy writes on inbound requests. nginx and Caddy write x-forwarded-for or x-real-ip depending on configuration; a CDN writes its own. Naming a header your proxy does not set is worse than naming none, because the address then comes straight from the caller.

TRUSTED_PROXY_HEADER=x-forwarded-for

Add TRUSTED_PROXIES only when there are two or more hops in front of the app, listing exactly the proxies you run as IPs or CIDR ranges, no more and no less. With a single proxy the address resolves to the hop it observed and the list is unnecessary. Behind two or more hops without it, every caller resolves to the same upstream address and shares one throttling budget. Too broad is the opposite failure: an entry that covers addresses where clients live lets a caller prepend a hop and choose its own identity. If a range really must cover everything, cover both address families (0.0.0.0/0,::/0); an IPv4-only blanket stops the walk at a prepended IPv6 hop and attributes the caller's chosen address. Entries that do not parse as an IP address or CIDR range refuse to start the app, so a typo surfaces at boot instead of silently disabling chain attribution.

TRUSTED_PROXIES=10.0.0.1,192.168.1.0/24

Upgrading

Your database holds real data, so schema changes apply as versioned migrations, never db:push (it force-syncs and can drop columns). Pull the latest code, apply migrations, re-apply the row-level-security objects, then rebuild:

git pull
bun install --production
bun run db:migrate
bun run db:rls
bun run build
bun run start

db:rls re-applies the canonical grants, SECURITY DEFINER functions, and RLS policies from docker/*.sql. It is idempotent (safe to run when nothing changed) and required whenever a release adds an RLS-protected table: the migration creates the table and enables RLS, but its grant and policy live in the hand-written docker/*.sql files that db:migrate does not apply.

Last updated July 28, 2026