Moving a forge out of this forge's process into its own sandbox
A forge this one hosts runs in one of two places. In a cell: a process of
its own behind a sandbox, held to its size. Or inside this forge's own
process (placement hosted): a second forge in the same process, with no
sandbox around its data and git operations, and its requests and timers on
this forge's one serving thread. Forges made before cells were the default,
and forges demoted before 0.7.587, are in the second place. This is how they
leave it.
Where it is said
- /forges: every row says where the forge runs. One in this process is
marked "in this forge's process" and has a Move into its own sandbox button.
- Home: one line, "N forges run inside this forge's own process; move
them into sandboxes", while there are any and this host can make a sandbox.
- /system: "Forges inside this process, last hour": for each, its
requests and how long they were open, how long its timers held the thread,
and the stalls named for it. The stall log itself names child:<name>.
GET /api/v1/forges, the MCPforgesandfamilytools:placement, and
where in words.
Moving one
- The button on its row;
mon the terminal's Forges screen. POST /api/v1/forges/{name}/sandboxwith{ "dryRun": false }(plans
unless dryRun is false; GET is the check alone).
- MCP:
forgeswith{ forge, sandbox: true, dryRun: false }.
The forge is closed here, its ledger is changed, its cell is started, and it is proven: it answers its health route and holds every user, repository, issue, pull and ref it held. Its address, accounts, tokens, apps, credit, follow links and claim state do not change; nothing is renamed, its body id and directory stay. Its owner sees one event in their forge: "This forge now runs in its own sandbox; nothing else changed." If anything fails it is put back exactly as it was and its row says why. While it moves, its address answers "waking up" and tries again by itself.
One thing does change for it: a forge in a cell runs its own crew and its own timers, as every forge made in a cell does. Inside this process it had no crew of its own.
What is checked first
Its repositories are read for what a sandbox would have contained and this
forge's process ran instead: a hook beyond the forge's two stubs, and a key
in a repository's config that runs a command (core.fsmonitor,
core.sshCommand, core.hooksPath, filter., alias., include.path
and the like). The check names them, per repository, and never shows what
they contain. A forge with any is not moved by itself: its row says what
was found, and the button reads I looked: move it (acknowledge: true
over the API).
What it holds on disk is weighed against its size's cell. A forge past nine tenths of its size's disk, or whose cell runs out of memory before it answers, is given the next size up when the host has room, and its row says so. With no room it is put back and the row names the limit.
By itself
Where this host can make a sandbox, the forge moves them without being asked: once at boot, before the hosted forges are brought back, and again each time one of them goes to sleep. One at a time, the smallest on disk first, each only while it is asleep. The pass stops at the first move that fails (that forge is put back, and is not tried again by the pass for a day); a forge with something found in its repositories, a lapsed one, or one that does not fit is passed over with the reason on its row. A move interrupted by a restart is found by the intent in its ledger and is finished, or put back, before anything else.
Where the host cannot make a sandbox (macOS, FORGE_CELLS=off), nothing
moves and each row says which host that is.
After the last one
When a host that can make a sandbox has no made forge left in its own
process, it says so once and keeps to it (sandboxed-host.json in its data
directory, an event forge.host_sealed, and a line under the list on
/forges). From then on, on that host:
- no forge is opened in this forge's process, whatever a ledger says. One
placed hosted again (an old tool, a hand's edit) is stopped, its address
says it is waiting to be moved, and the pass moves it;
- a forge in a cell is never brought into this process because the host's
own check of its sandboxes failed that day. It stays in its cell's place, stopped, with the reason on its row, and the host tries again;
- a new forge is placed in a cell or not at all.
The in-process path is left only where a host never could make a sandbox (a
developer's macOS, FORGE_CELLS=off from the first boot): such a host never
seals. A snapshot restored from before the seal is unsealed, as it was.
Taking the seal back is a hand's work on purpose: remove
sandboxed-host.json and restart.