# 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 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 fully provision, operate, and pay for **on its own**. No human signup, no API keys to copy out of a web dashboard, no human in the payment loop:

- **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
- **Node 22 serverless functions** with cron scheduling 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 contract wallets where private keys never leave AWS KMS

**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, no human approval. 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 — agents as first-class customers

Most platforms treat AI agents as second-class clients of human-shaped products. Run402 inverts this: the platform is shaped *for* agents.

- **Autonomous payment.** x402 (the HTTP 402 micropayment protocol) lets an agent settle a bill directly from its allowance without asking a human to click through a 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.** `bundle_deploy` / `r.deploy.apply` takes a single `ReleaseSpec` and converges the project (database + manifest + secrets + functions + site + subdomain) toward it; surgical patches and full replaces are first-class.
- **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-originated 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.

## 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://run402.com/llms-sdk.txt> |
| **`run402` CLI** | You're a shell-based / scripted agent. JSON in, JSON out, exit code on failure. | <https://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://run402.com/llms-mcp.txt> |
| **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 just 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 contract wallet** — $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:

```bash
npm install -g run402
run402 init                                # one-shot: allowance + faucet + tier check
run402 tier set prototype                  # FREE on testnet (verifies x402 setup)
run402 projects provision --name my-app    # → anon_key, service_key, project_id
run402 sites deploy-dir ./dist             # incremental upload (plan/commit transport)
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`**:

  ```bash
  npm install viem
  ```

  ```typescript
  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

```bash
run402 message 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://run402.com/llms-sdk.txt>
- Shell / CI / scripted agent? → <https://run402.com/llms-cli.txt>
- Claude Desktop / Cursor / Cline / Claude Code? → <https://run402.com/llms-mcp.txt>
- Direct HTTP? → <https://run402.com/llms-full.txt>
- Latest changes? → <https://run402.com/updates.txt>