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, or Google)

Docker Compose (recommended)

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

git clone https://github.com/heypinchy/pinchy.git
cd pinchy
git checkout v0.3.0
docker compose up --build

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

No configuration is needed to get started. All secrets (session key, encryption key, HMAC signing key) are auto-generated on first start and persisted in Docker volumes so they survive restarts.

Optional: production hardening

For production deployments, create a .env file in the project root to pin your own secrets instead of relying on auto-generated ones:

# Database password (default: pinchy_dev)
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, RBAC, agent access control)
PINCHY_ENTERPRISE_KEY=

DB_PASSWORD — Password for the PostgreSQL pinchy user. Defaults to pinchy_dev in Docker Compose.

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, RBAC, agent access control). 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, context files)
`pinchy-secrets`	`/app/secrets` (Pinchy)	Auto-generated encryption and HMAC keys
`openclaw-extensions`	`/openclaw-extensions` (Pinchy), `/root/.openclaw/extensions` (OpenClaw)	Pinchy plugins for OpenClaw

Port configuration

To change the exposed port, update both docker-compose.yml and the PORT environment variable:

services:
  pinchy:
    ports:
      - "3000:3000"
    environment:
      - PORT=3000

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 db:migrate

# Start the dev server
pnpm dev

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

Available commands

pnpm dev          # Start dev server with hot reload
pnpm build        # Production build
pnpm test         # Run test suite
pnpm lint         # Run ESLint
pnpm format       # Format code with Prettier
pnpm db:generate  # Generate new migration from schema changes
pnpm db:migrate   # Apply pending migrations
pnpm db:studio    # Open Drizzle Studio (database browser)

All commands run from the repository root and are forwarded to packages/web/ via pnpm workspace.