Installation

Note

This guide covers Pinchy v0.5.4. Check the Releases page for newer versions. Upgrading from v0.1.0? See the Upgrade Guide.

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

Tip

For fully air-gapped deployments, you can use local Ollama instead of a cloud provider. No API keys needed — everything runs on your hardware.

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.5.4/docker-compose.yml -o docker-compose.yml
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

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.

Tip

For a quick local trial, skip straight to the Getting Started guide — no .env file required.

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

# Public HTTPS origin for Better Auth callback and redirect URLs
BETTER_AUTH_URL=https://pinchy.example.com

# 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. 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.

BETTER_AUTH_URL — Public HTTPS origin used by Better Auth to build callback and redirect URLs, for example password reset, OAuth, and Telegram pairing flows. Set this to the same origin users visit, such as https://pinchy.example.com. Domain Lock is configured separately in Settings → Security; when you lock a domain, use the same hostname here.

Caution

The v0.4.4 docker-compose.yml shown above does not pass BETTER_AUTH_URL through. If your compose file does not include BETTER_AUTH_URL=${BETTER_AUTH_URL:-} under the pinchy service environment: block, upgrade to a newer compose file or add it via docker-compose.override.yml.

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, 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

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 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.