This walkthrough is for the person deploying KeyForge and the developer connecting an application. Start locally with SQLite, confirm the whole licensing flow, then follow the deployment guide for your host. KeyForge does not require a payment gateway or a customer account system.
- A machine with Git and the repository-pinned Node.js version from
.node-version(currently 24.21.0). - Vite+, which provides the project's
vpcommands and manages its package manager. Commands below run from the repository root. - Persistent storage for the database, keys and archives. For production, also use HTTPS and a service/process supervisor.
- A strong password for the first administrator. There is no public operator sign-up.
The snippets use a POSIX shell unless labelled PowerShell. vp and node commands are the same on Windows, Linux and macOS. Example addresses, customer names and IDs are placeholders; use your own values. Never paste actual credentials into issues, screenshots or source control.
git clone https://github.com/zdevzone/keyforge.git
cd keyforge
vp install --frozen-lockfile
cp .env.example .envIn PowerShell, replace the last command with:
Copy-Item .env.example .envDo not overwrite an existing deployment's environment or keys. The scaffolder generates independent deployment secrets with vp create keyforge@latest. The source-checkout procedure above also lets you run the server directly.
These values have different jobs. They must not all be copied into a client app.
| Value | Purpose | Where it belongs |
|---|---|---|
LICENSE_SIGNING_KEY_FILE or LICENSE_SIGNING_KEY |
Ed25519 private key that signs authorizations | Server only; configure exactly one source |
Public verification key and kid |
Verify the server's signatures | Pinned in the dependent app; not secret |
LICENSE_AUTH_SECRET |
Protect console authentication | Server only; independent random secret |
LICENSE_ADMIN_TOKEN |
Privileged CLI/API automation | Trusted administrative tooling; optional, never in customer apps |
LICENSE_DATA_KEYRING_FILE |
Encrypt stored product keys and per-product private keys | Server and separate secure recovery storage |
LICENSE_BACKUP_KEYRING_FILE |
Encrypt/decrypt .kfbackup archives |
Server and separate secure recovery storage |
| Database credentials | Connect to PostgreSQL, if used | Server only |
| Installation credential | Authenticate one registered installation | Generated by the SDK; protected by the app's secure storage adapter |
| Product/license key | Customer's purchased license | Given to that customer; entered during app onboarding |
| Metering service credential | Trusted-backend usage reporting | Your backend only, never desktop/browser apps |
The backup key is a key ring, not the signing key or a reusable user password. Retain old ring keys while data or archives reference them. A database backup does not include external signing or encryption key files; keep recovery copies separately.
Run this once from the project root (a pre-existing environment file is optional):
vp run secrets:initThis creates an Ed25519 private key as LICENSE_SIGNING_KEY in the ignored .env file, independent data and backup keyrings, an administrative API token, a session secret and a cron secret. It writes settings without printing secret values. The public verification key may be shared with dependent apps. Configure your deployment URL, database and administrator separately; provider credentials are entered in Settings → Backups.
For a separate deployment, use vp run secrets:init --env-file secrets/environments/staging/server.env instead of copying another environment's credentials. Export inline settings for any host with vp run secrets:export --env-file secrets/environments/staging/server.env --output secrets/environments/staging/deploy.env. See portable environments. When moving an existing deployment, restore its original keys rather than generating new ones.
On an existing setup, confirm the [Y/n] prompt before the file is updated. Existing keys and configured secrets are retained. For reviewed, noninteractive automation, pass --yes; a pipe without that flag cannot silently change an existing environment file. Recognized example placeholders are replaced, while real configured values are retained.
Keep vp run license keygen for explicitly generating a signing key, or vp run license keygen --force for a deliberate replacement. It also saves LICENSE_SIGNING_KEY_FILE in .env, asks before updating an existing file, and refuses to replace an existing key without --force. An inline signing key must be removed explicitly before switching to a newly generated file. Rotation changes client trust; distribute public keys deliberately. Never rotate production keys just to complete setup.
Edit .env, retaining your actual generated secrets:
LICENSE_SIGNING_KEY=<your-generated-private-key>
LICENSE_AUTH_SECRET=<your-generated-console-secret>
LICENSE_ADMIN_TOKEN=<your-separately-generated-optional-admin-token>
LICENSE_DATA_KEYRING_FILE=./secrets/data.keyring.json
LICENSE_BACKUP_KEYRING_FILE=./secrets/backup.keyring.json
LICENSE_SERVER_URL=http://localhost:4100/
LICENSE_DB_PATH=./db/licenses.sqliteThis example is explanatory, not a ready-to-use secret file. For SQLite, leave DATABASE_URL unset. Authentication and licensing share this one database. For PostgreSQL, set DATABASE_URL; it takes precedence over local database paths. See configuration for TLS, pools, precedence and every setting.
Build, create the first operator, then start:
vp run build:all
vp run admin:create --email admin@example.com --password "YOUR-STRONG-UNIQUE-PASSWORD" --name "Administrator"
vp run startThe operator email/password are console login credentials, not signing keys. Avoid running the example password verbatim. CLI password arguments may be retained in shell history; on managed hosts you can instead use secret-manager values for LICENSE_SEED_ADMIN_EMAIL and LICENSE_SEED_ADMIN_PASSWORD before startup. Seeding does not reset an existing operator's password.
Visit http://localhost:4100/healthz and expect a successful response, then open http://localhost:4100/login and sign in. Health alone does not prove the console and licensing workflow work.
In a second terminal, validate the configured signing key and compare it with the running server:
vp run license keycheck --serverThis requires the same LICENSE_ADMIN_TOKEN on the server and CLI. Without bearer administration enabled, use local vp run license keycheck and the console instead. Missing signing material is a startup error; missing LICENSE_AUTH_SECRET intentionally disables console authentication.
- Open Products, create/select your product and review its policy. Record its stable product ID and approved public verification keys.
- In Entitlements → Plans, define feature entitlements and create an active plan with duration, installation limit and an ETB price. A price of zero explicitly means complimentary; an unset price prevents issuance.
- In Licenses, issue from that plan. Terms are shown for reference and cannot be overridden during issuance. The license and its price snapshot create one linked sale, unpaid by default.
- If money was already received, choose Already paid and enter the method/reference. Otherwise record payment later in Sales & payments. Issuance does not process a payment or move money.
- Deliver to a registered installation, approve a customer's preinstallation request, or securely share the returned key manually. Delivery is separate from activation.
Changing a plan later does not rewrite historical licenses or sales. Existing licenses without sales information are not automatically counted as paid. Reports distinguish sales value, receipts, outstanding amounts and refunds.
The administrative CLI talks to the running server using LICENSE_SERVER_URL and LICENSE_ADMIN_TOKEN. Most commands accept --product ID (default default). To see its help, run vp run license.
vp run license list --product photos
vp run license issue --product photos --plan pro --to "Example customer" --request-id 550e8400-e29b-41d4-a716-446655440000
vp run license activations LICENSE_ID --product photos
vp run license deactivate LICENSE_ID --product photos --installation INSTALLATION_ID
vp run license revoke LICENSE_ID --product photosUse your actual product/plan/record IDs. Generate a new UUID for a new issuance; reuse the same UUID and arguments only when retrying that issuance. Do not reuse this illustrative UUID for unrelated sales. Issuance takes its terms from the plan; flags such as --entitlements and --expires are rejected.
license inspect only decodes a token; it does not verify trust. Use the SDK's verifier or license keycheck --token TOKEN for signature checks. The CLI reference also covers keys, machine trials, copying databases, demo data and recovery. Read the maintenance requirements before any reset, replacement or restore.
The API reference lists routes, bodies, roles and errors. Download client OpenAPI for the client-facing contract. HTTPS clients in any language can use these APIs; the provided SDK currently targets JavaScript/TypeScript.
There are separate authentication contexts:
- Console/administration: operator session cookies, or the optional administrative bearer token.
- Installation: its own random credential for registration, activation, refresh, notifications and public support messages.
- Trusted metering backend: a product-scoped service credential.
- Preinstallation request: the private request-link credential; it is not an operator login or installation credential.
Never substitute an admin token for a customer's installation credential. Never log credentials, raw license keys or private request links. A successful HTTP response is not always an authorization grant: refresh can return a signed revoked/expired status with HTTP 200.
For JavaScript/TypeScript, use the SDK guide and integration walkthrough. The SDK has a publishable package structure, but public registry publication is separate; use the built workspace or package archive rather than assuming a similarly named registry package is ours.
Configure the app with the server URL, product ID, pinned public verification keys and an application-supplied secure storage adapter. Optional device recognition uses the Node-only @zdevzone/keyforge-client/device-signals adapter for Windows, Linux and macOS. Browser/mobile runtimes retain installation-based operation; do not request elevated privileges for hardware signals.
The onboarding flow is: securely create/save installation identity → register online → activate a customer key or explicitly start a permitted trial → save signed authorization → check entitlements at protected operations → refresh online before the signed deadline. Skipping onboarding grants no paid access. Initial activation requires internet; cached authorization only permits bounded offline use. Hardware recognition never automatically transfers seats.
Other languages can use REST directly. Safe offline support additionally requires exact signed-token verification, pinned keys, secure credential storage and stable request replay. An OpenAPI-generated HTTP wrapper does not supply those protections. The AI integration context and integration skill explain the same boundaries.
Follow the deployment guide for your platform. Transfer secrets using its secret manager or durable mounts; never put .env, private keys, database files or encryption rings in Git or a container image.
On Render, use the repository's Blueprint or its documented build/start commands, rather than an old Yarn command. If LICENSE_SERVER_URL is unset, KeyForge uses Render's RENDER_EXTERNAL_URL. For a custom domain, set LICENSE_SERVER_URL to that HTTPS origin. Leave LICENSE_PORT unset to honor Render's assigned PORT. Remove the local HTTP origin and local port override when configuring production.
Use managed PostgreSQL or a persistent disk for SQLite. Ephemeral filesystems cannot safely retain a database or generated keys. Configure only one signing-key source, preserve data/backup rings across deploys, and check health and operator login and a test product's activation/refresh after deployment. The build must include both server and UI (vp run build:all).
In Settings → Backups, create a backup and verify it. Keep off-server archives and separate recovery copies of the signing key and encryption rings. PostgreSQL archive verification needs compatible database tools and a separate scratch connection; see backups.
Before a restore, stop all writers, preserve the current target, restore using the correct archive job UUID and backup ring, then verify login, licenses, bindings and usage. Settings → System → Reset application data is destructive: it requires DELETE ALL and preserves the first seeded admin. Its optional verified backup differs from the offline reset commands, which can remove operators. Read database maintenance before either operation.
| Symptom | Check and next step |
|---|---|
| Server refuses to start with a signing error | Check exactly one key source and file permissions; run vp run license keycheck |
| Console authentication is disabled | Configure an independent LICENSE_AUTH_SECRET and restart |
| Login fails locally or cookies do not stick | Use the local HTTP origin in LICENSE_SERVER_URL; do not configure HTTPS for a plain HTTP local server |
| Production console needs a public URL | Set the canonical HTTPS origin, or use Render's supplied URL fallback |
| CLI returns unauthorized/unavailable | Confirm administrative bearer access is enabled and the CLI/server tokens match |
| Issuance refuses an unset price | Edit the selected plan and save an explicit ETB price |
| Client rejects an unknown key | Distribute/pin the approved product key and kid; never trust discovery alone |
| Client needs reconnection | Refresh online; do not extend signed deadlines locally |
| Hardware signals are Partial/Unavailable | Read device diagnostics; continue normal installation licensing without elevation |
| Backup cannot run or verify | Check the backup ring, destination permissions and PostgreSQL verification tools/connection |
For source changes run vp run check, vp run test, and vp run build:all. The browser checks are vp run test:console, vp run test:issuance and vp run test:docs; install Chromium with vp exec playwright install chromium first. See the references for capabilities and limitations rather than assuming email, payment collection or hosted multi-tenancy is included.