Welcome

NanoSaaS.ai is a spec-driven marketplace for micro-applications. Instead of spending $4–$8 in LLM tokens regenerating solutions that already exist, you can buy a tested, hosted solution for a fraction of the cost — or publish your own and earn passive income every time someone purchases it.

The platform is built for two audiences: developers who want to save time and money, and AI agents that can search the marketplace programmatically via the MCP server or the Solution Router API.

This guide covers every aspect of the platform — from writing your first NanoSpec to receiving weekly payouts.

Getting Started

Signing Up

Create an account at /sign-up. Authentication is handled by Clerk — you can sign up with email or a supported OAuth provider. Once your account is created, a creator profile is automatically provisioned with a unique slug, display name, and a standard trust tier.

The Dashboard

After signing in, you land on the dashboard. The sidebar gives you access to:

• My Apps — view and manage your NanoApps
• New App — create a NanoApp from a spec
• Analytics — usage and adoption metrics (coming soon)
• Payouts — earnings summary and Stripe Connect setup
• Settings — your creator profile and payout configuration

Creator Profile

Your creator slug (e.g. @ian) is derived from your Clerk username or user ID. It appears in your NanoApp URLs: /apps/ian/auth/jwt-middleware. Your profile also tracks your trust tier and payout status.

The NanoSpec

What Is a Spec?

A NanoSpec is a declarative specification that describes what your NanoApp does. Nobody uploads code — the platform generates, audits, and hosts the code itself based on your spec. This is the key architectural decision that eliminates supply-chain trust issues.

Three Tiers

The spec system supports three representation tiers, each targeting a different workflow:

• Tier 1 — Natural: Write in plain markdown with a YAML frontmatter header. The platform uses an LLM to normalize your description into a full structured spec. Best for humans describing an idea in prose.
• Tier 2 — Structured: Write directly in YAML with the full NanoSpec schema. This is the canonical form that the platform consumes. Best for power users and teams who want precise control.
• Tier 3 — Machine: The same fields as Tier 2, but encoded as JSON. Designed for AI agents and programmatic spec generation.

Early Choices

Before writing your spec, you select two foundational settings:

• UI type: page (full web page), widget (embeddable component), api_only (pure API endpoint), or headless (background service). This determines the versioning model — api_only and headless use immutable versioning, while page and widget use rolling versioning.
• Auth type: none, api_key, oauth, or session. This affects how buyers access your NanoApp after purchase.

Spec Fields

A full NanoSpec includes: name (kebab-case), version (semver), description, category, ui_type, auth, inputs, outputs, pricing, and optional fields like tagline, tags, subcategory, and dependencies.

The Spec Editor

The dashboard provides a three-tab editor. The Natural tab lets you write prose and click Normalize to generate a structured spec. The Structured tab gives you a Monaco YAML editor with live validation. The Machine tab shows the JSON representation. All three stay synchronized.

Creating a NanoApp

Step 1: Write Your Spec

Navigate to New App in the dashboard. Choose your UI type and auth type, then write your spec in whichever tier suits you. If you use Natural mode, click Normalize to let the LLM expand your prose into a full Tier 2 spec. Review the result and adjust as needed.

Step 2: Save Draft

Click Save Draft to persist your spec. This creates (or updates) a listing in draft state. Your NanoApp is not visible in the marketplace yet — it is saved privately under your account.

Step 3: Submit for Analysis

Click Submit for Analysis to run your spec through the analysis pipeline. This validates your spec, runs a security audit, scores quality, assesses pricing, and checks for duplicate solutions. If the security audit passes, your version is promoted to preview state.

Step 4: Build and Publish

Once in preview, the platform can generate a Cloudflare Worker from your spec, deploy it to the edge, and publish it to the marketplace. See the Building & Publishing section for details.

The Analysis Pipeline

When you submit a spec for analysis, the platform runs four checks in parallel:

1. Duplicate Detection

Your spec is compared against all existing published listings to identify similar solutions. This helps surface potential overlaps and informs buyers about alternatives.

2. Security Audit

Claude Opus analyzes your spec for security concerns. Findings are classified as blocking or advisory. If any blocking findings are detected, your version cannot progress to preview — this is the primary trust gate.

3. Quality Score

The platform evaluates your spec across four quality dimensions and produces a weighted overall score. This score is displayed on your marketplace listing to help buyers assess quality at a glance.

4. Pricing Assessment

Claude Sonnet estimates the cost to regenerate your solution from scratch using Claude Opus, then compares that against your listed price. The result is a fairness rating: fair, high, or low. A savings multiple (e.g. “5.4x”) is also calculated, showing buyers how much they save by purchasing instead of regenerating.

Building & Publishing

Code Generation

The platform generates a self-contained Cloudflare Worker from your spec using Claude Opus. The generated code includes a fetch handler, input validation, authentication, and CORS configuration — all derived deterministically from your spec fields.

Security Scan

After generation, the code passes through a pattern-based security scan that rejects known-dangerous constructs: eval, new Function, importScripts, process.env, and require. This is a deterministic safety layer on top of the LLM-based security audit.

Preview vs Production

A build deploys a preview Worker and stores the artifact in Cloudflare R2. A publish promotes the preview to a production Worker, sets the version to stable (immutable) or current (rolling), and makes the listing visible in the marketplace.

Rolling vs Immutable

Rolling versioning (for page and widget apps) means new publishes replace the current version — the previous version is snapshotted. Immutable versioning (for api_only and headless apps) means each published version is permanent — consumers pin to a specific version and control when they upgrade.

Versioning

Version States

Every NanoApp version progresses through a state machine:

Rolling:    draft → preview → current → deprecated → retired
                                          ↘ snapshot → retired

Immutable:  draft → preview → stable  → deprecated → retired

Invalid transitions are rejected. For example, you cannot skip from draft directly to stable.

SemVer Bump Rules

The platform analyzes spec diffs to determine the required version bump:

• MAJOR: changing auth type, removing or changing inputs/outputs, adding required inputs, changing capability sets
• MINOR: adding optional inputs, adding new outputs
• PATCH: everything else (description changes, tag updates, etc.)

If you declare a PATCH bump but the spec diff requires a MAJOR change, the platform rejects the version.

Dependencies

NanoApps can declare dependencies on other NanoApps using namespace references like creator/category/app-name. Three pin styles are supported:

• Exact: @2.3.1 — pins to a specific version
• Wildcard: @1.x — latest matching major
• Floating: no suffix — latest stable or current version

The resolver detects diamond conflicts (two dependencies requiring incompatible major versions of the same NanoApp) and surfaces deprecation warnings.

Deprecation & Retirement

Creators can schedule deprecation with a minimum 90-day notice period before retirement. Once the retirement date passes, the version is automatically moved to retired and is no longer available for new purchases.

The Marketplace

Browsing & Filtering

The marketplace at /marketplace displays all published NanoApps. You can filter by category, search by keyword, and sort by newest, most popular, highest rated, or greatest savings.

Categories

NanoApps are organized into seven categories: auth, data, ui, ai, integration, domain, and infra. Each category can have subcategories for finer-grained discovery.

Listing Detail

Each listing page shows the spec summary, analysis scores (security status, quality score, pricing assessment, savings multiple), available versions, user reviews, and a savings card that compares the purchase price against the estimated cost to regenerate from scratch at current Opus pricing.

The Solution Router

The Solution Router is the intelligence layer that intercepts expensive generation before it starts. Rather than requiring developers to browse a marketplace, it inserts a recommendation at the exact moment they're about to burn tokens.

Stage 1: Semantic Match

A problem description is searched against all published listings to find candidates that exceed the similarity threshold. This stage is cheap — fractions of a cent per query. If no candidates match, the Router returns match_found: false and the developer proceeds to generate normally.

Stage 2: LLM Evaluation

Candidates are passed to Claude Sonnet for evaluation. For each match, the evaluator returns a quality score (0–1), a cost estimate for regeneration, and a mandatory caveat — a description of what the solution does not cover. The caveat is always required; the platform never oversells a match.

The Decision Card

The result is presented as a decision card: “Save ~$3.80. A solution exists that covers 85% of your use case. Buy for $1, or continue generating.” Two buttons. Clear savings. Honest caveats. The buyer decides.

Public API

The Router is accessible at POST /api/router — no authentication required, rate-limited to 60 requests per minute per IP. This is deliberate: the Router must be free and unauthenticated because its value is highest when agents use it automatically before generation, without requiring the developer to log in.

The MCP Server

The Model Context Protocol (MCP) server is the agent-native distribution layer for NanoSaaS. It lets AI agents search for solutions, inspect specs, and draft new NanoSpecs — all from inside the IDE, without opening a browser.

Installation

Install the MCP server globally via npm:

npm install -g nanosass-mcp

This installs the nanosass-mcp CLI binary, which communicates via stdio transport — no ports, no sockets, no networking setup required.

Configuration for Cursor

Add the following to your .cursor/mcp.json:

{
  "mcpServers": {
    "nanosass": {
      "command": "nanosass-mcp",
      "env": {
        "NANOSASS_BASE_URL": "https://api.nanosass.app",
        "NANOSASS_API_KEY": "your-api-key"
      }
    }
  }
}

Configuration for Claude Code

For Claude Code, a single command is all you need:

claude mcp add nanosass nanosass-mcp

The server also works with any other MCP-compatible agent that supports stdio transport.

Environment Variables

• NANOSASS_BASE_URL — the platform API URL. Defaults to https://api.nanosass.app.
• NANOSASS_API_KEY — your API key. Required for draft_nanospec (which calls the authenticated normalize endpoint). Optional for read-only search tools.

Available Tools

How Agents Use It

In practice, an AI agent calls search_solutions before generating code. If a matching NanoApp exists, the agent presents the savings and the developer decides: “buy it” or “continue generating.” Three seconds instead of three minutes.

The draft_nanospec tool enables the reverse flow: after a developer builds something worth sharing, the agent can draft a spec for it, making it easy to publish to the marketplace and start earning.

Planned Features (Phase 3)

Two additional MCP capabilities are planned: the session instrumentor (passive token spend tracking across your coding session) and the recognition engine (automatically identifies when you've built something worth publishing as a NanoApp).

Buying Solutions

Per-Use Purchases

For one-time purchases, the platform creates a Stripe PaymentIntent. Once payment succeeds, the purchase is recorded, the 70/30 revenue split is calculated, a payout is queued for the creator, and an API key is issued to the buyer for accessing the NanoApp.

Subscriptions

For recurring access, the platform creates a Stripe Subscription. When each invoice is paid, access is extended for another period. Subscriptions use the same 70/30 split, applied as an application fee percentage.

API Key Access

After purchase, buyers receive an API key tied to their account and the specific NanoApp version. This key is used to authenticate requests to the deployed Worker.

The Savings Display

Every listing shows a savings card: “Save ~$4.80 vs regenerating at Opus pricing.” This is not an abstract promise — it is a concrete, moment-of-decision comparison based on the analysis pipeline's regeneration cost estimate. The developer doesn't have to believe in the marketplace; they just have to compare two numbers.

Selling & Earning

The 70/30 Split

Creators keep 70% of every sale. The platform takes 30% for building, hosting, and trust infrastructure. This split is applied automatically at the payment level via Stripe Connect.

Stripe Connect Onboarding

To receive payouts, navigate to Payouts in the dashboard and click Set Up Payouts. This redirects you to Stripe's Connect Express onboarding flow where you complete KYC verification. Stripe Connect supports payouts to 46+ countries. Once onboarding is complete, your account is marked as payout-enabled.

Weekly Payouts

Payouts are batched weekly. The system aggregates all pending earnings by creator. For each creator whose total exceeds their payout threshold ($10 by default), a Stripe Transfer is issued to their Connect account. Weekly batching reduces Stripe API calls, aggregates many small transactions, and aligns with what creators expect from marketplace platforms.

Passive Income

Once a NanoApp is published, it earns revenue on every purchase without any further action from you. The marketplace listing, the Solution Router, and the MCP server all drive discovery. Each sale is automatically split, queued for payout, and transferred on the weekly cycle. Your Payouts dashboard shows this-week earnings, pending amounts, and all-time totals.

Pricing & Cost Model

Setting Your Price

Prices are defined in the NanoSpec pricing block. You choose a pricing model and set a dollar amount:

• per_use — a one-time payment per purchase (minimum $0.10)
• subscription — a monthly recurring charge
• free — no charge

Regeneration Cost Estimate

The analysis pipeline uses Claude Sonnet to estimate how much it would cost to regenerate your solution from scratch using Claude Opus at current token rates. This estimate produces two key numbers:

• Estimated regeneration cost — e.g. $5.40
• Savings multiple — e.g. 5.4x (the ratio of regen cost to your listed price)

Pricing Assessment

The pipeline classifies your price as fair, high, or low relative to the estimated regeneration cost. This assessment is shown to buyers and helps set expectations.

Token Usage and Authentication

The platform uses Anthropic tokens at several stages: spec normalization (Tier 1 to Tier 2 conversion), the analysis pipeline (security audit via Opus, quality scoring via Opus, pricing assessment via Sonnet), code generation (Opus), and Solution Router evaluation (Sonnet). These costs are borne by the platform, not by individual users. Buyer-facing pricing is the listed price on the NanoApp, not a per-token charge.

Trust & Security

Spec-Driven Trust Chain

The fundamental trust insight: nobody uploads code. By defining NanoApps as specifications rather than code, the platform controls the entire chain — from spec to codegen to security scan to deployed Worker. This eliminates npm-style supply chain risk entirely.

Multi-Layer Security

• Analysis pipeline security audit: Claude Opus reviews the spec for security concerns. Blocking findings prevent the version from reaching preview.
• Post-generation security scan: deterministic pattern matching rejects dangerous code constructs after generation.
• Spec-level constraints: Zod validation enforces cross-field rules at schema time (e.g. PHI data requires domain_sensitive trust tier).

Mandatory Caveats

Every Solution Router recommendation includes a mandatory caveat describing what the solution does not cover. Marketplaces die when buyers feel misled. A buyer who purchases a 92% match knowing about the 8% gap is a satisfied buyer.

Trust Tiers

Creators and listings have trust tiers: standard (default), elevated (higher scrutiny), and domain_sensitive (for apps handling sensitive domains like healthcare or finance). Higher tiers trigger stricter analysis and additional validation rules.

Downloadable NanoApps

Not every solution needs a live API. NanoSaaS supports downloadable artifacts — static files generated from a spec that buyers download and use offline, with no dependency on a running server.

When to Use Downloads

• Architecture documents — ADRs, API specs, runbooks, design systems
• Code components — React/Vue/Svelte components, utility modules, hooks
• Configuration templates — Terraform, Docker Compose, CI/CD pipelines, Kubernetes manifests
• Content bundles — prompt libraries, style guides, tutorial sets

How It Differs from Hosted NanoApps

Creating a Downloadable NanoApp

1. In the spec editor, set Delivery to Downloadable.
2. Choose an Artifact Format: Markdown, Component, Template, or Bundle.
3. Optionally specify language and framework in the artifact config to guide generation.
4. Write your description and spec as usual. The platform generates the files, bundles them into a .zip, and uploads to storage.
5. After analysis passes, publish. Buyers see a Download button on the listing page.

Artifact Formats

Pricing for Downloads

Pricing works the same way — per-use (one-time purchase), subscription, or free. The analysis pipeline estimates regeneration cost based on the artifact type and complexity. The 70/30 revenue split and weekly payouts are identical to hosted NanoApps.

Dashboard Reference