PoseForge – Local-first AI studio for images and video (Codex, ComfyUI)

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 install npm run dev

Open http://localhost:3000. npm install installs both the API and web dependencies. The embedded PGlite database is created and migrated automatically on first start. Settings can be configured in the app; copy .env.example to .env only if you want to set options such as API keys up front. To check a fresh install end to end (database and the 16 bundled offline poses), run npm run setup.

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.

Choose the identity. Upload one to four people, or reuse saved character references.

Choose the pose. Upload a pose, split a pose sheet, or select one of the bundled references.

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.

PoseForge keeps the parts that make a result look like the same person on your machine, then hands each provider the same carefully prepared inputs:

Output quality still depends on the engine and model you choose; PoseForge's job is to give each one the best, most consistent starting point.

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.

Studio supports seven interchangeable engines. Advanced Studio adds two more providers, Higgsfield and Dreamina, for image and video nodes, and uses fal.ai for video too:

Higgsfield and Dreamina usage is metered in credits and shown on the Metrics page next to token and dollar spend. Selected inputs leave your machine for both providers. 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: character → pose → result

The guided workbench. Pick up to four identity slots, a pose reference (or split a multi-pose sheet), then direct per-person styling, camera, lighting, and fidelity. A live workflow canvas shows what feeds the generation, recipes save your settings, and up to six variants can be queued at once. Normal mode keeps the controls compact; Advanced mode adds per-person direction and identity and pose fidelity controls.

A multi-project node canvas for workflows that do not start from a character and a pose. Start from a template or a blank canvas, wire nodes together, and run them from the canvas:

Node types include text/prompt, image and media inputs, image and video generators, and groups. Generator options (aspect ratios, resolutions, reference-image limits) come from what each engine can actually do rather than a global list. Generator nodes can run on Higgsfield and Dreamina as well as the Studio engines (see below). Projects autosave, edges can be cut, and the canvas has keyboard shortcuts and a selection toolbar. Open it at /studio-advanced.

The bundled "Example: baby running" project: prompts feed image generators, and their outputs chain into video generators. Fictional, AI-created subjects.

The Metrics page summarizes every generation stored locally: lifetime spend, tokens, success rate, median and P95 latency, queue wait, and active days. It adds a cumulative usage chart (group by day, week, month, or run; tokens or cost), a per-engine and per-model breakdown, recurring failure groups, and Codex and Antigravity account-limit windows. Switch between Historical and Session scope, and export JSON or CSV. Values are marked actual, estimated, partial, or local, so you can tell provider-reported usage from estimates; see the metrics reference.

A read-only static demo of the whole app, including sample Metrics data, is published from main to GitHub Pages: https://vishwakulkarni.github.io/PoseForge/. Generation is disabled there; run PoseForge locally to create images.

Studio: guided character → pose → result workbench described above.

Advanced Studio: node-canvas image, video, and storyboard workflows.

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: usage, spend, latency, reliability, and exports described above.

Documentation: repository Markdown rendered inside the application.

Architecture

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.

System architecture · Generation call flow · Object and data flow

Command Purpose

npm install Install API and web dependencies

npm run setup Optional: clean-install dependencies, create .env, migrate, and verify bundled poses

npm run dev Start the complete application with Next.js development mode

npm run build:web Create the production web build

npm run test:all Run API and web unit/component tests

npm run test:e2e Run Playwright desktop and mobile smoke tests

npm run docs:sync Regenerate in-app documentation from repository Markdown

bash scripts/generate-readme-demo.sh Rebuild the README MP4 and GIF locally

Documentation and community

User guide

Troubleshooting and FAQ

Compatibility and hardware matrix

Privacy and data flow

Security policy

Architecture

Contributor guide

Roadmap

Support

Changelog

GitHub Discussions

Configuration

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 start

npm start builds the web app on first run. After pulling updates, rebuild it with npm run build:web.

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.