FAQ

Is Forge actually free?

Yes — Apache 2.0, self-hosted, no seat licence. You provide the hardware and the operating effort. See the LICENSE.

What state is it in?

Public beta (1.0.0-beta.*). The quote-to-cash chain works end to end. APIs and schema still move between betas, and upgrades are expected to go through the forge-deploy reconcile path rather than by hand.

Do I need QuickBooks?

No, and you don't have to give it up either. Forge runs in integrated mode with QuickBooks Online (or Xero, FreshBooks, Sage, NetSuite, Wave, Zoho) as the book of record, or standalone with its own invoicing, payments and AR — and there's a native double-entry GL behind a capability for shops that want to keep their books entirely in Forge. See Accounting Modes.

What hardware do I need?

A 64-bit box with Docker: ~4 GB RAM minimum, 8 GB+ recommended. ARM is fully supported — a Raspberry Pi 4/5 is a legitimate deployment target, and all images are multi-arch. See Installation.

Can I run it on Windows?

Yes, via WSL2 — that's the supported path and it gets the full toolchain. Native PowerShell works for developer source-builds only; the forge-deploy CLI is bash and needs Linux paths.

Why can't I pull the images anonymously?

The ghcr.io/armoryworks/* packages require a GitHub token with the read:packages scope. Create a PAT and docker login ghcr.io. Details in Installation.

I installed it and half the features are missing.

That is almost certainly working as designed. Forge ships every feature in one binary and turns on a subset per install, chosen by a preset or the discovery wizard. An admin can toggle individual capabilities. See Capability Gating.

Why does /accounting redirect me to the dashboard?

The general ledger is behind CAP-ACCT-FULLGL, which is off by default and cannot be enabled for a book until that book's opening balances are posted. That gate is deliberate — see Accounting Modes.

How do I change the database schema?

Not with EF Core migrations — there aren't any. The schema is desired-state SQL in forge-db, reconciled with pg-schema-diff. The API provisions a fresh database and is a no-op on an existing one, so a stale dev volume will not self-heal; reconcile it with the forge-db harness. See Architecture.

My API container crash-loops with "relation … does not exist".

Classic stale-volume symptom, and the direct consequence of the answer above. Reconcile the database with forge-db rather than restarting and hoping.

Can I split the UI, API and database across machines?

Yes. Single-node is the default; the deploy toolchain supports split topologies without a Kubernetes commitment. See the forge-deploy README.

Does the AI assistant phone home?

No. The optional AI runs on local Ollama with pgvector for retrieval, in your own stack. It's profile-gated — if you don't enable it, the container doesn't run.

Does it work offline on the floor?

Partly, and the distinction matters. In a browser or installed PWA, a service worker prefetches the app shell and caches recent API reads, so the app opens and shows recent data without a network — but you cannot save. The offline write queue engages only in the native mobile shell, and only for a fixed set of floor actions. Full detail on Mobile and Offline.

Everything works, but I never entered any credentials.

That is the mock posture, and it is the shipped default. Most external integrations resolve to mock implementations returning fabricated data, so an evaluation box can appear to have QuickBooks, shipping and AI all working. Your install's readiness report tells you which enabled capabilities have nothing behind them — Configuration and Integrations.

I set up SSO and everyone gets "No account found".

Working as designed: SSO never provisions accounts. Create the user in Forge first, and their identity links on their first federated sign-in. Roles come from the local account, never from the identity provider — Configuration and Integrations.

How do I get an API token, and where are the API docs?

POST /api/v1/auth/login, then send the JWT as a bearer token; there is no refresh token, and an MFA-enabled account returns a challenge rather than a token on the first call. The interactive Scalar reference is served by the API itself but only in Development. See API Access.

How do I restore a backup?

Deliberately by hand: there is no restore subcommand. A snapshot is a pg_dump plus an object-storage mirror, and restoring means stopping the API, running pg_restore, and mirroring the buckets back. Also note that snapshots contain neither .env nor your TLS material, and nothing copies them off the box for you — Backup and Restore.

I upgraded and now the app says a column doesn't exist.

The schema reconcile did not run. It is gated on a flag that ships off, is auto-enabled only for release deploys, and silently reports success when the database is on a different machine — Upgrades and Rollback.

Is Forge only for job shops?

That is the primary audience, but the same binary also carries a professional-services shape and a retail/marketplace commerce layer, selected by preset — Business Shapes.

Can I run two companies on one install?

No. There is no tenant dimension in the data model — one install is one company. You get multiple sites and multiple currencies, but two legal entities means two stacks — Data Ownership and Export.

Can I get my data back out?

Yes, and without going through us: a full database dump and import from the admin UI in an open format, per-domain CSV/XLSX exports, and a read-only BI surface. Nothing phones home — Data Ownership and Export.

How do workers log in on the floor?

By badge. Tier 1 is an RFID/NFC tap plus a PIN, tier 2 a barcode scan plus a PIN; passwords are the desktop path. Admins never see or set a worker's password or PIN — they issue a setup token and the worker sets their own.

Where do I report a bug?

In the repo that owns the code — see the table on Home. Cross-cutting design questions go on the umbrella repo. Security problems are the exception: do not open a public issue — see Contributing.

Where's the authoritative documentation?

docs/ in the umbrella repo, versioned alongside the code. This wiki maps it; it doesn't replace it. If the two disagree, the repo wins. See Documentation Map.