--- name: run402 description: Build, deploy and operate full-stack applications with the Run402 CLI. Postgres, auth, storage, functions and hosting with a free prototype tier and an explicit spending allowance. Use for web apps, database-backed sites, APIs and deploy. metadata: openclaw: emoji: "🐘" homepage: https://run402.com requires: bins: - npx install: - kind: node package: "run402" bins: [run402] primaryEnv: RUN402_API_BASE --- # Run402 β€” Postgres, storage & deploys for AI agents Run402 gives an agent a real Postgres database with REST API and user auth, content-addressed CDN storage, static site hosting, Node 22 serverless functions, email, image generation, and KMS-backed on-chain signing. One command provisions; payment happens automatically with x402 USDC on Base. Prototype tier is free on testnet β€” no real money or human signup for the routine cold-start path. Run402 is agent-first because agents are first-class participants, not because people disappear. Act through your own Run402 principal and authenticator; do not borrow a human login, shared cloud account, or another agent's credential. Identity records who acted. Memberships, roles, grants, grant keys, freshness, and spend policy determine what you may do. A founder agent may legitimately own its org-of-one; an agent entering somebody else's organization uses bounded authority. **Use the CLI by default.** General operating examples below use CLI commands; application code and manifests keep their native syntax. The typed, opinionated SDK owns shared orchestration, authentication, payments, validation and safe retries; CLI and MCP are thin adapters over it and the underlying HTTP API. Use the SDK for programmatic TypeScript/JavaScript workflows; shell scripts and CI can keep using CLI. The CLI prints JSON to stdout, JSON errors to stderr, and exits 0 on success and nonzero on failure or non-coherent verification (inspect the command’s documented status) β€” designed for shells, scripts, and agent loops. ## 30-second start Install `npm install -g run402@latest`, then create the complete manifest and app files from https://run402.com/llms.txt in the intended application directory. `--name` explicitly requests a new project; `-y` approves required setup within that deploy intent. ```bash run402 up --name my-app -y # bootstrap/link/deploy run402.json, run402.deploy.json, or app.json run402 up verify # rerun app HTTP verification without deploying run402 up --verify # deploy, then wait for gateway/edge release coherence ``` That's a real Postgres database + a deployed static site, paid for autonomously with testnet USDC. `run402 up` is the CLI path for local repos with a deploy manifest. It classifies app-shaped `run402.json` through the app-install graph and release-shaped `run402.json` through the same ReleaseSpec normalizer as `run402 deploy`; malformed app manifests return `APP_SPEC_INVALID` instead of an internal JavaScript exception. It validates the manifest first, then recursively performs only missing prerequisites through the SDK action runner. Project resolution is `--project`, `.run402/project.json`, manifest `project_id`, approved creation from `--name`; global active state never selects a deploy target. `--check` returns nullable target intent, local evidence and explicit deferred gateway checks in `result.preflight`; it never claims gateway validation. `--print-manifest` exports reloadable snake_case JSON relative to the original manifest directory; `--print-spec` is advanced SDK inspection. Unsupported dynamic/secret/build constructs fail with field paths. `--plan` obtains a deploy plan; review it before approving deploy. If an app manifest defines `verify.http[]`, `up` reports fresh edge sentinel misses as `propagation_pending` while the host binding converges; tune with `--propagation-budget-s`, use `--no-propagation-wait` to return immediately, and run `run402 up verify` to rerun checks without upload, deploy, project creation, or resource mutation. Add `--verify` to a real deploy when you need `edge_coherence` evidence in the final JSON; a valid non-coherent report exits 2. ## MCP-only hosts and SDK scripting If your host has no shell, use https://docs.run402.com/llms-mcp.txt for MCP setup and the `up` tool. The MCP server has eight tools; every other operation is a `run` snippet against the SDK client `r` (the `docs` tool is its reference), and an operation that returns or consumes a one-time secret refuses there with `SECRET_REQUIRES_CLI`, naming the CLI command to hand the person. Do not assume tools are installed. For typed scripting use https://docs.run402.com/sdk/scripting/ and the native SDK reference. Direct HTTP is supported for intentional protocol-level integrations at https://run402.com/llms-full.txt. To update this skill, rerun the installation flow at https://run402.com/install.txt for the same host; a new discovery index does not update an already installed copy. ## Self-hosted Core target Use the same commands against a self-hosted Run402 Core Gateway by configuring the API base once: ```bash run402 init --api-base=http://my-core:4020 run402 projects provision --name my-app # β†’ anon_key, service_key, project_id run402 deploy --manifest app.json --project ``` For Core, `init --api-base` stores the target in the active profile and does not create a Cloud wallet, request faucet funds, or require a Cloud tier. The CLI, Node SDK, and MCP all read the same configured target by default. Unsupported Cloud-only manifest slices fail as Core capability errors; they are not silently deployed to Run402 Cloud. ## How to think about it | You want to… | Reach for… | |---|---| | Set up a wallet from scratch | `run402 init` | | Buy from an x402-priced URL | `run402 pay --max-usd ` | | Redeem a promo code you were given | `run402 redeem ` (or `run402 init --voucher `) | | Bootstrap/link/deploy a manifest repo | `run402 up --name -y` | | Bootstrap/link/deploy and wait for edge coherence | `run402 up --name -y --verify` | | Rerun app HTTP verification | `run402 up verify --project ` | | Point at self-hosted Core | `run402 init --api-base=` | | Make a database | `run402 projects provision` | | Run SQL on it | `run402 projects sql` | | Check an auth manifest before applying | `run402 projects validate-expose` | | Make a table reachable from the browser | `run402 projects apply-expose` | | Deploy a frontend from a directory | `run402 sites deploy-dir ` | | Link GitHub Actions deploys | `run402 ci link github` | | Stash a file with a paste-able CDN URL | `run402 assets put ` | | Run code on the server | `run402 functions deploy` | | Send email | `run402 email send` | | Sign on-chain | `run402 contracts call` | | One-call full-stack deploy | `run402 deploy --manifest app.json` | The active project is sticky β€” `run402 projects use ` server-validates the project and makes it the default for every subsequent ``-taking command. Most commands work without an explicit `` once a project is active. ## Multiple wallets (profiles) Hold several wallets on one machine - per-client isolation, personal vs work, blast-radius containment. Keys never leave the machine (non-custodial). The `default` wallet stays at `~/.config/run402/`; named wallets live under `~/.config/run402/profiles//`. ```bash run402 wallets new kychon # create a named wallet run402 wallets list # name, label, address, rail, active run402 wallets use kychon # set the global default wallet run402 wallets bind kychon # write ./.run402.json - this repo uses kychon (safe to commit) run402 wallets current # which wallet is active + how it was selected run402 --wallet kychon projects list # one-off override for a single command ``` Selection precedence for every command: `--wallet ` flag > `RUN402_WALLET` env > nearest `./.run402.json` directory binding > `wallets use` default > `default`. A `RUN402_WALLET` that disagrees with a `.run402.json` binding is a hard error - pass `--wallet`, `unset RUN402_WALLET`, or `run402 wallets unbind`. Non-default selections echo the wallet name on stderr so you always know which wallet you are on. ## Public Buzz/Nostr attribution `run402 identity link nostr begin|complete` is the agent EOA-plus-kind-1 ceremony. Human accounts instead use for a normal browser, fresh-passkey, and Buzz approval flow; never ask a human to paste an event or handle a passkey/session/private key/id. Both yield the same public `idlnk_…` shape with a discriminated proof protocol. One principal may hold multiple subjects; a subject has only one active principal. Links are attribution only, never authentication or organization authority, and link/membership revocation are independent. Existing reads preserve all returned link ids, protocols, and lifecycle states. `run402 buzz status` reports independent skill, adoption-offer/adoption, community-installation, and enrollment states. Use `run402 buzz adopt offer` for the durable HTTPS ownership transfer, and poll `offer show`; opening a link is never completion. A completed poll must show the terminal receipt, public human link, and ordinary owner membership separately. Only membership grants org authority; link/membership revocation are independent and the receipt remains completed. `buzz adopt direct` is advanced compatibility. MCP remains read-only for signing/passkey-sensitive work and returns exact HTTPS/CLI next steps. ## Project credentials After `provision`, two keys are cached in the selected profile's `credentials/project-keys.v1.json`: - `anon_key` β€” for the browser. Read-only by default; safe to embed in HTML. RLS still applies. - `service_key` β€” server-side admin. Never embed in browser code. CORS is intentionally open for x402 clients, so a leaked service_key is exploitable from any origin. Use only inside functions or when running CLI as the agent. Neither expires. Lease enforcement happens server-side. This is a local credential cache, not project inventory; server-visible projects come from `run402 projects list/get/use`. ```bash run402 credentials project-keys list run402 credentials project-keys status --project # redacted cache status run402 credentials project-keys export --project --reveal run402 projects get # server project detail, no keys ``` ## Error Envelopes and Safe Retry Run402 JSON errors may include canonical fields. Branch on stable `code`, not English `message` or legacy `error` text. Fields to use: - `code`: machine-readable reason, e.g. `PROJECT_FROZEN`, `PAYMENT_REQUIRED`, `MIGRATION_FAILED`, `MIGRATE_GATE_ACTIVE` - `retryable`: the same request may succeed later - `safe_to_retry`: repeating the same request should not duplicate or corrupt a mutation - `mutation_state`: one of `none`, `not_started`, `committed`, `rolled_back`, `partial`, `unknown` - `trace_id`: include when reporting an issue - `request_id`: routed/function failure handle; use `run402 functions logs --request-id ` for diagnostics. Distinct from gateway `trace_id`. - `details`: structured route-specific context - `next_actions`: advisory actions e.g. `authenticate`, `submit_payment`, `renew_tier`, `check_usage`, `retry`, `resume_deploy`, `edit_request`, `edit_migration`, `create_project`, `initialize_wallet`, `deploy`; never treat them as blindly executable. CLI-resolvable entries carry a literal `command`. Cold start: from `run402 deploy`, follow the chain it hands back β€” no local wallet -> `run402 init`, no tier -> `run402 tier set prototype`, no project -> `run402 projects provision` β€” then retry. `tier set` and `projects provision` accept `--idempotency-key` so retries never double-charge Retry policy: - Retry directly only when `retryable: true` and `safe_to_retry: true`; reuse the same idempotency key for mutating operations. - `safe_to_retry: true` alone is not a retry signal; it means duplicate-safe, not likely-to-succeed. Lifecycle-gated writes, auth token exchanges, and passkey verifies need the indicated action before retrying. - `run402 deploy` already handles safe `BASE_RELEASE_CONFLICT` release races for omitted/current-base specs by re-planning through the SDK. A handled retry appears as a `deploy.retry` stderr event; exhausted retries include `attempts`, `max_retries`, and `last_retry_code`. Static activation/config failures reported from `activation_pending` throw promptly with gateway metadata. Do not hand-roll this specific deploy race loop. - For mutating 5xx errors with `safe_to_retry: false`, or `mutation_state: "committed"`, `"partial"`, or `"unknown"`, inspect/poll/reconcile state before retrying. For deploys, inspect events or resume the existing operation instead of starting a duplicate deploy. - Lifecycle/payment codes usually require an action: `PROJECT_FROZEN`/`PROJECT_DORMANT`/`PROJECT_PAST_DUE` -> check usage or renew tier; `PAYMENT_REQUIRED`/`INSUFFICIENT_FUNDS` -> submit/fund payment. Examples: ```json { "message": "Project is frozen.", "code": "PROJECT_FROZEN", "category": "lifecycle", "retryable": false, "safe_to_retry": true, "mutation_state": "none", "next_actions": [{ "type": "renew_tier" }, { "type": "check_usage" }] } ``` ```json { "message": "Payment required.", "code": "PAYMENT_REQUIRED", "category": "payment", "retryable": true, "safe_to_retry": true, "next_actions": [{ "type": "submit_payment" }] } ``` ```json { "message": "Migration failed.", "code": "MIGRATION_FAILED", "category": "deploy", "retryable": false, "safe_to_retry": true, "mutation_state": "rolled_back", "trace_id": "trc_...", "details": { "operation_id": "op_...", "phase": "migrate" }, "next_actions": [{ "type": "edit_migration" }] } ``` ## Deploying ### Advanced primitive: `deploy-dir` `deploy-dir` walks a local directory, hashes each file client-side, and only PUTs bytes the gateway doesn't already have. Re-deploying an unchanged tree returns immediately with `bytes_uploaded: 0`. ```bash run402 sites deploy-dir ./dist > result.json 2> events.log ``` Skips `.git/`, `node_modules/`, `.DS_Store` automatically. Symlinks throw (no cycles). `stderr` streams progress events β€” one JSON object per line: | phase | When fired | Extra fields | |---|---|---| | `plan` | After the planning request | `manifest_size` (file count) | | `upload` | After each missing file finishes PUTing | `file`, `sha256`, `done`, `total` | | `commit` | Just before commit | β€” | | `poll` | Per server-side copy poll | `status`, `elapsed_ms` | Pass `--quiet` to suppress events; the final result envelope still goes to stdout. ### The deploy itself: `run402 deploy` `run402 up` does any missing setup (wallet, tier, project, workspace link) and then deploys; `run402 deploy` only deploys. For a database + migrations + manifest + secret dependencies + functions + site + subdomain, set secret values first, then deploy a value-free manifest: ```bash run402 secrets set OPENAI_API_KEY --file ./.secrets/openai-key run402 deploy --manifest app.json --final-only ``` Use `--final-only` (alias of `--quiet`) when an agent or CI job only wants the final stdout JSON envelope. Use repeatable `--allow-warning ` for reviewed warning codes; reserve broad `--allow-warnings` for reviewed exceptional cases. After deploys, inspect release state without starting another mutation: ```bash run402 deploy releases active --project prj_... run402 deploy status op_... --project prj_... run402 deploy verify op_... --project prj_... --wait --timeout 120 run402 deploy releases get rel_... --project prj_... run402 deploy releases diff --from empty --to active --project prj_... ``` After pointer-swap recovery, compose promote with verification: ```bash run402 deploy promote RELEASE_ID --project PROJECT_ID run402 deploy verify --operation OPERATION_ID --wait ``` Take `OPERATION_ID` from the promote result. A successful promote means the origin pointer is active, while mutable public URLs can still be converging. Inspect `edge.state`; `edge.verify_url` is the direct operation-scoped HTTP verification endpoint. Inventories expose site paths, `static_public_paths` when returned, functions, secret keys only, subdomains, materialized routes, applied migrations, `release_generation`, `static_manifest_sha256`, nullable `static_manifest_metadata`, and warnings when returned. `site.paths` is the release static asset inventory; `static_public_paths[]` is the browser reachability inventory with `public_path`, `asset_path`, `reachability_authority`, `direct`, cache class, and content type. `static_manifest_metadata: null` means unavailable, not zero. Release diffs use `migrations.applied_between_releases`, route `added` / `removed` / `changed` buckets, and `static_assets` counters for unchanged/changed/added/removed files, CAS byte reuse, eliminated deploy-copy bytes, and immutable/CAS warning counts. #### Same-origin web routes Use `run402 deploy` for `site.public_paths` clean static browser URLs and public browser routes to functions or exact method-aware static aliases. Release static asset paths and public browser paths are distinct: `events.html` can be a private release asset while `/events` is the public static URL. ```json { "project_id": "prj_...", "site": { "replace": { "index.html": { "data": "
" }, "events.html": { "data": "

Events

" } }, "public_paths": { "mode": "explicit", "replace": { "/events": { "asset": "events.html", "cache_class": "html" } } } }, "functions": { "replace": { "api": { "runtime": "node22", "source": { "data": "export default async function handler(req) { const url = new URL(req.url); return Response.json({ ok: true, path: url.pathname }); }" } }, "login": { "runtime": "node22", "source": { "data": "export default async function handler(req) { return Response.json({ ok: true }); }" } } } }, "routes": { "replace": [ { "pattern": "/api/*", "methods": ["GET", "POST", "OPTIONS"], "target": { "type": "function", "name": "api" } }, { "pattern": "/login", "methods": ["POST"], "target": { "type": "function", "name": "login" } } ] } } ``` `site.public_paths.mode: "explicit"` means only the complete `public_paths.replace` table is directly reachable as static URLs. In the example, `/events` serves release asset `events.html`, while `/events.html` is not public unless separately declared. `{ "mode": "implicit" }` restores filename-derived public reachability and can widen access; review gateway warnings before confirming that switch. Public-path-only site specs are meaningful deploy content. Omit `routes` or pass `routes: null` to carry forward base routes. Use `routes: { "replace": [] }` to clear the route table. Do not use path-keyed maps. Function targets use `{ "type": "function", "name": "" }`. Prefer `site.public_paths` for ordinary clean static URLs e.g. `/events -> events.html`. Static route targets use exact patterns only, methods `["GET"]` or `["GET","HEAD"]`, and `{ "pattern": "/events", "methods": ["GET", "HEAD"], "target": { "type": "static", "file": "events.html" } }` for route-only aliases; `file` is a release static asset path, not a public path, URL, CAS hash, rewrite, or redirect. Direct `/functions/v1/:name` remains API-key protected; browser-routed paths are public same-origin ingress, so the function owns application auth, CSRF for cookie-authenticated unsafe methods, CORS/`OPTIONS`, cookies, redirects, and spoofed forwarding-header hygiene. Function routes may declare fixed app x402 pricing: `{ "pattern": "/api/credits", "methods": ["POST"], "target": { "type": "function", "name": "credits" }, "pricing": { "mode": "always", "amount_usd_micros": 250000, "pay_to": "org_default_payout" } }`. `250000` is $0.25 per matching action. Portable ReleaseSpec also accepts `receipt: "on_fulfillment"` inside pricing; compatible hosts require `payment.fulfilled(response)` from `@run402/functions` after completed delivery. Run402-hosted evidence stays gated until the interoperable delegated-signer carrier exists and never silently downgrades receipt intent. Omit `networks` for production mainnet only; include `"testnet"` explicitly for testnet payments. Add `"lightning"` (or `"lightning-testnet"`) to sell for sats over x402 `exact` on Bitcoin Lightning, settled to the org's own node: register a receive-only Nostr Wallet Connect pairing once with `run402 orgs lightning-receiver set -` (pairing on stdin; never in a snippet), optionally pin the sats price with `"amount_msat"`; a Lightning-only route needs no payout wallet, and the function sees `amountMsat` with no payer. Static aliases cannot be priced, direct function invocation is not monetized, and service/admin keys do not bypass a priced browser route. Before deploying priced routes, ensure the org has a payout wallet with `run402 orgs payout-wallet `. For conditional credits, use one fixed-price `/api/credits` route and keep the app envelope unpriced behind app-local auth. In the handler, import `getRoutedPaymentContext` from `@run402/functions`, call `getRoutedPaymentContext(req)`, and key idempotency by `payment.paymentId`; audit with `run402 projects tenant-payments `. Matching is exact or final `/*` prefix only. `/admin/*` does not match `/admin`; use both `/admin` and `/admin/*` for a dynamic area root. Query strings are ignored for matching and preserved in the handler's full public `req.url`. Exact beats prefix, longest prefix wins, and method-compatible dynamic routes beat static assets. A `POST /login` route can coexist with static `GET /login` HTML. Unsafe method mismatch returns `405`; matched dynamic route failures fail closed. Routed functions use the Node 22 Fetch Request -> Response contract: `export default async function handler(req) { ... }`. `req.method` is the browser method, and `req.url` is the full public URL on managed subdomains, hosts, and verified custom domains. Derive OAuth callbacks from it, for example `new URL("/admin/oauth/google/callback", new URL(req.url).origin)`. Append multiple cookies with `headers.append("Set-Cookie", value)`; redirects, cookies, and query strings are preserved. The raw `run402.routed_http.v1` envelope is internal; do not write route handlers against it. Use `run402 deploy resolve https://example.com/events --project prj_123 --method GET` before mutating deploy state when the question is "what would this public URL serve?" The host/path form is `run402 deploy resolve --host example.com --path /events --project prj_123 --method GET`; never combine a URL with `--host`/`--path`. Output is JSON with `status`, `would_serve`, `diagnostic_status`, `match`, normalized `request`, warnings, full `resolution`, `edge_propagation`, and structured `next_steps`. URL query strings/fragments are disclosed in `request.ignored`. When returned, `asset_path`, `reachability_authority`, and `direct` explain which release asset backs the public URL and whether reachability came from implicit file-path mode, explicit `site.public_paths`, or a route-only static alias. Stable-host diagnostics may also include `authorization_result`, `cas_object` (`sha256`, `exists`, `expected_size`, `actual_size`), hostname-specific `response_variant`, route/static fields e.g. `allow`, `route_pattern`, `target_type`, `target_name`, and `target_file`, plus `edge_propagation` (`settled`, `propagating`, or `sync_pending`; non-settled means retry or run `run402 up verify`). Known `match` literals are `host_missing`, `manifest_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `none`, `static_exact`, `static_index`, `spa_fallback`, `spa_fallback_missing`, `route_function`, `route_static_alias`, and `route_method_miss`; preserve unknown future strings. Known `authorization_result` values include `authorized`, `not_public`, `not_applicable`, `manifest_missing`, `target_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `missing_cas_object`, `unfinalized_or_deleting_cas_object`, `size_mismatch`, and `unauthorized_cas_object`. Known `fallback_state` values include `active_release_missing`, `unsupported_manifest_version`, and `negative_cache_hit`; preserve unknown future strings. `result` is diagnostic body status, not CLI process status, so host misses can exit 0 with `would_serve: false`. Do not use diagnostics as a fetch, cache purge, or reason to hard-code `cache_policy` strings; branch on structured JSON e.g. `allow`, `cas_object`, and `edge_propagation`. Known route warning recovery: `PUBLIC_ROUTED_FUNCTION` is informational (`requires_confirmation: false` β€” it never blocks and needs no `--allow-warning`): review app auth, CSRF, CORS/`OPTIONS`, and cookies. Only warnings with `requires_confirmation: true` need `--allow-warning `; broad `--allow-warnings` is last resort after every warning is reviewed. `ROUTE_SHADOWS_STATIC_PATH` and `WILDCARD_ROUTE_SHADOWS_STATIC_PATHS` mean inspect affected paths, active routes, `static_public_paths`, and resolve diagnostics before confirming. `STATIC_ALIAS_SHADOWS_STATIC_PATH`, `STATIC_ALIAS_RELATIVE_ASSET_RISK`, `STATIC_ALIAS_DUPLICATE_CANONICAL_URL`, `STATIC_ALIAS_EXTENSIONLESS_NON_HTML`, and `STATIC_ALIAS_TABLE_NEAR_LIMIT` are route-only static alias warnings; prefer `site.public_paths` for ordinary clean URLs, inspect the backing `asset_path`, fix relative assets/canonical URLs, and avoid table-exhausting page-by-page routes. `ROUTE_TARGET_CARRIED_FORWARD` means inspect carried-forward function targets. `METHOD_SPECIFIC_ROUTE_ALLOWS_GET_STATIC_FALLBACK` means confirm static fallback is intended. `WILDCARD_ROUTE_EXCLUDES_MUTATION_METHODS` means a wildcard API prefix only allows `GET`/`HEAD`; add mutation methods e.g. `POST`, omit methods for an API prefix, or, when the GET/HEAD final-wildcard function route is intentionally read-only, acknowledge with `--allow-warning WILDCARD_ROUTE_EXCLUDES_MUTATION_METHODS`. `ROUTE_TABLE_NEAR_LIMIT` means consolidate routes. `ROUTES_NOT_ENABLED` means deploy without `routes` or request enablement. Runtime route failure codes to branch on: `ROUTE_MANIFEST_LOAD_FAILED` (manifest/propagation), `ROUTED_INVOKE_WORKER_SECRET_MISSING` (custom-domain Worker secret), `ROUTED_INVOKE_AUTH_FAILED` (internal invoke signature), `ROUTED_ROUTE_STALE` (selected route failed release revalidation), `ROUTE_METHOD_NOT_ALLOWED` (method mismatch), `PAYOUT_WALLET_REQUIRED` / `PAYOUT_WALLET_AMBIGUOUS` / `PAYOUT_WALLET_UNRESOLVED` (priced-route payout setup), `PAYMENT_PROOF_MISMATCH` (stale or wrong x402 proof), and `ROUTED_RESPONSE_TOO_LARGE` (body over 6 MiB). #### Recipe: static home page + SPA shell A SPA site ships `index.html` as the shell serving every unmatched route (match `spa_fallback`), so by default `GET /` serves the shell too. To serve a real static home page at `/` β€” real bytes under curl and without JavaScript β€” while keeping the shell for app routes, ship `home.html` at the site root alongside `index.html`, add an exact root static route alias to the manifest, and run `run402 deploy --manifest app.json`: ```json { "project_id": "prj_...", "site": { "replace": { "index.html": { "data": "
" }, "home.html": { "data": "

Welcome

Open the app" }, "app.js": { "data": "/* SPA bootstrap */" } } }, "routes": { "replace": [ { "pattern": "/", "target": { "type": "static", "file": "home.html" } } ] } } ``` Route matching runs before all static resolution β€” including the implicit `/` -> `index.html` root mapping β€” and SPA-fallback derivation is independent of the route table. So `GET /` serves `home.html` (match `route_static_alias`), unmatched app routes e.g. `/dashboard` still serve the `index.html` shell (match `spa_fallback`), and named static pages keep serving unchanged (match `static_exact`). Root placement of `home.html` keeps its relative asset URLs resolving identically to the direct file and avoids the `STATIC_ALIAS_RELATIVE_ASSET_RISK` warning. Expect two non-blocking plan lints: `STATIC_ALIAS_SHADOWS_STATIC_PATH` (warn β€” the alias overrides what `/` would otherwise serve; for this recipe that is accurate and expected, and the commit proceeds) and `STATIC_ALIAS_DUPLICATE_CANONICAL_URL` (info β€” `/home.html` stays directly reachable in implicit public-path mode; add `` to `home.html` if duplicate-content SEO matters). Omitting `routes` on later deploys carries the alias forward (informational `ROUTE_TARGET_CARRIED_FORWARD`); a pipeline that sends `routes.replace` must include the alias every time because replace is total. Verify with `run402 deploy resolve --project prj_123 --url https:/// --method GET` and confirm `match: "route_static_alias"` with `target_file: "home.html"`. #### Routed functions: locale awareness Declare supported locales as a `spec.i18n` release slice and the gateway negotiates a locale per routed-function request, then surfaces it to user code through two request headers. Add `i18n` to the deploy manifest alongside `functions` and `routes` and run `run402 deploy --manifest run402.deploy.json`: ```json { "project_id": "prj_...", "functions": { "replace": { "api": { "runtime": "node22", "source": { "data": "export default async (req) => { const locale = req.headers.get('x-run402-locale'); const def = req.headers.get('x-run402-default-locale'); return Response.json({ locale, default: def }); }" } } } }, "routes": { "replace": [ { "pattern": "/api/*", "target": { "type": "function", "name": "api" } } ] }, "i18n": { "defaultLocale": "en", "locales": ["en", "es", "fr", "zh-Hant"], "detect": ["cookie:wl_locale", "accept-language"] } } ``` Carry-forward semantics: omit `i18n` to carry forward from base release; pass `"i18n": null` to clear the slice on the new release; pass `{ defaultLocale, locales, detect? }` to replace. Simpler than `routes` β€” no `{ replace }` envelope. Locale-tag rules (strict, no canonicalization): - `defaultLocale` MUST be byte-identical to one entry in `locales[]`. The gateway does NOT silently canonicalize; the CLI/SDK validate this client-side before planning. - Each tag MUST match `/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/`. Tags are opaque β€” no BCP-47 semantic validation. - `locales[]` is non-empty, max 50 entries. - Negotiation returns canonical casing from `locales[]`, NOT the request's casing. Detection (`detect[]`, default `["accept-language"]`, max 10, `[]` allowed and means "always default"): - Walked in order; first match wins. - `"accept-language"` parses per RFC 9110, drops `q=0` and `*`, sorts by q descending; applies RFC 4647 Β§3.4 lookup-style truncation (`zh-Hant-TW` β†’ `zh-Hant` β†’ `zh`); longest matching prefix wins. A generic request tag does NOT match a more-specific `locales[]` entry β€” `Accept-Language: es` does NOT match `locales: ["es-MX"]`. - `"cookie:"` does a case-sensitive cookie-name lookup; the raw cookie value (no percent-decode) is matched case-insensitively against `locales[]`. Cookie names MUST match RFC 6265 grammar (`/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/`). Read the negotiated locale inside a routed function (single-arg `(req)` signature, not `(req, ctx)`): ```ts export default async (req) => { const locale = req.headers.get('x-run402-locale'); const defaultLocale = req.headers.get('x-run402-default-locale'); if (locale && locale !== defaultLocale) { return renderWithTranslations({ locale }); } return renderBase({ locale: defaultLocale ?? 'en' }); }; ``` `x-run402-locale` and `x-run402-default-locale` are OMITTED entirely when the active release has no `i18n` slice (additive-compat). The gateway injects them at request time, so already-deployed function bundles see new headers on the next deploy that adds `i18n` β€” no function redeploy required. The bundled `@run402/functions` runtime translates the routed envelope into a Web-standard `Request` before calling user code, so the routed-envelope `context.locale` is NOT visible to typical user functions β€” read the headers instead. Static-route hits do NOT receive locale negotiation; only routed HTTP function invocations do. Run402 does NOT inject `Vary` headers β€” apps that return public-cacheable responses varying by locale must set their own `Vary` until per-locale edge caching ships. #### Routed functions: visitor geo (`x-run402-country`) Routed function invocations carry the visitor's country as an edge-authoritative request header β€” identical on managed subdomains (`.run402.com`) and verified custom domains, with zero config (no release slice, always on when the edge knows the country): ```ts export default async (req) => { const country = req.headers.get('x-run402-country') ?? 'unknown'; // e.g. "DE" return Response.json({ country }); }; ``` - Value is ISO 3166-1 alpha-2 verbatim from the edge, plus the specials `T1` (Tor exit) and `XX` (unknown) on Cloudflare-fronted custom domains. - When the edge supplies no geo the header is **absent** β€” never empty, never a guessed value β€” so `?? 'unknown'` (or your preferred fallback) at the read site. - Spoof-proof: client-supplied `x-run402-country`, `cf-ipcountry`, and `cloudfront-viewer-country` are scrubbed at both edges; the header your function sees is always minted by the platform from edge geo data. - Compat: on custom domains only, the legacy `cf-ipcountry` header is also present with the same value. Prefer `x-run402-country` β€” it works on every hostname. - Static-route hits do NOT receive geo; only routed HTTP function invocations do. Country-varying public-cacheable responses must set their own `Vary`, same as locale. #### Client-side gotcha: language switchers must write a cookie Apps that persist locale to `localStorage` only (a common pattern from Astro/Next i18n tutorials) won't be seen by Run402's server-side negotiation. Mirror the locale to a cookie so the next request hits the right translations, then declare a cookie source in `spec.i18n.detect`: ```js function setLanguage(lang) { localStorage.setItem('wl_locale', lang); document.cookie = `wl_locale=${encodeURIComponent(lang)}; path=/; max-age=31536000; samesite=lax`; } ``` ```json { "i18n": { "defaultLocale": "en", "locales": ["en", "es"], "detect": ["cookie:wl_locale", "accept-language"] } } ``` The deploy manifest is a v2 `ReleaseSpec`; put the auth manifest under `database.expose`: ```json { "project_id": "prj_…", "database": { "migrations": [{ "id": "001_init", "sql_path": "setup.sql" }], "expose": { "$schema": "https://run402.com/schemas/manifest.v1.json", "version": "1", "tables": [ { "name": "items", "expose": true, "policy": "user_owns_rows", "owner_column": "user_id", "force_owner_on_insert": true } ] } }, "secrets": { "require": ["OPENAI_API_KEY"] }, "functions": { "replace": { "my-fn": { "runtime": "node22", "source": { "data": "export default async (req) => new Response('ok')" }, "config": { "timeoutSeconds": 30, "memoryMb": 256 } } } }, "site": { "replace": { "index.html": { "data": "…" }, "logo.png": { "data": "iVBORw0…", "encoding": "base64" } } }, "subdomains": { "set": ["my-app"] } } ``` The `database.expose` entry is auth-as-SDLC β€” your authorization travels with the release. The gateway validates it against the migration SQL and applies it atomically. If the manifest references a table the migration doesn't create, the deploy is rejected with HTTP 400 and a structured `errors` array listing every violation. For a new app, load `/_run402/config.js` and read `window.RUN402` at runtime, then deploy the complete files with `run402 up --name `. Manual provisioning and pasted public keys are only needed for deliberate external-host integrations. ### GitHub Actions OIDC deploys Link once locally, then let GitHub Actions run the same deploy command agents already use: ```bash run402 ci link github --project prj_... --manifest run402.deploy.json # Optional route authority for CI route declarations: run402 ci link github --project prj_... --manifest run402.deploy.json --route-scope /admin --route-scope /api/* git add .github/workflows/run402-deploy.yml run402.deploy.json git commit -m "Add run402 deploy workflow" ``` The generated workflow uses a pinned `run402@` CLI via `npx`, includes `permissions: id-token: write` and `contents: read`, and runs: ```bash run402 deploy --manifest run402.deploy.json --project prj_... ``` Useful follow-ups: ```bash run402 ci list --project prj_... run402 ci revoke cib_... ``` V1 intentionally keeps the shape narrow: `push` and `workflow_dispatch` only, no PR deploy flags, no raw subject or wildcard flags, and no soft repository-id binding. Without `--route-scope`, CI cannot deploy `routes`; with repeatable route scopes, it may deploy only matching exact paths e.g. `/admin` or final-wildcard prefixes e.g. `/api/*`. If CI returns `CI_ROUTE_SCOPE_DENIED`, re-link with covering scopes or run the route-changing deploy locally. Revocation stops future CI gateway requests but does not undo already-deployed code, stop in-flight deploy operations, rotate exfiltrated keys, or remove deployed functions. ## Authorization β€” the expose manifest Tables you create are dark by default. Until your manifest declares a table with `expose: true`, it's invisible to anon and authenticated callers. This eliminates the "agent forgot RLS, data leaked" footgun. The manifest is the single source of truth for what's reachable via `/rest/v1/*`. A valid anon key against an existing but undeclared table gets a structured `403 TABLE_NOT_EXPOSED` (never a bare Postgres `42501`) whose `next_actions` say exactly that: `expose_table` (declare it in `database.expose.tables` and `run402 up -y`), `edit_request` (the expose endpoint), or `use_function` (keep it dark and read it from a function with `adminDb()`). It is not an RLS problem. JSON Schema: . Set `$schema` on your manifest file and your editor gets autocomplete for free. ### Preferred: ship `manifest.json` in your bundle Authorization travels with your code. Put a file named `manifest.json` in the bundle's `files[]` and the gateway reads it, validates it against your migration SQL, applies it, and strips it from `files[]` before the site deploys β€” so it's never publicly reachable on your subdomain. The deploy response includes `manifest_applied: true` on success. ```json { "$schema": "https://run402.com/schemas/manifest.v1.json", "version": "1", "tables": [ { "name": "items", "expose": true, "policy": "user_owns_rows", "owner_column": "user_id", "force_owner_on_insert": true }, { "name": "audit", "expose": false } ], "views": [ { "name": "leaderboard", "base": "items", "select": ["user_id", "score"], "expose": true } ], "rpcs": [ { "name": "compute_streak", "signature": "(user_id uuid)", "grant_to": ["authenticated"] } ] } ``` If the manifest references a table the migration doesn't create, the deploy is rejected with HTTP 400 and a structured `errors` array listing every violation (not the first). ### Non-mutating validation: `validate-expose` Before applying, run: ```bash run402 projects validate-expose [id] --file manifest.json --migration-file migrations.sql ``` This validates the auth/expose manifest used by `manifest.json`, `database.expose`, and `apply-expose`; it is not deploy-manifest validation. Migration SQL is used only for reference checks and is not executed as a PostgreSQL dry run. The command prints `{ "hasErrors": boolean, "errors": [...], "warnings": [...] }` and exits 0 even when `hasErrors` is true β€” the validator ran, so the command succeeded; read `hasErrors` to decide what to do. ### Imperative escape hatch: `apply-expose` For ad-hoc changes outside a deploy β€” same JSON shape, no bundle: ```bash run402 projects apply-expose --file manifest.json run402 projects get-expose # source: "applied" | "introspected" ``` `get-expose` returns the live state. `source: "applied"` means it came from a prior `apply-expose` (or a bundled `manifest.json`); `"introspected"` means no manifest has ever been applied and the response was reconstructed from live DB state. Convergent: applying the same manifest twice is a no-op. Items removed between applies have their policies, grants, triggers, and views dropped. Always include everything you want exposed. ### Built-in policies | Policy | Allows | |---|---| | `user_owns_rows` | Rows where `owner_column = auth.uid()`. With `force_owner_on_insert: true`, a BEFORE INSERT trigger sets it automatically. Default for anything user-scoped. | | `public_read_authenticated_write` | Anyone reads. Any authenticated user writes any row. For shared boards / collaborative content. | | `public_read_write_UNRESTRICTED` | Fully open. Requires `i_understand_this_is_unrestricted: true` on the table entry. Only for guestbooks / waitlists / feedback forms. | | `custom` | Escape hatch. Provide `custom_sql` with `CREATE POLICY` statements. | Views always run with `security_invoker=true` β€” they inherit the underlying table's RLS, so they can't accidentally leak hidden columns. RPCs are not exposed unless listed in `rpcs[]` (a database event trigger revokes PUBLIC EXECUTE on every newly-created function). ## Storage β€” paste-and-go assets `run402 assets put` returns an `AssetRef`. The URL is content-addressed (`pr-.run402.com/_blob/-<8hex>.`), served through CloudFront, and never needs cache invalidation: ```bash run402 assets put ./logo.png --json run402 assets put ./app.js --json run402 assets put ./styles.css --json run402 assets put ./asset --key assets/logo --content-type image/svg+xml --json run402 assets put ./hero.jpg --meta uploaded_by=agent_abc --meta tags=hero,banner --exif-policy strip --json ``` Each response includes: | Field | Use | |---|---| | `cdn_url` | The content-addressed URL β€” paste straight into `src=` / `href=` | | `sri` | `sha256-` for `