Your coding agent can build a real Fabric app here, free, in minutes.

---
name: rayfin-claimable-apps
description: Build a temporary Rayfin app without a Fabric workspace using rfd, then hand the human private preview and claim links.
---

# Claimable Rayfin apps

This is the complete https://rayfin.dev guide for coding agents.
Build locally, publish at `https://<slug>.rayfin.app` for 24 hours, then let the human claim into Microsoft Fabric.
No Fabric sign-in or remote slot to start.

## Fast path: simple CRUD or single-screen apps

<!-- BEGIN EXPRESS LANE -->
For app-owned records without extra capabilities, use this sequence instead of the reading and first-deploy gates below. Node 24 and npm are required.

1. Run `rfd new <name> --pack data-modeling --deploy`. Do not spend a turn checking the environment. If the shell reports `rfd` not found, install: Windows PowerShell `irm https://rayfin.dev/install.ps1 | iex`; macOS/Linux `curl -fsSL https://rayfin.dev/install.sh | sh`. Use the printed PATH line if needed and run the same command again. This prepares store dependencies (120-second bound), installs the CRUD screen, builds and deploys. Check `packs[].state = applied`, `packs[].starter = crud`, and `deploy.served`. On failure, follow `next`; the scaffold and dev session are preserved. Do not re-scaffold or reapply the pack.
2. Report JSON `handover.appUrl`, `previewUrl`, `claimUrl`, `expiresAt` with timezone, and `graceEndsAt` when present. Paste `handover.humanMessage`. Keep preview/claim links private. Use the deployed starter, a working records app (title, notes, done) over `Item`, as a first deliverable for list, todo, notes and tracker requests. Report your checks; opening a browser is not CRUD verification.
3. Only when the request needs different fields, names or screens: edit the existing `packages/data/src/Item.ts` and `packages/frontend/src/App.tsx`, never create them. Use the absolute paths from `dir`/`next`. Then run `npm --prefix <dir> run build` and `rfd deploy --dir <dir> --open`. The entity and data/shared indexes are already registered; keep them aligned. Preserve `AuthProvider`, `AuthGate`, `assetAccess: protected` and the server-side owner policy. Use `selectRecords` for reads, `client.data.Item.create(input)`, `.update({ id }, patch)`, and `.delete({ id })` for writes; stamp `owner_id` from authenticated `session.user.id` on create. Reuse `components/useCrud.ts` and `states.tsx`.

Typecheck is not needed for the first deploy. When iterating, `npm run typecheck` is store-backed when `node_modules/.rfd/store.json` advertises `typecheck`; it takes a few seconds on that lane. Older or incomplete stores retain on-demand tooling restoration.

No capability-router reading, docs search, extra skill or pack reads, sleeps or polls, or browser harness. Do not run another installer. Build emits the schema; do not compile it separately. `--deploy` requires the store lane. `--pack` is repeatable and ordered. Other shipped packs are refused by `new`; use the full workflow below for them.
<!-- END EXPRESS LANE -->

## 1. See something

The `rfd` binary has no prerequisites. Editing or building an app requires Node 24 and npm.
`rfd` provisions Bun for Vite, with Node fallback; functions preview keeps Node Vite.
`RFD_RUNTIME=node` opts out.
Install `rfd` if missing:

- macOS / Linux: `curl -fsSL https://rayfin.dev/install.sh | sh`
- Windows PowerShell: `irm https://rayfin.dev/install.ps1 | iex`

If `rfd` is not found in the same shell after installation, run the PATH line the installer printed or use its full path.

Run `rfd new <name>`; it self-updates before scaffolding.
It opens the app in the human's browser and reports `browser.opened` while the supervisor prepares dependencies.
On the runtime-store lane, `rfd new` returns when dependencies are ready; never sleep or poll.
After the 120-second bound it returns the current state with `depsWaitTimedOut: true`, not false readiness; with `--pack`, incomplete preparation fails the command.
The npm fallback remains background and returns immediately without `--pack`; report incomplete state rather than inventing a delay.
As soon as `rfd new` returns, before anything else, tell the human in one sentence what opened (or failed to open) in their browser and what comes next.
Then enter the printed `dir`.
If `browser.opened` is false, run `rfd open`; resume a stopped server with `rfd dev --open`.
Never ask the human to open a URL that rfd can open.
Use `--no-open` only without a desktop (CI, container, SSH), not because you are an agent.
Read **Claimable mode** in the generated `AGENTS.md` first: it owns the in-project workflow.
For richer apps, pack skills and installed docs own API contracts.
Do not read every skill up front or follow Fabric-only commands before claim.

Edit the existing first screen in `packages/frontend/src/App.tsx`; do not create it again or start another install.
Use the absolute project `dir` and `next` recipe. `deps.state = ready` permits the runtime build and filesystem-only data pack without npm restoration.
`install.state = ready` and `install.runtimeReady = true` then describe the runtime lane, with full tooling deferred until a command needs it.
If `deps.state` is `unsupported` or `failed`, the existing npm fallback owns installation; inspect `deps.error` and report incomplete `install.state`, without a sleep or polling loop.
Edits appear once `vite.state` is `ready`. Apply packs serially and do not race tooling restoration, typecheck, or builds.
`rfd dev` runs the real backend with hot reload and schema watch.

## 2. Iterate visibly

Keep `AuthProvider`, `AuthGate`, and data permissions intact; show honest empty/loading states.
Build with `npm run build`, then `rfd deploy --open`.
`rfd deploy` does not rebuild: run `npm run build` first or use `rfd deploy --build`.
Read `diagnostics` (with fixes) and `nextSteps` in deploy/status results.
Deploy reports `phases` and waits up to 20 seconds for `served: true` on its exact `generation` (`--no-wait` skips; `"unknown"` is unverified).
For `served: false`, reload the preview once, then report; do not redeploy blindly.
After each deploy, send the human one sentence with its private `previewUrl`, what changed, and what comes next.

Add features in chunks; apply needed packs serially before editing seeds.
For app-owned records start with `npm run pack:add -- data-modeling` and follow its skill.
An app whose records live only in React component state is not finished.
Check and publish each meaningful chunk.
For continuous publishing, run `npm run build:watch` and `rfd deploy --watch` separately; the deploy watcher watches outputs, not source.

## 3. Hand over the links

First deploy needs only `npm run build`, then `rfd deploy --open`.
`npm run typecheck` uses the store when its `typecheck` capability and materialized receipt/files match. Older or incomplete stores retain on-demand restoration. Lint keeps its existing tooling path.
For later hardening, stop build watchers and run typecheck and build serially.
`rfd open --deployed` reopens the hosted app.
Check the deployed `previewUrl` and `rfd logs --source browser`.
Look at the preview the CLI opens and report what you actually saw.
For app-owned records, create a record, reload the preview, confirm it is still there.
The scaffold ships no test suite or validation commands; do not install a browser harness for this workflow.
Do not treat an HTTP success or empty logs as evidence of the rendered result.

The final message must contain, verbatim, the app URL, private preview link, private claim link, and expiry with its timezone.
Preview and claim links are private to the human: give them directly to the human, never post them elsewhere (unrequested files, commit messages, or public places).
Say what you verified in a browser and what you did not.
Paste `handover.humanMessage`, the ready-to-paste text from `rfd deploy` or `rfd status`, at the end of your final message.
Never invent missing values.
The human claims when ready; functions apps need source review and `rfd claim --local` on their computer.
After claim, follow the generated "Claimed into Fabric" handoff from `rfd claim --wait` or `rfd status`.

## Rules

- `rfd` self-updates from signed releases; `rfd update` updates now, `rfd update --check` only checks.
- Keep tokens, passwords, and signing keys private; keep `.rayfin/dev.json` out of source and logs.
- Keep secrets, personal data, and irreplaceable data out of the sandbox. Test users, rows, and uploaded files do not migrate on claim.
- Storage: sandbox file storage.
- Functions: labeled, untrusted browser-preview functions, not hosted code or a place for secrets.
- Connectors: explicit recordings with no live Fabric data; synthetic results require consent and a visible label. Follow the pack's claimable override.
- Current claim grace is 3 days after expiry, or 7 days after a claim page view or started claim. Existing apps keep their saved window.
- New apps: 10 per hour and 100 per day per shared network address; 20 per day per device. Address and device quota 429s name `scope` and `window`; honor `Retry-After`.
- The daily transfer allowance is 200 MB per app, resetting at midnight UTC. Read https://rayfin.dev/limits and honor `Retry-After`.
- If Windows or enterprise policy blocks rfd, stop and report the detection or policy failure for review. Do not disable protection or try another transport to bypass it.

## Commands you may need

- Every command prints one JSON object on stdout and progress on stderr; `rfd logs` prints JSON lines. `rfd new --no-dev` only scaffolds; `rfd dev --no-install` stays offline.
- `rfd deps prefetch` warms the machine store; `rfd deps status` reports its digest and path. `--no-deps-store` on `new` or `dev`, or `RFD_DEPS_STORE=0`, uses the npm path. `rfd deps clean` removes old stores and can invalidate older projects' package links.
- `previewUrl` signs in a shared test user with that user's full permissions (100 uses, expires with the app). Rotate leaks with `rfd share --refresh-preview`; `rfd share --as <email> [--uses <1-100>] [--expires-in 30m]` shares another test user (single-use by default). Manage with `rfd share list` and `rfd share revoke <grantId>`.
- `rfd users add <email> --password <test-only-password>` creates test users; use `--local` for the `rfd dev` sandbox, omit it for the deployed app. `rfd users --allow-signup off|on` controls signup (applied on deploy).
- Whoever opens the claim link first can claim it. If leaked, run `rfd claim --rotate` and send the new link directly to the human. Tell the human to open it and allow the browser to open rfd; if blocked, use the page's `rfd claim --sign-in` in the project folder on their computer. Apps with functions get a local-only panel instead; do not start server conversion for them.
- `rfd apps list` shows everything this agent created; `rfd apps dashboard --open` gives the human one page with all of them.
- On an older control plane without share routes, `previewUrl` is null and the CLI says why; hand over the sign-in URL plus a created test account instead.

The CLI is the supported deployment path. https://rayfin.dev/openapi.json is a protocol reference, not a CLI-free deployment recipe: requests require Ed25519 signing in addition to app authorization.