Quick Start

This guide walks you through getting Pinchy up and running — from downloading Pinchy to chatting with your first AI agent.

Prerequisites

• Docker (includes Docker Compose v2)
• An API key from an LLM provider (Anthropic, OpenAI, Google, or Ollama)

1. Download the Compose file

mkdir -p pinchy && cd pinchy
curl -fsSL https://raw.githubusercontent.com/heypinchy/pinchy/v0.5.4/docker-compose.yml -o docker-compose.yml

2. Start the stack

docker compose pull
docker compose up -d

This starts three services:

• Pinchy — the web app on port 7777
• OpenClaw — the AI agent runtime (internal, not exposed)
• PostgreSQL — the database

Wait until docker compose logs pinchy shows Pinchy ready on http://localhost:7777.

3. Create your admin account

Open http://localhost:7777 in your browser. The setup wizard appears automatically on first run.

Enter your name, email, and password. This creates the first admin user.

4. Configure your AI provider

After creating your account, Pinchy redirects you to the provider setup page. Choose your LLM provider and enter your API key:

Provider	Where to get a key
Anthropic	console.anthropic.com
OpenAI	platform.openai.com
Google	aistudio.google.com
Ollama	ollama.com

Your API key is encrypted at rest using AES-256-GCM before being stored in the database.

5. Chat with Smithers

Once your provider is configured, Pinchy redirects you to the chat interface. Your default agent — Smithers — greets you automatically and starts a short onboarding interview to learn about you (and your organization, if you’re an admin). This builds context that every agent on the platform can use.

Type a message and hit Enter. Smithers responds in real time via WebSocket. See Smithers Onboarding for what Smithers asks and how the context is saved.

6. Invite your team

Go to Settings → Users to invite team members. Enter their email address and Pinchy generates a one-time invite link.

Each invited user gets their own personal Smithers agent, created automatically when they claim the invite. Invite links are valid for 7 days.

7. Create a Knowledge Base Agent (optional)

You can create agents from templates. Creating an agent is simple: pick a template, give it a name, add an optional tagline, and click Create. Each agent gets a unique auto-generated avatar.

For example, a Knowledge Base agent can read text files, Markdown, and PDF documents (including scanned PDFs with vision-capable models) from directories you select — but has no access to anything else by default.

After creating the agent, you can customize it through the agent settings tabs. Which tabs you see depends on your role and the agent type:

Always visible:

• General — Change the agent’s name, tagline, avatar, and model
• Personality — Choose a personality preset or write custom personality instructions (SOUL.md)
• Instructions — Define what the agent should do and how it should handle tasks (AGENTS.md)

Admin-only, shared agents only:

• Permissions — Configure which tools and directories the agent can access
• Access Enterprise — Set visibility to all users or restrict to specific groups

Admin-only, any agent:

• Telegram — Connect a Telegram bot to this agent

Smithers is a personal agent per user, so Permissions and Access don’t apply — they only exist for shared agents. See Agent Settings for the full reference.

User and organization context (personal preferences, team structure, company conventions) is managed in Settings → Context, not in per-agent settings.

To try it out, mount a directory with documents into the Pinchy container and create an agent from the Knowledge Base template. See the Create a Knowledge Base Agent guide for the full walkthrough.

Recently added

• Web Search — Give agents live web access via the Brave Search API, with per-agent domain allow/deny lists
• Gmail Integration — Let agents read, search, draft, and send emails through a guided OAuth wizard
• Telegram Channels — Chat with your agents from Telegram, with user accounts linked via pairing code
• Odoo Integration — Give agents scoped, permission-aware access to your Odoo ERP with 16 pre-built templates
• Ollama (Local & Cloud) — Run agents fully air-gapped on your own hardware, or use Ollama Cloud models
• Usage & Costs Dashboard — Track token usage, estimated costs, and cache savings per agent and user

What’s next?

• Installation — Learn about environment variables, Docker volumes, and development setup
• Architecture — Understand how Pinchy wraps OpenClaw and the request flow
• Agent Permissions — Learn how Pinchy restricts what agents can access
• Audit Trail — Cryptographic audit logging for compliance and security
• API Reference — REST API endpoints for managing agents and settings