Documentation

Build, ship, learn

Belfort generates production-ready WebView paywalls and runs the analytics and remote-config backend that serves them. The path from a source app to a live release is one loop: generate, publish, activate, and measure.

Run Belfort locally

From the repository root, copy the local defaults, install the workspaces, start the complete Docker stack, and prepare Postgres and ClickHouse.

cp .env.example .env
npm install
docker compose -f docker-compose.yml -f docker-compose.full.yml -f docker-compose.minio.yml up -d --build
npm run db:migrate
npm run ch:migrate
npm run db:seed:docker

Generate a paywall

Build the @belfort/cli workspace and its dependencies, save your model credential once, then point Belfort at an iOS, Android, Capacitor, React Native, Flutter, or Unity source tree. The generated release is written to ./paywall-out.

npx turbo run build --filter=@belfort/cli...
node packages/cli/dist/cli.js init
node packages/cli/dist/cli.js run ./path/to/your/app --out ./paywall-out

Publish and activate

Publish the generated bundle with a management secret and activate it in the same command. The seeded key below is product-scoped. With an organization-scoped key, also pass --product <slug-or-id>.

BELFORT_SECRET=bsk_dev_write_secret \
BELFORT_ENDPOINT=http://localhost:9400 \
  node packages/cli/dist/cli.js publish ./paywall-out --activate

Install the SDK

Open a product in the dashboard, choose Info → Install, select the target platform, and download the stamped integration archive. The same screen includes copyable, product-specific instructions and the public client key.

• iOS ships a local Swift package that hosts the paywall in a WKWebView.
• Android ships a Kotlin library that hosts the bundle in a WebView.
• React Native, Capacitor, Flutter, and Unity currently receive an HTTP integration kit.

Calls to action

Restore purchases, Terms, and Privacy have no Hide option in the dashboard editor. Each one can be left at its default, handed to your app, bound to a URL, or bound to another paywall.

Restore uses the Belfort SDK by default. The SDK runs its configured billing restore path and reports the outcome. Other unbound actions are returned to your app; the SDK does not open a page or present another paywall for them:

• With the standard Swift configuration, automatic billing restores through RevenueCat when configured, otherwise StoreKit.
• Terms, privacy, and any other unbound action arrive on onCta with that action's key (terms, privacy, or a custom id from the design).
• Restore set to Unbound — app handles it arrives there too, as restore. Use it when your app runs its own restore flow; the SDK stays out of the way and reports nothing of its own.

Bind to Open URL or Open paywall only when Belfort should own the tap. Declared custom controls can also be hidden; built-ins have no Hide option in the dashboard editor. Wire app-handled actions in the SDK configuration:

onCta: { id in
    switch id {
    case "restore": runMyOwnRestore()
    case "terms": openTerms()
    case "privacy": openPrivacy()
    default: break
    }
}

Client and secret keys

The public client key starts with bk_. It identifies one product, ships in the app, and is sent as the belfort-client-id header for config and telemetry requests.

Management secret keys start with bsk_. They can publish bundles and mutate Belfort resources, so they belong only in trusted server or CLI environments—never in a mobile app.

Fetch config and report events

The native SDKs derive /v1/config and /v1/track from the API base URL. HTTP-kit integrations call the same endpoints directly with the product's public client key.

GET http://localhost:9400/v1/config?platform=ios&deviceId=device-123
belfort-client-id: bk_…

POST http://localhost:9400/v1/track
belfort-client-id: bk_…
content-type: application/json

Belfort skills

Install the belfort management skill to give supported coding agents the CLI commands, authentication rules, and resource model for operating a Belfort deployment.

npx skills add blubblub/Belfort --skill belfort -g

The source is skills/belfort/SKILL.md. A global install is stored at ~/.agents/skills/belfort/ and made available to the agents you select.

Paywall design skills

Generation and critique skills ship with the CLI under packages/cli/skills/, so they need no separate install. belfort run exposes them read-only inside each generated workspace at .scratch/.claude/skills/.

Core concepts

Products and paywalls

A product represents one app. Its paywalls are versioned generated bundles that Belfort can publish, activate, and measure independently.

Triggers and experiments

A trigger is a named placement such as onboarding or feature_unlock. Experiments split a trigger's traffic across paywall variants and record conversion and revenue for each one.

Release notes

Every tagged release, newest first. The dashboard shows each of these once, the first time you sign in after it ships; this is where they stay.