---
name: fuast-build-and-host-small-apps
description: Build a small web app with a database and sign-in and put it online at a shareable link in minutes, with no account or hosting setup. Use for an internal tool, tracker, form, dashboard, approval flow or sign-up page for a team, for "make a little app and put it online", or when fuast is mentioned.
---

# fuast

fuast runs small full-stack TypeScript apps, called capsules, and shares them like a doc. You write two files (a typed server and a Preact client), run one command, and the app is online at `https://<name>.fuast.com` with a realtime database, sign-in, file storage, schedules and email. There is nothing to provision.

**Nobody has to sign up or log in first.** `fuast deploy` without a login puts the app online as a preview and prints a claim link. Give that link to the person. They open it, sign in, and the app is theirs.

## When fuast fits

Use it for a small app a group of people shares: a tracker, a request form, an approval queue, an on-call rota, a lunch order, an RSVP page, a team dashboard fed by an API.

Do not use it for: a marketing site, a mobile app, anything that needs npm packages or a custom runtime, or data past 100000 rows.

## Pick your path

- **You have a terminal:** use the CLI. The rest of this file is the CLI path.
- **You have no terminal** (a chat app): use the MCP server at `https://fuast.com/mcp`. Call its `fuast_guide` tool first. If it is not connected, the person adds it from https://fuast.com/agents.

## Build and ship

You need [Bun](https://bun.sh) 1.2 or later. Run the CLI as `bunx @revnu/fuast` (written `fuast` below).

```sh
bunx @revnu/fuast new my-app      # or: init, inside an empty folder
cd my-app
```

Then:

1. **Read `AGENTS.md` in the new folder before you edit.** It holds the rules for this version of fuast and overrides this file.
2. Write `server/index.ts` (schema, queries, mutations) and `client/index.tsx` (the UI).
3. Run `fuast dev` in a terminal that stays open, and check your work from another:

   ```sh
   fuast check                 # build, type check, contract check
   fuast run <handler> '<json>'  # call a query or mutation; prints JSON
   fuast db dump --port 3000   # the rows that are really there
   fuast logs --port 3000      # handler errors
   ```

4. Deploy as soon as `fuast check` passes:

   ```sh
   fuast deploy
   ```

5. Verify the deployed app by its slug (`fuast run <handler> <slug>`, `fuast logs <slug>`), then give the person **both links** and say which is which:
   - **Claim link** (`https://fuast.com/claim/…`): makes the app theirs. It works once. Give it only to them.
   - **Preview link**: shows the app. Safe to pass on.

   Also tell them the preview is deleted after 72 hours unless it is claimed.

Templates to start from: `--template todo|guestbook|signature|approvals|live-demo`.

## Rules that agents get wrong

- No npm packages, no Node built-ins, no CSS files, no bundler. Server files import only `fuast/server`; client files import only `fuast/client`, `preact` and `preact/hooks`.
- Every database call is async: `await` it. Read through an index: `ctx.db.<table>.withIndex(name, q => q.eq(...)).order("desc").take(50)`. Use the built-in `by_creation` index for a plain list. There is no `where`, `orderBy`, `limit` or `all`.
- Queries and actions cannot write. Write in mutations.
- Never take a user id, email or name as an argument. Get the caller from `ctx.auth.requireIdentity()` (guest or account) or `ctx.auth.requireSignedIn()` (account only), and store it in a `userId()` field.
- In a preview everyone is a guest, so `requireSignedIn()` fails there. Use `requireIdentity()` for anything the person should be able to try before claiming.
- Email, team tables, the member list, schedules and jobs do not work until the app is claimed and the owner trusts it (`fuast trust <slug>`). Say so if the app needs them.
- While a query is `undefined`, render nothing for that section: no "Loading…", no spinner. An empty list is its own state.
- Style with full Tailwind class names in JSX. The design is yours and the person's: fuast has no house style. Build the look the request calls for.
- Limits per handler: 1000 rows returned, 5000 read, 10 seconds. Per app: 100000 rows, 64 MiB.
- Type errors block the deploy. Fix them, do not skip the check.

## After the first deploy

- `fuast deploy` again from the same folder updates the same preview, with the same links.
- `fuast claim` prints the links again. `fuast status` says what this folder is deployed as.
- Once the person has claimed the app, the next deploy asks for `fuast login`. A person must approve it in a browser: tell them, and wait.
- A claimed app is private. Share it when the person asks: `fuast share --visibility workspace | public | private --emails a@co.com`.
- Never print or send the edit token in `~/.fuast/previews.json`.

## Read more, only when you need it

Fetch the one page you need. Every page is plain Markdown.

- Full agent guide: https://fuast.com/agents.md
- Index of every page: https://fuast.com/llms.txt
- Server and client API: https://fuast.com/docs/capsule-api.md
- Database and indexes: https://fuast.com/docs/database.md
- Sign-in, guests, endpoint credentials: https://fuast.com/docs/auth.md
- Sharing, workspaces, team tables: https://fuast.com/docs/teams.md
- Storage, schedules, email: https://fuast.com/docs/storage.md, https://fuast.com/docs/schedules.md, https://fuast.com/docs/email.md
- Limits and their errors: https://fuast.com/docs/limits.md
- Every CLI command: https://fuast.com/docs/reference.md, or `fuast <command> --help`
- MCP server: https://fuast.com/docs/mcp.md