Run402 — Postgres, storage & deploys for AI agents

Site: https://run402.com API base: https://api.run402.com (NOT run402.com — that's a static docs site, POSTing returns 405) Operator: Kychee, Inc. Terms: https://run402.com/humans/terms.html Health: https://api.run402.com/health Status: https://api.run402.com/status Updates: https://run402.com/updates.txt

Hello, agent

If you're reading this, you're probably evaluating how to build something with Run402. This file is the wayfinder: it tells you what we offer, who we are, and which reference doc to fetch next based on what you're trying to do. Don't read everything — pick your integration surface and go to the matching llms-*.txt below.

If the human said Please install the run402.com skill, read https://run402.com/install.txt. In a managed Buzz conversation or ~/.buzz workspace, select run402-buzz, then load the verified installed skill directly and continue the same turn through connection and the contextual demo offer; otherwise select the ordinary run402 skill. The human does not need to know the skill name, bootstrap path, runtime target, terminal command, or a second setup prompt.

If you have an active wallet allowance and want to ship now, the 30-second start is at the bottom of this file.

What Run402 offers

A platform that an AI agent can provision, operate, and pay for through its own principal and authenticator—not a borrowed human account or invisible automation identity. The routine cold-start path requires no human signup, no API keys copied from a web dashboard, and no per-payment human click within the agent's permitted budget:

• Postgres databases with PostgREST REST API and user auth (passwords + Google OAuth, zero-config)
• Content-addressed CDN file storage — paste-and-go URLs with SRI integrity baked in
• Static site hosting at <name>.run402.com plus custom domains, with site.public_paths for clean browser URLs e.g. /events backed by release asset events.html
• Same-origin web routes with routes.replace mapping /admin and /admin/* to Node 22 Fetch Request -> Response functions, plus exact method-aware static aliases when a route table is the right tool. Function routes can declare fixed tenant x402 pricing such as amount_usd_micros: 250000 with pay_to: "org_default_payout"; portable ReleaseSpec also accepts receipt: "on_fulfillment" and compatible hosts require payment.fulfilled(response) after completed delivery. Run402-hosted evidence stays gated until the interoperable delegated-signer carrier exists. Set the org payout wallet first and read settled handler context with getRoutedPaymentContext(req) from @run402/functions (x-run402-payment-* headers are the gateway-confirmed backing data). req.url is the full public URL on managed and custom domains; direct /functions/v1/:name remains API-key protected. Runtime route failure codes include ROUTE_MANIFEST_LOAD_FAILED, ROUTED_INVOKE_WORKER_SECRET_MISSING, PAYOUT_WALLET_REQUIRED, and ROUTED_RESPONSE_TOO_LARGE.
• Node 22 serverless functions with durable function runs, schedule/email triggers, and an in-handler helper library
• Email — transactional sending, inbound parsing, custom sender domains, raw RFC-822 access for DKIM / zk-email
• AI helpers — image generation, text translation, content moderation
• KMS-backed Ethereum signing — provision signers where private keys never leave AWS KMS
• A hosted Git remote, encrypted before it leaves the machine — Run402 cannot decrypt your gitvault or repository history. The why, plainly: a host that can READ private repositories can index them, train models on them, or hand them to someone who will; GitVault is the remote that structurally cannot — which also makes it the natural encrypted SECOND remote beside a GitHub/GitLab primary (keep your workflow, add one remote). Vault-only is a first-class, zero-deploy-ceremony track: run402 init once, then plain git push origin main (or run402 repos create <name> in one call) hosts encrypted source history with no app, no manifest, nothing deployed.

Prototype tier is FREE on testnet — uses Base Sepolia USDC from the Run402 faucet to verify your x402 setup end-to-end. No real money, instantly available, and no human account approval for this prototype path. When you're ready for production, hobby ($5/30d) and team ($20/30d) tiers pay with real USDC on Base, pathUSD on Tempo, or Stripe credits.

Vision — people and agents as first-class participants

Run402 is agent-first because agents are first-class participants, not because people disappear. People and agents each act through their own Run402 principal and authenticator, and their actions remain attributable. Equal standing does not mean identical credentials or permissions: identity answers who acted; organization membership, roles, grants, delegates, freshness, and spend policy answer what that principal may do.

An autonomous founder agent may remain owner of its org-of-one. A person may join through explicit co-ownership. An agent entering an organization founded by somebody else receives bounded, revocable authority instead of borrowing a human login. Most platforms treat AI agents as second-class clients of human-shaped products. Run402 gives them a direct path while keeping human ownership, policy, recovery, billing, and high-stakes consent first-class too.

• Autonomous payment. x402 (the HTTP 402 micropayment protocol) lets an agent settle a permitted bill directly from its allowance without asking a human to click through each checkout. MPP (Stripe's Machine Payments Protocol) is the same pattern on Tempo.
• Dark-by-default safety. A table you create is unreachable from PostgREST until you declare it in the manifest with expose: true. This eliminates the "agent created a table, forgot to set RLS, data leaked" footgun.
• Content-addressed storage. blob put returns a URL bound to the bytes' SHA-256 — no cache-invalidation choreography, no dangling references after redeploy.
• One operation = one declarative spec. r.project(id).apply takes a single ReleaseSpec and converges the project (database + manifest + value-free secret declarations + functions + site + public static paths + subdomain) toward it; surgical patches and full replaces are first-class. Set secret values out-of-band with the secrets API, then use secrets.require[] as a dependency gate.
• One command = recursive app deploy. run402 up is a thin CLI shim over the SDK action runner: validate manifest, ensure missing allowance/tier/project/link prerequisites when approved, then call r.project(id).apply. The same behavior is available from @run402/sdk/node as r.up(...) / r.actions.run(...). For executable typed configs, use the reviewed loop run402 up --manifest run402.deploy.ts --check -> --plan -> --require-plan <plan_id>.
• Known-safe deploy contention is absorbed. For omitted/current-base specs, apply re-plans and retries BASE_RELEASE_CONFLICT only when the gateway marks it safe_to_retry: true, emitting deploy.retry so agents can see the recovery.
• CI without shared secrets. run402 ci link github binds a GitHub repo/branch or environment through OIDC, optionally with --route-scope exact/final-wildcard route authority, then the workflow calls the same run402 deploy apply primitive with id-token: write instead of storing Run402 service keys in GitHub secrets.
• Lifecycle that doesn't lose work. Lease expiry triggers a ~104-day soft-delete state machine; the live data plane keeps serving end users throughout. Subdomains are reserved for the original owner so a missed renewal can't lose a brand to a squatter.
• Agent-operable errors. Run402 JSON errors carry a canonical envelope with stable code, retryable, safe_to_retry, mutation_state, and next_actions so you can branch on machine-readable fields, not English message text.
• Astro SSR + ISR cache (v1.52+). export default run402(); in astro.config.mjs (the @run402/astro 1.0+ preset) wires SSR to AWS Lambda with SnapStart and an origin ISR cache — sub-second r.cache.invalidate(url) for admin-edit flows, generation-guarded so in-flight MISS renders cannot clobber a freshly-cleared state, bypass-by-default unless Cache-Control explicitly allows it. auth.* helpers from @run402/functions taint per-request caching so personalized renders never get stored.
• Public agent attribution without shared keys. run402 identity link nostr begin|complete proves that a separately-held Buzz/Nostr public key and Run402 EOA represented one agent during a short-lived dual-signature challenge. Run402 never accepts a Nostr private key; the link is public metadata and never authentication, authorization, ownership, payment, or transfer authority. Buzz users install the self-contained run402-buzz skill directly from buzz/; setup stops at verified readiness and asks before building or deploying anything.
• Buzz community control without shared credentials. run402 buzz status|adopt|install|enroll preserves four independent states: inert skill capability, Buzz-owner human adoption, Buzz-community ↔ Run402-org installation, and bounded per-agent existing-project grants. Relay descriptors are public discovery evidence, each agent keeps a distinct principal, MCP remains read-only for signing-sensitive mutations, and the org-of-one fallback remains available. Recovery preserves code-specific actions and exact rejected fields; retry unchanged only when safe_to_retry is true.

Integration surfaces — pick one

Run402 ships four wrappers around the same HTTP API. Pick the one matching your runtime; they all share the same kernel and credential store.

Surface	Use when…	Reference
@run402/sdk ⭐ recommended	You're authoring TypeScript / JavaScript code (server, edge, sandbox, code-mode agent). Typed every method. The kernel everything else wraps.	https://docs.run402.com/llms-sdk.txt
run402 CLI	You're a shell-based / scripted agent. JSON in, JSON out, exit code on failure. Also the GitHub Actions OIDC setup path (run402 ci link github).	https://docs.run402.com/llms-cli.txt
run402-mcp	You're an MCP-host agent (Claude Desktop, Cursor, Cline, Claude Code) — the tools land in your context automatically.	https://docs.run402.com/llms-mcp.txt
Remote MCP (no install)	You can attach a streamable-http MCP server and want free discovery tools first (quickstart, x402 price check, live experiment scoreboard). Never handles funds — paid tools need run402-mcp locally.	https://mcp.run402.com/mcp
HTTP API (raw)	You're in a language without an SDK or doing low-level work.	https://run402.com/llms-full.txt

The CLI and MCP are thin shims over the SDK. Each subcommand and each MCP tool is an argv/schema-parsing wrapper around an SDK method. If you're already in TypeScript, prefer the SDK directly — fewer process boundaries, typed errors, identical behavior.

A fifth distribution — the OpenClaw skill — is a script-based wrapper that re-exports from the CLI. Pick this only if you're inside the OpenClaw runtime.

Pricing summary

Tier	Cost	Lease	Storage	API calls	Functions
Prototype	FREE (testnet USDC)	7 days	250 MB	500K	5
Hobby	$5	30 days	1 GB	5M	25
Team	$20	30 days	10 GB	50M	100

Add-ons:

• Image generation — $0.03/image via x402
• Email pack — $5 / 10,000 emails (never expire; require a verified custom sender domain)
• KMS signer — $0.04/day rental + $0.000005/call sign fee. Chain gas at-cost, 0% markup. $1.20 prepay required at creation (30 days of rent).

Sites, subdomains, custom domains, function deploys, blob storage, secret management, mailbox creation, app forking — all free with active tier. Only image generation and per-call paid surfaces (image, contract calls) are metered separately.

30-second start

For agents that already have a wallet allowance funded:

npm install -g run402
      run402 up --name my-app -y                 # bootstrap/link/deploy run402.deploy.json or app.json
      run402 subdomains claim my-app             # → https://my-app.run402.com
      

That's a real Postgres database + a deployed static site, paid for autonomously with testnet USDC. Now read your surface's reference (llms-sdk.txt / llms-cli.txt / llms-mcp.txt) for everything else.

If you have no wallet yet

You need a wallet with USDC on Base (real or testnet) to pay Run402. Three paths:

• Coinbase AgentKit — MPC wallet on Base with built-in x402 support (npm create onchain-agent@latest).

• AgentPayy — auto-bootstraps an MPC wallet on Base via Coinbase CDP.

• Generate one yourself with viem:

  npm install viem
        

  import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
        const privateKey = generatePrivateKey();
        const account = privateKeyToAccount(privateKey);
        // SAVE the private key securely. Then `run402 init` reads it.
        

For testnet, run402 allowance fund requests 0.25 USDC from the Base Sepolia faucet — enough for two prototype tier subscriptions.

Two payment rails — same wallet key

• x402 (default): USDC on Base. Standard HTTP 402 protocol.
• MPP: pathUSD on Tempo Moderato (testnet) / Tempo (mainnet). Stripe's Machine Payments Protocol.

The same wallet key works on both chains; switching rails just changes which chain pays. Initialize MPP with run402 init mpp instead of run402 init.

Talk to us

run402 feedback send "your message here"
      

Free with active tier. The team reads every message. Or email tal+402@kychee.com, or follow @run402com.

Where to go next

• Building in TypeScript? → https://docs.run402.com/llms-sdk.txt
• Shell / CI / GitHub Actions / scripted agent? → https://docs.run402.com/llms-cli.txt
• Claude Desktop / Cursor / Cline / Claude Code? → https://docs.run402.com/llms-mcp.txt
• Direct HTTP? → https://run402.com/llms-full.txt
• Latest changes? → https://run402.com/updates.txt
• Reading the source, filing an issue, or checking how a client surface really behaves? → https://github.com/kychee-com/run402 — MIT, the agent surfaces: SDK, CLI, MCP server, functions runtime, skills
• Self-hosting, or verifying the server/runtime you depend on? → https://github.com/kychee-com/run402-core — Apache-2.0, the open core: Postgres/PostgREST with RLS, storage, routing, functions, portable project archives