velobase-harness

All AI developers deserve to get paid.

Turn your AI prototype into a paid SaaS with open-source infrastructure for usage billing, payments, attribution, affiliates, anti-abuse, and deployment.

Try Launchpad · Run Locally · Read the Docs

If Harness helps you ship, star the repo and join the community.

中文 · What You Can Ship · Open Source vs Cloud · Architecture

Build the product. Keep the revenue infrastructure.

AI coding tools make prototypes fast. Turning one into a reliable business still means rebuilding payments, usage metering, fraud controls, attribution, affiliates, lifecycle email, and deployment.

Velobase Harness packages that work into an MIT-licensed framework for AI SaaS builders. Start with a working product foundation, then spend your time on the part only you can build.

Harness helps you build and monetize the application. Velobase Cloud removes the infrastructure and deployment work.

What You Can Ship

Launch a paid AI product

Accept subscriptions and usage-based payments, manage credits, meter AI usage, and give customers a billing dashboard from day one.

Understand which growth channels work

Connect purchases to acquisition channels with server-side attribution, Google Ads offline conversions, X pixel events, and PostHog analytics.

Turn customers into a distribution channel

Run an affiliate program with a double-entry ledger, refund clawbacks, referral tracking, promo codes, and USDT cashout.

Protect expensive AI usage

Reduce free-credit abuse with rate limits, Turnstile, disposable-email checks, signup signals, guest quotas, and credit clawbacks.

Operate without assembling the backend yourself

Use built-in auth, multi-LLM chat, background workers, lifecycle email, admin tools, Docker, Kubernetes, and GitOps guidance.

Built For

Open Source or Managed Cloud

Harness is MIT licensed and can be self-hosted. Velobase Cloud is the managed path for builders who want to skip provisioning and deployment work.

Describe your product and try Launchpad

Quick Start

Option A: Start with Velobase Launchpad

Describe your product idea. Launchpad creates a repository, provisions cloud resources, and generates a prompt for your AI coding agent.

Create an AI SaaS with Launchpad

Option B: Run Harness Locally

Prerequisites: Node.js, pnpm, Docker Desktop, and Docker Compose.

pnpm install
cp .env.example .env
pnpm docker:db:up
pnpm db:push
pnpm db:seed
pnpm dev:all

Open http://localhost:3000 after the development server starts.

New here? Start with the local defaults. Payment providers, AI providers, attribution, outreach, and other integrations can be configured when you need them.

pnpm docker:db:up starts the local infrastructure from docker-compose.yml:

Stripe CLI is available as an optional Docker Compose profile for local webhook testing. Run pnpm docker:up when you need it.

The default .env.example already points to these local services:

DATABASE_URL=postgresql://velobase:velobase@localhost:5432/velobase
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

pnpm dev:all starts the default combined local runtime: Web on :3000 and Worker on :3001. The optional Hono API service is disabled by default; run SERVICE_MODE=all pnpm dev:all or pnpm api:dev when you need it.

You can also split processes across terminals:

pnpm dev
pnpm worker:dev

Add pnpm api:dev only when you are actively developing standalone Hono routes.

When you are ready to deploy, see the Cloud Deployment Guide.

If you are not entering through Launchpad flow, run Step 0 in FRAMEWORK_GUIDE.md before implementing product features: complete domain design, output the MVP scope and feature list, and wait for user confirmation before coding.

Architecture

flowchart TB
  browser[Browser] --> nextApp[Next.js Web]
  nextApp --> trpc[tRPC Routers]
  external[External Integrations] --> nextRoutes[Next Route Handlers]
  nextRoutes --> services
  trpc --> services[Domain Services]
  services --> db[(PostgreSQL)]
  services --> redis[(Redis)]
  services --> events[Event Bus]
  events --> modules[Pluggable Modules]
  worker[BullMQ Worker] --> redis
  worker --> services
  modules --> integrations[Product Integrations]
  hono[Optional Hono API] -. enable when needed .-> services

The same codebase can run as one process or as separate services:

SERVICE_MODE defaults to web,worker. It also supports all, web, api, worker, and combinations such as web,api. See Web/API/Worker split before enabling API in production.

From Template to Cloud

flowchart LR
  idea[Product Idea] --> launchpad[Velobase Launchpad]
  launchpad --> repo[GitHub Repo from Harness]
  launchpad --> cloud[Velobase Cloud Resources]
  repo --> ide[IDE Agent Development]
  ide --> push[Git Push]
  push --> actions[GitHub Actions]
  actions --> deployApi[Velobase Deploy API]
  deployApi --> liveApp[Live SaaS App]

Launchpad generates an IDE prompt that tells the AI agent how to use the Harness docs, where to implement product features, how to keep framework boundaries intact, and how to push changes back for Cloud deployment.

Documentation

Legacy non-locale paths under docs/ are compatibility shims. New documentation should use docs/en/** and docs/zh-CN/**.

Star History

Project Structure

src/
├── app/              # Next.js pages and API routes
├── api/              # Optional standalone Hono API entry
├── config/           # Module configuration
├── modules/          # Product modules and templates
├── server/           # Auth, billing, order, events, modules, features
├── workers/          # BullMQ queues and processors
├── components/       # Shared UI components
├── analytics/        # PostHog and ads event tracking
└── ...               # Hooks, i18n, shared libraries, stores, styles, and types

Quality Commands

pnpm lint
pnpm typecheck
pnpm check
pnpm format:check
pnpm build

package.json does not define a general unit-test script in this template. Service-mode smoke coverage lives in docker-compose.test.yml and scripts/test-service-mode.mjs.

Contributing

We'd love for you to help shape what's coming next — whether it's fixing bugs, building new features, or improving docs.

• 📘 Check out our Contribution Guide to get started
• 💻 Submit ideas, issues, or PRs on GitHub
• 💬 Join the conversation in our Discord — it's where the community lives

License

MIT — use it, fork it, ship it, make money with it.