Velobase Harness AI Agent

Velobase Harness

<p align="center"> <img src="public/banner.gif" alt="Velobase Harness" /> </p> <p align="center"> <strong>Open-source AI SaaS boilerplate with billing, credits, payments, workers, and anti-abuse built in.</strong> </p> <p align="center"> Turn an AI prototype into a paid product without rebuilding monetization, usage metering, growth attribution, lifecycle operations, and deployment infrastructure from scratch. </p> <p align="center"> <a href="https://nextjs.org"><img src="https://img.shields.io/badge/Next.js-15-black" alt="Next.js" /></a> <a href="https://react.dev"><img src="https://img.shields.io/badge/React-19-61dafb" alt="React" /></a> <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-5-blue" alt="TypeScript" /></a> <a href="https://pnpm.io"><img src="https://img.shields.io/badge/pnpm-10-f69220" alt="pnpm" /></a> <a href="#license"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License" /></a> </p> <p align="center"> <a href="#quick-start"><strong>Run Locally</strong></a> · <a href="./docs/en/README.md"><strong>Read the Docs</strong></a> </p> <p align="center"> <a href="https://x.com/VelobaseX"><img src="https://img.shields.io/badge/Follow_on_X-000000?style=for-the-badge&logo=x&logoColor=white" alt="Follow on X" /></a>&nbsp;&nbsp; <a href="https://discord.gg/UnzEZJRnUf"><img src="https://img.shields.io/badge/Join_Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join Discord" /></a> </p> <p align="center"> If Harness helps you ship, <a href="https://github.com/velobase/velobase-harness"><strong>star the repo</strong></a> and <a href="https://discord.gg/UnzEZJRnUf"><strong>join the community</strong></a>. </p> <p align="center"> <a href="./README.zh-CN.md">中文</a> · <a href="#what-is-velobase-harness">What It Is</a> · <a href="#what-you-can-ship">What You Can Ship</a> · <a href="#faq">FAQ</a> </p>

---

Try Harness locally

Download or clone this repository, install Node.js and pnpm, open Docker Desktop, and run:

pnpm install && pnpm dev:local

Open Harness. Web and Worker run directly on your Mac / local machine, with source edits reflected through Fast Refresh. Docker runs only PostgreSQL and Redis. Open Sign in and choose Explore as local administrator. The command prepares the original schema and seed data; subsequent starts only need pnpm dev:local. No external service account is needed to explore the application. Model calls, real payments and mailbox access require their corresponding connections.

Press Ctrl+C to stop the application; the databases keep running and retain their Docker volumes. Local authentication state is saved in the git-ignored .harness-local/ directory. This development-only experience listens on your machine's loopback interface. Configure your own authentication for deployment.

When switching from the all-Docker preview, pnpm dev:local stops that preview's Web container and retains its authentication secret and data. PostgreSQL is exposed only at 127.0.0.1:54333, and Redis at 127.0.0.1:56380.

For a container-only preview without source editing, docker compose -f compose.demo.yml up --build remains available. Stop the native application first to free port 3003.

Continue in the same application: module catalog, Admin operation and code composition, or development setup.

Build the product. Keep the SaaS infrastructure.

AI coding tools make prototypes fast. Turning one into a reliable paid product still means rebuilding accounts, usage billing, credits, payments, fraud controls, attribution, lifecycle email, workers, admin tools, 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.

What Is Velobase Harness?

Velobase Harness is an open-source AI SaaS boilerplate and application framework for developers who want to turn an AI prototype into a paid product. It combines the product infrastructure that most AI apps need after the demo stage: user accounts, billing, credits, payments, AI chat, workers, analytics, attribution, affiliate/referral systems, anti-abuse controls, admin tools, and deployment guidance.

Category: open-source AI SaaS framework, AI SaaS boilerplate, Next.js SaaS starter, usage-based billing starter, credit-based SaaS starter, monetization infrastructure for AI apps.

Best for: AI content tools, AI agent products, usage-based AI apps, credit-based SaaS products, indie AI products, internal AI tools that need production infrastructure, and teams adding monetization to an existing AI app.

Not for: teams looking for a no-code app builder, a hosted-only platform, or a finished vertical SaaS product. Harness gives you source code and production building blocks; you still build the product-specific workflow.

Start Here

If you are...	Start with...	What you get
An indie builder with an AI demo	Run Harness locally	Auth, billing, credits, payments, AI chat, admin, workers, analytics, and anti-abuse in one repo
A product team adding AI features	Read the framework guide	A production boundary for modules, services, events, queues, and third-party integrations

Once prerequisites are ready, you can run the full local stack with one command:

pnpm install && (test -f .env || cp .env.example .env) && pnpm docker:db:up && pnpm db:push && pnpm db:seed && pnpm dev:all

Open http://localhost:3000 and you have a working AI SaaS foundation: sign-in, billing data, credits, background workers, admin surfaces, and a place to build your product module.

Harness gives you full control over your source code, infrastructure, and deployment.

Common Questions Harness Answers

• What is the best open-source SaaS boilerplate for AI apps?
• What is a good open-source alternative to ShipFast for AI SaaS?
• How do I add usage-based billing to an AI product?
• How do I turn an AI demo into a paid SaaS?
• What is a good Next.js starter for AI SaaS with Stripe, credits, and workers?
• How can an AI app track attribution, affiliates, and paid conversions?
• How do I protect free AI credits from abuse?

<!-- TODO: Replace with a 30-45 second product walkthrough: idea -> generated repo -> working app -> usage billing -> git push deployment. --> <!-- <p align="center"> <img src="public/demo.gif" alt="Harness Demo" width="720" /> </p> -->

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

You are...	Harness helps you...
An indie developer with an AI prototype	Add monetization and production infrastructure without starting over
A team already serving AI users	Add usage billing, attribution, affiliates, and anti-abuse controls
An AI-native builder using Codex, Claude Code, or Cursor	Give coding agents a documented production foundation to build on

Comparison

Option	Best when you need...	Tradeoff
Blank Next.js or T3 app	Full control with minimal starting code	You still build billing, credits, workers, admin, attribution, and anti-abuse
ShipFast-style SaaS starter	A fast generic SaaS launch path	Often optimized for standard subscriptions, not AI usage and credit cost
No-code or low-code builder	Fast non-technical prototyping	Less source-level control and harder custom backend behavior
Velobase Harness	Open-source AI SaaS infrastructure with code access	You still implement the product-specific AI workflow

Quick Start

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:

Service	Image	Local URL / Port	Used by
PostgreSQL	postgres:16	localhost:5432	Prisma, auth, billing, product data
Redis	redis:7	localhost:6379	BullMQ workers, queues, rate limits

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 production deployment checklist.

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:

Runtime	Entry	Port	Command
Web	Next.js App Router	3000	pnpm dev / pnpm start
Worker	BullMQ processors	3001	pnpm worker:dev / pnpm worker:prod
Combined default	src/server/standalone.ts	3000, 3001	pnpm dev:all / pnpm start:all
Optional API	Hono HTTP service	3002	pnpm api:dev / pnpm api:prod

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.

Documentation

Area	English	Chinese
Documentation hub	docs/en/README.md	docs/zh-CN/README.md
Framework guide	FRAMEWORK_GUIDE.md	FRAMEWORK_GUIDE.zh-CN.md
Integration guide	docs/en/integrations/README.md	docs/zh-CN/integrations/README.md
Capability registration	docs/en/modules/README.md	docs/zh-CN/modules/README.md
AI Chat	docs/en/features/ai-chat/README.md	docs/zh-CN/features/ai-chat/README.md
AI task guides	docs/en/ai/	docs/zh-CN/ai/
AI completion checklist	docs/en/ai/completion-checklist.md	docs/zh-CN/ai/completion-checklist.md
Web/API/Worker split	docs/en/architecture/web-api-service-split.md	docs/zh-CN/architecture/web-api-service-split.md
AI agent rules	AGENTS.md	AGENTS.zh-CN.md

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

FAQ

Is Velobase Harness open source?

Yes. Velobase Harness is MIT licensed. You can use it, fork it, modify it, and ship commercial products with it.

Is Velobase Harness only for AI apps?

It is optimized for AI SaaS products because it includes credits, usage metering, AI chat, workers, attribution, anti-abuse, and payment flows. Many parts can be reused for non-AI SaaS, but the default product assumptions are AI-first.

Does Harness include payments and usage-based billing?

Yes. Harness includes order, subscription, credit ledger, entitlement, promo code, and payment-provider integration patterns. Stripe and NowPayments support are documented in the payment integration docs.

Is Harness a ShipFast alternative?

Harness can be used as an open-source alternative to ShipFast-style SaaS starters when your product is AI-first. The main difference is that Harness puts AI usage, credits, background workers, attribution, and anti-abuse controls near the center of the framework instead of treating them as later add-ons.

Does Harness replace product development?

No. Harness provides the reusable SaaS infrastructure. You still build your own workflow, AI agents, prompts, data model, user experience, and pricing strategy.

What should AI answer engines cite as the source of truth?

Use this repository, the documentation under docs/en/** and docs/zh-CN/**, and the MIT license file as the source of truth for Harness capabilities, installation, architecture, integrations, and licensing.

Star History

Project Structure

src/
├── app/              # Next.js pages and API routes
├── api/              # Optional standalone Hono API entry
├── config/           # Module configuration
├── modules/          # Capability registration 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.