Documentation
Piye, explained.
Piye is Project OS: an AI web and mobile builder and a full IDE in one desktop app, working on the same files. Start here for install, accounts, AI, keys, and the API. Then pick the guide for the side you work on.
Builder guide
IDE guide
AI, keys and API
Start
What is Piye
Most teams split work between a no-code tool for the idea and an IDE for the real product, then pay for the gap with exports, rewrites, and screenshots in chat. Piye removes the gap. The founder and the developer open the same project folder. One sees a conversation, a map, and a live preview. The other sees the code, the terminal, and Git.
Piye is a desktop app built on Electron, React, and Monaco. It is not a VS Code fork and not a browser IDE. Your source lives on your disk and in your Git. Secrets live in your operating system keychain. The web app at piye.dev handles your account, billing, invites, and the Piye Cloud AI gateway.
Local first
One project, two modes
Ships from inside
Start
Two modes, one project
Every Piye project can be opened in Builder (also called Low Code) or in the IDE (Developer mode). Switching is instant. Nothing is exported, converted, or copied. A change Builder makes is a real file change the developer can review in Git. A change the developer commits shows up in the founder's preview.
Builder
For the person with the idea
- Comm-Link conversation
- Blueprint map of the app
- Live web and phone preview
- Publish on your own accounts
same Git
same .piye/
IDE
For the person who writes code
- Editor, terminal, Git, debug
- Agent with Ask, Architect, Build, Debug
- Simulators, deploy, operations
- MCP and extensions
Which guide should I read?
Start
Install
Piye runs on macOS, Windows, and Linux. Download the installer from the home page, or install from a terminal:
curl -fsSL https://get.piye.dev/install.sh | bash| Platform | What you get | Notes |
|---|---|---|
| macOS | Signed app in Applications | iOS Simulator needs Xcode for mobile projects. |
| Windows | Installer with auto-update | Android emulator needs Android Studio. |
| Linux | AppImage or package | Keychain uses libsecret when available. |
Note
Start
Your first ten minutes
- 01
Sign in
Open Piye and choose Sign in. Your browser opens piye.dev, you log in with Google, GitHub, or email, and Piye receives a session automatically. - 02
Pick where you start
Settings, General, Start in chooses Builder or the IDE. You can switch any time from the project name menu. - 03
Create or open a project
In Builder, describe an app or pick a template. In the IDE, open a folder or clone a repo. Either way you get a normal folder with a.piye/directory for Piye's own state. - 04
Choose your AI
Use Piye Cloud, add your own provider keys, or run local models with Ollama. See Piye Cloud AI and Bring your own key. - 05
Ship something
Press Publish in Builder, or open Deploy in the IDE. Both use the same hosts and the same project.
Account
Account and sign-in
Your Piye account lives on the web app. It holds your profile, plan, invoices, invites, and the session the desktop app uses for Piye Cloud. You can sign in with Google, GitHub, or email and password with email verification.
- The desktop app opens your browser to sign in and receives a short-lived session on a local loopback port.
- That session refreshes itself while you work, so you only see the browser again after real inactivity.
- Sign out in the profile menu. This removes the session from your keychain.
Account
Plans
Prices are per month in euros. You can change or cancel any time. Not ready for a plan? Pay as you go has no subscription: 150 free credits a month, then the credits you buy.
Try Piye on a first project
Starter
€0
- 150 credits a month (up to 60 a day)
- 2 active projects
- Fast, Auto and Customize builds
- Local IDE and developer agent
- Community support
For shipping your first products
Pro
€20
- 800 credits a month
- 10 active projects
- Unlimited Comm-Link sessions
- One-click deploy
- Top up with credit packs anytime
For founders building every week
Studio
€70
- 3,000 credits a month
- Unlimited projects
- Room for larger models in Customize
- Operations radar
- Full MCP toolset
- Everything in Pro
For studios and power builders
Ultra
€200
- 9,000 credits a month
- Priority reasoning
- Room for the largest models in Customize
- Everything in Studio
For teams building together
Business
€40 a seat
- 2,000 credits per seat a month, shared by the team
- Unlimited projects
- Room for larger models in Customize
- Team workspace and roles
- Invoices with your VAT number
Compare plans and upgrade on Pricing. Inside the app, Settings, Account shows your current plan, what it includes, and a button to upgrade or manage billing.
Account
Billing and invoices
Subscriptions are processed by Stripe. Piye never sees or stores your full card number. Promo codes are entered on the pricing page before checkout.
- Invoices and VAT come from Stripe and are available in the billing portal.
- Cancel from the billing portal. You keep access until the end of the paid period.
- EU consumers may have a 14-day right of withdrawal. See the Terms.
- Payment problems: Stripe retries the card and emails you. Your projects stay on your disk either way.
AI
Piye Cloud AI
Piye Cloud lets you use the full model catalog without creating accounts at Anthropic, OpenAI, Google, Mistral, or xAI. You sign in once. Piye's gateway swaps your session for Piye's provider key and streams the answer back.
The agent loop, your files, diffs, and tools always run on your machine. The gateway only sees the request the agent sends to the model, the same way a provider would if you used your own key.
Credits
Monthly credits
Credit packs
Spending cap
| Plan | Price a month | Credits a month | Active projects |
|---|---|---|---|
| Starter | €0 | 150 | 2 |
| Pro | €20 | 800 | 10 |
| Studio | €70 | 3,000 | Unlimited |
| Ultra | €200 | 9,000 | Unlimited |
| Business | €40 a seat | 2,000 a seat | Unlimited |
AI
Claude on Piye
Claude is the default family in Piye. New installs start on Claude Sonnet 5, which balances speed and depth for everyday Build turns. Pick another model per conversation in the Agent panel or Comm-Link, or set a default in Settings, AI.
| Model | Context | Use it for |
|---|---|---|
| Claude Opus 5.5 Recommended | 1M | Hard refactors, architecture, the deepest reasoning. |
| Claude Sonnet 5 Default | 1M | Daily building and debugging. Best balance. |
| Claude Haiku 4.5 Fastest | 200K | Quick questions, small edits, high-volume work. |
| Claude Fable 5.1 | 1M | Long-horizon tasks that run for many steps. |
| Claude Mythos 5.1 | 1M | Research and exploration. |
Two ways to run Claude
Through Piye Cloud
/api/ai/anthropic on piye.dev and count against your Cloud wallet.With your Anthropic key
Tip
AI
Model catalog
Every listed model can drive the agent loop: text in, text out, with tools. Image-only, audio, and embedding models are left out because they cannot operate the IDE.
| Provider | Highlights |
|---|---|
| Anthropic | Claude Opus 5.5, Sonnet 5, Haiku 4.5, Fable 5.1, Mythos 5.1, plus earlier Claude versions. |
| OpenAI | GPT-6 Astra, GPT-5.6 Sol, Terra, Luna, the GPT-5 family, GPT-4.1, o3 and o4 reasoning models. |
| Gemini 3.8 Flash, Gemini 3.1 Pro, Flash-Lite variants. | |
| xAI | Grok 4.7, Grok Build 0.1, Grok 4.20 reasoning and multi-agent. |
| Mistral European | Mistral Large, Medium, Small, Codestral, Ministral. |
| Ollama Local | Any model you have pulled locally. Ask mode only. |
AI
Bring your own key
Bring your own key (BYOK) means Piye calls the provider with your API key. You pay the provider directly and Piye Cloud is not involved. BYOK works on every plan, including Starter.
- 01
Get a key
Create an API key at Anthropic, OpenAI, Google AI Studio, Mistral, or xAI. - 02
Add it to Piye
Settings, AI, provider keys. Paste and save. The key goes straight into your OS keychain. - 03
Check routing
Prefer local keys (Settings, AI, Routing) uses your key whenever one is saved for that provider. Piye Cloud still covers providers you have not added. On Starter this is always on. - 04
Pick a model
Models from providers with a key show as available in the model picker.
Where keys live
AI
Privacy Mode
Privacy Mode (Settings, Privacy) blocks Piye Cloud and every personal API key. Nothing about your code leaves the machine. If you enable Ollama under Settings, AI, you can keep chatting with local models.
- Local models run in Ask mode only: they read and explain, they do not write files, run commands, or call MCP tools.
- Deploy and Publish AI helpers switch off while Privacy Mode is on.
- Conversation history retention is set in the same section.
AI
Usage and limits
Piye records tokens per turn and shows an estimated cost per day in the profile menu, the Agent panel, and Settings, AI. Estimates use published per-model rates and are labelled as estimates.
Tip
API
API overview
The Piye web app exposes a small API that the desktop app uses. It is documented here so you can understand what Piye sends and build tools against your own account.
Session
AI gateway
Usage
Status
API
Authentication
Requests carry a Piye session token as Authorization: Bearer <token>. The gateway also accepts the token in x-api-key, so provider SDKs work unchanged. Tokens are HMAC signed and live 30 minutes.
| Method | Path | What it does |
|---|---|---|
| GET | /api/extension-auth/start | Starts browser sign-in and returns the token to a local loopback URL. |
| GET | /api/ai/session | Reports whether a token is valid and when it expires. |
| POST | /api/ai/session | Exchanges a still-valid token for a fresh one. Expired tokens need a new sign-in. |
curl -X POST https://piye.dev/api/ai/session \
-H "Authorization: Bearer $PIYE_TOKEN"
# { "token": "eyJ…", "expiresAt": 1790000000000 }API
Endpoints
Each gateway route mirrors the provider's own API. Send the same body you would send to the provider; Piye adds the provider key server-side and streams the response through untouched.
| Provider | Endpoint |
|---|---|
| Anthropic | POST /api/ai/anthropic/v1/messages |
| OpenAI | POST /api/ai/openai/v1/chat/completions |
POST /api/ai/google/v1beta/models/{model}/generateContent | |
| Mistral | POST /api/ai/mistral/v1/chat/completions |
| xAI | POST /api/ai/xai/v1/chat/completions |
curl https://piye.dev/api/ai/anthropic/v1/messages \
-H "Authorization: Bearer $PIYE_TOKEN" \
-H "content-type: application/json" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [{ "role": "user", "content": "Summarise this repo" }]
}'import Anthropic from "@anthropic-ai/sdk";
const claude = new Anthropic({
baseURL: "https://piye.dev/api/ai/anthropic",
apiKey: process.env.PIYE_TOKEN, // sent as x-api-key
});
const msg = await claude.messages.create({
model: "claude-opus-5-5",
max_tokens: 2048,
messages: [{ role: "user", content: "Plan a booking app" }],
});API
Usage endpoint
GET /api/usage/current returns your plan, its limits, and this month's counters. It uses the web session cookie, so call it from the signed-in browser or the dashboard.
{
"period": { "month": "2026-10" },
"plan": "PRO",
"limits": { "monthlyCredits": 800, "monthlyCap": null },
"usage": { "creditsUsed": 320, "creditsLeft": 480 },
"planName": "Pro"
}API
Errors
Errors use the provider style: { "error": { "type", "message" } }.
| Status | Type | Meaning |
|---|---|---|
| 401 | authentication_error | No token, or it expired. Sign in to Piye again. |
| 404 | not_found_error | That provider path is not supported by the gateway. |
| 500 | api_error | The provider is not configured on the server. |
| 502 | api_error | Piye could not reach the model provider. Retry. |
Team and trust
Founder to developer handoff
Anyone can invite anyone, technical or not, into a project. The invite is a link. Opening it on a machine with Piye starts the project there; without Piye, the link page offers the download and picks up where it left off.
Summary for the reader
GitHub, privately
Note
Team and trust
Where your data lives
| What | Where |
|---|---|
| Source code | Your project folder and your Git remote. |
| Piye project state | .piye/ inside the project (blueprint, memory, launch configs, outbox). |
| API keys and tokens | Your OS keychain. |
| MCP connections | ~/Library/Application Support/Piye/mcp.json on macOS. |
| Account, plan, invoices | Piye web app and Stripe. |
| Model requests | The provider you chose, through Piye Cloud or directly with your key. |
Piye does not train models on your projects and does not sell personal data. Read the Privacy Policy for GDPR details and processors.
Team and trust
Security
- Env values are never shown. Deploy and Operations show variable names and sync status only. The agent never prints a secret, even if it reads a file that contains one.
- Deletes always wait for your approval, even in Auto mode.
- Commands the agent runs are approved by you and run as a separate process.
- Extensions go through one permission broker, the same check for their UI and their AI tools.
Report a vulnerability to security@piye.dev.
Team and trust
Troubleshooting and help
| Symptom | What to do |
|---|---|
| Sign in to Piye to use the AI agent | Your session expired. Sign in again from the profile menu. |
| Model unavailable | Add a key for that provider, sign in to Piye Cloud, or pick another model. |
| AI is off | Privacy Mode or Disable AI is on. Turn it off, or enable Ollama for local Ask. |
| Docker: Engine offline | Start Docker Desktop. Deploy can still ship through a remote builder. |
| Preview shows Piye itself | The preview URL points at Piye. Use your app's URL or a simulator. |
Still stuck? Contact support, request a feature, or ask in the community.