ForgeOS

ForgeOS is an agent-native application framework and compiler. It gives AI coding agents and humans a generated contract for the app they are editing: commands, queries, liveQueries, policies, data, secrets, frontend routes, runtime rules, AI tools, and the commands needed to verify a change.

The current npm release line is forgeos@alpha. During alpha, use the @alpha tag explicitly; the latest tag is not the active release channel and may lag behind alpha while a prerelease hardens. See Changelog for version history.

Quickstart

Recommended public app creation:

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

Install ForgeOS globally:

npm install -g forgeos@alpha
forge --version

Or run once with npx:

npx forgeos@alpha --help

Equivalent explicit ForgeOS command:

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

ForgeOS is useful when you want a backend/runtime that is explicit, inspectable, and safe for code agents to operate without a mandatory dashboard. See Why ForgeOS for the full thesis.

Agent-first loop

forge do inspect --json
forge dev --once --json
forge inspect all --json
forge verify --standard

See Agent Workflow.

The 30-second agent workflow

An agent can enter a ForgeOS project and ask the app for its own operating context:

forge do inspect --json
forge inspect all --json
forge inspect capabilities --json
forge inspect agent-tools --json

The response gives the agent commands, queries, liveQueries, actions, workflows, policies, tables, frontend routes, package rules, AI tools, generated drift, risks, and the next command to run.

When a feature needs an external package, ForgeOS keeps the same contract-first model. Use forge add for known integrations and forge deps api when an agent needs exact SDK signatures before writing code.

What ForgeOS Generates

• AGENTS.md for agent and human workflow instructions.
• src/forge/_generated/agentContract.json for machine-readable project context.
• src/forge/_generated/agentTools.json for AI-callable tools and auto-tools.
• src/forge/_generated/agentCairGuide.md for compact CAIR navigation, guarded edits, and Forge-native action guidance.
• src/forge/_generated/appMap.md for a human architecture map.
• src/forge/_generated/packageGraph.json plus dependencyApis in agentContract.json for package/API evidence.
• Runtime guards for commands, queries, liveQueries, actions, workflows, policies, packages, secrets, auth, AI placement, and frontend wiring.

Core Loop

forge dev
forge dev --once --json
forge inspect all --json
forge verify --standard

Use forge dev for the local loop and forge dev --once --json when an agent needs a deterministic diagnostic snapshot.

Documentation Map

Start here

Topic	Page
Five-minute mental model	The Five-Minute ForgeOS Model
Install and first app	Getting Started
Alpha hardening path	Alpha Golden Path
Full first app walkthrough	First App Tutorial
Why ForgeOS exists	Why ForgeOS
Public capability map	Capabilities
Compiler/runtime architecture	Architecture
Generated artifact policy	Generated Artifacts
Template file trees	Examples
Templates (minimal-web, nuxt-web, agent-workroom, b2b-support-web)	Templates
Agent intent router (forge do)	Agent Workflow
Compact agent navigation and guarded edits	CAIR Protocol
External-agent demo shape	Agent-Native Demo
Agent issue-to-handoff loop	Agent Playbook
Build a feature with an agent	Build a Feature with an Agent
Local control panel	Dev Loop
CLI workflows	CLI
Full CLI list	CLI Reference

Core concepts

Topic	Page
Commands vs actions vs workflows	Runtime Model
Runtime flow by example	Runtime by Example
React hooks, liveQuery, capability map	Frontend
Frontend/backend wiring guide	Frontend Integration Guide
Simple generation, agents, tools	AI
Native AI tools and agent loop	AI Agents
Auth, policies, secrets, RLS, DB	Security and Data

Build and integrate

Topic	Page
forge make, feature blueprints	Authoring
Install integrations safely with generated adapters	forge add
Inspect SDK APIs before coding	CLI - Dependency API oracle
Package graph, runtime compatibility, API evidence	Package Intelligence
Integration recipes	Recipes
Payment flows and webhooks	Payments
AST-aware refactors	Codemods

Agents and quality

Topic	Page
Agent-readable contract	Agent Contract
Impact tests, repair, verify gates	Testing and Repair
Guard violations, verify, repair	Troubleshooting
External app validation	Field Testing
Production maturity by area	Production Readiness
Public security boundaries and threats	Threat Model

Ship

Topic	Page
Self-host compose and checks	Self-Host
Production-like operations and diagnostics	Operations
npm release and publishing	Release
Version history	Changelog