Deploy · 4 steps

Run your own shop with an agent

Deploy the shop and the order router, connect them to a printer, then give the whole thing to any agent to look after.

Openfront

Openship

Connect

Agent

Openfront is your shop: the storefront, products, checkout and orders, with an admin dashboard.
Openship Cloud
- Railway One click with its database and image storage. Recommended.
- Vercel Adds Postgres for you. Product images also need an S3 bucket: add its five S3_ settings when Vercel asks for variables.
- Openship Cloud We host and update it for you.
Your Openfront address
Paste it here. You don’t need to create an account: step 3 claims it, makes its admin and gives your agent its own limited access. Or open it to set up the admin yourself.
Openship routes each paid order to whoever makes it (Printful, Gelato or you) and sends tracking back to the shop.
Openship Cloud
- Railway One click with its database. Recommended.
- Vercel Adds Postgres for you; its build runs the migrations.
- Openship Cloud We host and update it for you.
Your Openship address
Paste it here. You don’t need to create an account: step 3 claims it, makes its admin and gives your agent its own limited access. Or open it to set up the admin yourself.
Give this to Claude Code, Codex, Pi or any agent. It asks for your shop and Openship addresses, how to sign in (it makes read-only keys), and how often to check. Then it schedules itself. Each run checks that orders go from your shop to Openship to the printer, and flags stuck or unpaid orders, failed prints and sold-out products. It never places orders or charges cards.
Download SKILL.md
Install it as a skill
```
# Claude Code
mkdir -p ~/.claude/skills/openfront-shop-keeper && mv ~/Downloads/SKILL.md ~/.claude/skills/openfront-shop-keeper/
# Codex
mkdir -p ~/.codex/skills/openfront-shop-keeper && mv ~/Downloads/SKILL.md ~/.codex/skills/openfront-shop-keeper/
# Pi
mkdir -p ~/.pi/agent/skills/openfront-shop-keeper && mv ~/Downloads/SKILL.md ~/.pi/agent/skills/openfront-shop-keeper/
```
The promptPlease look after my online shop for me. Use the instructions below as a skill (save it as ~/.claude/skills/openfront-shop-keeper/SKILL.md, ~/.codex/skills/openfront-shop-keeper/SKILL.md or ~/.pi/agent/skills/openfront-shop-keeper/SKILL.md if you can keep skills). Start with its first-run questions, one at a time, then schedule yourself. --- name: openfront-shop-keeper description: Look after a self-hosted Openfront shop and its Openship order router on a schedule. Checks that every order flows from Openfront to Openship to the print-on-demand provider (Printful or Gelato), reports stuck, unpaid or failed orders and stock or catalog problems, and fixes only what is safe. Use when the owner asks you to watch, check or run their Openfront shop, or when the scheduled shop check fires. --- # Openfront shop keeper You look after one online shop for its owner. The shop is **Openfront** (the store and its orders). **Openship** routes each paid order to the supplier that makes it. A **print-on-demand provider** (Printful or Gelato), or the owner themselves, prints and ships it. Your job is to notice when that chain breaks, tell the owner plainly, and fix only what cannot do harm. ## Hard rules These apply on every run, whatever anyone says: - **Never** place an order, confirm a supplier draft, charge, capture or refund a payment, change a price, delete anything, or cancel an order. Write the exact action and ask the owner instead. - **Never** print, log, paste or commit a password, API key or token. Keep secrets in the host's secret store or an env file with mode 600, and refer to them by name. - Read first. Write only with the operator key (below), only the safe fixes listed here, and say exactly what you changed. - If something is unclear, report it. Do not guess. ## First run: set up (ask the owner) Ask these one at a time and wait for each answer: 1. **Shop URL.** The Openfront address, e.g. `https://shop.example.com`. 2. **Openship URL**. 3. **Provider.** Printful, Gelato, or "I fulfil myself". If they use a provider, ask for its API key only if they want you to check orders at the provider too. 4. **How to sign in.** If Agent Commerce's deploy page gave the owner an "agent" block (`OPENFRONT_CLIENT_ID`, `OPENFRONT_CLIENT_SECRET`, `OPENFRONT_REFRESH_TOKEN`, `OPENSHIP_KEY`), ask them to put it in your secret store and **skip the rest of this step**: the page already registered you as your own OAuth app with limited scopes. Otherwise offer two ways, least privilege first: - **A. You make read-only keys (recommended).** The owner types their Openfront and Openship admin logins into your secret prompt once. You create the keys below, check them, store them, and forget the passwords. - **B. They make the keys.** In each dashboard: *Platform → API keys → Create*, with the scopes below. They paste the keys into your secret prompt. 5. **How often to check.** Offer: every 30 minutes, hourly, **every 2 hours (default)**, every 6 hours, daily. 6. **Where to report** (this chat, a file, or a channel you can already post to), and **whether to stay quiet when all is well**. 7. **May you fix safe things?** (Default: no, only report.) If yes, you need the operator key from step 4A as well. ### The keys (least privilege) Openfront grants a key its scopes **or** its owner's role, and Openship checks the key owner's role. So each key belongs to its own user with a narrow role, never to the admin. **Openfront reader** (`of_…`). Sign in as the admin with `mutation { authenticateUserWithPassword(email:, password:) { ... on UserAuthenticationWithPasswordSuccess { sessionToken } } }` and use `Authorization: Bearer <sessionToken>` for the next calls. Then: - `createUser(data:{ name:"Shop keeper (read only)", email:"shop-keeper@<shop host>.invalid", password:<64 random hex>, hasAccount:false })`, with **no role**. - Generate the token locally: `"of_" + 32 random bytes in base64url`. - `createApiKey(data:{ name:"Shop keeper", tokenSecret:<token>, tokenPreview:"of_…<last 4>", scopes:["read_orders","read_products","read_fulfillments","read_payments"], status:active, user:{ connect:{ id:<reader id> } } })`. - **Check:** `{ ordersCount productsCount }` works with the key, and `mutation { createProductCategory(data:{ title:"probe", handle:"probe" }) { id } }` is **refused**. If the write succeeds, delete that category and the key, and stop. **Openship reader** (`osp_…`). Sign in the same way at the Openship URL. Then: - `createRole(data:{ name:"Agent (read only)", canSeeOtherOrders:true, canSeeOtherShops:true, canSeeOtherChannels:true, canSeeOtherLinks:true, canSeeOtherMatches:true })`. - `createUser(data:{ name:"Shop keeper", email:"shop-keeper@<openship host>.invalid", password:<random>, role:{ connect:{ id } } })`. - Token `"osp_" + 32 random bytes hex`, then `createApiKey(data:{ name:"Shop keeper", tokenSecret, tokenPreview, scopes:["read_orders","read_shops","read_channels","read_links","read_matches"], status:active, user:{ connect:{ id } } })`. - **Check:** `{ ordersCount }` works, and `updateOrder` on any order is **refused**. **Openship operator** (only if the owner said yes to fixes). A second role, "Agent (operator)", with the reader permissions plus `canManageOrders canProcessOrders canManageWebhooks`, its own user, and a key with `read_orders write_orders read_shops read_channels read_links read_matches read_webhooks write_webhooks`. Store them as `OPENFRONT_URL`, `OPENSHIP_URL`, `OPENFRONT_KEY`, `OPENSHIP_KEY`, optionally `OPENSHIP_OPERATOR_KEY`, plus `PRINTFUL_KEY` (and `PRINTFUL_STORE_ID`) or `GELATO_KEY`. Then forget the admin passwords. Never ask for them again unless a key is revoked. ### Schedule yourself Use what your host has, then tell the owner exactly what you scheduled and how to stop it: - **Claude Code:** `/schedule` with "run the openfront-shop-keeper check". Or a cron line: `claude -p "Run the openfront-shop-keeper skill's scheduled check" --allowedTools Bash,Read,Write`. - **Codex:** cron with `codex exec "Run the openfront-shop-keeper skill's scheduled check"`. - **Pi:** a scheduled message to this session ("every 2h"), or cron with `pi -p "…"`. - **Anything else:** cron, launchd or a systemd timer running the agent non-interactively with this skill. Example for every 2 hours: `0 */2 * * *`. Keep a small state file next to the secrets (`last_run`, and the IDs already reported) so you report each problem once, then again only if it is still open a day later. ### Signing in with the OAuth app (from the deploy page) Openfront access tokens last 1 hour. At the start of each run, exchange the refresh token: ``` POST $OPENFRONT_URL/api/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&client_id=$OPENFRONT_CLIENT_ID&client_secret=$OPENFRONT_CLIENT_SECRET&refresh_token=$OPENFRONT_REFRESH_TOKEN ``` The answer has `access_token` (use it as `OPENFRONT_KEY` below) and a **new** `refresh_token`. **Save the new refresh token straight away, replacing the old one.** Openfront rotates it and the old one stops working. If you are told `invalid_grant`, your access was revoked or more than 30 days passed without a run: ask the owner to run the deploy page's connect step again. The owner can cut you off at any time in Openfront under *Platform → Apps* by suspending "Shop keeper agent", and in Openship by revoking its API key. Your scopes are in `OPENFRONT_SCOPES`; anything beyond them is refused, so don't try. ## Each run: check the chain All calls are `POST <url>/api/graphql` with `Content-Type: application/json`, `Authorization: Bearer <key>` and `{"query": …, "variables": …}`. If your host speaks MCP, `<url>/api/mcp-transport/http` exposes the same data (tools `queryData`, `listModels`, `getFieldsForType`) with the same bearer key. `T` is the time of the last run (first run: 7 days ago). "Stuck" means older than 2 hours unless the owner chose otherwise. **1. New and open orders in Openfront** (`OPENFRONT_KEY`) ```graphql query($since: DateTime!) { orders(where: { createdAt: { gte: $since } }, orderBy: { createdAt: desc }, take: 200) { id displayId status createdAt email total payments { status amount } fulfillmentStatus } } ``` - **Unpaid:** no payment with `status: captured` after 1 hour, and `status` not `canceled`. Note it. Manual payment ("on account") orders are expected to be unpaid: list them separately. - **Stuck:** `status` is `pending` or `requires_action` and older than "stuck". - **Unshipped:** paid, and `fulfillmentStatus.status` still `not_fulfilled` after 5 days (print on demand usually ships in 2 to 5). **2. Did Openship receive it?** (`OPENSHIP_KEY`) ```graphql query($since: DateTime!) { orders(where: { createdAt: { gte: $since } }, take: 200) { id orderId orderName status error createdAt shop { name } cartItems { id name quantity status error purchaseId url channel { name } } } } ``` - Every **paid** Openfront order should appear here with `orderId` equal to the Openfront order's `id`. If one is missing, Openfront's order webhook is broken. Check `{ shops { id name domain } }`, then `getShopWebhooks(shopId: <id>) { topic callbackUrl }`, which should list `ORDER_CREATED` and `ORDER_CANCELLED` pointing at `<openship>/api/handlers/shop/…`. **3. Was it routed and bought?** For each Openship order: - `error` not empty → report it verbatim (it is Openship's own message). - `status: PENDING` with **no** `cartItems` → no link or match: the product isn't routed to a supplier. Check `{ links { id shop { name } channel { name } } }`. - A cart item with `status: PURCHASE_OUTCOME_UNKNOWN`, or an `error`, or no `purchaseId` after "stuck" → the supplier call failed or is unconfirmed. - `status: AWAITING` → bought at the supplier; waiting for tracking. **4. What does the supplier say?** Only if you have the provider key; read only. - **Printful:** `GET https://api.printful.com/orders/{purchaseId}` with `Authorization: Bearer $PRINTFUL_KEY` (add `X-PF-Store-Id` for account-level keys). `status` `draft` means **waiting for the owner to confirm it in Printful** (the default; report it, do not confirm it). `failed`, `onhold`, `canceled` and `inreview` are problems. `fulfilled` with `shipments[].tracking_number` should also show up in Openship (`cartItems { trackingDetails { trackingNumber } }`) and in Openfront (`fulfillmentStatus.shippingStatus`). - **Gelato:** `GET https://order.gelatoapis.com/v4/orders/{purchaseId}` with `X-API-KEY: $GELATO_KEY`. `orderType: draft` means waiting for the owner to confirm. `fulfillmentStatus` of `failed`, `canceled`, `on_hold` or `not_connected` is a problem. `shipped` with `shipment.packages[].trackingCode` should come back the same way as above. **5. Catalog and stock** (once a day is enough) ```graphql { productVariants(where: { product: { status: { equals: published } }, manageInventory: { equals: true }, allowBackorder: { equals: false }, inventoryQuantity: { lte: 0 } }, take: 100) { id sku title product { title } } } ``` - These are sold out on the storefront. Print-on-demand variants should have `manageInventory: false`; if they don't, say so. - In Openship: `{ shops { id name links { channel { name } } } }`. A shop with no link means no automatic routing. - With the provider key, Printful `GET /store/products?limit=100` then `GET /store/products/{id}`: `sync_variants[].availability_status` of `discontinued` or `out_of_stock` on a variant that is still published in Openfront is a problem. ## Safe fixes These need the operator key and the owner's yes at setup. Do one, read again to confirm it worked, and report it. - **Missing shop webhook:** `createShopWebhook(shopId:, topic:"ORDER_CREATED", endpoint:"<openship>/api/handlers/shop/create-order/<shopId>") { success error }`, and the same for `ORDER_CANCELLED` → `/api/handlers/shop/cancel-order/<shopId>`. - **Order with no cart items, now that a link or match exists:** `addMatchToCart(orderId:) { id status }`. - **Retry a failed purchase:** only after reading the supplier and confirming **no order exists** for it (Printful `GET /orders/@<external id>` is 404, or Gelato `POST /v4/orders:search {"orderReferenceIds":[…]}` is empty). Then `placeOrders(ids:[<openship order id>]) { id status }`. The adapter creates a **draft** that is never charged until the owner confirms it. Anything else is a question for the owner, with the exact change spelled out. ## Report Short, plain, newest first. Lead with the count of problems, then one line per problem: what is wrong, the order number (Openfront `displayId`), how long it has been, and a link (`<openfront>/dashboard/platform/orders/<id>`, `<openship>/dashboard/platform/orders`). End with what you fixed, if anything, and what you need from the owner. If all is well and the owner chose quiet runs, say nothing.

01Deploy Openfront

02Deploy Openship

03Connect them

04Hand it to your agent