Threats

Who would attack this forge, what each wants, and what stands in the way. Every protection is one bullet ending in one Enforced by: line that names the test file (test/….test.ts) or the gate (scripts/….ts) that enforces it, or says none yet plainly, with (#N) when an open issue owns the gap. Each row of the internal-calls table names its enforcer in its last cell the same way. test/threats-enforced.test.ts fails on a row with no such line or a named path that does not exist, and prints how many rows say none yet. A protection nothing enforces is a gap, not a secret: the count is the to-do list, and only editing a row lowers it.

A snooper on the network

Wants: session cookies, tokens and pushed code in transit, or to learn who talks to whom.

script cannot read one and a plain-http hop does not carry it. Enforced by: test/own-session.test.ts

index does not replay as a login. Enforced by: test/tokens.test.ts

issued only for names the forge vouches for (on_demand_tls ask). Enforced by: none yet

plain HTTP on one machine or a pod network. Nothing encrypts it. Enforced by: none yet

A stolen token

Wants: to act as the person or agent it was issued to, for as long as it works.

wider one can. Enforced by: test/tokens.test.ts

log, and released when the run ends. Enforced by: test/run-secrets.test.ts

granted secret, from before the agent starts until the run ends: a run that says it leaves [redacted] in its log, its summary and every event. The two other children the forge starts with that credential, a one-shot and a conversation turn, are held the same way. Enforced by: test/boundary-secrets-run.test.ts

minutes, so a copy lifted from a run is useful to one door briefly. Enforced by: test/passport.test.ts

Enforced by: test/signin-throttle.test.ts

returned by any route. Enforced by: test/origins-security-auth.test.ts

or world-readable is refused, and a database file found too open is a degraded finding naming the chmod, never a silent change and never a stop. Enforced by: test/file-modes.test.ts

proposal token, a read credential offered and not yet sealed; the parent's spawn/<name>.json: the status token and the heartbeat key) are written 0600 (writePrivate), and one found wider is narrowed at boot and said once. Enforced by: test/boundary-tokens-follow.test.ts

app's) is refused on every route of every other repository before the route's handler runs, and ends with its repository: it never becomes an unbound one. Enforced by: test/boundary-tokens-gates.test.ts

revoke ends it at the next request, with no restart and no wait. A repository's admin sees and ends every child's read of it, whoever it was minted as; a suspended account's tokens stop with it. Enforced by: test/boundary-tokens-gates.test.ts

other host it talks to, and the token ends with the run. Enforced by: test/boundary-tokens-crew.test.ts

repository and kept by the parent as a hash; the child seals it with its own key and keeps it in no file, config or address. It lives a week at a time, renewed while the child follows, and ends when the child is removed, refuses the offer or is revoked; no log line or event on either forge carries it. Enforced by: test/boundary-tokens-follow.test.ts

at its own host, whoever's account they ride on. The token a preview's own process holds reaches its repository, its timers and its printer, and nothing else of its owner's. Enforced by: test/boundary-tokens-apphost.test.ts

anyone else. An open leaves one secret.read per name opened; no event carries a value, plain or sealed; the data browser shows no sealed column. The key file is 32 bytes only its owner reads, and one that others can read is refused by name. A lost key costs the values and nothing else. Deleting a repository removes the secrets scoped to it. Enforced by: test/boundary-secrets-store.test.ts

and its crew's runs only after a forge admin granted that name to that repository; a repository's own secrets need no grant. A name a run declares and nobody granted is never opened: the run goes on without it and says so in its log and once on its issue, with the link that grants it. Enforced by: test/boundary-secrets-store.test.ts

code and what it depends on read everything its owner reads, every private repository included. A preview's is bound to the app's one repository; production's is not, because reading the whole forge from an app is a documented feature (docs/APPS.md, examples/forge-live). Binding it too waits for the owner's word: it needs a per-app grant the owner sees listed, and until that grant is given it stops an app that reads its owner's other repositories on purpose. Enforced by: none yet

used from somewhere new. Enforced by: none yet

A compromised vendor

Wants: to run its code on the forge or in an app through something the forge trusts: a package, a model provider, a hosting provider, an origin it syncs from.

forge itself. Enforced by: test/deps.test.ts

home, own pid and network namespaces, memory, CPU and disk watched. A dependency an app pulls in gets no more than the app does. Enforced by: test/contain.test.ts

and only a directory that is there itself: a link its code leaves where its home goes is never mounted. What it hides (the forge's data, home and temp) is covered under the name it really has as well as the one it was given, before its own directory is bound back, and no neighbour's directory is ever shown. Enforced by: test/boundary-tenancy-cell.test.ts

without a newline: an app's or a step's line is cut at 64 KiB as it arrives and says so, a hosted forge's at 500 characters. That text is held in the forge's own memory, outside the cell's cap. Enforced by: test/boundary-tenancy-limits.test.ts

far as the cell's own limit of files (as many as its disk has 4 KiB blocks, a million at least), and a cell that reaches it is stopped and told so, never counted as the part that was seen. Enforced by: test/boundary-tenancy-limits.test.ts

carry a secret (every tmpfs, everything under /run): a second mount of the data volume, an env file or a backup volume bound in at another path is readable in every cell. FORGE_CELL_MOUNTS=allow-list closes it; it is not yet the default wherever the forge runs in a container. Enforced by: none yet

leaves [redacted] in its deploy's log, plain or encoded, so a careless dependency does not publish them to everyone who can read the runs. Enforced by: test/boundary-secrets-process.test.ts

repository declared and refuses names that resolve to private, loopback or metadata addresses. Enforced by: test/apps-adversarial.test.ts

identity. Enforced by: test/origins-security-provider.test.ts

to a private, loopback, link-local, tailnet or metadata address is refused before git starts, in the fetch's words; git dials the address that was judged and follows no redirect. A hosted forge's proposal to its parent trusts the parent's host by name for that one push. Enforced by: test/mirror-outbound-push.test.ts

Enforced by: test/origins-security-push.test.ts

Enforced by: test/snapshot-store.test.ts

Enforced by: none yet

A hostile agent inside a run

Wants: to read what it was not given, reach what it may not, or land code no person approved.

own repository's app (production and each open pull's preview), by exact host, and never another repository's app. The forge's repositories, index, key and every other agent's clone are denied by name and by allow-list, and a listing that fails refuses the run. Enforced by: test/crew-sandbox.test.ts

repository's bun install cache (crew/.cache/<repo id>/bun), which every run on that repository can write: a run can poison what the next run on the same repository installs. It is per repository: the cache root is denied whole and only this repository's directory re-allowed, so a cache made later is denied too, and deleting the repository removes it. Enforced by: test/crew-install-cache.test.ts

(check-install/<repo id>/bun) through a read-only bind and cannot write it, so one pull cannot plant a package the gate on main installs. The forge fills it on the host with --ignore-scripts, and reads no bunfig.toml or .npmrc of the pull's. Enforced by: test/check-install.test.ts

copies from it, so a preview cannot plant a package production installs; the forge fills it through the same lockfile rule as a check's. Enforced by: test/app-install-cache.test.ts

registry name@version with a sha512 integrity (checks/fillable.ts): the host never fetches a URL a pull chose and reads no file, link or workspace a pull points at, an override's or resolution's included. Enforced by: test/check-fillable.test.ts

Enforced by: test/crew-sandbox-real.test.ts

its base branch's forge.json declares, never the ones its own asks for, until the pull lands: code on a branch, the crew's as much as a guest's, cannot widen where its own check and preview send what they hold. The pull's page and the top of its logs say in one line what it asked for and that it applies when the pull lands. Enforced by: test/boundary-pull-egress.test.ts

Enforced by: test/protection.test.ts

either: a protected default takes a push from its admins only, so every other writer lands through a pull, its gate and its review. Enforced by: test/protected-default-push.test.ts

which runs code nobody has landed, reads a variable only when its owner chose "Also in previews" or set one for previews. Enforced by: test/app-env.test.ts

Enforced by: test/security-merge.test.ts

Enforced by: test/crew-limits.test.ts

Enforced by: test/security-xss.test.ts

An automated attacker at scale

Wants: accounts, spam, resources, or a way to exhaust the forge.

Enforced by: test/body-limits.test.ts

Enforced by: test/fuzz-parsers.test.ts

Enforced by: test/spawn-anon.test.ts

search on the page, the API and the terminal's guest palette, event streams, spawn plans) is limited per address and for every stranger together (src/http/strangers.ts, docs/ARCHITECTURE.md, concurrency invariant 7); a signed-in push keeps its share of the pool. Enforced by: test/strangers.test.ts

trusted proxy; X-Forwarded-For is read from the right, past trusted hops. Enforced by: test/client-address.test.ts

accounts. Enforced by: test/guard-new-accounts.test.ts

hour, and an admin can close it at once. Enforced by: test/guest-contribute.test.ts

settings, secrets or app, nothing runs for it, and its storage, forks and pulls are limited (docs/ROLES.md). Enforced by: test/guest-contribute.test.ts

the repository itself, so where a head lives says nothing about who wrote it: a contrib/<agent>/<segment>/… head is a guest's. Its check runs with nobody's permission, behind the owner's and the crew's work, in a cell that holds no variable, token or secret and is held to the hosts and limits the base branch declares; nothing from its branch is previewed, and the crew leaves it, until a writer approves the pull once. On a machine with no cell its check does not run unapproved either, and says the press that lifts it. Enforced by: test/boundary-tokens-crew.test.ts

store holds to whoever names it by id. So someone who reads a fork and may not read its parent (the parent was made private after the fork; they left its organisation or its crew) is held to what the fork's own refs reach: at the git door over protocol v2 and v0, for a commit, a tree or a file, and at the fork's pages, API, tools and terminal by a full id or a short one, answered exactly as an id nothing holds. A parent that is not public no longer moves a public fork, and a push into such a fork must carry every new object it names. Everyone else fetches as before, partial clones included. What a fork's own refs already held stays the fork's: the read-only forks-beyond-parent script lists the forks to look at. Enforced by: test/boundary-fork-objects.test.ts

proposal run nothing until a person who can write the repository approves that exact head, and the crew never lands one. Enforced by: test/guest-contribute.test.ts

(on a mirror, by someone its origin lets write), so its check and preview run at once. When its author is a guest from the origin, its preview and that preview's terminal still hold none of the app's variables, no forge token and no copy of production's data until a writer approves the pull. Enforced by: test/boundary-secrets-process.test.ts

Enforced by: test/limits.test.ts

here. Enforced by: none yet

Internal calls

FORGE_SELF_SWAP=1 binds the web port with SO_REUSEPORT so a release can share it, which also lets any process running as the forge's user join the listener and take a share of its connections, login posts included. It assumes nothing else runs as that user on the host network (agents and apps are sandboxed or in cells). Only one swap is made per process, so two landings never leave two releases serving. The swap is refused unless net.ipv4.tcp_migrate_req=1, for without it the old listener closing resets queued connections. Enforced by: test/release-swap.test.ts

How each part proves itself to the next, today.

CallAuthenticated byEnforced by
runner → forgethe run's scoped token (FORGE_TOKEN) and a few-minute passport (FORGE_PASSPORT)test/passport-edge.test.ts
git hook → forgeper-boot secret in x-forge-hook-secret on the internal listener; a call without it is refused and countedtest/crew-sandbox.test.ts
cell → proxythe proxy's Unix socket bound into the cell's own network namespace; no credential, the namespace is the identitytest/contain.test.ts
edge → podX-Plat-Edge-Token equal to FORGE_EDGE_TOKEN, compared as fixed-width digests; without it X-Plat-User is ignored; the signin.edge setting (admin, refused for an admin with no password or passkey) turns the edge's identity off on every doortest/edge-auth.test.ts
child → parenta heartbeat and a brokered sign-in are signed (HMAC) with the key spawn gave both sides, looked up by the name inside the signed body, so the door a call arrives on says nothing about whose it is; the lent model by a bearer whose hash the parent keeps; a child's door answers those routes and nothing else. Code is pulled over public git, and the claim link (sha256 kept, 24 hours, single use) hands the child to its persontest/boundary-tenancy-cell.test.ts

Gaps: edge → pod and runner → forge ride a shared secret, not a per-call signature.

A child forge running its own code (#11144)

A cell child's owner may switch it from the parent's code to its own <org>/forge main (spawn/own_code.ts). The code is then the child's author's, so treat it as hostile code in a cell, the same as any app.

What it cannot reach: the cell's memory, CPU, disk and I/O limits, its sandbox and its egress list are the same as with the parent's code, and nothing in the child's repository is read to make them. The parent's data, home and temporary directory are hidden; only the parent's code and the one checkout (a tree, with no .git) are revealed, read-only. Its forge.json is not run by the parent: the parent finds the repository only as a directory of the child's own (never through a link), refuses a repository or tree over 256 MB or 50,000 files and any symbolic link in either, checks that src/main.ts parses and forge.json is JSON, and never executes the child's code outside the cell. What the parent records about a failed start is fixed wording: one of a list of the parent's own sentences. Nothing the child wrote or printed reaches the ledger, the rollback row or the forge.rolled_back event; its last lines go to the parent's log.

What it can reach: everything a child forge can reach, no more: its own data directory, the parent's heartbeat door and public address, the hosts the admin allowed for models, registry, payment and origins (the public git hosts and the forges its parent holds beside it), and the sign-ins its parent brokers for it. It can lie in what it serves and in its heartbeat, and can break itself: a start that fails to answer within the deadline rolls back to the last commit that came up, then to the parent's code, and the owner's /forges page shows a Rolled back row saying so. A commit that failed is not tried again until main moves. A child that comes up and breaks later is not rolled back; the owner switches it off. Hosted children run inside the parent's process and cannot turn this on.

parent from outside, never read from the child's repository, so a child's own code is held exactly like any app. Enforced by: test/own-code.test.ts

leaves it stopped, its address and its host's forges page saying why and when the host tries again; it is not opened in the parent's process for that, since its directory (its repositories' hooks and git config included) is the child's to write. Only a host that holds no cell at all runs a child in its own process, and never one that has run code of its own. Enforced by: test/spawn-cell-stays.test.ts

put there by an older release) is moved into a cell of its own, by an admin's button or by the forge's own pass at boot and when one sleeps; a move that does not prove itself is put back (the sizes it is given are held by test/spawn-move-cell-sizes.test.ts). Enforced by: test/spawn-move-cell.test.ts

running nothing, for what that process may have executed while it had no wall: hooks beyond the forge's own stubs and config keys that make git run a command, reported by name and never by content. Enforced by: test/spawn-move-scan.test.ts

own process again whatever a ledger says, never moves a cell child into its process because its own probe of cells failed, and places a new forge in a cell or not at all. Enforced by: test/spawn-sealed-host.test.ts

crew at work, its public apps) off its serving thread, with a deadline, and only of plain tables: a view of the same name is never run, and a statement that does not end costs that child one answer of "unknown" and nobody else anything. Enforced by: test/child-db-off-thread.test.ts

cell (the stop note, the plan notice, the credit, the app links, the starts ledger, the key file) follows no link the child left there: one writer that makes its own file and moves it into place, one reader that takes a regular file or nothing and never waits on a pipe. A link under the key's name is a refusal, never read through and never minted over. Enforced by: test/boundary-tenancy-files.test.ts

directory with no link in it, and what is recorded when its start fails is a sentence from the parent's list, whatever was handed in. Enforced by: test/boundary-tenancy-files.test.ts

processes, network, IPC and hostname; its way out reaches its own door on the parent by that exact port and refuses a neighbour's door, a neighbour's port and the parent's own port on loopback; and a heartbeat or a model bearer made with one child's key opens nothing of another's. Enforced by: test/boundary-tenancy-cell.test.ts

cgroup: memory (no swap, the whole cell killed together), cores, processes and disk bandwidth, at a tenth of the forge's own weight. Where it has none, the hold changes hands and is said: a pin and pausing for cores, the watch for memory and processes. Enforced by: test/boundary-tenancy-limits.test.ts

floor on its own cgroup where that is delegated (memory.min and memory.low, a limit an admin sets), and every cell's and crew run's first process raises its own oom_score_adj above the forge's, so short of memory the kernel chooses a cell first. No hosted forge is refused a start for memory: when the sizes together pass the machine, /forges and the forge's needs say so in one line. Proven as the files written and the argv a cell starts as, not as the kernel's behaviour; a cell that sets out to can lower its figure back to the forge's own, never below it. Enforced by: test/boundary-tenancy-limits.test.ts

settings name, each on 443: the model, registry and payment hosts, the public git hosts, and the forges its parent holds beside it (one name ending in --<parent's host>). No other name under the parent's domain opens, and the list never holds a wildcard on a domain: under a shared suffix that would be everyone's host there. Enforced by: test/spawn-cell.test.ts

private, loopback, link-local, tailnet or metadata answer among public ones refuses it, in every spelling, whichever entry named it. A name that is not on the list is refused before it is looked up, and nothing is dialled. Enforced by: test/boundary-outbound.test.ts

name on 443, for that forge alone or for every one: never an address, a wildcard, another port or a name that is private by its shape, whether the forge asked for it or the admin typed it, and a name that resolves inside a network is not taken as an ask. A granted name is still judged by every address it resolves to. Only a person who is a site admin answers, from the parent's own pages; a form sent from another site changes nothing. What the hosted forge says about who asked and why is cleaned and only ever shown. Enforced by: test/ask-to-reach.test.ts

inside a minute, to the forge that began it and to no other, and what the parent keeps is an event naming the forge, the host and the account: never a token or a code. Before the provider is asked anything, the parent shows the person one page that names the hosted forge, from the parent's own ledger, and the provider, with one way on: the provider's own consent names the parent's application and may ask nothing. Enforced by: test/origin-broker.test.ts

restart too: the broker's rows are swept as the forge boots. Enforced by: test/origin-broker-boot.test.ts

Honeypots (later)

A kind: "honeypot" app, a decoy that records what touches it, is not built. forge.json accepts web and service only. Before one may exist:

real apps;

Until then, nothing here claims one.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs