Provision a new Postgres database. Returns project credentials on success, or payment details if x402 payment is needed.

Execute SQL (DDL or queries) against a provisioned project. Returns results as a markdown table.

Query or mutate data via the PostgREST REST API. Supports GET/POST/PATCH/DELETE with query params.

Apply a declarative authorization manifest to a project (POST /projects/v1/admin/:id/expose). The manifest describes the full authorization surface: tables (with policy, owner_column, force_owner_on_insert, i_understand_this_is_unrestricted, custom_sql), views (with base, select, filter), and rpcs (with signature, grant_to). Convergent: applying the same manifest twice is a no-op; items dropped between applies have their policies/grants/triggers/views revoked. Tables are dark by default — any table not declared with expose:true is unreachable via anon/authenticated.

Validate an auth/expose manifest without applying it. This checks the authorization manifest used by manifest.json, database.expose, and apply_expose; it is not deploy-manifest validation. Optional migration_sql is reference context only and is not executed. Use deploy planning/dry-run surfaces for deploy manifest questions.

Get the current authorization manifest for a project (GET /projects/v1/admin/:id/expose). Returns the last-applied manifest from internal.project_manifest, or a manifest reconstructed by introspecting live DB state if none has ever been applied. The source field is "applied" or "introspected".

Introspect the database schema — tables, columns, types, constraints, and RLS policies. Useful for understanding the database structure before writing queries.

Get project usage report — API calls, storage usage, limits, and lease expiry.

Upload a blob (file or inline content) to project storage via direct-to-S3. Accepts local_path (any size up to 5 TiB) or content (≤ 1 MB inline). Public blobs get a CDN URL; private blobs require authenticated reads. Use immutable: true to produce a content-addressed URL that never needs cache invalidation. For image uploads (jpeg/png/webp/heic/heif), the gateway also returns width_px/height_px/blurhash/display_url and a variants map (thumb 320w, medium 800w, large 1920w WebP — plus display_jpeg for HEIC sources) so apps can render responsive thumbnails without re-encoding client-side. See the SDK docs for the full AssetRef shape.

Download a blob to a local file path. Writes bytes directly to disk (no context-window bloat). Returns size + SHA-256 header (if the blob has one stored).

List blobs in a project with optional prefix filter over a flat key namespace. Supports pagination via cursor.

Delete a blob from project storage and decrement the project's storage_bytes.

Generate a time-boxed S3 presigned GET URL for a blob. Use this to share a private blob externally without exposing your apikey. Default TTL 1 hour, max 7 days.

Returns the live CDN state for a public blob URL (probed once from gateway-us-east-1 — NOT a global view). Use this when a deployed asset shows the wrong version or you suspect cache staleness. The result includes expectedSha256 (from gateway DB), observedSha256 (what CloudFront just served), recent invalidation status, and a human-readable hint with actionable next-steps. The probeMayHaveWarmedCache: true field warns that the probe itself populates the cache, so subsequent reads from elsewhere may differ. URLs outside the requesting project return 403; non-*.run402.com URLs return 400 unless they're on one of your active custom domains.

Polls the CDN until a MUTABLE blob URL serves the expected SHA-256, or the timeout elapses. For mutable URLs only — for immutable URLs (the immutableUrl returned by assets_put), no waiting is needed; they're bound to a SHA at upload time and never previously cached. Use this after a re-upload to an existing public mutable key when an end-user-visible URL must reflect the new content before continuing. The probe is single-vantage (us-east-1). On timeout, the tool returns isError=true so an agent can branch into a fallback — typically: switch to the immutableUrl.

Deploy a serverless function (Node 22) to a project. Handler signature: export default async (req: Request) => Response. The function can import { db, adminDb, auth, email, ai } from '@run402/functions' — auto-bundled by the platform. Additional npm packages are bundled at deploy time when listed in deps (bare names resolve to latest; pinned/range specs are honored verbatim; @run402/functions and run402-functions rejected; max 30 entries; native binaries rejected). The response includes runtime_version (the bundled @run402/functions version — surface as 'Functions runtime version', never bare 'runtime'), deps_resolved (map of dep name → installed concrete version), and an optional top-level warnings array (sibling to the function record).

Invoke a deployed function via HTTP. Returns the function's response body and status code. Useful for testing functions without building a frontend.

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

List all deployed functions for a project. Shows names, URLs, runtime, timeout, memory, and (for functions deployed under bundling-at-deploy) the Functions runtime version (@run402/functions version) and resolved direct deps. Functions deployed before that change have runtime_version and deps_resolved set to null.

Delete a deployed function from a project.

Update a function's schedule, timeout, or memory without re-deploying code. Pass schedule as a cron expression to set/update, or null to remove.

Refresh function(s) onto the platform's current entry wrapper + bundled runtime WITHOUT changing source (capability function-runtime-rebuild, gateway v1.69+). Provide name to rebuild one function, or omit it to rebuild every function in the project. Re-bundles from each function's STORED source with deps pinned to the recorded exact versions, so the source code_hash is unchanged and no new release is created — this is how a gateway-side wrapper fix (e.g. an SSR auth.* fix) reaches an already-deployed function (a plain redeploy with unchanged source does NOT pick it up). Strictly opt-in; the platform never auto-rebuilds. Wallet-authed (project ownership; no service key) and allowed during billing grace. Functions deployed before dependency locking return CANNOT_REBUILD_UNLOCKED_DEPS — redeploy them from source with deploy_function. Use list_functions (runtime_stale) or run402 doctor to find stale functions.

Set a project secret (e.g. STRIPE_SECRET_KEY). Values are write-only and injected as process.env variables in functions. Setting an existing key overwrites it. Use this before deploy, then declare the key with secrets.require.

List secret keys for a project. Values and value-derived hashes are never shown; use this only to check which keys are configured.

Delete a secret from a project.

Submit a fixed platform-managed job. The request must match the gateway jobs API shape: job_type, input with input.json, and max_cost_usd_micros. The SDK supplies the required idempotency header.

Get a managed job run by id.

Read recent runner logs for a managed job. Use tail to cap entries and since for an epoch millisecond lower bound.

Cancel a queued or running managed job.

Download a completed managed job's artifact by filename (e.g. proof.json, public.json, prove-output.log) to a local file. Discover the recorded filenames from the artifacts map returned by jobs_get; the legacy run402:// refs were retired in favor of these gateway URLs.

Deploy a static site (HTML/CSS/JS) from inline file bytes. Files are staged to a temp directory, then uploaded via the v1.32 plan/commit transport — only bytes the gateway doesn't already have are PUT. Served at a unique URL via CloudFront. Free with active tier.

Deploy a static site from a local directory. Walks the tree, hashes each file, and uploads only the bytes the gateway doesn't already have via the v1.32 plan/commit transport. Files named .git, node_modules, or .DS_Store are skipped; symlinks are rejected. Re-deploying an unchanged tree issues no S3 PUTs. Free with active tier.

Unified deploy primitive (v1.34+). Accepts a structured ReleaseSpec — database (migrations + expose), value-free secrets.require/delete declarations, functions, site, site.public_paths, subdomains, and routes.replace web routes — with explicit replace vs patch semantics per resource. Use site.public_paths for clean static URLs such as /events backed by release asset events.html; explicit mode does not expose /events.html unless separately declared, while mode: 'implicit' restores filename-derived reachability and can widen access. Route entries map exact/final-wildcard browser paths like /admin and /admin/* to Node 22 Fetch Request -> Response functions, or exact GET/HEAD method-aware static aliases such as /events to { type: 'static', file: 'events.html' }; intentional read-only GET/HEAD wildcard function routes may set acknowledge_readonly: true. Direct /functions/v1/:name remains API-key protected. Secret values must be set first with set_secret, never placed in deploy specs. All bytes ride through CAS (no inline-body cap). Returns release_id, URLs, warnings, and a structured progress-event log. Stops before upload/commit on confirmation-required warnings unless reviewed codes are passed with allow_warning_codes or allow_warnings is true.

Read-only authenticated diagnostics for a Run402 public URL or host/path pair. Explains whether the current live release would serve the URL, including match, diagnostic body status, static manifest/cache metadata when returned, structured warnings for ignored query/fragment, and next steps. This does not fetch bytes, purge cache, mutate deploy state, or expose internal CAS URLs.

Resume a deploy operation that ended in activation_pending or schema_settling (e.g. transient gateway failure between SQL commit and the pointer-swap activation). The gateway re-runs only the failed phase forward — SQL is never replayed. Idempotent: calling on an already-terminal operation returns the snapshot without re-running.

List recent deploy operations for a project. Returns operation_id, status, release_id, and timestamps. Use this to build deploy-history UIs or to find a recent operation_id to feed into deploy_resume / deploy_events. Pass limit to bound the result set; the gateway also returns a cursor for pagination when there are more.

Fetch the recorded phase-event stream for a deploy operation. Returns the same DeployEvent shapes the deploy tool emits inline during an in-flight deploy — useful for inspecting a deploy after the fact (e.g., a deploy that the agent didn't observe directly, or one being resumed from a different process).

Fetch a release inventory by id. Returns release metadata, effective/desired state kind, site path inventory, function inventory, secret keys, subdomains, and applied migrations. Use site_limit to cap large site inventories. Canonical SDK errors are preserved.

Fetch the current-live release inventory for a project. Returns release_id: null with an empty current-live inventory when no release is active yet. Use this before deploy diffs to understand what is currently serving. Canonical SDK errors are preserved.

Diff two release targets for a project. from may be empty, active, or a release id; to may be active or a release id. Returns release-to-release diff buckets and migrations.applied_between_releases. Semantic gateway errors such as invalid targets, same-release diffs, or no active release are preserved.

Create a GitHub Actions CI/OIDC deploy binding by sending a locally signed delegation to the SDK. This MCP wrapper does not sign or broaden authority; the signed delegation defines the repository/branch or environment, allowed events/actions, and optional route_scopes. Without route_scopes, CI cannot deploy route declarations.

List CI/OIDC deploy bindings for a project, including route_scopes when delegated. Use this to inspect which GitHub Actions subjects can deploy before editing bindings.

Get one CI/OIDC deploy binding by id, including its subject, allowed events/actions, repository id, revocation state, and route_scopes.

Revoke one CI/OIDC deploy binding. Revocation stops future CI gateway requests, but does not undo already deployed releases or rotate secrets.

Claim a custom subdomain (e.g. myapp.run402.com) and point it at an existing deployment. Free, requires service_key auth.

Release a custom subdomain. The URL will stop serving content.

List all subdomains claimed by a project.

Register a custom domain (e.g. example.com) to point at a Run402 subdomain. Returns DNS instructions for the human to configure.

List all custom domains registered for a project.

Check if a custom domain's DNS is configured and SSL is active. Poll this after registering a domain.

Release a custom domain mapping. Traffic to the domain will no longer route to Run402.

Browse public apps available for forking. Optionally filter by tags.

Fork a published app into a new project. Creates a full copy including database, functions, site, and optionally claims a subdomain.

Publish a project as a forkable app. Set visibility and tags for discoverability.

List published versions of a project.

Get tier pricing for Run402 projects. Free, no auth required. Shows prices, lease durations, storage limits, and API call limits.

Check current tier subscription — tier name, status, expiry, usage, and function authoring caps when returned (max timeout, memory, scheduled functions, min cron interval). Requires allowance auth.

Subscribe, renew, or upgrade tier. Auto-detects action based on allowance state. Returns success or payment details if x402 payment is needed.

Immediately and irreversibly delete a project: the gateway runs the full destructive cascade (drop tenant schema, delete Lambda functions, release subdomains, tombstone mailbox, remove sender domain, wipe secrets and app versions) and sets status=purged. This tool also removes the project from the local key store. Distinct from the automatic lease-expiry grace window — this action is the explicit purge and cannot be undone. To recover from a missed renewal use set_tier instead.

Rename a project (PATCH /projects/v1/:id) — fix an auto-generated name. Authorization is org-membership based (admin+ on the owning org, or a project:write grant) and authorize-before-reveal: an unauthorized or guessed id returns the same 403 as a real-but-unauthorized project, never a not-found oracle. Uses the wallet's SIWX auth (not a project service key), so it works even if the project isn't in the local key store. The server validates the name (non-empty, ≤ 200 chars, no control characters).

Toggle a billing account's lease_perpetual escape hatch (v1.57+). When lease_perpetual: true, the account never advances past active regardless of lease expiry; every project on the account inherits the pinned state. Enabling on a grace-state account (past_due / frozen / dormant) reactivates inline and returns reactivated: true. Platform-admin only — uses the configured allowance wallet for admin auth. Replaces the v1.56 pin_project (gateway endpoint /projects/v1/admin/:id/pin was removed in v1.57). Calls POST /billing/v1/admin/accounts/:account_id/lease-perpetual.

Operator moderation action — archive a single project (sets projects.archived_at = NOW()). Independent of account-level lifecycle: sibling projects on the same billing account keep serving. No-op when the project is already archived. Platform-admin only. Calls POST /projects/v1/admin/:id/archive.

Operator un-archive — flips projects.archived_at back to NULL. In v1.57 this was narrowed: it no longer touches account-level lifecycle. To reactivate a grace-state account, subscribe a tier (tier_set) or enable lease-perpetual (admin_set_lease_perpetual). Platform-admin only. Calls POST /projects/v1/admin/:id/reactivate.

Initiate a two-party project transfer (v1.59+). You must currently own the project (gateway verifies against fresh DB state). Creates a pending row with 72h expiry and freezes owner-side mutations on the project until accepted, cancelled, or expired. The recipient gets the project under the migrate billing policy (project moves into their billing account). Owner's tier lease is NOT refunded. GitHub repo ownership is NOT transferred. Calls POST /projects/v1/:project_id/transfers.

Fetch the preview document for a project transfer (v1.59+). Returns the safe review payload: project name, custom domains, subdomains, function names, secret NAMES (values are never returned), CI bindings that will be revoked at accept, mailbox summary, billing implications. Caller must be either the from_wallet or the to_wallet. Calls GET /agent/v1/transfers/:transfer_id.

Accept an incoming project transfer (v1.59+). Your wallet must equal the transfer's to_wallet. The accept transaction atomically: (a) flips ownership to your wallet, (b) revokes the previous owner's CI bindings on the project, (c) enqueues notifications to both parties, (d) stamps a persistent secrets_rotation_advised advisory. Secret VALUES are inherited (rotation strongly advised via set_secret for each name). GitHub repo ownership is NOT part of the transfer. Calls POST /agent/v1/transfers/:transfer_id/accept.

Cancel a pending project transfer (v1.59+). Either party (from_wallet or to_wallet) may cancel. Already-accepted/cancelled/expired transfers return 409 TRANSFER_ALREADY_PROCESSED. Calls POST /agent/v1/transfers/:transfer_id/cancel.

List pending project transfers OFFERED TO the authenticated wallet (v1.59+). Each entry carries preview_path for deep-linking into the preview tool. Calls GET /agent/v1/transfers/incoming.

List pending project transfers INITIATED BY the authenticated wallet (v1.59+). Each entry carries preview_path for deep-linking into the preview tool. Calls GET /agent/v1/transfers/outgoing.

Promote a user to project_admin role by email. Admins can manage secrets from the browser. Requires service_key.

Demote a user from project_admin role by email. Reverts to default authenticated role. Requires service_key.

Check the billing account balance for the agent's allowance wallet — available and held funds. The wallet is resolved to its billing account over SIWX (signed automatically); reading a wallet that is not linked to yours requires an admin key.

List projects from the named, domain-aware inventory (GET /projects/v1). Membership-scoped by default: every project owned by an org the agent's wallet is an active member of, with name, site_url, custom_domains, org (billing_account_id), and status. SIWX wallet auth is signed automatically. Pass org_id to filter to one org (authorize-before-reveal: non-member/guessed → 403, non-UUID → 400), all:true to read the cross-wallet inventory across every wallet controlling your operator email, or limit/cursor to paginate.

Check local agent allowance status — address, network, and funding status.

Create a new local agent allowance (Base Sepolia testnet). Generates a private key and derives the Ethereum address. Saved to ~/.config/run402/allowance.json.

Export the local agent allowance address. Safe to share publicly.

Request free testnet USDC from the Run402 faucet (Base Sepolia). Rate limit: 1 per IP per 24h. Returns 0.25 USDC — enough for 2 prototype databases.

Generate a PNG image from a text prompt. Costs $0.03 USDC via x402. Aspect ratios: square (1:1), landscape (16:9), portrait (9:16).

Create a project-scoped email mailbox at @mail.run402.com. One mailbox per project.

Send an email from the project's mailbox. Two modes: template (project_invite, magic_link, notification) or raw HTML (subject + html). Optional from_name for display name. Single recipient only.

List sent emails from the project's mailbox. Shows message ID, template, recipient, status, and timestamp.

Get a sent email with details and any replies.

Get the raw RFC-822 bytes of an inbound email message, base64-encoded. The decoded bytes are bit-identical to the DKIM-signed original — no parsing, normalization, or CRLF cleanup. Use this for cryptographic verification (DKIM checks, zk-email proofs). Inbound messages only; outbound returns 404. For display/threading, use get_email instead.

Get the project's mailbox info (ID, address, slug). Use to check if a mailbox exists.

Delete the project's mailbox (irreversible — drops all messages and webhook subscriptions). Requires confirm=true. If mailbox_id is omitted, resolves the project's mailbox.

Register a webhook on the project's mailbox. Receives POST notifications for email events (delivery, bounced, complained, reply_received).

List all webhooks registered on the project's mailbox.

Get details of a specific webhook by ID.

Delete a webhook. Idempotent — succeeds even if already deleted.

Update a webhook's URL and/or events. At least one field required. Events is a full replacement, not a merge.

List durable webhook delivery rows for the project's mailbox. Webhook delivery is at-least-once with bounded retries + backoff; failures land in 'failed_permanent' (the dead-letter queue). Filter by status to inspect what was lost. Consumers must dedupe on the envelope idempotency_key.

Re-queue a dead-lettered (failed_permanent) webhook delivery so the worker attempts delivery again. Use after fixing the consumer endpoint.

Translate text to a target language. Requires service key and active AI Translation add-on. Supports optional source language and context hint.

Run content moderation on text. Returns flagged status and category scores. Free for all projects, requires service key.

Get AI translation usage for the current billing period — used words, quota, and remaining balance.

Send a message to the Run402 developers. Requires an active tier.

Register agent contact info (name, email, webhook). New or changed emails start operator email reply verification. Free with allowance auth.

Get the current agent contact assurance state: wallet_only, email_pending, email_verified, passkey_pending, or operator_passkey.

Start or resend the operator email reply challenge for the active agent contact email. Does not expose the challenge secret.

Email a short-lived Run402 operator passkey enrollment link to the verified contact email. Requires email_verified.