PoseForge

Open the landing page and documentation · The full Studio runs locally because generation, storage, and its embedded database are intentionally not hosted on GitHub Pages.

Give PoseForge an identity photo and a pose reference. It returns the same person—or family—in the new pose and composition, with controls for camera, lighting, styling, fidelity, and output format.

PoseForge exists so Codex, Google Antigravity, and ComfyUI users can turn their existing AI access into a repeatable visual workflow instead of rebuilding the same multi-image prompt in chat for every photograph.

Watch the 15-second generation walkthrough · Download the lightweight 10-second MP4 · Quickstart · How it works · Examples · Landing page source · Documentation · Roadmap · Support · Discussions

Local-first, not automatically offline. Your workspace, embedded PGlite database, character library, pose library, and generated files stay on your machine. ComfyUI can keep inference fully local. Codex CLI, Google Antigravity, and hosted API engines send only the references, prompt, and settings selected for that generation to their provider. See Privacy and data flow.

Prerequisite: Node.js 20.9+. PGlite is embedded, so Docker and a separate database server are not required.

git clone https://github.com/vishwakulkarni/PoseForge.git
cd PoseForge
npm run setup
npm run dev

Open http://localhost:3000. The setup command creates .env when needed, installs locked dependencies, creates the embedded PGlite database, runs migrations, and verifies the 16 bundled offline poses. It preserves an existing .env and is safe to rerun after pulling updates.

No image engine is required to explore the interface. To generate images, authenticate Codex or Google Antigravity, connect local ComfyUI, or configure a hosted provider in Settings.

1. Choose the identity. Upload one to four people, or reuse saved character references.
2. Choose the pose. Upload a pose, split a pose sheet, or select one of the bundled references.
3. Direct and generate. Set composition, camera, lighting, styling, and fidelity; then run through Codex, Antigravity, ComfyUI, or a hosted API.

PoseForge stores successful pose uploads in the reusable pose library and keeps generation history, usage, latency, cost estimates, and outputs together on the local machine.

Consumer subscriptions and API billing are often separate products. Signed-in CLI behavior, quotas, and retention remain subject to the provider account and terms. Database-backed API keys and ComfyUI workflow JSON are stored in plain text in the local database; prefer environment variables where supported and read SECURITY.md before use on a shared machine.

PoseForge currently supports seven interchangeable engines. Adding another engine is a small adapter change; see the engine interface.

The people below are fictional, AI-created demo subjects. These visuals show the intended character → pose → result contract without publishing private user photos. They are product demonstrations, not provider quality benchmarks.

Identity stays recognizable while the reference contributes body position, camera framing, and composition; the final scene adds new lighting and art direction.

The middle photograph supplies only the arrangement: parents seated on either side while their two-year-old stands between them. The result keeps the Indian family identities and applies that family pose in a new festive setting.

The README animation combines both transformations into a character → pose → result story. AGY assembled the local media pipeline; sharp renders 300 frames and FFmpeg creates the MP4 and optimized GIF without network assets.

For generation benchmarks, record the exact engine, model, prompt, runtime, local hardware, and provider date. Do not compare providers using unrecorded launch assets or publish identifiable photos without permission.

• Studio: up to four identity slots, pose reference, live workflow canvas, per-person direction, camera and lighting controls, fidelity controls, multi-pose collage splitting, recipes, and up to six queued variants.
• Characters and poses: reusable local libraries with normalized image storage, pose filtering, and best-effort tagging.
• History: generation details, inputs, outputs, deletion, and rerun context.
• ID Photos: local formatting for U.S. and Indian passport, visa, e-Visa, and OCI profiles, with optional AI assistance kept separate.
• Metrics: tokens, spend estimates, latency, queue wait, engine mix, reliability, failure groups, and JSON/CSV exports.
• Documentation: repository Markdown rendered inside the application.

PoseForge runs as one Node.js server. Express owns /api, /storage, database rules, generation queues, and engine adapters; Next.js owns the interface. The browser talks to one local origin. See ARCHITECTURE.md for the request lifecycle, data model, and adapter contract.

flowchart LR
  Browser[Browser] --> Next[Next.js UI]
  Browser --> API[Express API]
  API --> DB[(PGlite / PostgreSQL metadata)]
  API --> Storage[(Local image storage)]
  API --> Queue[Generation queue]
  Queue --> Engines[Engine adapters]
  Engines --> Local[Local ComfyUI]
  Engines --> Providers[Codex, Antigravity, and hosted APIs]
  Local --> Storage
  Providers --> Storage

System architecture · Generation call flow · Object and data flow

• User guide
• Troubleshooting and FAQ
• Compatibility and hardware matrix
• Privacy and data flow
• Security policy
• Architecture
• Contributor guide
• Roadmap
• Support
• Changelog
• GitHub Discussions

The default .env.example uses embedded PGlite under storage/pglite. Set DATABASE_MODE=postgres and DATABASE_URL to use an existing PostgreSQL server instead. Other optional environment variables include CODEX_BIN, CODEX_TIMEOUT_MS, ANTIGRAVITY_BIN, ANTIGRAVITY_MODEL, ANTIGRAVITY_TIMEOUT_MS, GEMINI_API_KEY, GEMINI_IMAGE_MODEL, FAL_KEY, COMFYUI_URL, COMFYUI_MODEL, COMFYUI_WORKFLOW_PATH, and COMFYUI_TIMEOUT_MS.

PGlite is a single-process embedded database. Do not run multiple PoseForge server processes against the same PGLITE_DATA_DIR; use PostgreSQL for multi-process or remotely hosted deployments.

Keep the source DATABASE_URL in .env, stop PoseForge, and run:

npm run db:import-postgres -- --yes

The command builds and validates a fresh PGlite copy before replacing the configured PGLITE_DATA_DIR. It preserves the previous embedded database as a timestamped pglite.backup-* directory. Restart PoseForge after the import.

ComfyUI is restricted to loopback addresses unless COMFYUI_ALLOW_REMOTE=true is deliberately configured. OpenAI, Gemini, Replicate, and fal.ai credentials can also be configured in Settings.

npm run build:web
npm start

PoseForge is a trusted, single-user local application. It has no authentication or authorization layer and should not be exposed directly to the internet or a shared network. Review SECURITY.md and PRIVACY.md before changing that boundary.

Apache License 2.0. See LICENSE.