Product documentation

Build and operate NeedHer without weakening its safety boundaries.

NeedHer is a private consumer application for consented AI companion experiences and policy-controlled image and video generation. This guide covers the web app, desktop client, external media pipeline, commerce integrations, and NeedHer watermark nodes.

Maintainer quick start Web source

Product contract

One experience, several controlled systems

Companion and creator surfaces

Authenticated, age-eligible users can use only the experiences enabled by account state, consent, policy, and environment configuration.

Generated media

Approved requests pass identity, consent, policy, entitlement, and capacity checks before external media execution and provenance treatment.

Reports and removal

Users, represented people, rights holders, and trust operators need owned reporting, review, takedown, export, and deletion paths.

Current status

Version 0.1.0 is private development source, not a supported self-hosted service. A source checkout does not establish age assurance, moderation, consent, privacy, payment-provider approval, or production readiness.

Safety boundaries

Commercial entitlement never overrides policy.

No impersonation, non-consensual intimate imagery, sexual content involving minors, deceptive identity claims, or removal of required provenance.
Do not distribute private workflows, model weights, customer media, identity documents, credentials, signing keys, or production moderation rules.
Keep provider, database, payment, signing, and push credentials server-side. The browser is not authoritative for identity, policy, payment, or provenance.
Export, deletion, reporting, safety appeals, and takedown cannot be disabled to create a paid tier.

Bring existing data

Import a complete companion archive.

On first run, or later under Profile → Settings → Companion data, choose a companion-archive version 1 JSON file. The same authenticated POST /api/companion-archive operation is used by the web control and NeedHer Desktop; GET /api/companion-archive exports the account's retained archive.

Accepted data

The archive carries an exact format/version, source product and account identity, profiles or personas, characters, conversations, and ordered user/assistant messages. IDs, roles, order, timestamps, prompts, token counts, and bounded JSON message metadata are validated. Unknown fields, dangling character references, duplicate source IDs, invalid roles or timestamps, non-sequential message positions, and files over 10 MiB are refused before mutation.

Duplicates and failures

Source product plus source ID is the durable identity. An exact repeat is unchanged; a changed object with an existing identity is reported as conflicting and the retained object wins. New objects are committed in one database transaction, so an invalid archive or storage error leaves no partial import. Results report imported, unchanged, conflicting, and rejected counts without returning message contents.

Skipping the first-run import keeps an empty usable archive. Imported data is owned by the signed-in destination account under Supabase row-level security; it does not publish a character, generate content, send a message, overwrite an existing chat, or claim onboarding success before the database accepts the transaction.

CLI

The repository's npm run archive command invokes those same authenticated routes. Pipe the signed-in account bearer on standard input, never in an argument or the environment; imports print only result counts, and export refuses to overwrite an existing file. Install the declared bin from source and see every accepted command in the CLI reference.

# NEEDHER_API_URL names the API origin and is required; HTTPS except localhost
export NEEDHER_API_URL=https://<needher-origin>
skarbiec get <item> --field token | npm run archive -- import ./archive.json
skarbiec get <item> --field token | npm run archive -- export ./needher-export.json

Web development

Maintainer quick start

Use development-only identity, data, media, and payment endpoints. Missing production services should remain explicit failures; never point a local checkout at customer data just to make a route appear healthy.

git clone https://github.com/wisent-ai/needher-ai-web.git
cd needher-ai-web
npm install
cp .env.example .env.local
npm run dev

Open http://localhost:3000. The public surface should render or return a classified missing-configuration error.

Boundary	Configuration
Application	NEXT_PUBLIC_APP_URL and the configured identity/application backend
Card payments	STRIPE_SECRET_KEY, publishable key, and webhook signing secret
Solana	Merchant wallet, network, and an approved RPC endpoint
Commerce	Coinbase Commerce API and webhook credentials when that provider is enabled
Media	Approved content-platform and generation-service endpoints

Commerce

Treat provider redirects as intent, not settlement.

Stripe

Create checkout server-side. Verify the signed webhook and reconcile the provider object before granting Sparks.

Solana Pay

Validate recipient, token, amount, reference, network, and finality server-side before recording value.

Coinbase Commerce

Verify webhook signatures, expected charge data, currency, status, and idempotency before fulfilment.

Keep secrets in the deployment secret boundary and use HTTPS for every payment endpoint.
Compute products, prices, and credited amounts on the server; never trust browser totals.
Make webhooks idempotent and preserve a reconciliation path for failure, refund, and delayed settlement.
Provider integration is not commercial approval; launch still requires approved pricing, refunds, policy, and capacity.

External media pipeline

ComfyUI runs outside the Next.js app.

The web application reads finished media from the content platform. Generation belongs on an approved external host, and outputs must keep the manifest, provenance, consent, and watermark contracts expected by the application.

Install or update ReActor

COMFYUI_DIR=/path/to/ComfyUI COMFYUI_PYTHON=/path/to/ComfyUI/venv/bin/python npm run comfy:reactor:install

Restart ComfyUI and confirm the ReActor nodes appear.
Add the node to the approved generation workflow before upload to the content platform.
Keep outputs flowing through the manifest contract consumed by src/lib/dailyFill.ts.
Use only synthetic identities or references with the required rights and consent. Review GPL-3.0 and every model asset licence before production use.

Other repositories

Desktop and watermark integrations

NeedHer Desktop

The Electron + React client has AI companion and verified human creator modes. Its first-run sheet and Settings view send archive bytes to the same NeedHer web operation; the renderer never parses or stores the bearer. Configure NEEDHER_API_URL and NEEDHER_ACCESS_TOKEN in the desktop process. Import chooses a JSON file; export writes needher-companion-archive.json through a native save dialog.

git clone https://github.com/wisent-ai/needher-ai-desktop.git
cd needher-ai-desktop
npm install
NEEDHER_API_URL=https://www.needher.ai \
NEEDHER_ACCESS_TOKEN=your-signed-in-account-bearer \
npm run dev

Build a macOS package with npm run package -- --mac --dir --publish never. Packaging requires an Apple signing certificate and refuses an unsigned app; CSC_NAME selects the identity. Developer ID Application is required for distribution, while Apple Development can sign a local development package. The app keeps ai.wisent.needher.desktop across updates. A development signature is not notarization.

ComfyUI watermark nodes

The custom-node repository provides image overlay, watermarked WebP output, and video watermark nodes. Configure NEEDHER_WATERMARK_LOGO or an explicit transparent PNG path. Video output requires ffmpeg on PATH.

cd ComfyUI/custom_nodes
git clone https://github.com/wisent-ai/needher-comfyui-watermark-nodes.git
pip install -r needher-comfyui-watermark-nodes/requirements.txt