# Percher

> AI-native hosting for personal and small-scale apps. This is the short orientation file for agents. Read https://percher.app/llms-full.txt for the complete public documentation corpus, or https://percher.app/docs for the human-friendly version.

## Safe default workflow

1. Inspect the project before changing configuration.
2. Run `bunx percher publish` from the project directory. Use `npx percher publish` when Bun is unavailable.
3. If the command asks for sign-in or an app name, ask the user to complete or confirm that step. Never invent credentials, domains, billing choices, or destructive confirmations.
4. Keep secrets out of source code and `percher.toml`; set them with `percher env set KEY=VALUE`.
5. Wait for the deploy to become live, test the main user flow, and return the live URL. On failure, run `percher doctor` and follow its exact recovery action.

Copyable user prompt:

```text
Publish this project to Percher. Read https://percher.app/docs/quick-start first. If you cannot access the project files or run Percher tools, tell me how to connect you instead of guessing. Before the first deploy, confirm the public app name with me. Keep secrets out of source code and return the live URL when the deploy is healthy.
```

## Connect an AI assistant

- Local MCP (54 tools): run `bunx percher mcp` and use the printed configuration.
- Hosted MCP (23 tools): connect `https://mcp.percher.app/mcp` and authenticate through the client.
- Project instructions: `bunx percher ai-files install` manages `CLAUDE.md` and `.cursor/rules/percher.mdc`. Existing user-edited files are preserved unless the user explicitly chooses to replace them.
- GitHub: `bunx percher github connect https://github.com/OWNER/REPO`; a full HTTPS repository URL is required.

## Documentation map

- [Get started](https://percher.app/docs/quick-start): Get an AI-built app (or a Claude artifact) to a live URL
- [Recommended configurations by app type](https://percher.app/docs/recommended-setup): Resource and data presets per app type
- [CLI reference](https://percher.app/docs/cli-reference): Every public CLI command, grouped by task
- [Package versions and licences](https://percher.app/docs/licensing): The 1.0 licence boundary, generated project files, and upgrading npm tools
- [GitHub & CI/CD](https://percher.app/docs/github-cicd): Auto-deploy on push + PERCHER_TOKEN for GitHub Actions
- [Environment variables](https://percher.app/docs/env-vars): Set, unset, list, encryption
- [Password protection](https://percher.app/docs/password-protection): SITE_PASSWORD env + [web] password = true
- [percher.toml — full reference](https://percher.app/docs/percher-toml): Every field and allowed value
- [Deploy history and retention](https://percher.app/docs/retention): Rollback artifacts, build logs, live logs, and monitoring history
- [Telemetry](https://percher.app/docs/telemetry): What's collected from the CLI and local MCP server
- [Versions and rollback](https://percher.app/docs/versions): Git-backed deploy history
- [Zero-downtime deploys](https://percher.app/docs/graceful-deploys): Drain + canary + auto-rollback
- [Preview deploys](https://percher.app/docs/previews): Four ways to get a shareable URL before going live
- [Troubleshooting common errors](https://percher.app/docs/troubleshooting): Fixes for the errors you're most likely to hit during a deploy
- [Custom domains](https://percher.app/docs/custom-domains): TXT verification, then CNAME (or A records on an apex)
- [Publishing to the App Store & Google Play](https://percher.app/docs/app-stores): Use Percher as the backend/web layer for a store app
- [Persistent app data](https://percher.app/docs/persistent-data): /app/data volume mount
- [Deploy hooks](https://percher.app/docs/deploy-hooks): POST a URL to trigger a redeploy
- [Deploy instruction for AI agents](https://percher.app/docs/ai-agents): CLAUDE.md content for agentic deploys
- [MCP tools for AI assistants](https://percher.app/docs/mcp-tools): All 54 MCP tools
- [Hosted MCP connector](https://percher.app/docs/hosted-mcp): Add Percher to Claude, ChatGPT, Codex, Gemini, Cursor and other AI clients as a hosted, OAuth-protected connector — no install
- [Managed AI inference](https://percher.app/docs/managed-inference): Approval-gated, keyless LLM calls hosted in Paris
- [Bring your own LLM provider](https://percher.app/docs/byo-inference): Call any OpenAI-compatible API with your own key — no platform setup
- [Crash diagnostics](https://percher.app/docs/crash-diagnostics): Crash reports and runtime troubleshooting; external AI analysis is currently disabled
- [Monitoring & alerts](https://percher.app/docs/monitoring): External uptime probes, app.unhealthy / app.recovered, top error paths
- [Visitor analytics](https://percher.app/docs/analytics): Cookie-free visitor stats on paid plans
- [Cost optimization insights](https://percher.app/docs/cost-insights): Idle, memory-pressure, overprovisioned, deploy-regression
- [Multi-instance & auto-scaling](https://percher.app/docs/multi-instance): resources.instances and [resources.autoscale]
- [Event webhooks](https://percher.app/docs/webhooks): Signed deploy.succeeded / deploy.failed / app.crashed / domain.expiring
- [Security scanning](https://percher.app/docs/security-scanning): Automatic CVE scanning + alerts
- [Capsule — the zero-glue full-stack lane](https://percher.app/docs/capsule): Scaffold a db + auth + realtime app with the schema pre-provisioned
- [PocketBase — database, auth & files](https://percher.app/docs/pocketbase): Managed SQLite-backed backend
- [Connect an external database](https://percher.app/docs/external-databases): Keep Supabase, Convex, or another compatible provider
- [Per-app KV store](https://percher.app/docs/kv-store): Simple key/value API for flags, counters, and small caches
- [Export PocketBase data](https://percher.app/docs/export-data): Download your database and files as a .tar.gz archive
- [Backup & restore](https://percher.app/docs/backup-and-restore): Daily encrypted off-site backups, self-service restore
- [Billing & plans](https://percher.app/docs/billing): Dashboard, MCP, or Suggestions card
- [Migrating from Supabase](https://percher.app/docs/migrate-supabase): Keep Supabase or switch to PocketBase
- [Migrating from Convex](https://percher.app/docs/migrate-convex): Keep Convex or switch to PocketBase
- [Migrating from Vercel](https://percher.app/docs/migrate-vercel): What works, what needs changes
- [Migrating from Lovable](https://percher.app/docs/migrate-lovable): Build in Lovable, host on Percher — keep your Supabase backend