feat(packages): Moss wdocker 0.15.8 with its pinned Holochain 0.6.1

[Soushi888]

SoushAI analysis. Drafted by Soushi's AI assistant, reviewed and posted by @Soushi888.

Refs #28

Why

On 2026-09-27 the Sensorica Moss group and two Vines applets were hosted always-online on the homelab by wdocker, Moss's headless node, built by hand from the Moss sources. The next run is on a Holoport at the lab, where a hand build is where the session would stall. This PR is the first brick of #28: the package, not the service.

What

• packages.x86_64-linux.wdocker-0_15 (packages/wdocker.nix) builds wdocker from the Moss tag v0.15.8 (the release that bundles Holochain 0.6.1), offline in the Nix sandbox, with fetchYarnDeps and yarnConfigHook. npm's @theweave/wdocker@0.15.4 is unusable: it still carries file: workspace dependencies and dies with ERR_MODULE_NOT_FOUND @theweave/utils.

• The file: dependencies are resolved as workspaces, not symlinked by hand. wdocker's three file:../libs/api-style dependencies are rewritten to the workspaces' own versions, so yarn links them as workspaces; the root manifest is narrowed to the five workspaces wdocker needs (api, moss-types, utils, group-client, wdocker), which leaves the Electron app out. The upstream yarn.lock is consumed unmodified. A second yarn install --production drops typescript and the other build tools from the output.

• we-rust-utils: the prebuilt napi addon from npm (@lightningrodlabs/we-rust-utils-linux-x64-gnu@0.601.1, the version wdocker's range resolves to), patched by autoPatchelfHook (RPATH to libgcc), not built from source. bufferutil and utf-8-validate prebuilds likewise; their musl and foreign-platform prebuilds are removed.

• The Holochain 0.6.1 binary is in the package, and wdocker never downloads one. Decision below.

• checks.x86_64-linux.vmTestWdocker, added to the CI VM list: a NixOS VM with no network starts a throwaway conductor through wdaemon (the password on stdin, the one entry point that needs no TTY), and asserts the daemon reports ready, nothing was downloaded into wdocker's bins, the running conductor is the packaged binary, the admin port answers, wdocker list shows it running, and wdocker stop ends it.

• docs/moss-node.md: running the packaged wdocker by hand until the service lands, the restart-after-join rule, tagged tools, where data lives, the Moss network endpoints, and what is not headless yet.

The Holochain binary decision

Where wdocker looks and how it checks, at v0.15.8:

• The path is <data>/wdocker/0.15.x/bins/holochain-v0.6.1-moss-0.15-wdocker (wdocker/src/filesystem.ts:232-233, name from wdocker/src/const.ts:46).

• It downloads only when that file does not exist (wdocker/src/daemon/start.ts:137-140, fetchHolochainBinary at start.ts:279-319).

• The sha256 is checked once, right after a download (wdocker/src/utils.ts:76-83), against holochain-checksums.json. A file already in place is never hashed.

• wdocker stop finds the conductor by the first 14 characters of its process name (wdocker/src/commands/stop.ts:26).

So the package fetches the same release asset with fetchurl, pinned to the sha256 Moss pins (423f1111…ada7, checked at build time against the tag's holochain-checksums.json and moss.config.json), keeps the file name wdocker expects so stop still recognises it, and patches its ELF interpreter with autoPatchelfHook. Patching changes the file's hash, which is harmless because wdocker never hashes a binary it did not download; the BuildID is unchanged. It no longer needs nix-ld: its interpreter is the store's glibc, and it runs on the homelab with NIX_LD unset.

The binary's location is runtime state under the user's data directory, so the package cannot place it there; a one-line patch to filesystem.ts lets WDOCKER_HOLOCHAIN_BINARY name the binary, and the wrapper sets it by default. The wrapper also puts node and curl on PATH, because wdocker spawns node daemon.js by name (start.ts:102) and downloads the group hApp with curl (utils.ts:69).

How to test (exit codes observed)

Locally (Ubuntu with Nix, sandbox on):

nix build .#wdocker-0_15                     # exit 0
./result/bin/wdocker --help                  # exit 0, the 14-command listing
./result/libexec/wdocker/holochain-v0.6.1-moss-0.15-wdocker --version   # "holochain 0.6.1", exit 0
nix build -L .#checks.x86_64-linux.vmTestWdocker   # exit 0 (test script 256 s, 510 s on a loaded host)
nix run nixpkgs#alejandra -- --check .       # exit 0
nix flake check --no-build --accept-flake-config             # exit 0
nix flake check --no-build --all-systems --accept-flake-config   # exit 0

On the homelab (NixOS), from this branch, without starting any daemon:

nix build --no-link --print-out-paths --accept-flake-config "github:Sensorica/nixos-holochain/feat/wdocker-package#wdocker-0_15"
# exit 0, same store path as the local build: /nix/store/7vrjb99p…-wdocker-0.15.8
$P/bin/wdocker --help                        # exit 0
env -u NIX_LD -u NIX_LD_LIBRARY_PATH $P/libexec/wdocker/holochain-v0.6.1-moss-0.15-wdocker --version   # "holochain 0.6.1", exit 0

The native addon loads from the result: import('@lightningrodlabs/we-rust-utils') lists WeRustHandler happBytesWithCustomProperties saveHappOrWebhapp validateHappOrWebhapp, exit 0.

The VM check can go red: with the wrapper's variable renamed (a throwaway mutant, not committed), the same check exits 1, the daemon logging No holochain binary found. Downloading from Github... and the curl failing in the offline VM. With the mutant reverted, the committed tree passes again (exit 0).

Closure: 396 MiB, of which the wdocker path 144 MiB (node_modules and the Holochain binary) and Node 22 most of the rest.

Not covered

• The declarative service. No NixOS module, systemd unit, password credential, join from an invite file or restart after a join: that is Moss always-online node service #28 proper.

• Headless start. Every command except the daemon still prompts on a TTY. The headless environment variables from lightningrodlabs/moss PR #224 are not on tag v0.15.8; whether Moss always-online node service #28's service carries them as a patch or drives wdaemon over stdin is Soushi's call, and this PR does not build from main.

• aarch64. Moss pins an aarch64 Holochain binary and we-rust-utils ships a linux-arm64 addon, but nothing here has run on ARM, so the package is x86_64 only.

• Tool bytes by hash. A tagged tool whose webhapp URL serves different bytes than the group recorded still fails to install (Moss always-online node service #28, finding 3); the docs give the hand workaround.

• wdocker --version prints 0.15.4, the version in wdocker's own package.json at the tag; the package version is the Moss tag, 0.15.8.

[Soushi888]

SoushAI analysis. Drafted by Soushi's AI assistant, reviewed and posted by @Soushi888.

Review follow-up: the one blocking item is fixed, and the branch is up to date with main.

What changed

• e93f493 merges origin/main (now including docs: rescue a failed install over SSH, learned on the homelab #25, feat(edgenode): declare the Holochain Foundation binary cache #34, chore: license the repository under MIT #36, docs: add SECURITY.md, issue forms and a pull request template #48, feat(release): CHANGELOG and a tag-driven release workflow #49 and feat: holochain-bootstrap module and relayAllowPlainText #62). Two conflicts, both resolved by keeping both sides: the CI VM build list now carries vmTestWdocker next to vmTestBootstrap and edgenodeConfigRender, and the README docs/ tree lists moss-node.md next to releasing.md.
• 0dcbc00 fixes the README count and the missing row. With feat: holochain-bootstrap module and relayAllowPlainText #62 on main there are now ten VM checks (vmTest, vmTest-0_6, vmTestWithHapp, vmTestWithHapp-0_6, vmTestConductorMetrics-0_6, vmTestGrafana, vmTestGateway, vmTestWindtunnel, vmTestWdocker, vmTestBootstrap), so both the status line and the Tests heading say ten, and the Tests table has a vmTestWdocker row. The same commit adds packages/wdocker.nix to the tree in docs/architecture.md (non-blocking item, same kind of fix).

Local checks on 0dcbc00's tree

• nix flake check --no-build --all-systems: exit 0.
• nix build .#options-doc diffed against docs/module-options.md: in sync.
• examples/sensorica-fleet: nix flake check --no-build --override-input nixos-holochain <this checkout>: exit 0.
• checks.x86_64-linux.vmTestWdocker evaluates to the same derivation before and after the merge (r2wvkn4v…-vm-test-run-wdocker-smoke.drv), so the merge does not change what the green run on 891e77b built. No VM test was rerun locally.

Left for later

• The wdocker stop question (whether the node daemon survives when only the conductor is killed) is still unconfirmed and belongs to upstream; it does not affect the Moss always-online node service #28 service, which stops through systemd.
• No CHANGELOG line yet: main's [Unreleased] stops at chore(example): lock nixos-holochain to main after the stack #23, and the merged PRs since then have none either, so this is better done in one catch-up commit.