Run402

run402: full-stack backend infrastructure for AI agents

Postgres, auth, storage, serverless functions and staged deploys — provisioned, operated and paid for by an agent through the CLI, with a typed SDK for scripting and MCP for tool-native hosts. No cloud console, no signup. Open source.

Run402 is open-source backend infrastructure for AI agents and coding agents — a backend-as-a-service addressed to a machine rather than to a person. An autonomous agent provisions a Postgres database, user auth, file storage, serverless functions and site hosting, ships them through one staged deploy workflow, and pays for the usage itself. Comparable in surface to Supabase, Firebase or Vercel; different in that there is no dashboard you have to sign into to get started (the console exists for people; the agent never needs it) and no human-issued API key to copy.

This is the backend Kychee's open products run on. We needed a layer an agent can drive end to end, with room for whatever each app turns out to need, and nothing off the shelf had all of it, so we built it and opened it the same way we open the apps: this repo holds the agent surfaces (MIT), run402-core holds the open self-hostable runtime slice (Apache-2.0; the managed Cloud control plane remains proprietary, see CLOUD_VS_CORE.md), and kysigned is the first product running on it.

One call to run402 gives an agent a full Postgres database, REST API, user auth, content-addressed file storage, static site hosting, serverless functions, and image generation, paid with x402 (USDC on Base) or MPP (pathUSD on Tempo, or sats over Bitcoin Lightning) — or card-funded allowance. The prototype tier is free on testnet.

Run402 is agent-first because agents are first-class participants, not because people disappear. A person or agent acts through its own Run402 principal and authenticator, and its actions remain attributable. Identity answers who acted; memberships, roles, grants, grant keys, freshness, and spend policy determine what that principal may do.

An autonomous agent may remain the legitimate owner of the org-of-one it creates. People may join through explicit co-ownership. Agents entering somebody else's organization receive bounded authority instead of borrowing a human account. Different keys. Equal standing. Explicit authority.

Use the CLI by default to provision, deploy, inspect and recover. Use the typed, opinionated SDK when writing programmatic TypeScript/JavaScript workflows; shell scripts and CI can keep using CLI. MCP serves MCP-native hosts, and direct HTTP supports deliberate lower-level integrations.

This monorepo ships these interfaces:

These interfaces share a single typed kernel where appropriate: @run402/sdk. MCP tools, CLI subcommands, and OpenClaw scripts are thin shims over SDK calls. @run402/functions is the in-function helper that runs inside deployed code; the npm package on the registry is the artifact Cloud bundles. @run402/astro layers the SDK and functions runtime into Astro's build and SSR flow. The HTTP API is the foundation; the SDK owns shared client workflows and orchestration; CLI and MCP expose them in machine-friendly forms. Native SDK/MCP references explain intentional alternatives.

Deploy summaries share the SDK workflow view. CLI writes redacted detail under .run402/diagnostics/; MCP retains it through expand_result. Typed SDK callers keep the full result. Snapshot collection excludes platform runtime files automatically.

30-second start

First create the complete run402.json and index.html from Your first deploy. Run these commands in that application directory; --name requests a new project.

npm install -g run402@latest

run402 up --name my-app -y # bootstrap wallet/tier/project/link, then deploy manifest run402 up verify # rerun app HTTP verification without deploying run402 up --verify # deploy, then wait for gateway/edge coherence

That's a real Postgres database + a deployed static site, paid for autonomously with testnet USDC.

Buy from any x402 seller with the same wallet and a default $0.10 ceiling:

run402 pay https://seller.example/translate --method POST \

--body '{"text":"hello"}' --max-usd 0.05 \ --idempotency-key translation:1 --require-receipt

The SDK equivalent is r.pay.fetch(url, init, { maxUsdMicros, idempotencyKey, requireReceipt }); MCP callers run the same SDK call as a run snippet. All three return the same x402-commerce-result.v1 settlement, movement/replay, delivery, offer, merchant-receipt, signer-relationship, policy, and raw-evidence fields and pass unpriced URLs through with payment: null. Requiring a receipt rejects before payment when no wallet-rooted offer is eligible. If a promised receipt cannot be verified after settlement, PaymentPolicyError retains the upstream response and paid result and tells the caller to reconcile—never to pay again. For a trusted Run402 PAYMENT_INTENT_PENDING, all three surfaces prescribe one recovery path: wait for Retry-After, then repeat the same request with the same payer and key. Never replace the key. The SDK and MCP can also re-present an ambiguous proof while their process remains alive; custom/arbitrary sellers remain ambiguous and require reconciliation.

Prefer run402 up when a repo has run402.deploy.json or app.json. The CLI stays a thin shim over the Node SDK action runner (r.actions.run(...) / r.up(...)): it validates the manifest first, then recursively performs only the missing prerequisites. Project resolution is --project, .run402/project.json, manifest project_id, approved creation from --name; global active state never selects a deploy target. --name is project creation/link metadata only; it is not part of the deploy manifest and never renames an existing project. Use --check for local validation and --plan for gateway-reviewed intent before applying. Local validation covers every file the manifest references (migration sql_path/sql_file, function sources and files, site paths and dir() targets, assets.put sources): a missing one fails with MANIFEST_FILE_MISSING (details.missing[] of { field_path, path, kind }, one create_file next action per file) before any gateway call, in every mode and in run402 deploy. With no manifest in the working directory, UP_MANIFEST_REQUIRED looks one directory down and names what it found (details.nearby_manifests[], a read-only run_in_directory action for a single candidate, or one unranked select_application action for multiple apps); --manifest to a missing file is a typed MANIFEST_NOT_FOUND.

If an app manifest defines verify.http[], run402 up verifies those URLs after deploy. Fresh run402 edge sentinel misses are reported as propagation_pending rather than permanent failures while the binding is still converging; tune that wait with --propagation-budget-s (default 120) or return immediately with --no-propagation-wait. run402 up verify reruns the same HTTP checks without uploading, deploying, creating projects, or mutating resources.

The CLI checks for newer run402 releases opportunistically and fail-open. Success stdout stays the command result; stale-version notices are advisory JSON on stderr, or cli.update_available NDJSON events in --json-stream. run402 doctor --refresh is the explicit live npm check and reports the install context plus the safest upgrade command for local, global, or ephemeral installs. run402 doctor answers { ok, blocking[], warnings[], checks[] }: ok is true exactly when blocking[] is empty, every check carries severity: "blocking" | "advisory" | "info", advisory findings (an unbound passkey, a stale CLI, vault gaps, a tier-less own org that can still reach another org's projects: TIER_MISSING_ON_OWN_ORG) land in warnings[] without changing ok or the exit code, and the tier check's status is a fixed vocabulary (ok | inactive | frozen | past_due | dormant | purged | missing | unknown | error, never a tier name; the name and raw lifecycle are in value.tier / value.lifecycle).

Typed deploy configs use the same commands. Executable configs are trusted local code, so v1 only runs them when passed explicitly:

run402 up --manifest run402.deploy.ts --check

run402 up --manifest run402.deploy.ts --plan run402 up --manifest run402.deploy.ts --require-plan plan_...

--check and --print-spec are local-only (both verify that every referenced file exists). --plan asks the gateway for a reviewed plan with plan_id, plan_fingerprint, warnings, diff, and one next action. --require-plan reapplies only if the normalized spec and reviewed gateway events still match.

import { defineConfig, dir, nodeFunction, sqlFile } from "@run402/sdk/config";

export default defineConfig(({ env }) => ({ project_id: env.required("RUN402_PROJECT_ID"), database: { migrations: [sqlFile("db/001_init.sql")] }, site: { replace: dir("dist"), public_paths: { mode: "implicit" } }, functions: { replace: { api: nodeFunction("dist/functions/api.js") } }, secrets: { require: ["OPENAI_API_KEY"] }, }));

Helpers normalize to the same ReleaseSpec as JSON manifests. dir() walks deterministically