Forge packs: a premade forge to deploy (/packs)
A pack is a pack.json in a repository (src/packs/pack.ts holds the format, version 1): a name, title, semver version, description, the apps it brings (each a source that is either an https address of a public git repository or owner/name of a repository on a forge, with a name and description) and the crew it starts with (username, roles of planner/builder/reviewer, a brief, optionally a model and a per-run budget). Anyone can publish one. A pack may not carry data, secrets or variables: any key that names one (secret, env, token, data, key…) at any depth is refused, not ignored.
A pack is a public forge repo with a pack.json at its root, named like the pack (packs/games, packs/business); its apps may name forge repos (packs/2048). Nothing ships in the source tree or the image: an admin lists the repos /packs shows in Settings › Packs (the packs.repos setting, kept in forge_setting_change), and src/packs/catalog.ts reads each one's pack.json from git at its default branch. A repo not listed is not a pack; a listed one that is missing, private, without a valid pack.json or named otherwise is left out and named on that page. The catalog is read at boot, on save and by /packs, so a pushed change shows within seconds. The fixtures the tests use are in test/fixtures/packs/.
- Marking a pack, three doors, one rule (
src/packs/set.ts: admin only, validated, kept inforge_setting_change, then the catalog is re-read, so the change is on /packs at once): Settings › Packs; the Pack repositories screen in the terminal palette (admins only,src/tui/screens/packrepos.ts); andrepo_settingswith{ packRepos: ["packs/games", …] }over MCP, which answers{ repos, problems }. Reads of git are single-flight (refreshCatalog): one at a time, so an older read never overwrites a newer one; a read that fails is logged and the catalog stays as it was, at boot and on every page. - Setting up a forge's packs. A fresh forge lists no pack. For each pack, create a public repository named like the pack (any owner you can push as; not under
packs/, which is read-only to everyone but the mirror), push thepack.jsonto its default branch (test/fixtures/packs/games.jsonandbusiness.jsonare the two the forge used to ship), then markowner/namein Settings › Packs.bun scripts/pack.ts up <name>readspacks/<name>onFORGE_PACKS_FROM(default the public forge) at that repository's default branch (raw/HEAD). - Why the fixture packs still name https upstreams. An app's
sourceis the project's real home on purpose:upclones and follows it, and the mirror (below) turns each https source intopacks/<app>on a forge that wants a local copy. Writingpacks/2048into the shipped data would make a deploy depend on that forge having mirrored first. A pack that wants forge sources may use them (see below).
- Deploy one, one command. After
git clone … && cd forge && bun install,bun scripts/pack.ts up gamesmakes the owner account (its passphrase is shown once and kept 0600 inforge-data/owner-passphrase;FORGE_DATAandPORTmove the data and the port), boots this tree's forge on http://localhost:3000, makes each app, pushes the source's whole history (branches and tags), turns on following the source (Settings shows it; a new upstream commit shows as drift at the next check), adds the crew, and stays up serving. Nothing is asked but the model credential: with none in the environment it says the crew is off until one is added in Settings › Subscriptions. Run it again to finish a partial deploy: what exists is kept (history is never pushed again), and an app that was made but never followed is followed now; with no branch from the pack or the clone, that step fails rather than guess one. The carried branch becomes the app's default branch. Whether the crew has a credential is read from the data directory (Settings › Subscriptions) as well as the environment. Against a forge you already run:FORGE_URL=… FORGE_TOKEN=forge_… bun scripts/pack.ts deploy games. SetFORGE_ORGor pass--orgto create the apps in an organization the token can write, instead of the token's account. - See one.
/packslists them,/packs/<name>says what it brings, the deploy commands, and how a stranger helps build its apps (get a guest account or use their own forge; a guest's pull waits for a person, and paths touching secrets, credentials, permissions or release machinery are named on it —docs/ROLES.md). The home page (/) has one press for each pack in its "Get your own forge" section, a link to/packs/<name>with an emptydata-slot="host"beside it for a later hosted deploy; the pack page shows the commands in onecopyFieldblock (#pack-command, a read-only text area you select with a click; its copy button isjs-only, so it is on the page only when script runs). Reached from the user menu, the signed-out menu and the palette.bun scripts/pack.ts show gamesprints the same in a terminal, and the SSH terminal has a Forge packs screen (palette,src/tui/screens/packs.ts): the list, a pack's apps and crew, the deploy commands (theupline included: the web page and the screen both take them fromdeployCommands) and what happens to a stranger's pull. The words are shared insrc/packs/words.ts. - Nightly.
scripts/pack-compat.tsboots a clean forge per pack, deploys it with the real sources and fails if any step or app page fails (jobpack-compat,src/nightly/jobs.ts). - Code:
src/packs/,src/web/pages/packs.ts,scripts/pack.ts. Tests:test/packs.test.ts,test/packs-up.test.ts(the whole path against a fake source for both packs,up()itself with a real child forge on a free port, the owner reused on a second run, a stored credential, a partial deploy finished, a new upstream commit showing as drift),test/packs-hands.test.ts(the git credential is scoped to the forge and never sent to a pack's source; only 409 means "exists"; the terminal screen; anowner/namesource is forked with lineage, kept on 409, a 422 or 429 refusal failing that step with the forge's message, an unreachable forge, andabsorbabsorbing the fork as its owner). - A source on a forge (
owner/name). Deploying forks it with lineage (POST /forks) instead of pushing history: nothing is carried over the network and nothing is followed (no follow is set; the fork's lineage is the link). The fork keeps the app's name.owner/nameis resolved on whichever forge the deploy targets, not on the pack author's forge. An existing fork (409already_forked) counts as kept; a name already taken by something else fails that step. Non-admins are held to the fork limit (FORKS_PER_DAY, 5 a day), so a pack with more than five forge apps fails the rest with "at most 5 forks a day"; run it again the next day. Mirroring (below) is for https sources only: a forge-form source is reported as failed ("not an address a mirror may follow").
Not done yet: a hosted "deploy this pack" press, a stable follow link from each app back to its source, the guest sign-up gate and the crew filtering guest pulls on automode (owner decisions on #9428).
The upstream mirrors (#10530)
An admin brings each https source in a marked pack's pack.json in once as a public repository packs/<app> (owner packs, an account nobody signs in as), from any of three doors: the "Mirror the upstreams" button on /packs, the "Mirror the packs' upstreams" screen in the terminal palette (admins only), or repo_settings with { mirrorPacks: true } over MCP, which answers { made, kept, failed, says }. The request only reads each upstream's default branch, creates the repository and its follow, and stops at 20 seconds in all: what it did not reach is listed as failed ("press again"). The first sync is the scheduled follow's, as is every later one; it moves the default branch to the upstream's tip instead of opening a pull, and a failed sync is noted on the follow's row. Running it again leaves existing mirrors as they are.
Read-only is enforced where writes are decided: canWrite is false for every packs/* repository except for its owner, which only the follow acts as, so pushes (http and ssh, told why), web file edits, the contents and branch API, and opening or merging a pull are all refused, admins included. Open on purpose: issues and comments, and a repository admin's settings (visibility, delete, transfer). A mirror tracks the branch that was the upstream's HEAD when it was made; if the upstream renames its default branch, delete the mirror and mirror again.
Curated packs (#11006)
/packs shows curated packs: a pack is a named, ordered list of public repos on this forge, with a one-line pitch and a crew brief. They live in the forge's database (curated_pack*, src/packs/curated.ts), not in code or on GitHub, and a site admin who is a person edits them on the pack's page: rename, change the pitch and brief, add a repo (type to search the repos you can see), remove one, move one up or down; every change is saved at once and kept as who, what, when under History. New pack on /packs makes one. The same rule is the API: GET /api/v1/packs, GET/PUT /api/v1/packs/{name} with {title, pitch, brief, repos:["owner/name"…]} (a new name makes the pack). Anyone reads shown, the public repos on this forge; only a person admin also gets repos (the list as kept) and left_out (each left one with why), because those name private and missing repos. The same holds on the page: "Left out for now" is an admin's.
The terminal has it too (src/tui/screens/packs.ts, palette "Forge packs"): the list opens curated packs first, then the deployable ones; a pack's screen shows its shown repos and brief, s opens the new-forge form with the pack's repos and brief as they stand, and for a person admin a adds a repo, x removes, u/d move, t/p/b edit title, pitch and brief, and n on the list makes a pack. It goes through changeRepos/editPack as the page does, reads the database on every draw, so a change in either door is on the other at once. A guest's screen names no private or missing repo and the edit keys do nothing. Test: test/packs-tui.test.ts.
Each card shows the repos inside with a live link when the repo runs an app here, how many there are and how fresh, and Start a forge from this (/forges/new?pack=name): the form opens with the pack as it stands now (its repos ticked, the brief as the direction), so what you post is what is copied, and a later edit never reaches a forge that exists. A repo that is missing or not public is left out and named on the pack's page. Two packs, Business and Gamer, are seeded with the owner's lists; trim them on their pages.
The seeded repo lists are the owner's and are not checked against a forge here: a name that is missing or not public is left out of the cards and named to an admin, who trims it on the pack's page. Not done: drag to reorder (the arrows do it), a repo's "Add to pack…" menu, an MCP tool (the API is the door), a preview image on each card, and the crew brief is carried as the child's direction, not as a per-agent brief. The older pack.json packs still list under "Deploy on your own machine".
A source may not point inside (#11971)
Before a pack's source is cloned, src/packs/source_guard.ts resolves its host and refuses it when any answer is loopback, private, link-local, unique-local, CGNAT/tailnet or unspecified (the list in src/kernel/outbound.ts, the forge's one). Git then dials the address that was judged and follows no redirect. Only port 443 is allowed, unless the forge itself is the source. parsePack drops an internal address literal at once; the port rule is the guard's alone, because only it knows the forge's own address. Every deploy path runs the guard on the address the pack names, even when a test clones from elsewhere.
What a new forge gets (#13303)
A pack.json pack's page (/packs/<name>), the terminal's pack screen and the MCP templates tool (its packs list, the same as GET /api/v1/forges/templates) say what a forge made from it gets: the apps it creates, each crew member's roles and per-run budget. Anything the pack does not state reads "not stated". Code: src/packs/facts.ts; test: test/pack-facts.test.ts.