Installation

System requirements

Docker Engine 20.10+ and Docker Compose v2+
4 GB RAM minimum (for Pinchy + OpenClaw + PostgreSQL)
An LLM provider: API key (Anthropic, OpenAI, Google, Ollama Cloud) or a local Ollama instance

Docker Compose (recommended)

The simplest way to run Pinchy. One command starts the full stack.

mkdir -p pinchy && cd pinchy
curl -fsSL https://raw.githubusercontent.com/heypinchy/pinchy/v0.8.0/docker-compose.yml -o docker-compose.yml
echo "PINCHY_VERSION=v0.8.0" > .env
docker compose pull && docker compose up -d

Services

The docker-compose.yml defines three services:

| Service | Image | Port | Purpose | | ---------- | ---------------- | ---------------- | ----------------------------- | | pinchy | Custom (Next.js) | 7777 (exposed) | Web UI, API, WebSocket bridge | | openclaw | Custom (Node.js) | 18789 (internal) | AI agent runtime | | db | postgres:17 | 5432 (internal) | Database |

Only port 7777 is exposed to the host. OpenClaw and PostgreSQL are only reachable within the Docker network.

Environment variables

Almost no configuration is needed to get started: session key, encryption key, HMAC signing key, and the database password are auto-generated on first start and persisted in Docker volumes so they survive restarts. The one value you set yourself is PINCHY_VERSION — the Compose file refuses to start without a pinned version. See the Getting Started guide.

Optional: production hardening

For production deployments, extend the .env file to pin your own secrets instead of relying on auto-generated ones:

# Database password (auto-generated and applied on first start if omitted)
DB_PASSWORD=your-secure-password

# Better Auth session secret (auto-generated if omitted)
BETTER_AUTH_SECRET=your-random-secret

# Encryption key for API keys — 64 hex characters (auto-generated if omitted)
ENCRYPTION_KEY=

# HMAC secret for audit trail signing (auto-generated if omitted)
AUDIT_HMAC_SECRET=

# Enterprise license key (optional — enables Groups, agent access control, basic RBAC)
PINCHY_ENTERPRISE_KEY=

DB_PASSWORD — Password for the PostgreSQL pinchy user. If omitted, Pinchy generates one on the first production start, persists it in the pinchy-secrets volume, and applies it to PostgreSQL automatically (the public pinchy_dev default never stays active). Set it explicitly if you want to manage the credential yourself — Pinchy applies your value on the next restart, even if the database still runs on an older one.

BETTER_AUTH_SECRET — Used by Better Auth for session security. Auto-generated and persisted in the pinchy-secrets volume if omitted. For production, set explicitly with openssl rand -hex 32.

ENCRYPTION_KEY — Used to encrypt provider API keys at rest (AES-256-GCM). Auto-generated and persisted in the pinchy-secrets volume if omitted. For production, set explicitly with openssl rand -hex 32.

AUDIT_HMAC_SECRET — Used to sign audit trail entries with HMAC-SHA256. Auto-generated and persisted in the pinchy-secrets volume if omitted. Set explicitly if you need consistent signatures across deployments.

PINCHY_ENTERPRISE_KEY — License key for enterprise features (Groups, agent access control, basic RBAC — granular RBAC with custom roles is planned). Optional — can also be entered via Settings → License in the UI. See Enterprise Setup for details.

Data persistence

Docker volumes ensure data survives container restarts:

| Volume | Mounted at | Purpose | | --------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | pgdata | /var/lib/postgresql/data | PostgreSQL data | | openclaw-config | /root/.openclaw (OpenClaw), /openclaw-config (Pinchy) | Shared OpenClaw configuration | | pinchy-data | /data (OpenClaw) | Agent-accessible files (Knowledge Base documents) | | pinchy-workspaces | /root/.openclaw/workspaces (OpenClaw), /openclaw-config/workspaces (Pinchy) | Agent workspaces (SOUL.md, AGENTS.md, uploads/, workbench/) | | pinchy-secrets | /app/secrets (Pinchy) | Auto-generated encryption and HMAC keys | | openclaw-secrets | /openclaw-secrets (both) | tmpfs — runtime-only SecretRef bundle. Cleared on container restart and rebuilt from the DB. | | pinchy-pdf-cache | /var/cache/pinchy-files (Pinchy) | Cached PDF-text extractions so repeated reads of the same upload skip re-parsing | | openclaw-extensions | /openclaw-extensions (Pinchy), /root/.openclaw/extensions (OpenClaw) | Pinchy plugins for OpenClaw |

Port configuration

Pinchy always listens on port 7777 inside the container. By default, it binds to 127.0.0.1:7777 on the host — only reachable from localhost. Set PINCHY_PORT to override the binding (host interface and/or port):

# Localhost-only on a different host port (default behaviour, custom port)
PINCHY_PORT=127.0.0.1:3000 docker compose up -d

# Expose on all interfaces (use only behind a reverse proxy or for testing)
PINCHY_PORT=0.0.0.0:80 docker compose up -d

Or add it to your .env file:

PINCHY_PORT=127.0.0.1:3000

The default is 127.0.0.1:7777. The docker-compose.yml maps ${PINCHY_PORT:-127.0.0.1:7777}:7777. Accepted forms are HOST_PORT (e.g. 3000) or HOST_IP:HOST_PORT (e.g. 0.0.0.0:80). Do not include the container port in PINCHY_PORT — it's appended automatically.

Development mode

For development with hot reload (code changes reflect immediately in the browser), use the dev-mode Docker override:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

After the initial build, subsequent starts only need:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

What hot-reloads and what doesn't

React components, pages, styles — instant HMR via Next.js dev server
server.ts — requires container restart (docker compose restart pinchy)
package.json / dependencies — requires rebuild (--build)

Development setup

For local development without Docker (except for the database and OpenClaw):

# Install dependencies
pnpm install

# Start database and OpenClaw in Docker (dev override exposes port 5434)
docker compose -f docker-compose.yml -f docker-compose.dev.yml up db openclaw -d

# Set database URL for local dev
export DATABASE_URL=postgresql://pinchy:pinchy_dev@localhost:5434/pinchy

# Run database migrations
pnpm -C packages/web db:migrate

# Start the dev server
pnpm dev

The app starts at http://localhost:7777 with hot reload.

Available commands

# Run from the repository root
pnpm dev          # Start dev server with hot reload
pnpm build        # Production build
pnpm test         # Run test suite

# Run from packages/web (no root script forwards these)
pnpm -C packages/web lint         # Run ESLint
pnpm -C packages/web format       # Format code with Prettier
pnpm -C packages/web db:generate  # Generate new migration from schema changes
pnpm -C packages/web db:migrate   # Apply pending migrations
pnpm -C packages/web db:studio    # Open Drizzle Studio (database browser)

Only dev, build, and test are exposed at the repository root and forwarded to packages/web/. The linting, formatting, and database commands live in packages/web/ only, so run them with pnpm -C packages/web <command>.