run402

Category: Databases & Storage | Uploader: kychee-com | Downloads: 0 | Version: v1.0（Latest）

Provision and manage AI-native Postgres databases with REST API, auth, storage, and row-level security. Pay with x402 USDC micropayments on Base.

Changelog: Source: GitHub https://github.com/kychee-com/run402

Directory Structure

Current level: Root

📁 .claude/
- 📁 commands/
  - 📄 publish.md 1.6 KB
📁 .github/
- 📁 workflows/
  - 📄 codeql.yml 401 B
  - 📄 test.yml 498 B
- 📄 logo.svg 1.1 KB
📁 cli/
- 📁 lib/
  - 📄 agent.mjs 2.6 KB
  - 📄 apps.mjs 8.4 KB
  - 📄 config.mjs 1.5 KB
  - 📄 deploy.mjs 3.9 KB
  - 📄 functions.mjs 6.5 KB
  - 📄 image.mjs 3.5 KB
  - 📄 message.mjs 2.0 KB
  - 📄 projects.mjs 8.7 KB
  - 📄 secrets.mjs 2.5 KB
  - 📄 sites.mjs 4.5 KB
  - 📄 storage.mjs 3.9 KB
  - 📄 subdomains.mjs 3.0 KB
  - 📄 wallet.mjs 7.5 KB
- 📄 cli.mjs 3.2 KB
- 📄 package-lock.json 21.1 KB
- 📄 package.json 715 B
- 📄 README.md 2.6 KB
📁 openclaw/
- 📁 scripts/
  - 📄 agent.mjs 2.4 KB
  - 📄 apps.mjs 7.5 KB
  - 📄 config.mjs 1.3 KB
  - 📄 deploy.mjs 3.1 KB
  - 📄 functions.mjs 6.0 KB
  - 📄 image.mjs 3.1 KB
  - 📄 message.mjs 1.9 KB
  - 📄 package-lock.json 20.9 KB
  - 📄 package.json 346 B
  - 📄 projects.mjs 7.6 KB
  - 📄 secrets.mjs 2.1 KB
  - 📄 sites.mjs 3.4 KB
  - 📄 storage.mjs 3.4 KB
  - 📄 subdomains.mjs 2.6 KB
  - 📄 wallet.mjs 6.1 KB
- 📄 README.md 2.3 KB
- 📄 SKILL.md 19.2 KB
📁 src/
- 📁 tools/
  - 📄 archive-project.ts 1.1 KB
  - 📄 billing-history.ts 1.7 KB
  - 📄 browse-apps.ts 1.7 KB
  - 📄 bundle-deploy.ts 4.7 KB
  - 📄 check-balance.test.ts 2.5 KB
  - 📄 check-balance.ts 1.4 KB
  - 📄 create-checkout.ts 1.2 KB
  - 📄 delete-file.ts 1.1 KB
  - 📄 delete-function.ts 1.1 KB
  - 📄 delete-secret.ts 1.0 KB
  - 📄 delete-version.ts 998 B
  - 📄 deploy-function.test.ts 4.0 KB
  - 📄 deploy-function.ts 2.7 KB
  - 📄 deploy-site.ts 3.0 KB
  - 📄 download-file.ts 1.2 KB
  - 📄 fork-app.ts 2.9 KB
  - 📄 generate-image.ts 2.0 KB
  - 📄 get-app.ts 1.8 KB
  - 📄 get-deployment.ts 1.2 KB
  - 📄 get-function-logs.test.ts 3.0 KB
  - 📄 get-function-logs.ts 1.7 KB
  - 📄 get-quote.ts 1.1 KB
  - 📄 get-schema.ts 2.4 KB
  - 📄 get-usage.ts 1.9 KB
  - 📄 invoke-function.test.ts 3.3 KB
  - 📄 invoke-function.ts 2.2 KB
  - 📄 list-files.ts 1.6 KB
  - 📄 list-functions.ts 1.6 KB
  - 📄 list-projects.ts 1.5 KB
  - 📄 list-secrets.ts 1.3 KB
  - 📄 list-subdomains.ts 1.4 KB
  - 📄 list-versions.ts 1.7 KB
  - 📄 provision.test.ts 4.0 KB
  - 📄 provision.ts 2.6 KB
  - 📄 publish-app.ts 2.3 KB
  - 📄 renew.test.ts 2.6 KB
  - 📄 renew.ts 2.1 KB
  - 📄 request-faucet.ts 2.2 KB
  - 📄 rest-query.test.ts 4.8 KB
  - 📄 rest-query.ts 2.3 KB
  - 📄 run-sql.test.ts 4.5 KB
  - 📄 run-sql.ts 1.7 KB
  - 📄 send-message.ts 844 B
  - 📄 set-agent-contact.ts 1.5 KB
  - 📄 set-secret.test.ts 3.0 KB
  - 📄 set-secret.ts 1.3 KB
  - 📄 setup-rls.ts 1.9 KB
  - 📄 subdomain.test.ts 6.6 KB
  - 📄 subdomain.ts 3.0 KB
  - 📄 update-version.ts 1.7 KB
  - 📄 upload-file.test.ts 3.3 KB
  - 📄 upload-file.ts 1.5 KB
  - 📄 wallet-create.ts 2.3 KB
  - 📄 wallet-export.ts 932 B
  - 📄 wallet-status.ts 1.1 KB
- 📄 client.test.ts 6.0 KB
- 📄 client.ts 1.5 KB
- 📄 config.ts 480 B
- 📄 errors.test.ts 4.5 KB
- 📄 errors.ts 3.2 KB
- 📄 index.ts 15.6 KB
- 📄 keystore.test.ts 3.7 KB
- 📄 keystore.ts 1.5 KB
📄 .gitignore 26 B
📄 CLAUDE.md 4.7 KB
📄 Dockerfile 332 B
📄 LICENSE 1.0 KB
📄 package-lock.json 57.4 KB
📄 package.json 1.4 KB
📄 README.md 6.7 KB
📄 README.zh-CN.md 4.8 KB
📄 SECURITY.md 1.6 KB
📄 SKILL.md 15.0 KB
📄 SKILL.test.ts 4.0 KB
📄 sync.test.ts 24.9 KB
📄 tsconfig.json 396 B

SKILL.md

---
name: run402
description: Provision and manage AI-native Postgres databases with REST API, auth, storage, and row-level security. Pay with x402 USDC micropayments on Base.
metadata:
  openclaw:
    emoji: "🐘"
    homepage: https://run402.com
    requires:
      bins:
        - npx
    install:
      - kind: node
        package: "run402-mcp"
        bins: [run402-mcp]
    primaryEnv: RUN402_API_BASE
---

# Run402 — Postgres for AI Agents

Run402 gives you a full Postgres database with a REST API, user auth, file storage, and row-level security. You pay with a single x402 micropayment on Base — no signups, no dashboards, no human approval needed.

One tool call. One payment. You get back `anon_key`, `service_key`, and a project ID. Start creating tables immediately.

## Tools Reference

You have 10 tools available through the `run402-mcp` server.

### provision_postgres_project

Provision a new Postgres database. Handles x402 payment negotiation. Saves credentials locally.

**Parameters:**
- `tier` (optional, default: `"prototype"`) — `"prototype"` ($0.10, 7 days), `"hobby"` ($5, 30 days), or `"team"` ($20, 30 days)
- `name` (optional) — Human-readable project name. Auto-generated if omitted.

**Returns on success:**
```json
{
  "project_id": "prj_1709312520_0001",
  "anon_key": "eyJ...",
  "service_key": "eyJ...",
  "tier": "prototype",
  "schema_slot": "p0001",
  "lease_expires_at": "2026-03-06T14:22:00.000Z"
}
```

**Returns on 402 (payment required):** Payment details as informational text (not an error). Guide the user through payment, then retry.

Credentials are saved automatically to `~/.config/run402/projects.json`. You never need to pass keys manually after provisioning.

### run_sql

Execute SQL statements (DDL or queries) against a project's database.

**Parameters:**
- `project_id` (required) — Project ID from provisioning
- `sql` (required) — SQL statement to execute

**Returns:** Markdown-formatted table with results, row count, and schema name.

**Examples:**
```
run_sql(project_id: "prj_...", sql: "CREATE TABLE todos (id serial PRIMARY KEY, task text NOT NULL, done boolean DEFAULT false, user_id uuid)")
run_sql(project_id: "prj_...", sql: "SELECT * FROM todos WHERE done = false")
```

Uses the stored `service_key` automatically. Both `SERIAL` and `BIGINT GENERATED ALWAYS AS IDENTITY` work for auto-increment columns.

### rest_query

Query or mutate data via the PostgREST REST API.

**Parameters:**
- `project_id` (required) — Project ID
- `table` (required) — Table name to query
- `method` (optional, default: `"GET"`) — `"GET"`, `"POST"`, `"PATCH"`, or `"DELETE"`
- `params` (optional) — PostgREST query params: `{ select: "id,name", order: "id.asc", limit: "10", done: "eq.false" }`
- `body` (optional) — Request body for POST/PATCH
- `key_type` (optional, default: `"anon"`) — `"anon"` (respects RLS) or `"service"` (bypasses RLS)

**Returns:** HTTP status code and JSON response body.

**Examples:**
```
rest_query(project_id: "prj_...", table: "todos", params: { done: "eq.false", order: "id" })
rest_query(project_id: "prj_...", table: "todos", method: "POST", body: { task: "Build something", done: false }, key_type: "service")
rest_query(project_id: "prj_...", table: "todos", method: "PATCH", params: { id: "eq.1" }, body: { done: true }, key_type: "service")
rest_query(project_id: "prj_...", table: "todos", method: "DELETE", params: { id: "eq.1" }, key_type: "service")
```

Use `key_type: "anon"` for user-facing reads. Use `key_type: "service"` for admin writes or when RLS would block access.

### upload_file

Upload text content to project storage (S3-backed).

**Parameters:**
- `project_id` (required) — Project ID
- `bucket` (required) — Storage bucket name (e.g., `"assets"`)
- `path` (required) — File path within bucket (e.g., `"logs/2024-01-01.txt"`)
- `content` (required) — Text content to upload
- `content_type` (optional, default: `"text/plain"`) — MIME type

**Returns:** `{ key: "assets/logs/2024-01-01.txt", size: 1234 }` with the stored file path and size in bytes.

**Example:**
```
upload_file(project_id: "prj_...", bucket: "assets", path: "data.csv", content: "name,age\nAlice,30\nBob,25")
```

Uses the stored `anon_key` automatically.

### renew_project

Renew a project's lease before it expires.

**Parameters:**
- `project_id` (required) — Project ID to renew
- `tier` (optional) — Renewal tier. Defaults to the project's current tier.

**Returns on success:** Renewal confirmation with new `lease_expires_at` timestamp.

**Returns on 402 (payment required):** Payment details as informational text (not an error). Guide the user through payment, then retry.

Updates the local keystore with the new expiry date.

### deploy_site

Deploy a static site (HTML/CSS/JS/images). Files are uploaded to S3 and served via CloudFront at a unique URL.

**Parameters:**
- `name` (required) — Site name (e.g. `"family-todo"`, `"portfolio"`)
- `project` (optional) — Project ID to link this deployment to an existing Run402 project
- `target` (optional) — Deployment target (e.g. `"production"`)
- `files` (required) — Array of files to deploy:
  - `file` — File path (e.g. `"index.html"`, `"assets/logo.png"`)
  - `data` — File content (text or base64-encoded)
  - `encoding` (optional) — `"utf-8"` (default) for text, `"base64"` for binary files

**Returns on success:**
```json
{
  "id": "dpl_1709337600000_a1b2c3",
  "name": "family-todo",
  "url": "https://dpl-1709337600000-a1b2c3.sites.run402.com",
  "status": "READY",
  "files_count": 3,
  "total_size": 4096
}
```

**Returns on 402 (payment required):** Payment details as informational text (not an error). Costs $0.05 USDC per deployment.

**Examples:**
```
deploy_site(name: "my-app", files: [
  { file: "index.html", data: "<!DOCTYPE html><html>..." },
  { file: "style.css", data: "body { margin: 0; }" },
  { file: "app.js", data: "console.log('hello');" }
])
```

SPA fallback: paths without file extensions (e.g. `/about`) serve `index.html`. Static assets are served with correct Content-Type headers. Max 50 MB per deployment.

### deploy_function

Deploy a serverless function (Node 22) to a project. Functions are invoked via HTTP at `/functions/v1/:name`.

**Parameters:**
- `project_id` (required) — Project ID
- `name` (required) — Function name (URL-safe slug: lowercase, hyphens, alphanumeric)
- `code` (required) — TypeScript or JavaScript source code. Handler: `export default async (req: Request) => Response`
- `config` (optional) — `{ timeout?: number, memory?: number }` — Timeout (seconds) and memory (MB), capped by tier
- `deps` (optional) — Array of npm package names to install alongside pre-bundled packages

**Returns on success:**
```json
{
  "name": "stripe-webhook",
  "url": "https://api.run402.com/functions/v1/stripe-webhook",
  "status": "deployed",
  "runtime": "node22",
  "timeout": 10,
  "memory": 128
}
```

**Pre-bundled packages:** stripe, openai, @anthropic-ai/sdk, resend, zod, uuid, jsonwebtoken, bcryptjs, cheerio, csv-parse.

**DB access inside functions:**
```typescript
import { db } from '@run402/functions';
const users = await db.from('users').select('*');
const result = await db.sql('SELECT count(*) FROM orders');
```

**Secrets:** Access via `process.env.SECRET_NAME`. Set with `set_secret`.

### invoke_function

Invoke a deployed function via HTTP. Useful for testing without building a frontend.

**Parameters:**
- `project_id` (required) — Project ID
- `name` (required) — Function name
- `method` (optional, default: `"POST"`) — HTTP method
- `body` (optional) — Request body (string or JSON object)
- `headers` (optional) — Additional headers to send

**Returns:** Status code, duration, and response body.

### get_function_logs

Get recent logs from a deployed function (console.log/error output and error stack traces).

**Parameters:**
- `project_id` (required) — Project ID
- `name` (required) — Function name
- `tail` (optional, default: 50) — Number of log lines to return (max 200)

**Returns:** Timestamped log entries from CloudWatch.

### set_secret

Set a project secret. Secrets are injected as `process.env` variables in all functions.

**Parameters:**
- `project_id` (required) — Project ID
- `key` (required) — Secret key (uppercase alphanumeric + underscores, e.g. `"STRIPE_SECRET_KEY"`)
- `value` (required) — Secret value

Setting an existing key overwrites it. All project functions are automatically updated with new env vars.

**Example:**
```
set_secret(project_id: "prj_...", key: "STRIPE_SECRET_KEY", value: "sk_live_...")
```

## Standard Workflow

Follow this sequence to go from zero to a working database:

### Step 1: Provision a database

```
provision_postgres_project(tier: "prototype")
```

If the user hasn't paid yet, you'll get payment details back. Explain the cost and guide them through payment. Once paid, retry and you'll get project credentials.

### Step 2: Create tables

```
run_sql(project_id: "prj_...", sql: "CREATE TABLE todos (id serial PRIMARY KEY, task text NOT NULL, done boolean DEFAULT false, user_id uuid)")
```

Design tables based on what the user needs. Add `user_id uuid` columns if you plan to use row-level security.

### Step 3: Enable row-level security (optional)

Use `run_sql` to apply RLS if users should only see their own rows:

```
run_sql(project_id: "prj_...", sql: "-- Use the /projects/v1/admin/:id/rls endpoint via HTTP for RLS templates")
```

Three RLS templates are available via the API:
- **`user_owns_rows`** — Users can only access rows where `owner_column = auth.uid()`. Best for user-scoped data.
- **`public_read`** — Anyone can read. Only authenticated users can write.
- **`public_read_write`** — Anyone can read and write. Use for guestbooks, public logs.

### Step 4: Insert data

```
rest_query(project_id: "prj_...", table: "todos", method: "POST", body: { task: "Build something great", done: false }, key_type: "service")
```

Use `key_type: "service"` for admin/seed writes. Use `key_type: "anon"` only when you want RLS to apply.

### Step 5: Query data

```
rest_query(project_id: "prj_...", table: "todos", params: { done: "eq.false", order: "id" })
```

PostgREST query syntax: `column=eq.value`, `column=gt.5`, `column=like.*search*`, `order=column.asc`, `limit=10`, `offset=0`, `select=id,name`.

### Step 6: Set up user auth (optional)

If your app has users, use the HTTP auth endpoints directly:
- `POST /auth/v1/signup` with `apikey` header — create a user
- `POST /auth/v1/token` with `apikey` header — login, get `access_token`
- The `access_token` works as an `apikey` for user-scoped REST queries subject to RLS

### Step 7: Upload files (optional)

```
upload_file(project_id: "prj_...", bucket: "assets", path: "report.csv", content: "col1,col2\nval1,val2")
```

### Step 8: Monitor usage

Use `run_sql` to check project health, or call the usage endpoint via HTTP:
```
run_sql(project_id: "prj_...", sql: "SELECT count(*) FROM todos")
```

## Payment Handling

Run402 uses the x402 HTTP payment protocol. Here's what you need to know:

**When payment is needed:** Only `provision_postgres_project` and `renew_project` require x402 payment. All other tools (run_sql, rest_query, upload_file) use stored project keys — no payment needed.

**What a 402 response looks like:** When payment is required, the tool returns payment details as informational text (not an error). The response includes the price, network (Base L2), and payment address.

**How to handle it:**
1. Explain to the user what the cost is (e.g., "$0.10 for a 7-day prototype database")
2. If the user has a wallet set up, help them complete the payment
3. If not, guide them through wallet setup (see Wallet Setup below)
4. Once payment is complete, retry the same tool call

**Pricing tiers:**
| Tier | Price | Lease | Storage | API Calls | Functions | Timeout | Memory | Secrets |
|------|-------|-------|---------|-----------|-----------|---------|--------|---------|
| Prototype | $0.10 | 7 days | 250 MB | 500,000 | 5 | 10s | 128MB | 10 |
| Hobby | $5.00 | 30 days | 1 GB | 5,000,000 | 25 | 30s | 256MB | 50 |
| Team | $20.00 | 30 days | 10 GB | 50,000,000 | 100 | 60s | 512MB | 200 |

**Budget enforcement:** When a project hits its tier's API call or storage limit, REST/SQL calls return 402 with usage details and a renew URL. Suggest renewing the project at the same or higher tier.

## Tips & Guardrails

**SQL blocklist:** The SQL endpoint blocks dangerous operations: `CREATE EXTENSION`, `COPY ... PROGRAM`, `ALTER SYSTEM`, `SET search_path`, `CREATE/DROP SCHEMA`, `GRANT/REVOKE`, `CREATE/DROP ROLE`. If you hit a 403, check the `hint` field for alternatives.

**No GRANT needed:** Table and sequence permissions are managed automatically. Use RLS templates for access control instead of GRANT/REVOKE.

**Key usage patterns:**
- Use `service_key` (via `run_sql` or `key_type: "service"`) for: table creation, RLS setup, seeding data, admin queries
- Use `anon_key` (via `rest_query` default or `upload_file`) for: user-facing reads, file uploads
- Use `access_token` (from auth login, via HTTP) for: user-scoped CRUD subject to RLS

**Tier selection:**
- **Prototype** ($0.10): Testing, demos, disposable data. Start here.
- **Hobby** ($5): Real applications, persistent data, moderate traffic.
- **Team** ($20): Multi-user apps, heavy traffic, large storage needs.

**Lease lifecycle:**
- Active: full read/write access
- Expired (day 0): read-only for 7 days
- Grace period ends (day 7): archived, no access
- Permanent deletion at day 37 after expiry
- Renew anytime before deletion with `renew_project`

**Schema isolation:** Each project runs in its own Postgres schema. Cross-schema access is blocked.

**Rate limiting:** 100 requests/second per project. Exceeding returns 429 with `retry_after`.

**Idempotency:** When provisioning or renewing, include an `Idempotency-Key` header to prevent double-charging on retries. The MCP tools handle this automatically when possible.

## Wallet Setup

To pay Run402, the user needs a crypto wallet with USDC on Base. If they don't have one yet, here are the options:

**Option A: Coinbase AgentKit (recommended)** — Gives you a wallet on Base with built-in x402 support. No KYC, no manual key management.

**Option B: AgentPayy** — Auto-bootstraps an MPC wallet on Base using Coinbase CDP. Purpose-built for x402.

**Option C: x402 OpenClaw Skill** — Install the x402 skill from ClawHub for x402 payment capabilities.

**Funding the wallet:** Once the user has a wallet address, they need USDC on Base. The simplest path: download Coinbase Wallet, buy USDC, send to the wallet address. Base transactions cost under $0.01.

**Testnet:** For testing without real money, use Base Sepolia testnet. Get test USDC from Circle's faucet. The Run402 API supports testnet at the same endpoints.

**Asking for an allowance:** If the user's human controls the wallet funding, suggest:
- Trial: $1 in USDC covers 10 prototype databases
- Monthly: $10/month covers two Hobby projects or 100 prototypes
- One-off: $10 for a project plus buffer for renewals

## Links

- **Full API docs:** https://run402.com/llms.txt
- **API health:** https://api.run402.com/health
- **MCP package:** https://www.npmjs.com/package/run402-mcp
- **Homepage:** https://run402.com

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

run402

Directory Structure

SKILL.md

Report

Notice