User guide

PoseForge is a local-first photo studio for putting a saved person into a new pose, composing portraits, and preparing document photos. Your database, workspace, and generated files live on your computer.

Privacy boundary

ComfyUI can keep both files and inference on your machine.
Local formatting in ID Photos crops, resizes, and creates print sheets without sending the portrait to an AI provider.
OpenAI, Gemini, and Replicate send the selected references and prompt to that provider's API.
Codex CLI and Antigravity CLI use the account and provider connection of the locally installed CLI. They may send references to their provider.

PoseForge has no hosted account or gallery service. Review SECURITY.md before exposing the app outside a trusted machine.

Studio

Studio combines identity photos, a pose reference, and art direction.

Add one to four subjects in Sources, or select a saved character.
Add a pose image, choose one from the pose library, or use a pose collage in Advanced mode.
Set the background, style, and optional creative brief.
Choose a ready generation engine in the docked action bar.
Review the token and cost estimate, then generate.

Normal mode keeps the core workflow compact. Advanced mode adds per-person direction, fidelity controls, camera and lighting, composition, retouching, aspect ratio, recipes, pose-collage splitting, and up to six queued variants. The generate action stays docked at the bottom of the workspace.

HEIC and HEIF uploads are converted for browser preview and processing. The original subject should be clear, well lit, and large enough to recognize.

Characters and poses

Characters stores people you use repeatedly. In Studio, Use character fills the next available subject slot. Poses contains curated references and uploaded poses. Use this pose returns to Studio with that pose selected.

Uploaded pose images are saved automatically. Use search and category filters to narrow the library before opening a pose.

ID Photos

ID Photos supports the U.S. and India profiles supplied by the API, including passport, visa, India e-Visa, and India OCI application photos.

Choose the country and document.
Upload a recent, front-facing portrait.
Keep Local format selected for crop, resize, and optional 4×6 print-sheet generation with zero provider tokens.
Compare the result against the checklist and linked official source.

Every profile shows when PoseForge checked the guidance and, when the authority publishes one, the source's own update date. Government acceptance is never guaranteed. The official authority is the source of truth.

AI assist is experimental and may be unsuitable where an authority requires an unaltered photograph. It uses the selected engine and displays an estimated usage cost before generation.

History and Metrics

History contains the runs stored by this PoseForge installation. Open a run to inspect its engine, status, output, and recorded usage.

Metrics aggregates the same generation records into cost, tokens, reliability, latency, queue time, and engine/model breakdowns. Use Session for runs since the API process started or Historical for all stored runs. Export the current scope as JSON or CSV. See docs/METRICS.md for exact definitions.

Settings and engines

Settings reports engine readiness, selects the default engine, and stores the configuration required by API providers. Credential fields are write-only in the browser; saved secrets are never rendered back into the page.

Codex and Antigravity require their CLIs to be installed and authenticated. ComfyUI requires a running server and an exported API workflow. Gemini, OpenAI, and Replicate require provider API keys. Follow the setup instructions shown beside each engine in Settings.

Troubleshooting

If an engine is unavailable, open Settings and read its readiness reason.
If a generation fails, open History for the recorded error and request ID.
If a cloud engine rejects an image, confirm its size, format, and provider policy; try a JPG or PNG if its API does not accept HEIC directly.
If the UI cannot load data, restart the single PoseForge process with npm run dev and review its terminal output.