---
title: Build your own shop
description: Run the local reference shop, connect Auth0, and adapt the deployment to your accounts.
sidebar:
  order: 2
  label: Getting started
---

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](/poppy). 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`.

```sh
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

1. Choose a tenant and a public login domain. The [issuer and keys](/architecture/auth0#issuer-and-keys) must remain
   distinct: tokens carry the login issuer, while Auth0 signature verification uses the canonical tenant's keys.
2. Configure the [resource servers](/architecture/auth0/resource-servers) and [clients and grants](/architecture/auth0/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`.
3. Enable the tenant capabilities you intend to demonstrate. [My Account](/architecture/auth0/my-account#configure-the-built-in-api)
   requires activation and correct audience identifiers. [Invited agents](/architecture/auth0/invited-agents) also
   require platform registrations and Session Delegation. These prerequisites are not completed by a Terraform apply.
4. 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.
5. Exercise [Poppy sign-in](/poppy#first-sign-in) or [connect an MCP client](/mcp). 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:

```sh
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](/architecture/deployment) 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](/runbooks/account-recovery) and [scheduled jobs](/runbooks/scheduled-jobs) guides before testing
provider failures.