mpp-runtime

mpp-runtime is a self-hosted prepaid edge runtime for private paid workers on Cloudflare¹.

It lets you expose a worker behind a simple flow:

1. preview the run price
2. return a real 402 Payment Required challenge
3. execute inside a budget-capped sandbox
4. settle only the actual spend
5. return a receipt, artifacts, and audit trail

This repo started as the lean runtime product for private paid workers, and now also ships optional tools, stream, lanes, batch, and marketplace profiles on top of the same core. You can deploy the runtime by itself, or use the same repo and CLI to launch a self-hosted marketplace layer later.

Product Profiles

This repo now supports multiple product surfaces on top of the same core:

• runtime
  The default lean runtime profile for private paid workers, with routes like /runtime/* and /runs/*.

• tools
  A paid tool gateway profile that exposes the same core as tool-native routes like /tools/*, /tool-runs/*, and one-shot /tool-tickets.

• stream A streamed session profile for prepaid long-running or interactive flows, with routes like /sessions/* and session-oriented ops.

• lanes A priority-lanes profile for premium routing and scarce-capacity offers, with routes like /lanes/*, /lane-auctions/*, and /lane-runs/*.

• batch A batch-jobs profile for prepaid queued or collection-shaped work, with routes like /batches/*, /batch-runs/*, and batch-oriented ops.

• marketplace A self-hosted discovery and publishing layer for public listings, with routes like /marketplace/*, /publishers/*, and /catalog/*.

Initialize the tools profile with:

npx mpp-runtime init --profile tools

Initialize the stream profile with:

npx mpp-runtime init --profile stream

Initialize the lanes profile with:

npx mpp-runtime init --profile lanes

Initialize the batch profile with:

npx mpp-runtime init --profile batch

Initialize the marketplace profile with:

npx mpp-runtime init --profile marketplace

Which Profile Should I Use?

• runtime Choose this when you want private paid workers or internal team-owned endpoints.

• tools Choose this when you want one-shot paid actions for agents or API consumers.

• stream Choose this when you want prepaid long-lived sessions with checkpoints and close flow.

• lanes Choose this when you want premium routing, priority execution, or scarce-capacity offers.

• batch Choose this when you want one prepaid request to cover many items, retries, and aggregate receipts.

• marketplace Choose this when you want public discovery, publisher onboarding, storefront pages, or federated source indexing.

What It Does

• Turn a private worker into a prepaid API endpoint.
• Cap spend before execution starts.
• Run bounded worker packages in isolated Cloudflare execution paths.
• Restrict workers to declared bindings and limits.
• Store receipts, artifacts, audit events, retention policies, and ops state.
• Let operators deploy, update, roll back, inspect, and export runtime activity.
• Optionally add a self-hosted marketplace layer for public discovery, publisher onboarding, and staged public releases.
• Add trust and economics signals to the marketplace layer, including publisher badges, run counts, payout summaries, and source-health metadata for federated listings.

Why People Would Use It

LLMs can generate or reason, and Tempo/MPP can handle the payment rail, but neither one gives you a complete paid runtime with hard execution limits, policy enforcement, receipts, and operator controls.

mpp-runtime is useful when you want a paid action to be:

• prepaid instead of postpaid
• budget-capped instead of open-ended
• private instead of publicly listed
• inspectable instead of opaque
• self-hosted in your own Cloudflare account

Real Use Cases

• Summarize this repo for at most \$0.05
  An internal AI tool can call a private summarizer worker, preview the cost, prepay, run it, and get a receipt without giving the agent broad infrastructure access.

• Normalize this customer JSON payload for at most \$0.02
  A SaaS product can sell premium transformations with explicit user-approved spend instead of metering later.

• Run a paid internal compliance check
  A platform team can expose policy or enrichment workers to other teams while keeping capability access narrow and auditable.

• Charge per premium edge action
  A product can offer repo analysis, data cleanup, or enrichment as small prepaid jobs without building a full marketplace.

How It Works

The lean runtime has three layers:

• Control plane worker
  Handles preview, 402 challenge flow, run creation, receipts, audit, retention, private worker lifecycle, and ops.

• Execution target worker
  Receives the pinned manifest, attested package, input, quote, and session context across a real service boundary.

• Execution sandbox worker
  Runs the bounded package with the declared limits, bindings, metering, and artifact handling.

Storage and payments:

• Durable Objects keep live control-plane state transitions.
• D1 mirrors queryable indexes for runs, receipts, audits, publishers, workers, and artifacts.
• R2 stores large blobs like code packages and artifact bodies.
• Tempo / MPP powers the preview -> challenge -> authorize -> settle payment rail.²³

What The CLI Provisions

The npm CLI provisions the runtime into your Cloudflare account:

• control plane worker config
• execution target worker config
• execution sandbox worker config
• execution dispatch namespace
• runtime D1 database
• artifacts R2 bucket
• code-packages R2 bucket
• generated Wrangler configs
• local secret scaffolding and deploy order

Launch-Grade Examples

The repo now ships a copy-paste example pack for every profile in examples/profiles/README.md.

Included examples:

• runtime.preview.json, runtime.run.json, runtime.publish.json
• tools.preview.json, tools.run.json, tools.publish.json
• stream.preview.json, stream.run.json, stream.publish.json
• lanes.preview.json, lanes.run.json, lanes.publish.json
• batch.preview.json, batch.run.json, batch.publish.json
• marketplace.preview.json, marketplace.run.json, marketplace.publish.json
• marketplace.sources.json for safer federation config

5-Minute Quickstart

Install and start in local stub mode:

bun install
cp .env.example .dev.vars
npx mpp-runtime init
npx mpp-runtime provision --dry-run
npx mpp-runtime secret bootstrap
npx mpp-runtime doctor
bun run dev

After init, the CLI also writes:

• .mpp-runtime/GETTING_STARTED.md
• .mpp-runtime/starters/<profile>.preview.json
• .mpp-runtime/starters/<profile>.run.json
• .mpp-runtime/starters/<profile>.publish.json

Those files give each profile a small self-hosted guide plus starter payloads you can use immediately while bringing the runtime up. The repo example pack under examples/profiles/README.md is the stable reference version of those payloads.

That gives you a local runtime with:

• /runs/preview
• /runs
• /workers
• /runtime/studio
• /ops

For the tools profile, the equivalent surface is:

• /tools
• /tool-runs/preview
• /tool-tickets
• /tools/studio
• /ops

For the stream profile, the equivalent surface is:

• /sessions/preview
• /sessions
• /sessions/:sessionId
• /sessions/:sessionId/events
• /sessions/:sessionId/close
• /ops

For the lanes profile, the equivalent surface is:

• /lanes
• /lane-auctions
• /lane-runs/preview
• /lane-runs
• /ops

For the batch profile, the equivalent surface is:

• /batches
• /batch-runs/preview
• /batch-runs
• /batch-runs/:batchRunId
• /batch-runs/:batchRunId/events
• /batch-runs/:batchRunId/result
• /ops

For a real Cloudflare deployment:

npx mpp-runtime login
npx mpp-runtime init
npx mpp-runtime provision
npx mpp-runtime secret bootstrap
npx mpp-runtime secret sync
npx mpp-runtime deploy
npx mpp-runtime doctor

Upgrade an older alpha workspace with:

npx mpp-runtime upgrade --dry-run
npx mpp-runtime upgrade
npx mpp-runtime doctor

deploy now runs a preflight before it touches Cloudflare. If generated Wrangler config, the provisioned D1 id, or required local secrets are missing, it stops early with actionable next steps instead of failing half-way through deployment.

Local Configuration

Copy .env.example to .dev.vars.

The default file is intentionally set up for local stub mode. The Tempo block is commented and uses Moderato testnet example values so you can see the shape of the config without accidentally treating them as production defaults.

The fastest safe setup path is:

npx mpp-runtime secret bootstrap

That mints strong local defaults for:

• DEV_SIGNING_SECRET
• EXECUTION_TARGET_TOKEN
• EXECUTION_SANDBOX_TOKEN
• OPS_ADMIN_TOKEN
• CATALOG_ADMIN_TOKEN
• PUBLISHER_ONBOARDING_TOKEN
• MARKETPLACE_METADATA_SECRET on the marketplace profile

Core settings:

• PAYMENT_RAIL_MODE
• PAYMENT_RECIPIENT
• DEV_SIGNING_SECRET
• EXECUTION_BACKEND
• EXECUTION_TARGET_TOKEN
• EXECUTION_SANDBOX_TOKEN
• MARKETPLACE_INSTANCE_NAME
• MARKETPLACE_BASE_URL
• MARKETPLACE_METADATA_SECRET
• MARKETPLACE_INDEX_SOURCES

For marketplace federation, MARKETPLACE_INDEX_SOURCES can be a simple comma-separated list of marketplace base URLs or a JSON array with per-source controls like trustLevel, cacheTtlMs, metadataSecret, allowlisted, and denied. JSON is the safer production shape. Any source marked trusted without a metadataSecret is downgraded to unverified at runtime.

Tempo mode additionally needs:

• MPP_SECRET_KEY
• TEMPO_RPC_URL
• TEMPO_CHAIN_ID
• TEMPO_CURRENCY_ADDRESS
• TEMPO_FEE_TOKEN_ADDRESS
• TEMPO_RECIPIENT_ADDRESS
• TEMPO_RECIPIENT_PRIVATE_KEY

Lean Runtime Features

• Private worker package build, validation, upload, deploy, update, and rollback
• Publish checks and staged release flow for private workers
• Tempo-backed prepaid payment flow with receipts and close reconciliation
• Budget-capped execution with bounded package policies
• Audit trail, exports, retention controls, and operator console
• Cloudflare-native deployment with a real multi-worker execution plane

Tools Profile Features

• Tool-native discovery and execution routes via /tools and /tool-runs
• One-shot prepaid capability tickets via POST /tool-tickets
• Tool-first authoring routes via /tools/studio, /tools/code-packages/*, and /tools/private-tools/*
• Tool-specific ops aliases and exports via /ops/tool-runs, /ops/tools, and /ops/tool-tickets

Stream Profile Features

• Session-native prepaid routes via /sessions/preview, /sessions, and /sessions/:sessionId
• Pollable session event history and spend checkpoints via GET /sessions/:sessionId/events
• Session close summaries via POST /sessions/:sessionId/close
• Session-specific ops aliases and exports via /ops/sessions and /ops/exports/sessions

Lanes Profile Features

• Lane-native discovery via /lanes and /lanes/:laneId
• Fixed-price premium lane offers via /lane-auctions and /lane-auctions/:auctionId
• Premium routing run aliases via /lane-runs/preview, /lane-runs, and /lane-runs/:laneRunId/result
• Lane-specific ops aliases and exports via /ops/lane-runs, /ops/lanes, and /ops/exports/lane-runs

Batch Profile Features

• Batch-native discovery via /batches and /batches/:batchId
• Prepaid batch-run aliases via /batch-runs/preview, /batch-runs, and /batch-runs/:batchRunId/result
• Batch event history via GET /batch-runs/:batchRunId/events, including checkpoints and child-run progress
• Batch-specific ops aliases and exports via /ops/batch-runs, /ops/batches, and /ops/exports/batch-runs
• batch-runs accepts either one input or many items[], supports stable itemId values plus retryPolicy, and executes them sequentially inside one bounded prepaid run
• v0 stores one parent batch run plus one child run per attempt, supports replay-safe batchRequestId / Idempotency-Key submit semantics, returns per-item attempt history plus one aggregate receipt, and does not yet support parallel fan-out or lane allocation

Marketplace Profile Features

• Public marketplace discovery via /marketplace, /marketplace/discover, /marketplace/publishers, and clickable item/publisher detail pages
• Compact transactional item pages that can preview price, trigger runs, and mint tool tickets across runtime, tools, stream, and lanes
• Trust and storefront signals for public listings, including release stage, publish-check status, attestation presence, source label, version state, and starting-price hints
• Optional federated discovery by pointing MARKETPLACE_INDEX_SOURCES at other self-hosted marketplace deployments, with local proxy item/publisher pages plus same-origin preview/run/result/session proxy routes for remote listings
• Marketplace trust and economics overlays, including publisher badges, listing usage counts, payout summaries, federated source-health/caching metadata, and publisher earnings views via /marketplace/publishers/:publisherId/earnings
• Production-safety defaults in the CLI and doctor flow, including strong secret bootstrap, placeholder-secret detection, missing-auth warnings, and trusted-source downgrade when signed metadata is absent

Commands

Use the published CLI with:

npx mpp-runtime@alpha --help

Main commands:

• mpp-runtime init
  • Generates .mpp-runtime/config.json, .mpp-runtime/GETTING_STARTED.md, and profile starter payloads.
• mpp-runtime login
• mpp-runtime provision
  • Generates Wrangler config and can provision D1, R2, and dispatch resources.
• mpp-runtime upgrade
  • Migrates legacy CLI config to the current schema and regenerates onboarding plus Wrangler scaffolding.
• mpp-runtime secret bootstrap
  • Mints strong local defaults for common signing, execution, ops, and marketplace metadata secrets.
• mpp-runtime secret set
• mpp-runtime secret sync
• mpp-runtime deploy
  • Runs a deploy preflight, syncs secrets, then deploys sandbox -> target -> control plane.
• mpp-runtime doctor
  • Checks onboarding assets, generated config, local secrets, placeholder/weak secret safety, payment rail health, federation trust config, and deploy readiness.

From this repo, the equivalent is:

bun run cli -- <command>

Development

Before shipping changes:

bun run typecheck
bun run test

Before publishing a release:

bun run release:check

Key docs in this repo:

• CHANGELOG.md
• RELEASE.md
• lean-version-roadmap.md
• product-profiles.md
• UPGRADING.md
• runtime-marketplace-v1.md
• mpp-payment-flow.md
• worker-manifest.schema.json
• run-receipt.schema.json
• progress.md

License: MIT. See LICENSE.

Footnotes

Footnotes

1. Cloudflare Workers for Platforms / Dynamic Workers: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/ ↩

2. Tempo docs: https://docs.tempo.xyz/ ↩

3. MPP docs: https://mpp.dev/overview ↩