# bld402 — Build & Deploy Web Apps

bld402 lets you build and deploy complete web apps for a user who described what they want.
Your job: handle ALL technical details silently. Only ask the user about what the app should DO (features, look, behavior). Never ask about databases, API keys, deployments, wallets, or infrastructure.

## Install (pick one)

### Option A: MCP plugin (recommended)
Add to your MCP config:
```json
{ "mcpServers": { "run402": { "command": "npx", "args": ["run402-mcp"] } } }
```

For Claude Code, run:
```
claude mcp add run402 -- npx -y run402-mcp
```

IMPORTANT: The MCP server provides 52 tools. Your environment may only load a subset initially. If a tool listed below is not in your palette, search for it (e.g. ToolSearch "deploy_function") to load its schema before calling it.

Available tools by category:

**Setup & billing:** init, set_tier, tier_status, status, check_balance, allowance_create, allowance_status, allowance_export, request_faucet, create_checkout, billing_history
**Projects:** provision_postgres_project, project_info, project_keys, project_use, list_projects, get_schema, get_usage, archive_project
**Database:** run_sql, apply_expose / setup_rls, validate_manifest, get_expose, rest_query
**Deployment:** apply/deploy with a ReleaseSpec, deploy_site_dir for site-only updates, get_deployment
**Subdomains:** assign with `subdomains.set` during apply; delete_subdomain, list_subdomains for maintenance
**Functions:** deploy_function, invoke_function, list_functions, delete_function, get_function_logs, set_secret, list_secrets, delete_secret
**Storage:** upload_file, download_file, list_files, delete_file
**Apps:** publish_app, get_app, browse_apps, fork_app, list_versions, update_version, delete_version
**Other:** generate_image, send_message, set_agent_contact, get_quote

### Option B: CLI
```
npx run402-mcp          # start MCP server
```

### Option C: Website workflow (no install needed)
Start at https://bld402.com/build/step/1 and follow the guided steps.

## What you can build

Any client-side web app with: database tables, user auth (email/password + Google OAuth), file uploads (content-addressed CDN with SRI), static hosting, Node 22 serverless functions, AI image generation. Default tier is Prototype — FREE on testnet (Base Sepolia) via the faucet.

Examples: todo lists, recipe books, expense splitters, landing pages, trivia games, workout trackers, gift registries, flash card apps, voting polls, micro-blogs.

13 ready-made templates available — browse at https://bld402.com/templates/

## How to build an app

1. Figure out what the user wants (ask product questions only — "What should the app do? Who will use it?")
2. Install run402-mcp if not already installed (Option A or B above)
3. Use `set_tier` with tier=prototype. If it says "already subscribed" or returns a payment error, that's OK — check with `tier_status` to confirm your tier is active.
4. Use `provision_postgres_project` with a name for your app. This returns a project_id and saves credentials to the local key store. Then call `project_info` with the project_id to get the anon_key, service_key, and REST API URL — you need these for the frontend.
5. Use `run_sql` (or include `database.migrations` in the deploy spec) to create tables and seed data.
6. **Declare which tables are reachable (required for public apps).** Tables are dark by default. Use `apply_expose` with a manifest, or include `database.expose` in the deploy spec. Policies: `user_owns_rows`, `public_read_authenticated_write`, `public_read_write_UNRESTRICTED`, `custom`. One policy per table. Without an exposed entry the anon key cannot read or write and your app's REST calls will return 404 / 401.
7. **Deploy functions (if needed).** For server-side logic (password hashing, secret matching, etc.), include `functions.replace` in the deploy spec or call `deploy_function`. Use `set_secret` for environment variable values (set values OUT-OF-BAND, then assert keys via `secrets.require[]` in the spec — secret values never appear in deploy payloads).
8. Build the HTML/CSS/JS frontend. Use the anon_key from step 4. REST API calls need `apikey: <anon_key>`. Call functions via `https://api.run402.com/functions/v1/<function_name>` (API-key protected) or via same-origin web routes (`routes.replace` in the deploy spec) like `/api/*` that hit the function transparently from the static site.
9. **Deploy everything in one call.** Use the Run402 MCP apply/deploy tool or `run402 deploy apply --manifest` with a unified `ReleaseSpec` containing `site`, `subdomains.set`, and any DB/functions/secrets you want. Subdomain assignment happens inline. SDK 2.46+ form: `(await r.project(id)).apply(spec)`. The HTTP wire is `POST /apply/v1/plans` + `/commit`.
10. Show the user their live URL — done!
11. If they want changes: edit files and redeploy. The deploy diff-and-skip pipeline only re-uploads bytes that changed and only rebuilds functions whose source/config changed.

For the full API reference, see: https://run402.com/llms.txt

## Critical rules

- NEVER ask the user about technical details (databases, API keys, deployments, hosting, wallets)
- NEVER show the user raw API responses, keys, or error traces
- NEVER use jargon in the app UI (see banned words below)
- Handle wallet creation, payments, and infrastructure silently
- If something fails, fix it yourself or explain in plain language what went wrong
- The user should only ever see: their app idea → a live URL they can share

## Banned words in app UI

Never show these to users in the app you build:
API, endpoint, schema, payload, query, webhook, middleware, database, server, cluster, deployment, container, embedding, vector, tokenize, inference, LLM, GPT.

Rewrite: "Querying the database..." → "Loading your data..."

## Capabilities

| Feature | Details |
|---------|---------|
| Database | Postgres (tables, columns, indexes, SQL) |
| REST API | Full CRUD with filtering, pagination (PostgREST) |
| Auth | Email/password + Google OAuth, JWT tokens |
| Row-level security | Expose manifest: user_owns_rows, public_read_authenticated_write, public_read_write_UNRESTRICTED, custom. Tables are dark by default. |
| File storage | Content-addressed CDN with SRI (`r.assets.put` → paste-and-go URL). Bulk bytes ride through the apply CAS pipeline. |
| Static hosting | Unified `(await r.project(id)).apply()` (or `deploy` MCP tool). Clean URLs via `site.public_paths`. |
| Web routes | Same-origin `/admin`, `/api/*` patterns to Node 22 Fetch functions on the static site's domain. |
| Functions | Node 22 Fetch handlers (`export default async (req) => Response`). |
| AI images | $0.03/image generation |
| Subdomains | myapp.run402.com (free, inline in deploy spec) |
| Testnet | Base Sepolia — Prototype tier completely free via faucet |

## Limitations

| Not possible | Alternative |
|---|---|
| Fully custom domains (myapp.com) | Use myapp.run402.com subdomain — assigned inline in the deploy spec |
| WebSocket / real-time | Polling (fetch every 3-10s) |
| Email / SMS / push notifications | Use the email service (`r.email.send`) for transactional; in-app notifications for the rest |
| OAuth providers other than Google | Google OAuth + email/password (both built in) |
| Payment processing (beyond x402/MPP) | Track balances in the database |
| Total project storage over tier cap | Prototype 250 MB / Hobby 1 GB / Team 10 GB. Deploys are no longer body-capped — bytes ride through CAS. |
| More than per-tier api_calls sustained | Prototype 500K / Hobby 5M / Team 50M API calls per lease; client-side caching for spikes |

## Source code

Open source (MIT): https://github.com/kychee-com/run402-mcp

## Powered by

run402.com — full-stack infrastructure for AI agents. For the full API reference, see https://run402.com/llms.txt