Getting started

From zero to a running poppy

A poppy is two folders and a manifest: a frontend the host renders in a tab, an optional backend process the host spawns, and extension.json — the contract that declares exactly what cloud access it needs. This page gets the example poppy running on your machine; the tutorial then builds your own.

What you need

AgentsPoppy installed — download it for macOS, Windows, or Linux.
An AWS account connected in the app (the free tier is fine; a spare sandbox account is even better for development).
Node.js and the platform repository for the developer scripts and the hello-poppy example.
An AI coding agent (Claude Code, Cursor, …) — optional but recommended; the docs are written for it.

The anatomy of a poppy

extension.json

The manifest

Identity (reverse-DNS id, a name ending in Poppy, icon, semver version), the permission set (every grant: service, actions, resource scope), declared capabilities, and entry points. The host re-reads it on every load — declared scope can never silently drift.

frontend/

The face

Plain HTML/JS (or a bundled app) rendered as a tab in the host. It talks to the host bridge — it never sees credentials.

backend/

The hands (optional)

A process the host spawns. It receives scoped, short-lived credentials from the broker — only for its own connection, only what the user approved. It declares its runtime ("runtime": "node22") and ships a small JS bundle — the platform provides Node, so a poppy is a few MB, never a bundled runtime.

Run hello-poppy in five minutes

The example is deliberately zero-build — no npm install, no toolchain; its source is its built output. From the platform repository root:

Install it as a dev extension

node scripts/install-dev-extension.mjs \
  --src      examples/hello-poppy \
  --frontend examples/hello-poppy/frontend \
  --backend  examples/hello-poppy/backend/server.mjs

Launch the app
```
npm run -w @agentspoppy/app tauri:dev
```
The broker discovers installed extensions at startup — a Hello Poppy tab appears.
Approve the connection

Open the tab and approve the requested access. Hello-poppy asks for a single read-only action, so it rates green and the permission view says “No risks to other resources identified.” That screen is what your users will judge you by — remember it.

The dev loop

Three commands carry you from editing to shippable:

Command	What it proves
`npm run validate-manifest -- path/to/extension.json`	The manifest is well-formed — all problems reported at once, not one by one.
`npm run certify -- --extension . --yes`	Leaves no trace. Runs your teardown with the host's safety-net cleanup switched off and verifies nothing survives in the cloud account. Writes `leaves-no-trace.cert.json`. Must pass before you submit.
`node scripts/pack-extension.mjs --src …`	Produces the release zip — byte-reproducible, so anyone can re-derive it from your open repo and check it against your published sha256. Prints the sha256 and a ready-to-paste catalogue entry, and refuses to pack a bundled runtime (a Node SEA or embedded service binary) — declare it instead.

// the two rules people trip on

Only touch what you create. A poppy may only ever mutate AWS resources it itself created — scoped by tags or concrete names, never * on a mutate-existing action. Broad grants rate red and won't pass review.

Every button must respond. A dead click is the single most common defect in shipped poppies. Show a pending state, wrap handlers in try/catch/finally, and click-test every control before you submit.

Build your own: the tutorial hands one prompt to your AI agent and takes you from idea to a packaged poppy. Or read how the broker actually works first.

← Overview Tutorial →