Upgrading Pinchy

Pinchy handles most upgrade steps automatically — database migrations run on startup, and the OpenClaw configuration is regenerated from your current settings. A typical upgrade takes under a minute.

Standard upgrade

Back up your database

Before any upgrade, create a database backup. This lets you roll back if anything goes wrong.
Terminal window
```
docker compose exec db pg_dump -U pinchy pinchy > backup-$(date +%Y%m%d).sql
```

Pull the new version

cd pinchy
git fetch --tags
git checkout v0.2.0  # or the version you're upgrading to

Rebuild and start
Terminal window
```
docker compose up --build
```
This rebuilds the Docker images, applies any pending database migrations, regenerates the OpenClaw configuration, and restarts all services.
Verify

Open http://localhost:7777 and confirm everything works. Check the logs for any warnings:
Terminal window
```
docker compose logs pinchy --tail 50
```

What happens automatically

You don’t need to worry about these — Pinchy handles them on every startup:

Database migrations — Drizzle ORM tracks which migrations have been applied and only runs new ones. This is idempotent and safe to run repeatedly.
OpenClaw configuration — Rebuilt from your database state (agents, providers, permissions) every time Pinchy starts. Config format changes between versions are handled transparently.
Plugins — Copied from the source code into the OpenClaw extensions volume during the Docker build.

What you might need to check

New environment variables — Check the release notes for any new variables. Pinchy won’t crash if they’re missing (features may just be disabled), but review them in your .env file.
Docker Compose changes — If docker-compose.yml changed between versions (new volumes, new services), git pull picks those up automatically. New volumes are created on first start.

Restoring from backup

If you need to roll back after an upgrade:

Stop Pinchy
Terminal window
```
docker compose down
```

Restore the database

docker compose up db -d
docker compose exec -T db psql -U pinchy pinchy < backup-YYYYMMDD.sql

Check out the previous version

git checkout v0.1.0  # the version you were on before

Rebuild and start
Terminal window
```
docker compose up --build
```

Upgrading from v0.2.1 to v0.3.0

Standard upgrade — no breaking changes, no new required environment variables.

git fetch --tags
git checkout v0.3.0
docker compose up --build

What’s new in v0.3.0

Usage & Cost Stats dashboard — admins can view token usage and estimated costs per agent and per user at /usage.
Smart PDF reading — Knowledge Base agents can now extract text from PDFs automatically.
Dynamic model selection — the default model is selected from your provider’s live model list rather than being hardcoded.
Rate limiting on WebSocket connections — protects the gateway from connection floods.
Setup password recovery — admins can recover access via the PINCHY_ADMIN_EMAIL environment variable if locked out.
Security hardening — timing-safe token validation, fail-closed audit logging.

New optional environment variable: PINCHY_ADMIN_EMAIL

If you want to be able to recover admin access via the setup wizard, add this to your .env:

PINCHY_ADMIN_EMAIL=your-admin@example.com

This is optional — Pinchy works fine without it.

Upgrading from v0.2.0 to v0.2.1

This is a docs-only release — no code changes, no database migrations, no breaking changes. Just pull the new tag and rebuild:

git checkout v0.2.1 && docker compose up --build

Upgrading from v0.1.0 to v0.2.0

This section covers what changed and what to expect.

All users must log in again

The authentication system was upgraded to Better Auth. Existing login sessions are invalidated during the migration. Passwords are preserved — users just need to log in again.

New environment variable: PINCHY_ENTERPRISE_KEY

v0.2.0 introduces enterprise features (Groups, RBAC, agent access control). To enable them, set the PINCHY_ENTERPRISE_KEY environment variable in your .env file or docker-compose.yml. This is optional — Pinchy works fine without it, and the key can also be entered via Settings in the UI.

OpenClaw runtime updated

The bundled OpenClaw runtime was updated from 2026.3.7 to 2026.3.13. This happens automatically when you rebuild with docker compose up --build.

Version history

Check the Releases page for detailed changelogs and any version-specific upgrade notes.