Getting Started

ForgeOS requires Node.js 22.14 or newer.

This page gets you from zero to a running Forge backend and web app. For the longer walkthrough, see First App Tutorial.

Create an app

Recommended public quickstart:

npm create forgeos-app@alpha notes-app -- --template minimal-web
npm create forgeos-app@alpha nuxt-notes -- --template nuxt-web
cd notes-app
npm run dev

npm create forgeos-app@alpha creates a new app without installing ForgeOS globally. It is the best first command for new users. During alpha, use the @alpha tag explicitly; latest is not the active release channel and may lag behind alpha while a prerelease hardens.

The generated app contains:

• a Forge backend under src/;
• a small web UI under web/;
• AGENTS.md with agent workflow instructions;
• package scripts that call the local Forge CLI.

Open the right URL

npm run dev prints two kinds of URLs:

URL	Purpose
Web URL	The app you open in the browser.
API URL	The Forge JSON runtime used by hooks, commands, queries, and liveQuery.

Open the web URL for the user-facing app. The API URL returns JSON responses and may return unknown route at /; that does not mean the app is broken.

Install options

Install globally only if you want the forge command available everywhere:

npm install -g forgeos@alpha
forge --version

Run once without global install:

npx forgeos@alpha --help

In generated apps, use the installed or package-script CLI shown by that app:

forge status --json
npm run forge -- dev --once --json

If you are maintaining the ForgeOS framework checkout itself, run the source-tree entrypoint instead:

node bin/forge.mjs status --json
node bin/forge.mjs verify framework

Do not ask app users to run framework verification. forge verify is app-scoped; verify framework is only for this repository.

Use the lower-level command when you need explicit flags:

forge new notes-app \
  --template minimal-web \
  --package-manager npm \
  --forge-spec "npm:forgeos@alpha" \
  --install \
  --no-git

Templates

Template	Best for
minimal-web	Learning Forge, small prototypes
nuxt-web	Nuxt/Vue apps with generated Forge composables
agent-workroom	Showing ForgeOS as an external-agent development cockpit
b2b-support-web	Tickets, policies, Stripe, AI triage, liveQuery showcase

See Templates and Examples for file trees, package aliasing, and generated-app git hygiene.

First checks

Run these before editing a generated app:

npm run forge -- do inspect --json
npm run forge -- dev --once --json
npm run forge -- inspect all --json
npm run forge -- check --json

These commands tell you what exists, what is stale, which routes call which runtime entries, and which command to run next.

If the first feature needs a provider SDK or integration, do not start with npm install. Start with Forge's integration workflow:

npm run forge -- add stripe --dry-run --json
npm run forge -- add stripe --json
npm run forge -- deps api stripe checkout.sessions.create --json

forge add applies integration recipes, registers secret names, emits adapters, and updates runtime/package metadata. forge deps api gives an agent exact SDK signatures and placement hints before it writes code.

Run these before handing off a change:

npm run generate
npm run forge -- verify --standard

Use verify --strict for release or final handoff gates.

What to read first

Generated apps include files for humans and AI agents:

AGENTS.md
src/forge/_generated/agentContract.json
src/forge/_generated/appMap.md
src/forge/_generated/runtimeRules.md
src/forge/_generated/frontendGraph.json
src/forge/_generated/capabilityMap.json

Read them. Do not edit them. Change source files, then run:

npm run generate

Next steps

Topic	Page
End-to-end first app	First App Tutorial
Runtime flow by example	Runtime by Example
Build a feature with an agent	Build a Feature with an Agent
Agent issue-to-handoff loop	Agent Playbook
Agent-first workflow (forge do)	Agent Workflow
Local dev diagnostics	Dev Loop
Architecture and generated files	Architecture
Capability overview	Capabilities
Template file trees	Examples
Runtime rules (commands vs workflows)	Runtime Model
Frontend hooks and liveQuery	Frontend
Frontend/backend wiring	Frontend Integration Guide
AI generation and agents	AI
Native AI tools and agent loop	AI Agents
Scaffold resources and blueprints	Authoring
Auth, policies, secrets, RLS	Security and Data
Add Stripe, PostHog, Sentry, Zod, or AI SDK	forge add
Package graph and API oracle	Package Intelligence
Inspect package APIs for agents	CLI - Dependency API oracle
Fix guard violations	Troubleshooting
Version history	Changelog