Build your own shop

Run the local reference shop, connect Auth0, and adapt the deployment to your accounts.

Start from a local checkout of this project. It is a reference shop for learning how to combine a storefront, Auth0 and Personal Agent Protocol. The committed infrastructure describes one personal deployment; the project has not yet been installed from scratch on another account.

Run the commands below from the checkout root. The checkout’s SETUP.md is the detailed provisioning guide; this page gives you a first working demo and the decisions needed before connecting real providers.

Run the local demo

Use Node 24.8 or newer and the pnpm version pinned in the root package.json.

pnpm install --frozen-lockfile
API_LOCAL_ISSUER=1 pnpm dev

Open http://localhost:3300. The storefront and Shop API run in one local Worker process, with the API also available on port 3600. The launcher creates and migrates local D1 state in apps/webshop/.wrangler-local/. The fake issuer supplies local machine credentials; it does not create real Auth0 users or tenant features.

Try now	Configure providers first
Product browsing, guest cart, guest checkout and order lookup	Customer sign-in and My Account with Auth0
Simulated payments	Card payments and 3-D Secure with Stripe test keys
Fern’s read-only fallback commands	Model-backed Fern replies with an Anthropic key
Universal Login screen previews	Real Poppy and MCP sign-in with the Auth0 proxy and Auth0

Stop the dev process before deleting apps/webshop/.wrangler-local/ to reset local state. Do not run the standalone API launcher alongside this combined launcher against the same state: local D1 cannot be shared by two Worker processes.

To work on these docs, run pnpm dev:docs and open http://localhost:3700.

Connect Auth0 and agents

Choose a tenant and a public login domain. The issuer and keys must remain distinct: tokens carry the login issuer, while Auth0 signature verification uses the canonical tenant’s keys.
Configure the resource servers and clients and grants. Copy apps/webshop/.env.example to apps/webshop/.env.local if you do not already have a local file. Fill in your website client, issuer, JWKS, origin and secret values using the storefront section of SETUP.md.
Enable the tenant capabilities you intend to demonstrate. My Account requires activation and correct audience identifiers. Invited agents also require platform registrations and Session Delegation. These prerequisites are not completed by a Terraform apply.
Configure and start the Auth0 proxy using apps/proxy-auth0/config/prod.example.json as the configuration reference and apps/proxy-auth0/README.md for local launch settings. Its discovery must advertise your API and MCP origins.
Exercise Poppy sign-in or connect an MCP client. Standard MCP OAuth and Poppy are separate flows; an ordinary MCP login does not create a Poppy Session.

For payments, use Stripe test keys and route webhooks to the Shop API’s /webhooks/stripe. Saved cards must be added by a person. Agents can purchase with a saved card under checkout, but cannot complete a bank challenge.

Configure your own deployment

Real deployment needs Terraform 1.11 or newer, an Auth0 tenant with the features you enable, and a Cloudflare account with Workers, D1, Durable Objects, KV, R2 and your DNS zones. Email delivery also needs the sending-domain setup. Alchemy and Wrangler come from the workspace; configure the deployer’s Alchemy Cloudflare profile before planning.

The domains tarnandtimber.com and sandrino.run in diagrams and committed settings belong to the existing personal instance. They are examples, not defaults for your installation. Adapt at least these locations:

Location	Replace or configure
`infra/terraform/*/prod.tfvars.json` and `prod.s3.tfbackend`	Your tenants, origins, account IDs and state backends
`apps/proxy-auth0/config/prod.json`	Your issuer, tenant and advertised API/MCP resources; start from `prod.example.json`
`infra/terraform/auth0/universal-login-release.json`	Your login asset origin and a release built for it
`infra/alchemy/email.run.ts`, `shop.ts`, `infra/terraform/email/main.tf`, `packages/email/src/cloudflare.ts`	Your sender and mail domain
`infra/alchemy/docs.ts`, `mailbox.ts`, `shop.run.ts`, `company.run.ts`	Hostname defaults and API-origin fallbacks
`infra/alchemy/terraform-state.run.ts`	A state bucket name appropriate for your account

Follow the secrets, domains and provider steps in the checkout’s SETUP.md before running:

pnpm infra:plan
pnpm infra:deploy

Review the plan against your intended resources. When continuing an existing deployment, recover its state and keep its logical resource IDs; empty replacement state can propose duplicate resources. Keep populated environment files, plans and state out of Git. The deployment page explains stack order and ownership.

Verify before relying on it

pnpm check validates boundaries, formatting, lint and types. pnpm test runs local tests, including infrastructure checks that require Terraform; pnpm ready adds production builds. The Universal Login build requires your HTTPS shop and asset origins. Browser e2e suites are separate commands documented in each app’s README.

The documentation check is pnpm --filter @retail-demo/docs test; it requires the Chromium revision installed by pnpm --filter @retail-demo/docs exec playwright-core install chromium.

Local tests use synthetic providers. Work through docs/manual-acceptance.md in your checkout for actual tenant sign-in, token exchange, revocation, bank challenges and email delivery. Inspect the account recovery and scheduled jobs guides before testing provider failures.