platform-archive/tdobbertin-espo.forge

Public: anyone can read this; nobody can change it.

Archived from git.open-platform.sh/tdobbertin-espo/forge (retired Forgejo), 2026-11-13.

workbenchthis machine

Archived on

Something wrong? Report a problem, no account needed.

This repository has no app yet.

History

README.md

forge

A software forge you can read in an afternoon and mold by hand.

It runs the apps it hosts, and a crew of agents builds them. You describe an app in a sentence; the sentence becomes an issue, and the agent it is assigned to works it in its own fork and opens a pull. Every push redeploys that pull's own preview — its own URL, on its own copy of production's data — and every deploy is the check on that pull. No agent can move the default branch, so the only way code reaches production is a merge a person made: the crew proposes, you decide what ships.

That view is the studio, and it is the front door — a browser with no forge_mode cookie lands there. It speaks four words for the whole loop: _tell_, _working_, _look_ and _shipped_; an autonomous app lands its own green changes, and nothing waits on a person. docs/STUDIO.md is the tour; docs/APPS.md is the contract for apps, previews and runs. The git underneath is one click away — the switch in the top bar, or ?mode=dev on any URL — and it is the rest of this page.

A forge this one spawned (hosted) runs the apps it was given too: its bakery answers at bakery--<child>--<this forge's host>, in this forge's lanes, on the child's own data, and /forges says how many are running and why any is not. In the terminal an admin's palette offers "Forges you sent": each forge with its claim state and the same apps-running note, never a claim link.

Each agent's scorecard — pulls landed of opened, review rounds, red checks, reverts, time to land — is on Settings → Crew (/settings/crew) and in the terminal's palette as "Crew scorecard per agent"; both are a forge admin's only. Settings → Crew also shows, each only when it has something, a "Handed to the planner" card (issues the crew parked twice: repo, issue link, when last parked, why) and a "Restore drill" card (the last drill's pass or fail and when). The terminal's palette has the same as "Crew hand-overs", a read-only list of the same rows (repo#number, title, reasons; it does not open the issue — use the link on the page). Both are a forge admin's only. Under the agents, each team that has a pull has one pooled row (its members' counts added, the ratios taken from the sums; an agent on two teams counts in both): data-team rows on the page, "team <name>" rows in that terminal screen. Landed, review rounds and red checks stand as the last 30 days (pulls opened since then) beside all time, so tuning an agent shows as movement; reverts and time to land are all time. Under each agent, a sub-row per model and prompt version its pulls ran on (the agent's latest run on the pull decides) carries the same figures, so a change of model or brief shows against the one it replaced; pulls opened before runs recorded either read "unrecorded", and are counted, never dropped. The sub-rows list every pairing ever used; a pairing unused in the last 30 days shows dashes there. The terminal shows them as indented ↳ rows.

Scripts and agents read the same figures as JSON: GET /api/v1/crew/scorecard and the MCP scorecard tool answer {agents:[{username, all, recent, splits:[{model, prompt, …figures, recent}]}]}, where all is all time and recent the last 30 days. A ratio over nothing is null, and an agent with no pull has all and recent null. Any token of a forge admin may read it (401 with none, 403 for anyone else); the tool is listed for admins only.

Git hosting, code browsing, and a JSON API in one fast Bun process, with zero runtime dependencies — the package.json dependency list is empty and stays that way. The one exception is dev-only: @anthropic-ai/sandbox-runtime (a devDependency, with its own few transitive packages) lets test/crew-sandbox-real.test.ts run a shell under the very sandbox Claude Code builds from the crew's settings; it never ships and the app never imports it. Everything worth having is written here: the Result type, the router, the SSR templates, the design system, the markdown renderer. The only thing forge asks of the host is a git binary.

Forgejo is the reference for what a forge should _feel_ like. This is that feeling on a foundation sized for one person.

Run it

bun install          # dev-only: types + tsc (native, 7.x), no runtime deps
bun run src/main.ts  # web on :3000, ssh on :2222 (FORGE_SSH_PORT=0 turns it off; a taken port turns it off with one warning)
bun src/main.ts --preflight  # can this tree boot? config parses, migrations run on a copy of the database; one line, exit 0 or 1, no socket opened. Run it before the swap, not under load: the copy is not atomic against a live writer, and a `preflight-*` directory a killed run left behind is swept by the next run once an hour old, and a missing data directory is created, as boot would
bun src/main.ts --rollback <sha>  # swap back to a kept release: a full 40-hex sha under $FORGE_DATA/releases/, PORT as the running forge's. Exit 0 once that release reads healthy as that sha, else 1 with one line
bun src/main.ts --first-admin  # a forge with no admin: print a one-time code that makes one (below)

Apps and agent runs are contained only where bwrap (bubblewrap) and socat are on PATH (Linux); without them they run uncontained, and the boot log says so. The crew also needs the claude CLI and a model credential.

The container image pins Bun to an exact patch release in Dockerfile (test/dockerfile-pin.test.ts refuses a floating tag). To move it, change that one FROM line, run the check, and watch the first hour of /system.

Set FORGE_REPO=owner/name to the forge's own code and a pull the crew lands there is written to $FORGE_DATA/releases/<sha>/ (the newest FORGE_RELEASES_KEEP, default 5, are kept), preflighted with that tree's own --preflight, and recorded in the release table (sha, landed pull, verdict, its line, when). A red preflight is asked again once (the copy of the live database can tear under load); a second red is logged and told to the landed pull. Other repositories are untouched, and nothing is swapped unless FORGE_SELF_SWAP=1: then the forge binds its port with SO_REUSEPORT, a green release is started from releases/<sha>/ beside it on the same port (FORGE_COMMIT set to the sha), /api/v1/health is read until an answer names that sha and is well (FORGE_SWAP_BUDGET_S, default 60), and only then does this process drain as a SIGTERM does — except that it stops accepting at once, so every new connection is the release's, and answers what it already holds (a long push or clone) to the end, for up to five minutes, before it closes. A release not healthy in its budget is killed, the old keeps serving, and the log and the landed pull say so. One swap per process: a landing while another swap is in its budget, or after one succeeded, is released and recorded but not started (the new process runs it from the next restart). The SSH terminal is not handed over yet (the new process cannot bind the old one's port), so a process holding the SSH listener refuses the swap and tells the landed pull; run with FORGE_SSH_PORT=0 to swap. The swap also needs net.ipv4.tcp_migrate_req=1 (Linux 5.14+): without it the kernel resets the connections still queued on the old listener when it closes, so a swap is refused (and told to the landed pull) rather than failing requests. The release is a child of the old process, so the swap is for a forge run directly, not under a supervisor that kills its children when the old process exits (PID 1 of a container, a systemd unit with the default KillMode=control-group). SO_REUSEPORT lets any process of the forge's user bind the same port and take a share of its connections, so FORGE_SELF_SWAP=1 assumes nothing else runs as the forge's user on the host network (agents and apps are sandboxed or in cells). --rollback <sha> starts the kept release beside the running forge by the same health-read swap (FORGE_SWAP_BUDGET_S does not apply: it waits the default 60s), and a release that is not healthy is killed with the old still serving. It refuses, with one line and exit 1, a sha that is not kept (never checked out, or pruned) and a release whose schema has fewer migrations than the live database has applied (<sha> predates schema N; rolling back would need a down-migration); a release with a newer schema is allowed, as it migrates forward on boot, and the database's refusal of a future schema is unchanged. It does not drain the forge that was serving: until part 2 of the rollback does, both processes share the port and the operator stops the old one (the command prints that). It does not check tcp_migrate_req or SSH either; stopping the old process cleanly needs the same net.ipv4.tcp_migrate_req=1 setup as the swap, and the SSH port stays with the old process. /releases lists the kept releases (short sha, landed pull, when, and since when the live one has been healthy: this process's start); a person who writes the FORGE_REPO repository (never an agent: the button is hidden and the POST is a 403) gets a Roll back button on a kept, schema-compatible release, which runs the same refusals and swap and then drains this process (so it needs FORGE_SELF_SWAP=1); only readers of that repository and site admins see the page and the home line (anyone else gets a 404), and the forge's SSH terminal has the same, gated the same (src/release/gate.ts): the palette's Releases shows live: <sha> since <time> and the kept releases, only to those readers, and Enter on a rollable release asks to confirm then runs the same rollback as the button (a person who writes the repository only, never an agent; told when FORGE_SELF_SWAP is off); the home carries a live: <sha> since <time> line linking there. FORGE_REPO also names the parent code that spawned child forges fork.

Keeping a domain drill: POST /api/v1/drills (a site admin person; an agent is refused with 403, and a session needs a same-origin request) takes {domain, seen:{health, board}, backSeconds}: a domain key from docs/DOMAINS.md, what the drill read from health and the board (text, at most 8000 characters each), and whole seconds until the forge was well again (0 to 31536000). The body is capped at 32000 bytes (413). It answers 201 {id, domain, backSeconds, green, why}: the verdict is judged against the domain's own words and kept whether green or red. An unknown domain, bad seen or bad backSeconds is 422. Kept drills are read back on Settings → Backups, in its Failure domains card (below). To run a drill by hand, FORGE_TOKEN=… bun scripts/drills/run.ts <domain> --forge <url> (plain http is refused unless the host is loopback or you pass --insecure) prompts for the fault, watches health and the board until the forge is back, and posts this for you (docs/DOMAINS.md).

If your shell already has FORGE_URL set — a crew workspace sets it to the forge you work for — this forge takes it as its own canonical address and refuses every form a browser posts to localhost: run it with env -u FORGE_URL bun run src/main.ts, or set FORGE_URL to wherever you will actually browse it.

No sign-up makes the admin, not even the forge's first, and that first one is held to the signup setting and Turnstile like any other. Accounts sign up with a passkey and an email address (there is no password signup), and the browser at /signup, the API and the terminal all make an account that is not an admin. The site admin is made from the operator's terminal with --first-admin, which needs no browser at all and works whatever signup says, or, on a spawned child, by its /claim link (code that sets a forge up directly, like test fixtures, seeds one):

# One-time code, printed only here: works once, for 15 minutes, and never once
# anyone is admin. --child <name> mints for a child this forge hosts; --url
# names the address to print. The forge keeps only its hash. Run it beside
# the running forge with the same FORGE_DATA (and PORT, or --url, for the
# link); before the forge's first boot there is no database and it refuses.
bun src/main.ts --first-admin

# A person opens the printed link and makes the admin with a passkey.
# A headless agent trades the part after "#" for a token instead:
TOKEN=$(curl -sX POST localhost:3000/api/v1/first-admin \
  -d '{"code":"<code>","username":"you","email":"[email protected]","scope":"rw"}' \
  | grep -o '"token":"[^"]*"' | cut -d'"' -f4)

curl -sX POST localhost:3000/api/v1/repos -H "authorization: Bearer $TOKEN" \
  -d '{"name":"hello","visibility":"public"}'

git clone "http://you:$TOKEN@localhost:3000/you/hello.git"

POST /api/v1/first-admin takes {code, username, email, scope, name?, expiresIn?} (scope is ro, rw or admin; name names the token) and answers 201 once with {user, scope, id, token, expiresAt, expiresIn}. The token always expires: in a day (86400 seconds) unless expiresIn asks for whole seconds from 60 to 2592000 (30 days); anything else is 422 invalid_expiry and spends nothing. The account has no password or passkey and a token cannot mint tokens, so once its token lapses it cannot sign in.

If that leaves no admin with a working credential (no password, passkey, unexpired token, live session, SSH key or sign-in with the parent), running --first-admin again prints a recovery code for the stranded admin instead (--user <name> picks one when there are several). It has the same rules: it works once, for 15 minutes, only its hash is kept, and it is rate-limited. Send it to POST /api/v1/first-admin/recover with {code, scope, name?, expiresIn?} and you get back a new expiring token for that existing admin, in the same shape as above. No account is made, and each kind of code is refused at the other's door. The command refuses, and a live code dies, as long as any admin can still sign in. The audit records it as user.recovered with via: first-admin-recovery. Every refusal of the code (wrong, used, expired, replaced, or the forge already has an admin) is the same 403. Every attempt, at either door, is counted before the code is read, per address and for the whole forge, at the sign-in limits (429 past them). The account made is in the audit as user.created via: first-admin, and the sign-in page links /first-admin only while the forge has no admin. Later tokens come from Settings → Tokens, or POST /api/v1/tokens from a signed-in session with {"name", "scope"}; the admin adds "adminConfirm": true to mean a token that acts as admin. ro and rw are open to anyone; a member asking for admin gets 403 ("Only an admin can make a token with admin scope; ro and rw are open to you."), and the Settings form offers admin only to an admin.

The same token spawns a child forge (dryRun is true unless false, so without it you get the plan and nothing is made). The child's admin comes from the operator's --first-admin --child, or from the claimUrl the spawn answers once:

curl -sX POST localhost:3000/api/v1/forges -H "authorization: Bearer $TOKEN" \
  -d '{"name":"kid","dryRun":false}'
# {…, "url":"http://kid--localhost:3000", "claimUrl":"http://kid--localhost:3000/claim#…"}
bun src/main.ts --first-admin --child kid

The child keeps this forge's scheme and port at <name>--<host>, on its own data under $FORGE_DATA/children/. Browsers send *.localhost to this machine; curl needs --resolve kid--localhost:3000:127.0.0.1. The rest is in docs/SPAWN.md.

The commits the forge writes for you — merges, squashes, reverts, web edits — carry [email protected].<forge host>, never your account email. Choosing your real address is an opt-in under Commit email in /settings (or PATCH /api/v1/user with {"commitEmail":"account"}); commits you push yourself carry whatever your own git says.

Attaching the Claude app or Grok (OAuth)

Add a custom connector with the URL https://<your forge>/mcp. The client registers itself at /oauth/register (the Claude app's callback is https://claude.ai/api/mcp/auth_callback), sends you to /oauth/authorize to sign in and choose ro or rw and a token name, then exchanges a single-use 60-second code with its PKCE S256 verifier at /oauth/token for the same token Settings mints; revoke it there. Details in docs/MCP.md.

Proposal tokens

A writer of a repository can hand a child (a fork, or a project on another forge) a credential that reads this repository's code (so the child's forge can fork it), proposes, and nothing more:

curl -sX POST localhost:3000/api/v1/repos/you/hello/proposal-tokens \
  -H "authorization: Bearer $TOKEN" \
  -d '{"child":"kid","origin":"https://kid.example.com/","childRepo":"kid/hello"}'

child is lowercase words and hyphens; origin an https address; childRepo (optional) a fork of this repository, and deleting it deletes the token, as does deleting the repository. The token expires in 30 days. It is listed as proposal:<child> among your tokens, and revoking it there ends it. Over HTTPS it clones and fetches this one repository (private or not; no other repository, secret, app or issue; a fetch sees every branch, other children's child/* included), pushes only child/<name>/… branches of this repository (anything else is refused with one line) and POST …/pulls from one of them, with a body of at most 64 KiB and 20 requests a minute. Every other request is a 403, decided in src/http/proposal_gate.ts before any handler runs. A proposed pull runs no check and no preview until a writer approves its head or lets it run (Let it run here, which is not a review; a new push waits again), and a bare push to child/… starts none. A pull opened with it says "proposed by child … from …" on every tab of the pull's page, in the terminal's pull view, and as proposal in the pull's JSON (GET …/pulls/:number, and MCP's pull tool). GET …/pulls/:number?diff=0 reads the pull without its diff (and skips computing it); diff is 0 or 1, default 1, and anything else answers 422. GET …/issues?fields=brief lists issues with only number, kind, title, state, labels, assignee, author, originAuthor, authorIsAgent, createdAt and updatedAt (and untrusted where it applies); no bodies or comments. fields is brief or left out, and anything else answers 422 invalid_fields. GET …/repos/:owner/:name/events answers { items, next_cursor }, newest first, limit 1 to 200 (default 50) and cursor from next_cursor (anything else is a 422); it used to answer a bare array of every event, so a client that read the array reads items now. A request reads at most 1,000 events, so when most of them are hidden from the reader a page can come back short with a next_cursor: keep following it until it is null. MCP's events tool answers the same.

Proposing to a parent forge

A spawned forge can offer its own change to the forge it came from. The parent mints a proposal token for the child (above); the child keeps it in parent.json as "proposal": {"child": "kid", "token": "…"} beside the parent's address. On the child's /<org>/forge/following page a writer presses Propose to the parent forge (or POST …/following/propose-parent): the default branch is pushed to child/<name>/<branch>-<tip> at the parent, and the pull opens there, titled by the change that landed last and naming it (org/forge#7). Asking again for the same tip returns the pull already made.

The repository's admin changes how the forge follows its parent (tell-me or take-updates) from the radio form on the same page, with PATCH /api/v1/forge/following {"mode"}, with the MCP follow_mode tool, or by pressing m on the chain screen in the terminal. The record in parent.json is rewritten atomically and a forge.follow_mode event is appended. A non-admin is refused (403), a value outside the two modes is 422, and a severed forge is 409; each leaves parent.json untouched.

Take the N new commits (shown to the admin on /<org>/forge/following when the parent is ahead, POST /api/v1/repos/:owner/:name/following/take, the MCP take_updates tool, or t on the chain screen in the terminal) opens, or updates, the one forge/take-updates pull whatever the follow mode, and never moves the default branch; a conflict opens the converge issue instead, and nothing behind answers "Already up to date."

The page and GET …/following/proposals show each proposal as open, merged or closed, read from the parent (the token may read back only pulls it opened) and cached for a minute (only a signed-in viewer makes the parent get asked); a merged or closed one is final. A parent that does not answer shows the last state with "parent unreachable" — never an error page. In the terminal, the Chain card lists the proposals and p proposes. The MCP propose_to_parent_forge tool (writer only) proposes with the page's words, and forge_proposals lists each proposal with its state and "parent unreachable" where that applies. No dependency was added. Left out: a UI to paste the token into parent.json (part 2 of #2182 covers minting and handing over).

Minting, listing and revoking go through one action (src/actions/proposal_tokens.ts) at every door, and only a writer of the repository may; anyone else is told "no such resource here, or it is not visible to you", as the API says it. The secret is shown once, on minting. The repository's settings page is one more door: a writer sees their proposal tokens one to a line (child, origin, expires, last used) with Revoke, and a form that mints one and shows its secret once; others see no section.

The check cell's memory is on the same page under Check cell, and in the terminal on a repository's About card (I, for an admin): the limit the machine enforces, read from forge.json on the default branch. When check.limits.memory asks for more than the machine's ceiling it shows both numbers and where the cut comes from (FORGE_CELL_MEMORY_MAX_MIB, else a share of the pod's memory); otherwise one number. The ceiling is read once and kept (src/apps/check-memory.ts).

  • MCP: the proposal_tokens tool with repo and a verb: mint

(child, origin, optionally childRepo), list (the ones you minted for the repository) or revoke (id).

  • Terminal: ctrl+k, Proposal tokens, then the repository as

owner/name. n mints (the child's name, then its https address) and shows the secret once on its own screen; x revokes the one under the cursor.

Page-view beacon

Every page links one static, immutable script (src/web/beacon.ts, under 2 KB, no dependency) that sends, once per page view with sendBeacon, the route's path, TTFB, load time, LCP, INP (the worst interaction) and CLS to POST /_measure. The route is same-origin only, validates every field, caps the body at 512 bytes and the rate per client, and answers 204. Reports land in page_vital (bun:sqlite) keyed by route pattern; no IP and no user agent string is stored. A unique visitor is a hash under a salt that rotates daily (yesterday's salt is deleted), rows are kept 90 days. Do-Not-Track and the forge_measure=off cookie send nothing, and the server stores nothing for them either. The CSP is unchanged: the script is nonce'd like the shell's.

How long the golden path took

An app's repository home wears the pace on its app strip, the terminal's Deploys screen shows it under the title, /apps (and any shelf of apps) says first preview 14s in each row's meta line once one has served (one grouped query, firstPreviews; the terminal has no apps list of its own to carry it), and GET /api/v1/repos/:owner/:name/app returns it as firstPreviewMs and firstProductionChangeMs. It measures milliseconds from New app to the first preview that served, and from New app to the first production deploy that began after the first merged pull; a figure is left out until it exists. Anyone who can read the repository sees it (goldenPath in src/apps/golden_path.ts, appPace for the terminal).

Every app's visitors

An app made from the template ships the same beacon as static/beacon.js, posting to POST /__forge/measure on the app's own host. The forge answers that door itself (src/apps/measure.ts), before the app is woken: same-origin only, 30 reports a minute per client and 600 per app (429), a body over the cap is a 413, and a private app or a sealed pull's preview refuses anyone its gate refuses. The app is the host's, never the body's. Production reports are kept in app_vital (src/apps/vitals.ts, TTFB, load, LCP, INP and CLS, a visitor hashed under the day's salt, no address, kept 90 days and removed with the app, at most 20,000 rows per app a day); previews store nothing. Only Do-Not-Track opts a visitor out on an app's host: the forge_measure=off cookie is set on the forge's host and never reaches an app's. Read the numbers (visitors today and over 7 days, p75 TTFB, load, LCP, INP and CLS) on the app's settings page under Visitors and speed, or as vitals in an admin's GET /api/v1/repos/:owner/:name/app. Both doors show them only to people who administer the repository (appVisitors in src/actions/apps.ts), so a reader or an anonymous caller sees no vitals. The page also draws p75 load for each of the last 30 days as a sparkline (server-rendered, no script); a day with no reports is a gap in the line, not a zero, and an app with none in 30 days says so in words. The same 30 values, oldest first with null for a silent day, are vitals.loadDays in the API. In the terminal all five are on the second line of the app's Deploys screen over ssh, and a third line there shows the 30 days as block characters with · for a silent day, then the range.

The app_vital board source (src/boards/sources.ts) charts those reports: one row per app per day with app (the app's id), day, load_p75, inp_p75 (ms) and reports (rows kept that day), the percentiles nearest-rank per app per day as reach does. max or avg over several days summarises daily percentiles, not the percentile of the whole range. Its rows belong to the app's repository, so a query sees only the repos in its scope. Today boards query with repoIds: "all" (src/web/pages/boards.ts) and only a site admin reaches them; no non-admin scope exists, so nothing yet applies the settings page's canAdmin gate per repository, and whoever builds one must. Days older than the 90-day trim are gone, not zero. The slug and the visitor hash are not columns. No dependency was added. Left out: a starting board for it; pick app_vital in the /boards source picker.

The board's notes

/board opens on its panels. Everything that is not a panel — the forge's health (admins), a planner that declined and waits for you, agent pulls that wait for your review — is folded into one quiet line under the title, "3 notes · 2 need you". It is closed by default; click it (or Tab to it and press Enter) to open the list in place, and it stays open across live updates. A declined planner has its answer box right in its note. The crew's own housekeeping (an issue parked twice) is not a note; it is on /map. The terminal's first screen says the declined and review-wait notes too, one line each, under the forge strip; a list cut to three says "+N more". The line is the shared .quiet-details disclosure, and the "need you" count carries the attention dot.

Live in the terminal

ssh into the forge and you get the whole thing — repositories, code, issues, pull requests with a real diff viewer, review comments, merges, settings, tokens and keys — as a keyboard-driven terminal app. The same port serves git.

ssh -p 2222 localhost                        # the terminal UI
git clone ssh://localhost:2222/you/hello.git # git, same port

A big repository clones over either transport. To skip its large files until a checkout needs them, run git clone --filter=blob:none <url>. See docs/GIT.md.

After a GitHub migration you choose what happens to the original: leave it alone (the default), archive it, or keep it as a read-only mirror. The choice is the "Afterwards" field on /migrate, in the terminal's migrate screen, and after (leave, archive, mirror) on POST /api/v1/migrate. Archive marks the GitHub repository archived using the account you connected. Mirror leaves GitHub untouched at first, then copies later changes on the branches GitHub had at migration back to it; branches made afterwards, such as the crew's work branches and pull heads, stay on the forge. If someone pushes to GitHub meanwhile, the forge stops rather than overwrite them, and the repository's settings page (and the terminal's status line) says why it stopped and when it last pushed. "Stop mirroring" there, or U in the terminal, ends it and leaves GitHub as it is. Archiving needs admin rights on GitHub: without them the migration still succeeds and says the repository was not archived, so you can do it there yourself. Only repositories read through a connected origin have an original to change; a pasted URL does not.

Migrate from the terminal. Press M on the dashboard (or pick "Migrate a repository" in the palette, ctrl+k). The list is your connected origins' repositories, private ones marked; / filters it and u pastes a URL instead. Enter on a repository lists its branches with their last commit, your own newest first and marked "(suggested)", so Enter again takes it; a pasted URL skips this step. The form asks for name, owner, visibility, agent, autonomy and afterwards (leave the original alone, archive it, or keep it as a mirror; tab moves, space changes); ctrl+d migrates. The job is a checklist of stages: esc hides it and never cancels, and a toast says when it lands, on the new repository. It is the same migrateRepo as /migrate and POST /api/v1/migrate: the chosen branch becomes the default branch and the crew's brief says the app lives on it. The web form takes it too (it lists the picked repository's branches newest first), as does the API's branch field.

A GitHub migration also carries each milestone (title, description, due date, open or closed) as an issue here, with the due date and GitHub's milestone number kept in milestone_origin; carrying again makes no duplicates. Which issues belong to a milestone is not carried yet.

On a forge made for a client (one that was spawned, signed in by its claim link), the home is their apps, one plain sentence each and one more saying whether its agents are working, about to start, or waiting: no map, board or settings until asked. /?all=1 is the whole home, and its "Just my apps" link comes back. Each app row also says what its agents are on ("Working on: …") or the last change landed in the past 7 days ("Last change: …, 3 days ago"); a quiet app says nothing more. The terminal's first screen opens with the same lines, from the same queries (src/core/client-apps.ts).

Home shows nine figures first, from src/flow/kpis.ts: shipped per hour (with a 24 h sparkline), the live version and since when, the median check time, the crew builders running of their slots, and the crew's spend today of the forge's daily ceiling (FORGE_CREW_CEILING_USD; without one, the spend alone and no ceiling), and the age of the last off-box backup (the newer of the mirror's newest snapshot, mirror/state.json, and the newest that landed in a destination that is a bucket, snapshot/state.json; src/snapshot/off_box.ts; 3 h ago, the exact time in its title), linking to /settings/backups. The spend tile links to /settings/crew, where the meter is. The backup tile past 24 hours, or with none (never), takes the card's existing data-tone="attn" and says overdue in its label. The last three (src/flow/reach.ts, the reach board source's rows) are visitors (5 today, 31 in 7 days), accounts (1 of 2, signed in today) and page speed (the slowest quarter's page load over 7 days, and reacts in 180 ms, the same for the delay after a tap), from the page-view beacon. Each links to the Reach starting board (/boards/reach). The visitor hash rotates daily, so the 7-day visitors is each day's distinct count summed. They count every repository, so only a site admin sees them, on both doors; nobody else does, and neither does the lean client home. On the web each is a card linking to /board, /releases, /boards or /boards/reach. The terminal's first screen shows the same nine as lines above the forge strip (kpiLines in src/flow/kpi_words.ts). They are read when the page or screen loads and do not refresh on their own.

On a host that cannot hold cells or the crew's shell sandbox, a site admin sees Reduced protection: … in one line, under the filter on the terminal's first screen and in the web footer; nobody else does, and a fully protected forge shows nothing.

A new version proves itself once per version: after a boot that changes FORGE_VERSION, the forge waits (up to 10 minutes) for its public URL to answer /healthz as that version, then runs the smoke checks (src/release/smoke.ts) against it and keeps the verdict in $FORGE_APP_DATA/release/proof.json. A failure is a Release X is unproven: … card on an admin's board and on the terminal's first screen (the same cards), and is paged once; a later passing version clears it.

The outsider suite (#663) is the proof a person reads before flipping signup to open. It adds the proof only: it removes no gate and reopens nothing. signup-gate.yaml and outsider-gate.yaml in trevato-apps/gitops stay up until a person deletes them there.

It tries what a stranger must not do through all the doors a stranger has:

  • HTTP API and web form (src/release/outsider.ts): an admin token, a

repository or app of their own, any read of the owner's private repositories, and assigning a crew member on a real issue — the JSON PUT …/issues/:n/assignee with a token, and the form POST /:owner/:name/issues/:n/assignee with the cookie session a browser would hold. A refusal is positively seen: a 403 with its error code, a 404 only for private repositories, or a redirect whose landing page says so. The issue is read back and its assignee and the repository's runs must not have moved, and the owner's own call to the assignee route must answer 422 so a rename turns the suite red.

  • MCP (same module): tell, make_it_yours, signup, and reads of

private repositories through repo, usage and apps, each required to answer as an error; tools/list must still name them.

  • Terminal (test/helpers/outsider-tty.ts, run by

test/outsider-tty.test.ts): the stranger drives the terminal in process, asks for a new repository, searches for a private one and opens the assign picker on a public issue; the screen must show the refusal and nothing may change. The terminal is a client of the forge's actions, not of HTTP, so it cannot be driven against a live forge: it runs in the gate only.

test/outsider-suite.test.ts and test/outsider-tty.test.ts run in the gate and each prove the suite goes red with a door left open. FORGE_TOKEN=… bun scripts/smoke.ts <url> --outsider runs the HTTP and MCP doors against a live forge. It makes a real account on that forge, so point it only where that is wanted. Its result is valid for reopening signup only together with a green gate run of the terminal test; HTTP and MCP green alone do not cover the terminal door. Without FORGE_TOKEN, --outsider exits 2 and the suite reports owner token as not tried, so a partial run is never read as a pass. Spend and run bounds are proven in process only; this pull adds the proof but does not reopen signup — the gitops gate stays for a person.

bun scripts/smoke.ts <url> --standards prints the website-specification report (src/release/webspec.ts, webspec-site.ts): it fetches each path in forge.json's app.looks from <url> and prints one line per finding with the specification.website section it cites. Head and header findings come per path. Once per site it also checks the well-known files (robots.txt and the sitemap it names, with each listed same-origin URL, at most 50, fetched anonymously; /.well-known/security.txt with a future Expires:; the web manifest with a name and icons; /llms.txt; /.well-known/change-password redirecting) and the error pages (a random path must answer 404 with the app's own HTML page). --error-path <path> names a path that is meant to answer 500 with the custom page; the 500 check runs only when it is named, because the report never causes an error on its own. It only reports and always exits 0. (edge) marks a finding the edge in front of the app may own (HSTS), so fix it there rather than in the app. Each fetch gives up after 10 seconds.

--standards also runs axe-core (src/release/axe.ts) over each path in light and dark and loads each with JavaScript off, reporting an empty <main> or a missing <h1>; it needs chromium on PATH or FORGE_CHROMIUM (without one it falls back to a regex read of the served HTML). axe-core is a devDependency of this check only, never loaded by the server: its rules need a rendered page and an accessibility tree, which nothing dependency-free gives.

What you asked for: Ctrl+K, then Asked, is /asked in the terminal — your thoughts, then the issues you can write to that are not shipped, oldest first (j/k move, enter gives the issue's web address, r refreshes). It is read only, shows a guest nothing, and names nothing of a placement in a repository you cannot read.

Review: /review lists the asks waiting on you, one row each (title, repository, age, why, and the crew's advice or that it has not advised yet), newest first. A pull's row also carries the check verdict for its head (the pull page's badge: passed, failed, running, cancelled, or none) in the row's trail, and, when its repository is an app, an "Open the preview" link under it (shown for any app, even before a preview is deployed); and, when the pull has a look the viewer may fetch, its preview thumbnail beside production's under that (sized, lazy, never inside the row's link; the pull's is the only link, named for a screen reader, and production's is a named picture; a viewer who may not fetch it sees none); all of it comes from the database, never git. The row's trail also says the pull's size (3 files changed, +40 −7), kept per base and head commit (src/web/studio/review_evidence.ts); a request never waits on git: until the stat is kept the row says "Diff loading — reload for the size" while the app computes it in the background (at most 4 at once, stopped by closing the app), and a failed stat says "Diff size unavailable" and is not asked again for a minute, so a bad pull cannot spawn git on every visit. Visits while a stat is running share it. It only reads; the buttons stay on /asks, which links to it, and signed out it sends you to sign-in. The terminal has no page of its own for it: the same asks are the dashboard's On you card.

A client's forge: Ctrl+K, then New forge (any signed-in person's, as the page is), is /forges/new in the terminal — name, for whom, what it is for, apps to fork (owner/name, comma-separated), a fresh one-line app, model key (hidden as typed), API base URL and budget, through the same spawnDoor as the page, POST /api/v1/forges and the MCP spawn. Ctrl+P shows the plan and makes nothing; enter on the plan spawns, and the claim link is shown once, in a dialog, never kept.

The family across forges: : → Family in the terminal, /family on the web, GET /api/v1/family and the MCP family tool all give the same view. The forge that sent this one is shown to anyone; the forges it sent, only to a site admin (docs/SPAWN.md, "The family across forges"). Each sent forge also says how many of its apps run and names those that do not ("1 of 2 apps running — bakery asleep").

Passkeys: Settings → Passkeys lists, adds and removes them (several per account; src/auth/webauthn.ts verifies, no dependency, none attestation). The sign-in page's "Sign in with a passkey" gives the same HttpOnly session a password does. Lost your device? "Lost your device?" on the sign-in page leads to /recover: give the email on your account and, if it is verified, a link that lasts 30 minutes and works once registers a new passkey and signs you in. The relying party is the address the browser used (or FORGE_URL), so a passkey does not follow a forge to another hostname. Sign-up is a username and a password of at least 12 characters (/signup, POST /api/v1/users with {username, password, email?}, the terminal), hashed with argon2id; the email is optional and, when given, gets the verify link (an account with none has nothing to prove). A passkey (src/web/pages/signup-passkey.ts, which does take an email) is offered beside the password. Nothing in the path touches an edge, parent or Forgejo account. An operator can still refuse password sign-ups with passkeyOnlySignup. The owner claim of a spawned forge (/claim, web/pages/claim.ts) takes the same: a username and a password with the email optional, or a passkey (which needs an email; challenges from POST /claim/options), and a claim with neither a long enough password nor a passkey is refused without spending the link. An admin's everyday account (web/pages/everyday.ts) still makes its account with a passkey only (web/passkey-ceremony.ts, challenges from POST /settings/everyday/options): it reads no password, and without JavaScript the page says a passkey needs it.

Password checks are bounded (src/core/hash-gate.ts): at most 4 argon2 verifications run at once, and a password over 1024 bytes is never hashed and cannot be set (sign-up, claim and change-password refuse it with "Use 1024 bytes or fewer."). A check over the cap is refused at once, not queued: the caller sees the same throttled answer as a full sign-in window (429 with Retry-After: 1 on HTTP Basic, the API and the sign-in page, "try again" in the terminal; an over-long Basic password is a plain 401), and the attempt is given back to the sign-in windows. The 4-hash cap is a deliberate trade-off: an attacker who keeps 4 hashes busy can make real sign-ins get "try again in 1s"; the per-source sign-in window is what limits how long they can.

A forge with a parent (FORGE_PARENT_URL, or the upstream in a spawned forge's parent.json) lists the parent under "Link an account you have" on /signin. The forge registers itself once at the parent's /oauth/register (the client id is kept in rp_client), sends the person through the parent's authorize page with PKCE, and on return checks state (also bound to the browser by an HttpOnly cookie), nonce, iss, aud, exp and the ES256 signature against the parent's JWKS (kernel/jwt.ts; keys are cached ten minutes and an unknown kid refetches them once a minute at most). The parent's sub — never the username — maps to a local account that is already linked to it; a sub nobody holds makes no user and ends on /signup (#2883) (core/federation.ts; http/rp.ts has the two routes). No dependency added. The parent's answers are read by bytes and refused past 16 KiB (64 KiB for the key set), and starting a sign-in is throttled like a password attempt. An account made this way has no password, so the terminal's username-and-password door (s) cannot let that person in. They add an SSH key under Settings → Keys once signed in on the web; after that the terminal signs them straight in as that account, as for anyone with a key.

Your SSH key is your identity. A key the forge knows signs you straight in; any other key browses public repos as a guest and can press s to sign in with a username and password — which links that key to your account, so the next connection is instant. j/k to move, enter to open, esc to go back, / to filter, ? for the keys, : for the command palette, t for the theme.

Milestones. : → Milestones in a repository → owner/name lists a repository's limbs in the order the crew takes ready work (enter opens a limb's own limbs). A person who administers the repository presses r to Raise or l to Lower the limb under the cursor: a preview of the new order and of the top of the ready list first, then enter to apply (esc backs out), then u to undo the last move. p hands the limb to the planner to re-plan as fewer, larger pieces: it lists what the planner will be given, then enter confirms; the row reads with the planner, and p takes it back until the planner starts. It is the same fleet operation the web milestones page uses, and a move is heard by that page when it is open. Anyone else sees the order and no keys to change it; a guest sees only what the web shows them. Whoever may see owner facts also gets two lines under the list for the limb under the cursor: Cost and landed (dollars spent, changes landed) and its costliest three issues; a reader or guest sees none. The web page has the same Cost and landed section on a milestone, and the milestones API and MCP carry it as spend (usd, landed, costliest), owner only.

Working on the UI itself? bun run src/tui/main.ts --user alice runs it over stdio against your local data directory. That --user flag is a development convenience and exists only there: over SSH, the key decides who you are and nothing else can.

Configuration is environment variables, all with defaults: FORGE_DATA (data/; the forge refuses to boot when it is the checkout itself or a path inside it that git does not ignore), PORT (3000), FORGE_SSH_PORT (2222; 0 turns SSH off), and FORGE_HOST (localhost, the hostname in clone URLs). FORGE_DRAIN_LINGER_S (10, 0 to 120) is how long a forge sent SIGTERM keeps answering while routers learn it is going, so a roll refuses nobody (docs/ops/ROLL.md). Connecting origins adds FORGE_URL (the canonical public base URL, needed for OAuth callbacks), FORGE_GITHUB_CLIENT_ID / FORGE_GITHUB_CLIENT_SECRET, and FORGE_ORIGIN_ALLOW (hosts an operator vouches for on a LAN). Behind a platform edge that signs people in for every app it serves, FORGE_EDGE_TOKEN is the edge's secret: a request carrying it and X-Plat-User is that person, signed in by the platform if an account of that name exists. An unknown login makes none: it is sent to /signup, where the signup setting decides, and the name there is pinned to the login the edge vouched for (a visitor the edge has not vouched for is sent through it first), so a platform user's name can never be taken by someone else. The terminal cannot see X-Plat-User, so behind an edge sign-up is on the web page only and the terminal says so. Setting signin.edge to off (Settings → Capacity → "Sign in through the platform edge", boot default FORGE_SIGNIN_EDGE, also /api/v1/admin/capacity and the MCP capacity tool) makes the forge ignore X-Plat-User even when the secret matches; people then sign in with a password or a passkey. An admin with neither is refused, so no one locks themselves out. Accounts the edge made cannot sign in while it is off until they add a passkey (a password-less account cannot set a password: /settings/password asks for the current one). Account settings show "open-platform.sh: linked as <login>" or "not linked": Link records the login the request carries against the signed-in account, Unlink removes it (same-origin POSTs). An edge sign-in finds the account by its link first, then by name; one login links to one account, and a login that is another account's name cannot be linked. The terminal's "What I can do" screen shows the same line and u unlinks (SSH carries no edge header, so linking is on the web page only). On a forge with a parent, settings also show "<parent host>: linked" or "not linked". Link is a same-origin POST that runs the /signin/parent PKCE round trip for the signed-in account and, on return, writes its federated_identity row (never an account); an identity another account holds, or a second identity for this account, is refused. Unlink removes it. The terminal's "What I can do" shows the line and p unlinks; linking needs a browser. Mail out (the link that proves a newcomer's email) is SMTP submission over TLS, configured by the forge-level secrets MAIL_SMTP_URL (smtps://user:pass@host:465) and MAIL_FROM, set live under Settings → Secrets, or at boot by FORGE_SMTP_URL / FORGE_MAIL_FROM. With neither, no mail is sent and a newcomer waits for the owner to verify them. With FORGE_TURNSTILE_SECRET and FORGE_TURNSTILE_SITEKEY set (the forge refuses to boot with only the secret), /signup renders the Turnstile widget, its CSP allows https://challenges.cloudflare.com, and signup asks Cloudflare's siteverify about the posted cf-turnstile-response (API: turnstile_token), refusing a missing or bad token before it hashes a password or makes an account. Unset, signup is open. The terminal (SSH) cannot show a widget, so with Turnstile on it creates no account, the forge's first neither; everyone is told to sign up on the web page. Accounts made through the platform edge are not checked. Behind a proxy, FORGE_TRUSTED_PROXIES (comma-separated CIDR ranges, e.g. 10.42.0.0/16 for a k3s ingress) names the proxies allowed to say who the client is; limits for strangers and the signup audit then see each outside client, read from X-Forwarded-For right to left past the trusted hops, or from FORGE_CLIENT_IP_HEADER when the edge sets one (cf-connecting-ip behind a Cloudflare tunnel, where the ingress rewrites X-Forwarded-For; read only from a listed proxy). Once set, only the listed ranges are proxies: this machine is not one unless listed, since every app runs beside the forge. Unset, only this machine may say so, and the named header is never read. Everything a forge instance _is_ lives under the data directory — the SQLite index, the bare repos, and the SSH host key, in plain layout. Tar it up and it moves.

/forges/new, POST /api/v1/forges and the MCP spawn make a client's forge from forks of the apps you pick, plus optionally one fresh app from a one-line description (fresh, at most 200 characters), and end in one claim link; see docs/SPAWN.md.

FORGE_PARENT_URL names the forge this one was spawned from. It must be https:// with no credentials or query (the forge refuses to boot otherwise). The parent serves /releases.json as {"releases":[{"name","url"}]}, newest first; the child reads it with a 3 s timeout, no redirects and a 256 KB cap, caches it under FORGE_APP_DATA for 10 minutes, and says "N releases behind <parent>" on a fork's following card, in the terminal's About card (I), and as parentForge ({host, behind, releases, fetchedAt, down}, null when unset) in GET /api/v1/repos/:owner/:name/following and the MCP following tool. A page never waits for the parent: it shows the cached copy and refreshes in the background, and a parent that is down or answering garbage leaves a "could not be reached" with the age of the last copy. Unset, nothing is shown. Read only: taking a release is not done here. This forge publishes its own /releases.json (the version names, each linking to that document), so any forge can be a parent. The terminal shows the count, not the release names.

A spawned forge's own code is a fork of its parent's (<org>/forge, chosen followMode tell-me or take-updates; in take-updates the hourly check puts what the parent gained in a pull. A spawn may also name a size: small, medium or large (src/spawn/sizes.ts maps each to CPU, memory and disk). It is recorded in the plan only when given, so a plan without one hashes as it always did, and an unknown size is a 422 on size. Nothing enforces the limits yet, and the table's numbers are provisional. GET /api/v1/forges/sizes (no sign-in, ETag, cached for 5 minutes) and the MCP tool sizes give the same answer — each size's CPU, memory and disk, read from that table, and one sentence on what it is for — so a page or an agent offering a size reads it there. Once an hour, and on demand, a forge that follows and has not severed fetches its parent's code into refs/upstream/* of its own <org>/forge (no branch of the fork moves) and keeps { behind, parentTip, checkedAt, error } in upstream.json under FORGE_APP_DATA; the count shows on the chain page, in the terminal's Chain (c checks now), and as upstream in the API and MCP payloads. POST /:owner/forge/following/check (a writer, same-origin) checks on demand; a fetch is cut at 60 s and a failure is recorded, not thrown. In take-updates the check then puts refs/upstream/HEAD (a fast-forward, or a clean merge commit) on the fork's forge/take-updates branch and opens one pull, "Take updates from <parent>", into main, or updates that pull when it is open (spawn/take.ts); the fork's check runs on it like on any pull and a person merges it. Main is never moved, so nothing deploys by itself. It is recorded as taken in upstream.json (the chain line reads "N commits from your parent are in pull #P") and as a forge.updates_taken event; a pull closed unmerged is not reopened until the parent moves again. forge/take-updates belongs to the check: a commit a person pushes there is overwritten by the next check that finds something different to put on it (open a branch of your own to build on it). On a conflict nothing changes and one open issue, "Take updates from <parent>", names the files. In tell-me, a new parent tip makes one inbox card for the owner (an issue on the fork assigned to them, "Your parent forge has N new commits", linking the chain page); toldTip in upstream.json keeps it to one per tip, and take-updates or a severed link makes none. Its chain to the root is at /:owner/forge/following, in chain of GET /api/v1/repos/:owner/forge/following and the MCP following tool, and in the terminal's Chain command; the owner severs it with the page's Sever, POST …/following/sever or the MCP sever tool (nothing is deleted). Taking updates into a conflict opens the converge issue at every door. See docs/SPAWN.md and docs/FOLLOWING.md.

Who can see it

Every repository page says, beside the Private/Public badge, who can see it in one sentence ("Private: only you and the crew."), and a writer's click goes to Settings. GET /api/v1/repos/:owner/:name returns the same words as audience: { level, sentence }, the MCP repo tool carries it too, and the terminal's About card (I) shows it. It gives counts, never names; site admins are not counted. All of them read audienceFor in src/core/audience.ts.

Archive

An admin puts a repository away from Settings → Archive, with PATCH /api/v1/repos/:owner/:name {"archived":true|false} (admins only; anyone else gets 403), or in the terminal with a on the About card (I). The repository page and the card then say when it was archived, and an admin gets a Wake button or the same key to undo it. Archiving twice keeps the first date. An archived repository starts no new crew run. Assigning an issue to an agent, queueing a run again, asking the crew to propose a resolution, redirecting a wave and converging a fork each answer "This repository is archived; wake it to start a run."; the API answers 409 archived, and the terminal and MCP show the same line. The autonomy tick skips it. A run already going finishes, and Wake undoes all of it. Clone, push and links keep working, and the repository page still answers.

An archived repository leaves the web home's apps, the inbox (work assigned to you there included, and the terminal's and MCP's asks), the stalled-steps reader and the explorer's default view; /explore shows it with archived:yes (the Show archived toggle). It stays in /apps, search, the palette and the repository API (GET /api/v1/repos).

/apps lists live (unarchived) apps only, with an "N archived" line linking to /apps?archived=1, which lists just the archived ones (no All/Live filters, one "Back to apps" link); each view reads its own window of 200 repositories. In the SSH terminal the dashboard's Yours leaves archived repositories out too; type in its filter (/) to reach them, as the filter searches every repository you can see.

A site admin archives many at once from the home. In the Your apps card, Select shows a checkbox per app (they take no room until then); tick some and press Archive. This is the fleet's archive operation over those repositories (POST /home/archive, same-origin, a site admin's), so it has the fleet's receipt: the page that answers lists what was archived and an Undo button for the person who ran it (kept for a day), after which the apps are back on the home. The terminal's dashboard archives and undoes the same way (below), and so does the MCP archive tool given repos (at most 50; it answers the operation id, which limb with action: "undo" reverts for a day); each door refreshes an open web home (the fleet.operated event).

Where it came from

A repository brought here with Migrate (/migrate) keeps where it came from as links, never as a connection: the source's address, and — when its host says it is a fork — what it forks (GitHub's parent and source, Forgejo's and Gitea's parent; a pasted address's host is asked once, anonymously, after the clone). The repository header then reads "Migrated from github.com/Trevato/SO-ARM100 · fork of TheRobotStudio/SO-ARM100", each part a link up. A fork made here of a migrated repository inherits its parent's trail and reads "forked from … · migrated from … · fork of …" — at every door below, for anyone who may read the parent; only the parent's admin can hide that inherited part, and a fork's own record, if it has one, wins. The terminal's About card (I) shows the same as migrated from and fork of rows, GET /api/v1/repos/:owner/:name as provenance { source, sourceUrl, parents: [{ fullName, url }], migratedAt }, and the MCP repo tool the same field.

An admin turns it off with Settings → Show where this came from, PATCH /api/v1/repos/:owner/:name {"showProvenance":false}, t on the About card, or the MCP trail tool (dry by default, admin scope). Off hides the line on every page, in the terminal, and provenance is null in the API and MCP; the record is kept, so on brings it back as it was. A source that was private on its connected origin starts off, whatever it is migrated here as: its name and owner on the other host are not published until an admin turns the line on (a later re-record never overrides that choice). It is a person's call: anyone else, an agent included, is refused (the API answers 404 before any other field in the same request is saved). Repositories migrated from a pasted address before this existed were filled in from their migration's push event, without a fork chain; one picked from a connected origin then has none.

Search

/search answers repositories and issues in full, and greps code repository by repository. A first search starts no new git grep after 30 ms (codeBudgetMs in the forge config; a soft stop, since the grep in flight still finishes, one batch of four) and shows what it has with one link, More code results (?code=all), that greps the rest. The API and the terminal palette always grep everything.

Health

GET /api/v1/health (and the MCP health tool) answer a site admin with degraded: one entry per thing that needs a person, {cause, sentence, since, href}. cause is a stable key (disk, errors, internal, queue:<kind>, stuck:<runId>, budget:<runId>); since is when it began, by the oldest evidence (oldest queued run, last heartbeat, oldest error or refused call in the hour) or else the first time the forge saw it, and holds until the cause clears; href is the page to look at. The board's forge strip links each entry, and the terminal dashboard prints each with its start. When the guard view holds something that needs a person (a held or stuck rollout, an OOM kill, or a platform view gone stale), the board's strip and the terminal dashboard both lead with one line, needs you: forge <what>, and do not repeat it as a rollout line. A drain that runs too long is not on either; it is a push, not a door: an admin with a notify URL is paged once when a drain passes five minutes and once, by the draining process as it exits, when it ends. A process that dies mid-drain says nothing more.

The same push pages the vitals causes errors, internal, queue: and disk once each has held five minutes, and says Recovered once it has been gone five (a flap in between is no news). A cause present at boot is taken as already paged. Every other cause (drill, mirror, stuck:, red:, snapshots, budget:) is paged elsewhere or is a setting, and is ignored here.

Origins

Outbound git refuses a host that resolves to a private address. A site admin can vouch for exact host names (the owner's own Forgejo, reached by its in-cluster address): FORGE_OUTBOUND_TRUSTED_HOSTS=git.example.test (comma or space separated), plus the same list editable by an admin on Settings → Origins. A trusted host may resolve privately for origin sync, mirror, migrate and write-through; trust is by name, never by address range, and webhooks never read it. The origin row says "trusted internal host". In the terminal, the palette's Trusted hosts reads and saves the same list (admins only, same audit). An entry that is not a bare host name (an address, a wildcard, a URL) is refused with its name, on the page and in the terminal, never silently dropped.

Your forge is the index of everything you work on, wherever it actually lives. An origin is a connected account on another forge — GitHub, Forgejo, Gitea. Mirror a repository in and its issues, pulls, comments and labels come with the git objects; anything you then do here is written through to the origin first and reflected locally after it succeeds. For a mirror the origin is truth, exactly as git is truth for a native repo.

Resolving a conflicted pull. When a pull conflicts with its base, a writer sees Resolve in the "Can't merge" box, which opens /:owner/:name/pulls/:n/resolve: one file at a time, each conflict block a card with the two sides named by their branch and the taps Ours, Theirs, Both and Mine (words typed in the box count as Mine), a running "2 of 3 resolved", and the merged file beneath. The choices ride in the query string until you press Finish, which commits them: the resolved file becomes a merge commit on the pull's branch (as you, the base as second parent, built with git plumbing — no clone, no agent), and the pull re-checks as mergeable. Finish is for writers with rw scope and refuses, writing nothing, when the branch or base moved since the page was drawn, when a block has no choice, when the pull has more than one conflicted file or a conflict with no text blocks, and for cross-repo or mirrored pulls. In the terminal, v on a conflicted pull does the same: n/p move over the blocks, o/t/b take ours, theirs or both, e opens a box for your own text, each file shows "N of M resolved" with its merged file beneath, and f finishes with the same refusals in words. On a conflicted pull held by an agent, the same page (and the same view in the terminal) also offers Have the crew propose to writers with rw scope: it queues one resolve run for that agent, on the pull's own branch, with a brief carrying both sides' commits, the conflict blocks and the tests that cover them. The agent merges the base in, commits the resolution and pushes; its report becomes the note on the pull. Until the run settles the card says it is working and refreshes itself on the run's events (in the terminal, r looks again and never asks), and a run that fails says why. When it lands the card shows the note, the commit the run left (kept on the run, so a later push is never called the crew's) and the files to edit by hand; once the head moves on, the card goes. The tap is refused, writing nothing, for a reader, a closed pull, a pull with no conflicts, a pull no agent holds, one the crew is already working on, and when the crew's ceiling or breaker has no room. In the terminal c in the conflict view is the only key that asks, with the same refusals in the same words. See docs/PULLS.md. Readers and guests get neither.

Read the whole README

↑↓ navigate ↵ open esc close

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs