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.

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

Projects are normal folders. Close Piye and your code is still a Next.js, Expo, or Electron repo.

One project, two modes

Builder and IDE are two views of the same files, not two products that sync.

Ships from inside

Simulators, deploy targets, app stores, and live operations live in the same window.

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 folder
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?

If you describe what you want and judge the result by looking at it, read the Builder guide. If you read diffs and run commands, read the IDE guide. Most teams use both.

Start

Install

Piye runs on macOS, Windows, and Linux. Download the installer from the home page, or install from a terminal:

Terminal
curl -fsSL https://get.piye.dev/install.sh | bash
PlatformWhat you getNotes
macOSSigned app in ApplicationsiOS Simulator needs Xcode for mobile projects.
WindowsInstaller with auto-updateAndroid emulator needs Android Studio.
LinuxAppImage or packageKeychain uses libsecret when available.

Note

Piye manages the command line tools it needs (for example Vercel, Railway, or EAS) inside the app. You do not have to install every host CLI yourself before you start.

Start

Your first ten minutes

  1. 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.
  2. 02

    Pick where you start

    Settings, General, Start in chooses Builder or the IDE. You can switch any time from the project name menu.
  3. 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.
  4. 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.
  5. 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.

Piye on your machinepiye.dev gatewayModel providerStreamed answer
Piye Cloud request path. Files and tools never leave your machine; only the model request does.

Credits

Monthly credits

Every plan includes credits each month: Starter 150, Pro 800, Studio 3,000, Ultra 9,000, Business 2,000. One credit is $0.01 of what the AI work really costs.

Credit packs

On paid plans and Pay as you go, buy packs whenever you run low. They carry over month to month.

Spending cap

Set a monthly cap on the web. Piye Cloud stops at the cap. Your own keys and local models keep working.
PlanPrice a monthCredits a monthActive projects
Starter€01502
Pro€2080010
Studio€703,000Unlimited
Ultra€2009,000Unlimited
Business€40 a seat2,000 a seatUnlimited

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.

ModelContextUse it for
Claude Opus 5.5 Recommended1MHard refactors, architecture, the deepest reasoning.
Claude Sonnet 5 Default1MDaily building and debugging. Best balance.
Claude Haiku 4.5 Fastest200KQuick questions, small edits, high-volume work.
Claude Fable 5.11MLong-horizon tasks that run for many steps.
Claude Mythos 5.11MResearch and exploration.

Two ways to run Claude

Through Piye Cloud

No Anthropic account. Requests go through /api/ai/anthropic on piye.dev and count against your Cloud wallet.

With your Anthropic key

Paste a key in Settings, AI. Requests go straight to Anthropic and are billed by Anthropic. Piye adds nothing.

Tip

Builder's Auto setting picks quick models for each step. With Customize you choose the model for each step yourself, such as Claude Opus for the design. See Build power.

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.

ProviderHighlights
AnthropicClaude Opus 5.5, Sonnet 5, Haiku 4.5, Fable 5.1, Mythos 5.1, plus earlier Claude versions.
OpenAIGPT-6 Astra, GPT-5.6 Sol, Terra, Luna, the GPT-5 family, GPT-4.1, o3 and o4 reasoning models.
GoogleGemini 3.8 Flash, Gemini 3.1 Pro, Flash-Lite variants.
xAIGrok 4.7, Grok Build 0.1, Grok 4.20 reasoning and multi-agent.
Mistral EuropeanMistral Large, Medium, Small, Codestral, Ministral.
Ollama LocalAny 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.

  1. 01

    Get a key

    Create an API key at Anthropic, OpenAI, Google AI Studio, Mistral, or xAI.
  2. 02

    Add it to Piye

    Settings, AI, provider keys. Paste and save. The key goes straight into your OS keychain.
  3. 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.
  4. 04

    Pick a model

    Models from providers with a key show as available in the model picker.

Where keys live

Keys are stored with the operating system keychain through Electron safe storage, under a reserved owner id no extension can read. The interface only ever receives a yes or no for "is a key saved", never the key itself. On Linux without libsecret, Piye falls back to a documented local file.

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

Your plan, the credits you have left this month and your spending cap show in Settings, Account and on the web. When you run out or reach your cap, the current turn finishes and new Piye Cloud turns pause until next month, a credit pack, a higher cap, or a switch to your own key.

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

Sign in through the browser, then refresh a short-lived session token.

AI gateway

Provider-compatible passthrough for Anthropic, OpenAI, Google, Mistral, and xAI.

Usage

Read your plan, limits, and current month usage.

Status

The API is stable for the desktop app. Public API keys for scripts arrive with billing. Until then, requests use your signed-in session token.

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.

MethodPathWhat it does
GET/api/extension-auth/startStarts browser sign-in and returns the token to a local loopback URL.
GET/api/ai/sessionReports whether a token is valid and when it expires.
POST/api/ai/sessionExchanges a still-valid token for a fresh one. Expired tokens need a new sign-in.
Refresh a session
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.

ProviderEndpoint
AnthropicPOST /api/ai/anthropic/v1/messages
OpenAIPOST /api/ai/openai/v1/chat/completions
GooglePOST /api/ai/google/v1beta/models/{model}/generateContent
MistralPOST /api/ai/mistral/v1/chat/completions
xAIPOST /api/ai/xai/v1/chat/completions
Claude through Piye Cloud
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" }]
  }'
Anthropic SDK pointed at Piye
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.

Response
{
  "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" } }.

StatusTypeMeaning
401authentication_errorNo token, or it expired. Sign in to Piye again.
404not_found_errorThat provider path is not supported by the gateway.
500api_errorThe provider is not configured on the server.
502api_errorPiye 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.

Founder invitesLink by emailDeveloper opens PiyeSame project, IDE side

Summary for the reader

Invites carry a short summary written for the person receiving it, developer or non-technical.

GitHub, privately

Piye can push the project to a private repo on your GitHub through the Piye GitHub App, so the developer clones a real repository.

Note

Handoff shares a project. It is not live multiplayer editing.

Team and trust

Where your data lives

WhatWhere
Source codeYour project folder and your Git remote.
Piye project state.piye/ inside the project (blueprint, memory, launch configs, outbox).
API keys and tokensYour OS keychain.
MCP connections~/Library/Application Support/Piye/mcp.json on macOS.
Account, plan, invoicesPiye web app and Stripe.
Model requestsThe 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

SymptomWhat to do
Sign in to Piye to use the AI agentYour session expired. Sign in again from the profile menu.
Model unavailableAdd a key for that provider, sign in to Piye Cloud, or pick another model.
AI is offPrivacy Mode or Disable AI is on. Turn it off, or enable Ollama for local Ask.
Docker: Engine offlineStart Docker Desktop. Deploy can still ship through a remote builder.
Preview shows Piye itselfThe 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.

© 2026 Piye TechnologiesPrivacyTermsCookiesSupportChangelog
Docs · Piye