Quick Start
This guide walks you through getting Pinchy up and running — from cloning the repo to chatting with your first AI agent.
Prerequisites
Section titled “Prerequisites”- Docker and Docker Compose (v2+)
- An API key from an LLM provider (Anthropic, OpenAI, or Google)
1. Clone the repository
Section titled “1. Clone the repository”git clone https://github.com/heypinchy/pinchy.gitcd pinchy2. Start the stack
Section titled “2. Start the stack”docker compose up --buildThis starts three services:
- Pinchy — the web app on port 7777
- OpenClaw — the AI agent runtime (internal, not exposed)
- PostgreSQL — the database
Wait until you see Pinchy ready on http://localhost:7777 in the logs.
3. Create your admin account
Section titled “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
Section titled “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 |
| aistudio.google.com |
Your API key is encrypted at rest using AES-256-GCM before being stored in the database.
5. Chat with Smithers
Section titled “5. Chat with Smithers”Once your provider is configured, Pinchy redirects you to the chat interface. Your default agent — Smithers — greets you automatically.
Type a message and hit Enter. Smithers responds in real time via WebSocket.
6. Invite your team
Section titled “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)
Section titled “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:
- 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)
- Permissions — Configure which tools and directories the agent can access
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.
What’s next?
Section titled “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