Source: https://www.orchestro.org/docs/quickstart
Updated: 2026-09-15

# Start with one real project.

Updated September 15, 2026[Read as Markdown ↗](https://www.orchestro.org/docs/quickstart.md)

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, that is an afternoon rather than a sprint — most of it is choosing which capability matters and which signal is readable, not configuration. Steps 5–6, the permissions and the scheduled watcher, are a separate decision you can make later.

**You’ll need repository access.**

Factory is currently private. [Request early access](https://www.orchestro.org/early-access) before running the checkout commands below. There is no public Factory npm installer.

## 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.

check your machine

```
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`.

repository setup

```
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\. Let your agent guide the connection

Open your coding agent in the Factory directory and ask:

prompt for your coding agent

```
Connect Factory to my project at /absolute/path/to/my-app.
Read .agents/skills/onboard-project/SKILL.md and follow it.
Start in observation mode. Explain what you found before running work.
```

The onboarding workflow inspects the project, proposes what to watch, sets up a project pack and guides the first audit. 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`.

inspect and explore

```
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:

run configured work

```
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:

scheduled operation

```
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.

To inspect the full command reference in your installed checkout:

terminal

```
npm run northstar -- --help
```