Quickstart

This takes you from a fork to your first pull request on your own accounts. It’s the short version of the full self-host guide. Every command below is copied from that guide, and a test in the repo checks each one against the code.

One thing to know first. bin/selfhost-install.sh plans your install, but the step that creates the resources, --apply, is not built yet. Run it today and it exits 2 without touching anything. So you check your settings with the dry-run, then create the resources by hand.

What you need

• A GitHub account that owns your fork, plus a GitHub App or a personal access token.
• A Cloudflare account (D1, Workers, KV, R2, Pages).
• A Fly account, or a VM you already run.
• A model credential: a Claude Code subscription token or an Anthropic API key.

Fork and clone

The upstream repo is cromford-ai/cromford. Fork and clone it in one step:

gh repo fork <upstream-owner>/<repo> --clone

Or clone a fork you already made:

git clone https://github.com/<you>/<repo>.git

Fill in your settings

Run everything from the root of your clone. Copy the settings template:

cp env-templates/selfhost.conf.example selfhost.conf

Fill in selfhost.conf, one KEY=value per line. An unknown key or a key set twice is refused. Secrets never go in this file. They live under /etc/harness/env/ on the box. The self-host guide has a row for every key and where to find its value.

Check the plan

bin/selfhost-install.sh --config selfhost.conf --dry-run

A good run exits 0. It prints every resource, env line, spend cap and secret name your install needs, and ends with SUMMARY ... live_calls=0 writes=0. That last part means nothing was touched. If a setting is wrong, it exits 1 and names every problem in one message.

Create the resources by hand

--apply is not built yet, so build the resources from your dry-run plan by hand. OPERATOR-SETUP walks through it. Your plan gives you the exact names, env lines and secret names to use.

The spend caps are on by default: $5 on one agent call and $20 per lane per day, until you change them.

Add your first repo

Once your hub is up, enroll a repo:

bin/load-project.sh <owner/repo> --project <name> --box <box>

Always pass --box. Loading a project builds nothing on its own. Cromford only acts on issues labeled ai-build. Onboarding a repo says what this command does.

Open your first ticket

gh issue create -R <owner/repo> --label ai-build --title "<title>" --body "<what you want built>"

Triage reads the thread and decides if it’s ready. A ready ticket gets a plan, a build, a review by a separate session, and then a PR. That PR is your first one. Merging only happens through Cromford’s own gates, never from the build session.