Start Forge locally and verify the real product paths, not just the code.

If you want to try Forge, contribute to it, or operate it locally, this page shows the main commands and the checks that matter. The key rule is simple: make sure the app and API actually load where users expect them.

Local Development

These commands get the app running in a realistic local setup.

Install and run

npm install
npm run dev

The normal repo dev command starts the Fastify backend and the Vite UI together.

OpenClaw data-root variant

npm run dev:server:openclaw-data
FORGE_BASE_PATH=/forge/ npm run dev:web -- --host 127.0.0.1 --port 3027

Use this path when you need the repo runtime aligned with the tracked shared Forge data root.

Plugin entrypoint in dev mode

FORGE_OPENCLAW_DEV=1 node ./openclaw-plugin/server/index.js
npm run dev:openclaw-plugin-runtime

The OpenClaw plugin entrypoint stays on the built runtime by default. Set FORGE_OPENCLAW_DEV=1 only during local development to have that same entrypoint launch the source-backed autoreloading backend on port 4317.

Workflow Model

Forge’s planning workflow belongs here, not on the landing page.

Planning sequence

The canonical Forge planning flow is: PRD -> issues -> tasks -> subtasks when needed -> closeout. Projects are PRD-backed, issues are vertical slices, and tasks should fit one focused AI session.

Execution modes

Issues can be AFK or HITL. Task generation typically follows Schema -> Logic -> API -> UI, with tests interleaved instead of deferred.

Lean work item contract

Detailed work lives mainly in description and aiInstructions. Structured workflow fields stay narrow: execution mode, acceptance criteria, blocker links, and completion reports with modified files, work summary, and linked git refs.

Git workflow default

Forge defaults to direct commits on main. Feature branches and pull requests can exist, but the product and agent docs should not assume them as the default execution model.

Primary Commands

The main commands for building, testing, and exporting docs.

Command	Purpose
`npm run dev`	Run Fastify and Vite together for repo-local development.
`npm run build`	Build the main Forge web app.
`npm run test`	Run the Vitest frontend suite.
`npm run test:server`	Run the server test suite through Node + tsx.
`npm run docs:openapi`	Export the current generated OpenAPI document into the Pages artifact.
`npm run build:openclaw-plugin`	Bundle the published OpenClaw package with the built Forge runtime payload.

Verification

After changes, verify the product is still reachable and trustworthy.

Static verification

npx tsc --noEmit
node --import tsx --test --test-concurrency=1 server/src/*.test.ts
npm run test

Live runtime verification

tailscale serve status
curl -I http://127.0.0.1:4317/api/v1/health
curl -I http://127.0.0.1:3027/forge/

Forge treats live verification as mandatory. Passing types or unit tests is not enough if the app shell or API mount is broken.

Docs Pipeline

The public guide and API explorer are generated from the product itself.

Where the API contract comes from

Forge generates its OpenAPI document in server/src/openapi.ts. The runtime serves that same document at /api/v1/openapi.json.

How GitHub Pages stays accurate

The docs export script writes the current generated spec into openclaw-plugin/docs/api/openapi.json so GitHub Pages can render the same contract without a live Forge server.

npm run docs:openapi

Release Paths

These commands matter when Forge is being packaged or published.

OpenClaw package

Use npm run build:openclaw-plugin to produce the published OpenClaw package payload with the built runtime.

Plugin parity

Run npm run check:openclaw-plugin when the adapter surface, runtime packaging, or manifest behavior changes.

Pages deploy

The GitHub Pages workflow publishes the static docs site from the repo’s docs artifact, including the exported OpenAPI JSON.