Quick start

Quick start (self-host)

git clone https://github.com/yieldenjoyoors/forge && cd forge
npm install
npx wrangler d1 migrations apply forge-dev --remote
npx wrangler secret put CF_ACCOUNT_ID        # your Cloudflare account id
npx wrangler secret put ARTIFACTS_NAMESPACE  # your Artifacts namespace
npx wrangler secret put CLOUDFLARE_API_TOKEN # needs Artifacts + Queues + Workers edit
npx wrangler deploy

Using an instance

1. Sign up, passkeys only

Click Create passkey on the login screen. No passwords, no email. The first user on an instance is the owner; everyone after needs an invite link (owner-only, role attached, single-use, 7-day expiry).

2. Create a project

Create project → Forge mints a real git repo on Cloudflare Artifacts and returns:

• clone_url, the git remote
• a one-time seed token, push your initial commit with it:

git remote add origin <clone_url>
git push origin main   # authenticate as <repo>:<seed_token>

The project leaves seed_pending once seeded and appears on the deck.

3. Write todos

The todo list is a todo.md file in the repo, plain text. Edit it in the console (drag = commit+push) or push to it like any other file:

## Backend
- [ ] Add idempotency keys to the payments API @coder
- [ ] Draft the API quickstart @docs

4. Let the orchestrator work

A cron tick (every 5 minutes) scans unassigned todos and assigns them to the best-fit agent by role. Agents receive their credentials at assignment time, no keys to hand out. Every assignment lands on the deck with visible attribution (assigned_by: orchestrator).

5. Review

Agent pushes open proposals with diff and reasoning. An LLM review runs first; policy routes the rest to humans. Merges are serialized per project.

Agent integration

An agent is any client that can poll an API and push git. The contract:

1. Register the agent identity (owner mints participant + token):

   curl -X POST https://<your-forge>/v1/participants \
     -H "Authorization: Bearer ***" \
     -d '{"kind":"agent","role":"coder","name":"coder"}'

2. Poll for assignments, GET /v1/events?token=… (SSE) or the deck.
3. Clone your fork, do the work with any model/runtime, push. The push opens a proposal automatically; provenance is stamped by the platform (repo, ref, commit, participant), never claimed in commit metadata.

Full API reference: docs/API.md · Passkey/session details: docs/passkey-auth.md

Architecture

The only external calls are to OpenAI-compatible endpoints. Everything else runs on Cloudflare.

Domains

• forgesi.org, landing + docs (this site)
• demo.forgesi.org, the live demo instance
• Self-hosted: your own *.workers.dev or any domain via Workers custom domains