Machines (#9418, first slice)

A machine is a named configuration a crew member's shell runs in: the tools its role is given, what it may use up, and how far it may reach. src/crew/machines.ts holds the catalog and the validation; src/crew/machines_read.ts reads a repository's choice.

Configure

At the top level of forge.json, read at the default branch's tip (a run cannot widen its own machine by editing the file on its branch):

"machines": { "audit": { "tools": ["gitleaks", "trivy"], "reach": [] } },
"machineFor": { "reviewer": "audit" }

nuclei, zap, testssl.sh, nmap. A name is never a command.

today) or []. A machine cannot name a host, so it can only narrow the sandbox; the forge's secrets stay denied by crew/sandbox.ts whatever a machine says.

role with none runs in standard, which is today's sandbox exactly.

tools, aimed at the forge's own copies only.

ceilings, e.g. "audit": { "memory": 2048, "cpus": 2 }. They only narrow: cpus is never above the forge's own FORGE_CREW_CPUS, and a machine that sets neither (standard, security) runs exactly as today, uncapped in memory. The kernel holds them in the run's cgroup cell (src/crew/run-cell.ts, src/apps/cgroup.ts): past memory the run is OOM-killed, never the forge. A run with a memory cap enters its cell strictly, so it never runs uncapped in a cgroup made for it.

controller), the run's log says so in one line, e.g. machine: memory 2048 MiB not applied: no cgroup v2 here; where it can, machine: held to memory 2048 MiB and 2 CPUs.

What a run gets

FORGE_MACHINE and FORGE_MACHINE_TOOLS (names only) in its environment, a line in its brief, and its apps reach. Both report what is installed, not what is declared (#9506): FORGE_MACHINE_TOOLS lists only the machine's tools found on the forge's PATH (Bun.which, PATH only: nothing is downloaded or run), and the brief names those with what each is for, then lists the rest as "not installed on this forge". A machine with none of its tools on PATH gets one line saying so. Installing the tools is a separate step, not done yet.

A shell into a machine (#9471)

src/machines/shell.ts. A WebSocket at /<owner>/<repo>/machines/<machine>/shell opens a shell into one of the repository's machines:

token) with write permission on the repository, from this forge's own pages: the Origin must be the forge's, and a missing one is refused. A reader is refused 403 on a public repository; a private one, or a machine it does not declare, answers 404.

in a cell (apps/contain.ts) under the machine's memory and CPU ceilings, with the forge's data hidden. It reaches the forge and, when the machine says apps (as standard does), the repository's own production and each open pull's preview, each at its exact host and port through the cell's egress proxy (shellReach, #9934); a machine with reach: [] reaches the forge alone. Another repository's app and every other host stay refused, and nothing a machine says un-hides the forge's data. Each writer has a directory and home of their own on each machine, <data>/machines/<repo id>/<machine>/<user id>: one writer's files and shell history are never the next's. A forge that cannot hold a cell closes the socket (1011, "this forge cannot hold a machine's shell") rather than hand out a shell on its host. The command is a constant: nothing a person sends reaches a command line. A shell that fails to start leaves no pty, cell or open row behind (its row ends failed).

one closes with 1009) and screen bytes out; a peer that stops reading (over 1 MiB waiting) is closed. A text frame is {"type":"resize","cols":n,"rows":n} (cols 1–500, rows 1–300); any other text frame closes the connection (1003).

handshakes per person a minute. Past either the handshake answers 429.

(another tab, a reload) joins the running session and sees the same output. The session ends when the shell exits, after 30 minutes with no keystroke, or — checked every 5 seconds and when its last connection closes — once its owner is suspended or can no longer write here.

shell_idle_minutes (default 30, 5 to 1440, set at /admin/limits, read at every check) ends as idle; one that prints, like a build, is never idle.

start, end and why: exit, idle, stopped, revoked, failed). No shell outlives its forge, so a row a stop or crash left open is closed as stopped when the forge boots. Writers see the last 20 at /<owner>/<repo>/settings/machines (in the settings frame for an admin, on its own for a writer who is not one), and in the terminal: the palette's Machines of a repository (src/tui/screens/machines.ts), writers only.

The shell in the browser (#9472)

/<owner>/<repo>/settings/machines lists the machines with Open shell, which goes to /<owner>/<repo>/machines/<machine>/shell: the same path as the socket, answered as a page when it is not an upgrade. Writers only, like the socket (a reader is refused 403; a private repository or an undeclared machine answers 404). The page renders on the server and draws the terminal with one script:

0.4.0, vendored unmodified in src/web/vendor/ghostty-web (MIT; what was copied and its hashes are in its README). src/web/machine-term-asset.ts bundles it with the page's client (src/web/machine-term-client.ts) into /assets/machine-term-<hash>.js (about 75 KB, dropping the module's own inlined copy of the WebAssembly) and serves ghostty-vt.wasm at /assets/ghostty-vt-<hash>.wasm (423 KB); both are content-addressed and cached immutable.

is write, onData, resize and fit, and all of the protocol (wire) is written against that, so it is tested without a browser and the emulator can be swapped without touching it.

page option wasm in src/web/layout.ts): it admits compiling WebAssembly, not eval or inline script. Every other page's policy is unchanged.

session (above). On open the page sends its size; a connection's first size equal to the pty's own makes the server pass the pty through one row less for 30 ms (resizePlan, src/machines/shell.ts), because the kernel signals only a change and tmux redraws the whole screen on the signal. So the reloaded page shows the screen, not a blank one.

(debounced 100 ms) and sends one resize frame per new size, never the same size twice; tmux redraws the prompt at the new size.

idle, the forge cannot hold a shell) and to reload to reattach.

Try it: on a preview, sign in as a writer of a repository, open /<owner>/<repo>/settings/machines, press Open shell on standard. A forge that cannot hold a cell says so in the status line and closes.

Not done yet (split from #9418)

Disk ceilings are not declared (#9460); the tools are declared, not yet installed in an image (the brief reports which are on PATH).

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs