# 9web local catalogue (Linux) `9web --catalog FILE` runs a local website catalogue in the gateway process. It serves existing generated websites immediately, supervises requested builds, and inventories listening TCP sockets without making requests to them. No separate site servers are needed. The existing `--upstream` gateway mode is unchanged; catalogue mode and an explicit upstream are mutually exclusive. Set the top-level registry field `"filesystem": "/"` to expose the whole workstation in the Files tab. The real `/` remains the root; the catalogue is mounted at `/_9web`. Startup refuses an existing real `/_9web` rather than hiding it. Without this opt-in field, the previous catalogue-only tree is unchanged. Only `/` is accepted: this export is not a restricted directory sandbox. Host files support reading, editing, uploads, mkdir, rename and removal through the normal 9P/WebSocket and HTTP `/fs` interfaces. Symlinks and mount points are followed, including `/mnt/9p`. Access is checked by the kernel as the service's user, not root; the 9P permission bits are permissive because its engine cannot represent POSIX group/ACL checks. Device nodes, FIFOs and sockets are listed but refused as file contents. Open files retain their descriptors across reads. Blocking reads use bounded background tasks so one FUSE event stream does not block all requests on the shared 9P connection. Non-seekable FUSE files use streaming reads/writes rather than positional I/O. The installed service runs `9ns --mntgen -- 9web ...`: `/mnt/9p` is the posted registry in that service's namespace, not an assumption about another shell's mount namespace. No host-global mount is changed. Newly posted services are discovered by 9ns in the usual way. ## Configuration and serving See [catalog.example.json](catalog.example.json). Every site has a unique `name`, `title`, absolute `cwd` and `root`, and a distinct nonzero HTTP `port`. Optional `build` and `watch` values are argument arrays, not shell command strings. Use an explicit `sh -c` only when a trusted recipe needs shell syntax. ``` 9web --listen '[::]:8090' \ --catalog "$HOME/.config/9web/sites.json" \ --catalog-socket "$XDG_RUNTIME_DIR/9web/catalog.sock" \ --state-dir "$HOME/.local/state/9web" ``` Create the socket's parent directory first. Configuration is read at startup; restart the service to change it. A failed site-port bind fails startup rather than advertising a site that is not actually served. All site listeners use the dashboard's bind address. `[::]` uses a dual-stack listener for all IPv6 and IPv4 interfaces; `0.0.0.0` restricts this to IPv4. Each site occupies its own HTTP origin so root-relative `/assets/` and `/blog/` URLs work without HTML rewriting. Directory URLs redirect to a trailing slash and serve `index.html`; extensionless paths try `.html`. Static serving supports MIME types, HEAD, single byte ranges, and streaming large files. Symlink traversal, dotfiles, `..`, and encoded path separators are refused. Directory listings are available through 9P, not through site HTTP roots. The HTTP site root is static: provider-specific `_redirects`, `_headers`, and Worker APIs are not executed. For example the café's articles and assets work, but its Cloudflare poke API is not reproduced locally. ## Builds and watch The regular 9web interface has **files**, **sites**, and **services** views in catalogue mode. They share the existing header, stylesheet, tables and file browser. The root opens files; `/?view=sites` and `/?view=services` are direct links to the other tabs. Browser history and reload preserve the selected view. Switching tabs preserves unsaved file edits. Ordinary upstream mode shows only files and does not poll the catalogue API. Files uses the main directory table and breadcrumbs; there is no duplicate sidebar tree. Each file entry has a `follow` link (`?follow=1`) which opens metadata first and starts an SSE read without first waiting for a finite snapshot. Use it for event streams; stop does not reopen the file or discard received text. Ordinary file navigation still reads finite contents for editing. The sites table has build, watch and cancel controls, plus files and log links that open the same file browser. Builds execute in the configured working directory with the service's environment. One child job runs per site. Repeated build requests during a build coalesce into one later build. Build writes enqueue work immediately; serving does not wait for compilation. For managed watch, configure `inputs` as source paths relative to `cwd` (or absolute paths for shared libraries outside the project). The watcher checks source names, modification times and sizes once per second and invokes the build recipe on changes. It skips hidden entries, symlinks and common generated directories (`out`, `dist`, `build`, `node_modules`, `__pycache__`). List a particular build script explicitly if it lives in one of those directories. This is a metadata watcher, not a content hash or a Typst dependency graph. Changes during a build are detected by the next scan. Browser refresh is manual. Alternatively, `watch` can specify an existing persistent watcher. Its stdout and stderr go to the same log, and watch-off cancels its process group. A native watcher may itself serve a preview port, but the catalogue never requires that preview to serve the site's generated files. Manual builds are refused while a native watcher is active. Cancel disables watching and clears queued work. Server shutdown under systemd kills the whole service cgroup, including build descendants. Each new job replaces `/.log`. The UI and 9P expose its last 256 KiB; the on-disk log is not rotated during a long-running native watcher. Watch state and build status reset at service restart; generated output remains. No build or watch is started automatically. Builders currently write to their configured output directories in place. `9web` does **not** provide atomic publication or a last-good snapshot: a failed build can leave partial output, and a file truncated during a response closes that response. Builders needing atomic publication should generate a separate release directory and arrange publication themselves. The served root can be a symlink; symlinks below that root are refused. ## 9P and HTTP controls The catalogue is itself a 9P backend, consumed by the ordinary gateway mux. `--serve` and WebSocket clients see the same tree as direct socket clients: With `"filesystem": "/"`, prefix every catalogue path below with `/_9web`. For example, the control URL becomes `/fs/_9web/sites/entomology/ctl` and its mounted path is `/mnt/9p/web/_9web/sites/entomology/ctl`. UI links and controls select the prefix automatically from the catalogue snapshot's `namespace`. ``` /index.html /sites//public/ complete generated output tree (read-only) /sites//ctl build | watch on | watch off | cancel /sites//status JSON state, PID, exit code, times, generation /sites//log last 256 KiB of current/most recent job /sites//events blocking stream of JSON state changes /services/index.json recognized HTTP/HTTPS listeners /listeners/index.json all observed TCP listeners, including unknown ones ``` ``` 9ns --unix "$XDG_RUNTIME_DIR/9web/catalog.sock" --name web -- sh echo build > /mnt/9p/web/sites/entomology/ctl cat /mnt/9p/web/sites/entomology/status cat /mnt/9p/web/sites/entomology/log ``` Event opens receive the current state, then park until its revision changes. Each reader has its own cursor; slow readers receive the newest state, not a durable history of every transition. 9P flush cancels parked reads. State events also work through `/fs/sites//events?follow=1` as SSE. `status` is the finite snapshot to use for ordinary polling. The sites and services views read `GET /_cloud9/catalog.json` while visible. Build controls use `PUT /fs/sites//ctl`, through the same HTTP-to-9P mapping as file editing. The earlier `POST /_cloud9/sites//ctl` endpoint remains compatible for existing clients. Logs use the normal file viewer rather than a separate dialog. Polling preserves site-row focus and pauses in background tabs. ## Passive discovery Every five seconds, an embedded Python 3 inventory helper reads `/proc/net/tcp*`, joins socket inodes to process descriptors, and recognizes executable/argument patterns for miniserve, Python `http.server`, Typst watch, Vite and Wrangler dev. 9web advertises only its explicitly registered HTTP ports: its 9P listener is never labelled HTTP just because the owning executable is 9web. No TCP connections or HTTP probes are performed. Unknown or inaccessible process ownership stays unknown. Full command lines and environments are not published; entries contain address, actual bound port, PID, executable, cwd and the evidence for classification. Process races and permissions can make entries temporarily unknown. Discovery is in the service's network namespace, not across containers. The helper is a short-lived child of 9web, not another daemon. Wildcard addresses in dashboard links use the browser's current server hostname. Specific addresses remain specific; loopback services are labelled local-only. There is no automatic proxy to loopback-only services. Recognizers identify likely HTTP listeners from process evidence; they cannot prove application health. ## Service and access [9web.service](9web.service) is a user-systemd unit template. Install the binary at `~/.local/libexec/9web`, the config at `~/.config/9web/sites.json`, and the unit at `~/.config/systemd/user/9web.service`, then: ``` systemctl --user daemon-reload systemctl --user enable --now 9web.service systemctl --user status 9web.service journalctl --user -u 9web.service ``` The unit supplies a private runtime directory and socket, restarts on failure, and kills child jobs together with the service. Lingering must be enabled if the user service should run without an interactive login. It needs `python3`, `setsid`, and the configured project build tools in PATH. Miniserve remains independent. This is a trusted-network operator interface: it has **no login or TLS**. Anyone who can reach the dashboard can read the catalogue and trigger configured jobs. With `"filesystem": "/"`, they can additionally read or modify any file the service user can access, including credentials, configuration and source code, and operate control files under `/mnt/9p`. This can amount to arbitrary code execution as that user. Only enable this export for clients you fully trust. Browser control requests reject foreign Origins; numeric Host validation and separate site origins prevent served pages from using the dashboard as a same-origin control API. This is not authentication. Bind to loopback or place an authenticated gateway in front of it when those network permissions are inappropriate. No arbitrary command can be supplied to the catalogue build-control parser itself; its commands come from the local registry. A whole-host writable export removes that as a security boundary, since clients can edit the registry and build inputs. ## Verification Mounted synthetic files commonly report length zero and are non-seekable. Their normal EOF must become an empty 9P read, not `Rerror EndOfStream`. The browser reads until EOF, so that error previously discarded otherwise valid contents. Directory HTTP reads are now sized to the receiving buffer, and JSON/HTML listings stream rather than overflowing a fixed-size buffer or hiding a read failure behind an empty listing. The browser's WASM adapter also releases its previous borrowed reply frame before submitting another request. Without that release, a full-msize read could fail with `InputFull` even though small files worked. ``` zig build catalog-test http-fs-test mux-test -Doptimize=ReleaseSafe zig build catalog-ui-test -Doptimize=ReleaseSafe zig build -Doptimize=ReleaseSafe # install 9ns and the 9proc-demo fixture too zig build host-fs-test -Doptimize=ReleaseSafe ``` The catalogue integration test uses temporary real sites and processes. It checks immediate static serving, pretty URLs, MIME, HEAD/ranges, traversal and symlink rejection, Host/Origin checks, HTTP and raw 9P controls, watched rebuilds, failed build status, process-group cancellation, nonblocking event readers, and actual socket ownership discovery. Existing gateway HTTP/filesystem and mux suites cover the original mode. The Chromium UI test checks the shared shell and styles, view navigation and history, direct tab links, builds through `/fs`, logs in the file browser, preservation of unsaved edits and focused controls, and mobile layout. It writes inspection screenshots to `.zig-cache/catalog-ui/`. It uses the installed `google-chrome-stable` binary (or `CLOUD9_CHROME`), with no npm dependencies. It also checks that live HTTP ports stay exclusive and recent connections do not prevent an immediate restart of the dashboard or site listeners. `host-fs-test` additionally checks a 1,500-entry directory, mounted 9P reads, control writes, non-seekable EOF, blocking FUSE reads concurrent with other requests, and 40 flush/clunk cycles without exhausting background readers. The Chromium test navigates a real mounted fixture, reads a 180 KB file and opens/stops a live event stream directly from its directory entry. ## Publication and namespace policy There are three separate mechanisms, not one registration service: * 9P servers may use `serve.Runner.listenPosted` to publish a Unix listener at `$XDG_RUNTIME_DIR/9p/`. 9ns lists the registry and connects on a walk. No request is made to 9web; publication lifetime belongs to the producer. * Website roots and build recipes in this catalogue are startup configuration in `sites.json`, not self-registration. The private catalogue socket itself currently uses `listen`, not `listenPosted`. * HTTP listener discovery observes `/proc` socket ownership and process metadata. It neither registers services nor probes HTTP endpoints. The Plan 9 reference was checked against the local Principia Softwarica sources: `ROOT/docs/man/3/srv`, `kernel/devices/sys/devsrv.c`, `lib_networking/lib9p/post.c`, `ROOT/docs/man/4/mntgen`, and `ROOT/docs/man/4/exportfs`. Plan 9's `/srv` stores references to already-open channels; Unix listeners are a Linux adaptation, not identical semantics. Original `mntgen` creates mountpoints on demand; 9ns's registry auto-connection is additional policy. Explicit configuration is not itself contrary to Plan 9: `ROOT/docs/man/6/namespace` specifies configured mount/bind/import composition. The coherent next design step, **not implemented here**, is to expose a pure site/build-control 9P view and compose it into the consumer's namespace, with HTTP serving those same paths. Shared supervision can remain in one process; no extra daemon is required per static site. Do not post the current mixed host/catalogue root back under its own `/mnt/9p`: that creates recursion and possible self-dependent waits. Arbitrary-upstream composition and unifying the separate disk-based static-site HTTP handler remain outstanding. ## Installed workstation configuration The application is named **9web** in its header, footer and page titles. The existing `/_cloud9/` asset/protocol URLs and library module names are retained for compatibility; they are not a different application name. The workstation registry enables `"filesystem": "/"`. Files opens the host root, including the service's live `/mnt/9p` registry mount; the virtual catalogue is under `/_9web`. The unit wraps the separately installed 9web binary with 9ns. Ordinary `--upstream` mode is unchanged. Composition with an arbitrary explicit upstream is still not implemented; this mode composes the host filesystem with the catalogue, and existing 9P servers are available through `/mnt/9p`. The initial workstation setup uses dashboard port 8090 and site ports 8091–8095: Entomology lab, 0x4200.cafe, Standards, Pardes website, and the older café hub archive. The archive is read-only (no build recipe registered). Other sites have explicit local build recipes and opt-in managed watches. Port 8081 remains miniserve's. Runtime config is `~/.config/9web/sites.json`; the service uses a separately installed binary so subsequent development builds do not change the running service's executable on disk. Source and deployment changes are described in the implementing git commit; no remote push is required for the local service.