Start with one real project.

Updated October 4, 2026Read as Markdown ↗

Connect a small project you know well. Start by observing it, then decide how much work to hand over.

What it takes: steps 1–4 below get you to a first capability map and an opening checkpoint. On a repository you already know, the main work is choosing which outcome matters, which signals are readable and what actions are permitted. Setup time depends on the domain and its integrations. Steps 5–6, the permissions and the scheduled watcher, are a separate decision you can make later.

1. Check the basics

You need Node.js 22.16.0 or newer, an installed and signed-in coding CLI, and the GitHub CLI authenticated for your project. Your project also needs at least one signal a machine can read: a test, a log check or a product metric.

node --version
gh auth status

2. Open the Factory checkout

After access is granted, clone Factory and install its dependencies. The current internal package and CLI use the name northstar.

git clone https://github.com/khaoss85/agentic-factory.git
cd agentic-factory
npm ci
npm run northstar -- preflight --agent codex

Use --agent claude or --agent grok if that is your configured CLI. Preflight checks that the executable exists; it cannot independently confirm every provider’s login. Sign in through your CLI before starting work.

3. Give the project a goal

In the private checkout, scaffold a new pack with the real CLI:

npm run northstar -- init --dir packs/my-app --slug my-app --goal "Reduce material product failures with independent evidence."

Init creates a domain manifest. It does not discover credentials, connect sources, grant permissions or start a worker. For an existing pack, continue with its actual path instead of creating another one.

Then ask your coding agent to guide the configuration:

Connect Factory to my project at /absolute/path/to/my-app.
Use the goal scaffold at packs/my-app.
Read .agents/skills/onboard-project/SKILL.md and follow it.
Start in observation mode. Explain remaining readiness gaps before running work.

Domain Builder / Compiler V1 validates the proposed operating model against available capabilities. The project still needs real sources, tools, evidence rules, verification and permissions. Keep credentials in the project’s existing secret storage.

4. Inspect the project and open the board

Use the actual pack path produced during onboarding in place of packs/my-app.

npm run northstar -- readiness --pack packs/my-app
npm run northstar -- checkpoint --pack packs/my-app
npm run northstar -- serve --packs packs

Open the local URL printed by the server. Look at the mapped capabilities, open problems and missing evidence before enabling automated work.

5. Choose your operating boundaries

Observation, implementation, merge and release are different permissions. Configure the project’s autonomy contract before running an agent. The onboarding guide walks you through that choice.

For an already configured project where you have authorized execution:

npm run northstar -- run --pack packs/my-app

6. Keep checking on a schedule

After the pack’s schedule, run command and permissions are configured, start the periodic watcher:

npm run northstar -- watch --pack packs/my-app

Keep that process running on an awake host. The watcher measures at the configured times and launches the run command when the checkpoint finds work. It also records observations when there is nothing to repair. This is how operation can continue across days.

Each worker run still has time and invocation limits. Authentication, subscription quotas, human decisions and missing evidence can stop work. The project’s recorded history survives an individual agent session; multi-day operation does not mean one unlimited model call.

Observe from the cloud when connected

The private cockpit reads a project-scoped cloud projection; it does not host the execution loop. Configure publishing through the private onboarding process, then inspect synchronization locally:

npm run northstar -- cloud status --pack packs/my-app

A connected binding alone is not proof of a fresh observation. Read snapshot age and last durable progress separately. See the cloud and MCP boundaries.

To inspect the full command reference in your installed checkout:

npm run northstar -- --help