Tutorial

Build your first poppy — with your AI agent

This is the honest secret of the platform: you don't hand-write a poppy, you direct one into existence. The SDK, the build guide (AGENTS.md), and the example are written for AI coding agents. You describe what to build; your agent does the rest inside the guardrails. Founders here ship 3–4 polished poppies a week this way.

The flow at a glance

1. Start from the example

   Copy examples/hello-poppy. Give it a reverse-DNS id (com.you.your-poppy) and a display name that ends in “Poppy” — that's the one required use of the brand, and your name must be unique in the catalogue. Draw your own icon; imitating another poppy's mark is grounds for delisting.

2. Hand your agent the starter prompt

   The platform ships a copy-paste starter prompt (docs/STARTER_PROMPT.md) that points your agent at the build guide, the SDK, and the example — plus the non-negotiable rules. You fill in one placeholder: what to build. Plain language is enough: “a poppy that hosts a private photo archive in my AWS with albums and sharing links.”

3. Declare access like your rating depends on it — it does

   Everything your poppy can do in the cloud comes from the manifest's permissionSet. Least privilege isn't a virtue here, it's a conversion rate: scoped grants rate green or amber on the user's approval screen; an unscoped mutate-existing grant rates red — and red doesn't ship.

4. Validate and install

   npm run validate-manifest -- path/to/extension.json
   node scripts/install-dev-extension.mjs --src path/to/your-poppy

   Relaunch the app (npm run -w @agentspoppy/app tauri:dev), open your poppy's tab, and check the approval screen: the target is amber or green with “No risks to other resources identified.” If it's red, tighten resourceScope — don't ask users to accept more risk.

5. Prove it leaves no trace

   npm run certify -- --extension . --yes

   Certification tears your poppy down with the host's safety-net cleanup off and verifies the cloud account is exactly as it was. This is the promise users install on — a poppy that can be completely undone.

6. Pack it

   node scripts/pack-extension.mjs --src path/to/your-poppy

   You get a byte-reproducible zip, its sha256, and a ready-to-paste catalogue entry. Publish both in a release on your public repository, then submit from the dashboard.

What your agent must respect (and review will check)

• Only its own resources. Mutating grants are scoped to what the poppy created — tags or concrete names, never *.
• Declare runtimes, don't ship them. The manifest names the runtime ("runtime": "node22") and you ship a small JS bundle; the platform provides the runtime. Packing rejects a bundled Node or service binary.
• Cloud work survives navigation. Long operations run in the background and can be resumed; closing a tab never corrupts state.
• Destructive actions take a real two-step confirmation. Never one bare click.
• Every button responds. Pending state, error state, plain-language messages. The #1 rejected defect.
• Live prices, never hardcoded. If your poppy shows AWS costs, they come from the live price APIs.
• No in-poppy paywalls. If you sell, it goes through the platform checkout — see monetisation.