authoravatarclover caruso<git@paperclover.net>2026-10-22 13:14:53-07:00
committeravatarclover caruso<git@paperclover.net>2026-10-24 19:01:23-07:00
log78daa503d015fc5d1b70bd8a1927000f47ceb64b
tree42a6f9a110fa397929a2955bc24f31b5d70a7c82
parent628f936c593ab09248911fa3f03f28e819d870d4
signature Signed by SSH key SHA256:52mNGHRsVFBDED9IAX5pe+LRWUefqTbxEReunq21QvU

Run Knife agents directly beside shared ZFS storage

Run the headless Fedora agent environment as a boot-enabled Podman service with a separate container store and the existing Mac workspace paths. Preserve mesh identity, floating profiles, canonical instructions, skills, and memories when retiring the isolated VM. Verified 8,470 agent-home paths against the stopped VM, both memory databases, a fresh runtime-directory startup, and two independent off-server application/database/key restores. Deployment export tests pass. Assisted-by: claude-opus-5.5 Assisted-by: gpt-6.1-sol

7 files changed, 279 insertions(+), 1 deletions(-)

nixos/knife-linux.Containerfile created+28
......@@ -0,0 +1,28 @@
1FROM registry.fedoraproject.org/fedora:44@sha256:0d2a354dfdf7ba75083fe371eb6239842fe13f38c52d339dae1ebcf13c7c4062
2
3# Development tools, plus the libraries and fonts T3's headless Chrome needs.
4RUN dnf -y install --setopt=install_weak_deps=False \
5 bzip2 cargo cmake diffutils fd-find file findutils gcc gcc-c++ git hostname iproute jq less \
6 lsof make neovim openssh-clients openssl-devel patch procps-ng python3 ripgrep rsync rust tar \
7 time tree unzip which xz zip zlib-ng-compat-devel zsh \
8 alsa-lib at-spi2-atk at-spi2-core atk dbus-libs expat fontconfig glib2 libX11 libXcomposite \
9 libXdamage libXext libXfixes libXrandr libxcb libxkbcommon liberation-mono-fonts \
10 liberation-sans-fonts liberation-serif-fonts mesa-libgbm nss \
11 && dnf clean all
12
13RUN curl -fsSLo /tmp/node.tar.xz https://nodejs.org/dist/v26.12.1/node-v26.12.1-linux-x64.tar.xz \
14 && echo "6170b2d474e1c626f43cff3adc118df9fe3b573258a4fc3d850c8dbc6b079bbd /tmp/node.tar.xz" | sha256sum -c \
15 && mkdir -p /opt/node/26.12.1 \
16 && tar -xJf /tmp/node.tar.xz -C /opt/node/26.12.1 --strip-components=1 \
17 && rm /tmp/node.tar.xz \
18 && ln -s /opt/node/26.12.1/bin/node /opt/node/26.12.1/bin/npm /opt/node/26.12.1/bin/npx /usr/local/bin/ \
19 && npm install --global --prefix=/usr/local --allow-scripts=pnpm pnpm@12.14.0 vite-plus@1.3.0 \
20 && npm cache clean --force
21
22ARG UID
23ARG GID
24RUN groupadd --gid "$GID" chloe && useradd --uid "$UID" --gid "$GID" --no-create-home --home-dir /home/clo clo
25USER clo
26ENV HOME=/home/clo LANG=C.UTF-8 PATH=/home/clo/.local/bin:/usr/local/bin:/usr/bin:/bin
27WORKDIR /Volumes/Code/project
28ENTRYPOINT ["/home/clo/.local/bin/knife", "start", "--mode", "desktop", "--host", "127.0.0.1", "--port", "3773", "--no-browser"]
nixos/knife-linux.nix created+54
......@@ -0,0 +1,54 @@
1{ config, lib, pkgs, ... }:
2let
3 sandbox = (builtins.fromJSON (builtins.readFile ../config/mac-studio-sandbox.json)).mountPoint;
4 root = "/srv/knife-linux";
5 uid = toString config.users.users.clo.uid;
6 gid = toString config.users.groups.chloe.gid;
7 engine = pkgs.writeText "knife-linux-containers.conf" ''
8 [engine]
9 tmp_dir = "/run/knife-linux/libpod"
10 lock_type = "file"
11 '';
12 # A second rootful store must not share Nomad's lock segment or state directory.
13 podman = pkgs.writeShellScriptBin "knife-linux-podman" ''
14 export CONTAINERS_CONF_OVERRIDE=${engine}
15 exec ${pkgs.podman}/bin/podman --root=${root}/containers/storage --runroot=/run/knife-linux/containers "$@"
16 '';
17 run = "${podman}/bin/knife-linux-podman";
18in
19{
20 environment.systemPackages = [ podman ];
21
22 systemd.services.knife-linux = {
23 description = "The Knife Linux agent container";
24 wantedBy = [ "multi-user.target" ];
25 wants = [ "network-online.target" ];
26 after = [ "network-online.target" "mac-studio-sandbox.service" ];
27 requires = [ "mac-studio-sandbox.service" ];
28 serviceConfig = {
29 Type = "notify";
30 NotifyAccess = "all";
31 ExecStartPre = [
32 "${pkgs.util-linux}/bin/mountpoint -q ${root}"
33 "${run} build --quiet --build-arg=UID=${uid} --build-arg=GID=${gid} --tag=localhost/knife-linux --file=${./knife-linux.Containerfile} /var/empty"
34 ];
35 ExecStart = lib.concatStringsSep " " [
36 run "run --rm --replace --name=knife-linux --pull=never"
37 "--sdnotify=conmon --cgroups=no-conmon --log-driver=journald --init --hostname=knife-linux"
38 "--user=${uid}:${gid} --umask=0077 --cap-drop=ALL --security-opt=no-new-privileges"
39 "--memory=32g --cpus=12 --pids-limit=32768 --shm-size=2g --network=podman"
40 "--volume=${root}/home:/home/clo"
41 "--volume=${sandbox}:/Volumes/Code"
42 "--volume=/opt/studio-project-store/current/bin/jj-real:/usr/local/bin/jj:ro"
43 "localhost/knife-linux"
44 ];
45 ExecStop = "${run} stop --ignore --time=90 knife-linux";
46 ExecStopPost = "${run} rm --ignore --force knife-linux";
47 KillMode = "mixed";
48 TimeoutStartSec = "30min";
49 TimeoutStopSec = 120;
50 Restart = "always";
51 RestartSec = 5;
52 };
53 };
54}
nixos/snowglobe.nix+1-1
......@@ -16,7 +16,7 @@ let
1616 };
1717in
1818{
19 imports = [ ./snowglobe-network.nix ./mac-studio-sandbox.nix ./mac-vm.nix ./zfs-read-cache.nix ];
19 imports = [ ./snowglobe-network.nix ./mac-studio-sandbox.nix ./knife-linux.nix ./mac-vm.nix ./zfs-read-cache.nix ];
2020
2121 networking.hostName = "snowglobe";
2222 environment.etc."machine-info".text = ''
tools/agent-home.py created+47
......@@ -0,0 +1,47 @@
1#!/usr/bin/env python3
2"""Package Claude and Codex instructions and skills with shared local targets."""
3import argparse
4from pathlib import Path
5import tarfile
6
7
8def main():
9 parser = argparse.ArgumentParser(description=__doc__)
10 parser.add_argument("archive", type=Path)
11 parser.add_argument("--source-home", type=Path, default=Path.home())
12 args = parser.parse_args()
13 instructions = [args.source_home / ".claude/CLAUDE.md", args.source_home / ".codex/AGENTS.md"]
14 if instructions[0].read_bytes() != instructions[1].read_bytes():
15 parser.error("Claude and Codex have different global instructions; choose a shared version first.")
16 targets = {}
17
18 def keep(member):
19 return None if any(part in {".DS_Store", "__pycache__", ".git"} for part in Path(member.name).parts) else member
20
21 with tarfile.open(args.archive, "w:gz", dereference=True) as archive:
22 archive.add(instructions[0], arcname=".config/agents/AGENTS.md")
23 for provider, name in [("claude", "CLAUDE.md"), ("codex", "AGENTS.md")]:
24 link = tarfile.TarInfo(f".{provider}/{name}")
25 link.type = tarfile.SYMTYPE
26 link.linkname = "../.config/agents/AGENTS.md"
27 archive.addfile(link)
28 for skill in sorted((args.source_home / f".{provider}/skills").iterdir()):
29 if not skill.is_dir():
30 continue
31 source = skill.resolve(strict=True)
32 target = targets.get(source)
33 if target is None:
34 target = f".config/agents/skills/{skill.name}"
35 if target in targets.values():
36 parser.error(f"Different skills share the name {skill.name}; choose their shared version first.")
37 targets[source] = target
38 archive.add(source, arcname=target, filter=keep)
39 link = tarfile.TarInfo(f".{provider}/skills/{skill.name}")
40 link.type = tarfile.SYMTYPE
41 link.linkname = "../../" + target
42 archive.addfile(link)
43 args.archive.chmod(0o600)
44
45
46if __name__ == "__main__":
47 main()
tools/knife-linux-codex.patch created+40
......@@ -0,0 +1,40 @@
1--- a/apps/server/src/provider/Drivers/CodexHomeLayout.ts
2+++ b/apps/server/src/provider/Drivers/CodexHomeLayout.ts
3@@ -30,7 +30,7 @@
4
5 const PRIVATE_ENTRY_NAMES = new Set(["auth.json", "models_cache.json"]);
6 // Finder maintains metadata separately for each directory, including shadow homes.
7-const SHADOW_LOCAL_ENTRY_NAMES = new Set(["log", "memories", "tmp", ".DS_Store"]);
8+const SHADOW_LOCAL_ENTRY_NAMES = new Set(["log", "memories", "tmp", ".tmp", ".DS_Store"]);
9 // Codex creates these runtime locks itself when it starts in a shadow home before the shared
10 // home has one. They guard shared state, so a local copy is replaced with the shared link.
11 const REPLACEABLE_SHARED_RUNTIME_ENTRIES = new Set(["mcp-oauth-locks", ".sqlite-maintenance.lock"]);
12--- a/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts
13+++ b/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts
14@@ -234,11 +234,13 @@
15 yield* fileSystem.makeDirectory(path.join(sharedHome, "log"));
16 yield* fileSystem.makeDirectory(path.join(sharedHome, "memories"));
17 yield* fileSystem.makeDirectory(path.join(sharedHome, "tmp"));
18+ yield* fileSystem.makeDirectory(path.join(sharedHome, ".tmp"));
19 yield* writeTextFile(path.join(sharedHome, "config.toml"), 'model = "gpt-5-codex"\n');
20 yield* writeTextFile(path.join(shadowHome, "auth.json"), '{"shadow":true}\n');
21 yield* fileSystem.makeDirectory(path.join(shadowHome, "log"), { recursive: true });
22 yield* fileSystem.makeDirectory(path.join(shadowHome, "memories"), { recursive: true });
23 yield* fileSystem.makeDirectory(path.join(shadowHome, "tmp"), { recursive: true });
24+ yield* fileSystem.makeDirectory(path.join(shadowHome, ".tmp"), { recursive: true });
25
26 const layout = yield* resolveCodexHomeLayout(
27 decodeCodexSettings({
28@@ -260,7 +262,12 @@
29 .readLink(path.join(shadowHome, "tmp"))
30 .pipe(Effect.result);
31
32+ const dotTmpLinkResult = yield* fileSystem
33+ .readLink(path.join(shadowHome, ".tmp"))
34+ .pipe(Effect.result);
35+
36 expect(configTarget).toBe(path.join(sharedHome, "config.toml"));
37+ expect(dotTmpLinkResult._tag).toBe("Failure");
38 expect(logLinkResult._tag).toBe("Failure");
39 expect(memoriesLinkResult._tag).toBe("Failure");
40 expect(tmpLinkResult._tag).toBe("Failure");
tools/knife-linux.md created+100
......@@ -0,0 +1,100 @@
1# Headless Knife on Snow Globe
2
3`knife-linux` is a Fedora 44 Podman container that runs The Knife for Linux
4agents directly beside ZFS. [knife-linux.nix](../nixos/knife-linux.nix) builds it
5from [knife-linux.Containerfile](../nixos/knife-linux.Containerfile) on each start
6and runs it as the `knife-linux` system service: uid 3000 (`clo`), no
7capabilities, 12 CPUs, a 32 GiB memory limit, and Podman's NAT network. Knife
8listens on container loopback port 3773; devices reach it through the mesh as
9`snowglobe` (device `4b85ee48…`). User namespaces work inside, so Chrome's
10sandbox and agent sandboxes run unprivileged.
11
12| Container path | Host source |
13| --- | --- |
14| `/Volumes/Code` | the Mac VM's NFS export, `/srv/mac-studio-vm/sandbox` |
15| `/home/clo` | `/srv/knife-linux/home` on `globe/clover/knife-linux` |
16| `/usr/local/bin/jj` | the storage host's `jj-real`, read-only |
17
18Projects keep the Mac VM's paths, so jj workspaces, Knife project paths, and
19Claude memory keys match on both. A workspace's `node_modules` serves one OS at
20a time; run `vp i` after moving a workspace between them. pnpm's global config
21uses the storage host's `/Volumes/Code/cache/pnpm12` store and `files` index
22format. jj per-repo configs in `~/.config/jj/repos` are copies of the Mac VM's,
23keyed by each repository's `config-id`.
24
25`globe/clover/knife-linux` must stay case-sensitive. Its parent is not, and
26Fedora packages and overlay layers fail under case folding. Podman's store lives
27on this dataset because the root NVMe is nearly full. `knife-linux-podman` is the
28only entry point to that store: it pins a separate temp directory and file locks,
29because a second rootful store sharing Nomad's lock segment would free the other
30store's locks during its post-reboot refresh.
31
32```sh
33ssh root@10.0.0.1 'systemctl status knife-linux'
34ssh root@10.0.0.1 'journalctl -u knife-linux -n 80 --no-pager'
35ssh -t root@10.0.0.1 'knife-linux-podman exec -it knife-linux bash -l'
36```
37
38The mesh identity and floating profiles in `~/.knife` are the ones the retired
39`knife-linux` VM enrolled. Only the container runs that identity. Retirement
40recovery archives are kept privately on the owner's Mac at
41`~/.local/share/knife-linux-recovery/20261023` and on the external Documents drive
42at `Knife Recovery/20261023`. Each copy was restored into an isolated container
43with networking disabled, checking the application, databases, and identity keys.
44
45## Runtime and updates
46
47The active runtime is `~/.local/share/knife-server/current`, pointing to
48`build-372d14b9d5b4-linux-tmp`. This is a pinned native build of Clover's
49`knife-merge` fork, not the older published Linux container. Source archive
50SHA256: `372d14b9d5b41eef1e8bcc856966fbc8749dd091df1ac09682c9238770f68b39`.
51Private installation archives are on ZFS in `/srv/vm/.knife-linux-deploy-20261023`.
52Apply [knife-linux-codex.patch](knife-linux-codex.patch) before building. It keeps
53Codex's `.tmp` plugin locks local to each profile so restarts can recreate drivers.
54[knife-server](knife-server) is the `~/.local/bin/knife` launcher.
55
56Build inside the container from a fresh source directory, keeping the current
57runtime available until verification succeeds:
58
59```sh
60pnpm install --frozen-lockfile
61vp run --filter t3 build
62CARGO_BUILD_JOBS=8 cargo build --locked --release \
63 --manifest-path native/knife-mesh/Cargo.toml -p knife-mesh-node \
64 --target x86_64-unknown-linux-gnu
65CARGO_BUILD_JOBS=4 cargo build --locked --release \
66 --manifest-path native/resource-monitor/Cargo.toml
67```
68
69After the server build, stage `libknife_mesh_node.so` as
70`apps/server/dist/knife-mesh/linux-x64/knife_mesh.node` and the resource monitor as
71`apps/server/dist/resource-monitor/linux-x64/t3-resource-monitor`. Stage the font
72assets in `apps/server/dist/client/fonts` and link `node` in the runtime root to
73`/opt/node/26.12.1/bin/node`. Switch `current` and `systemctl restart knife-linux`
74only when idle. Automatic fork updates are not configured for this source build.
75
76## Agent homes
77
78[agent-home.py](agent-home.py) exports global instructions and skill catalogs,
79dereferencing Mac/Nix links. Instructions live once in `~/.config/agents/AGENTS.md`;
80Claude and Codex link to it. Shared skill trees live in `~/.config/agents/skills`.
81
82Memory snapshots from the owner Mac and the Mac VM were imported separately from
83credentials and transcripts. Claude project paths under `~/.claude/projects`
84link to canonical stores in `~/.local/share/agents/imported-memories`, including
85the Mac VM's `/Volumes/Code/project` keys. Conflicting versions are preserved,
86and indexes include both versions. Original sources remain intact.
87
88Codex uses the shared Claude-memory hook at `~/.config/agents/codex-memory-hook.py`,
89configured in `~/.codex/config.toml`. Generated Codex memory artifacts also retain
90their original `~/.codex/memories*` locations. Managed agent homes use the global
91instructions, skills, project memories, and hook configuration.
92
93Knife links each Codex profile home's shared entries to `~/.codex`. If Codex
94writes a real file where Knife expects a link, that profile fails at startup with
95"already exists and is not a symlink". If the file matches the `~/.codex` copy,
96delete it; Knife recreates the link on restart.
97Initialize the global Codex home before materializing fresh floating profiles:
98independent first runs create local SQLite files that conflict with shared-home
99links. Do not copy `.knife` identities, auth vaults, or a live SQLite database
100file over an active process.
tools/knife-server created+9
......@@ -0,0 +1,9 @@
1#!/bin/sh
2set -eu
3
4runtime="$HOME/.local/share/knife-server/current"
5export T3CODE_HOME="${T3CODE_HOME:-$HOME/.knife}"
6export T3CODE_CLI_PATH="$HOME/.local/bin/knife"
7export KNIFE_MESH_ADDON="$runtime/apps/server/dist/knife-mesh/linux-x64/knife_mesh.node"
8export T3CODE_RESOURCE_MONITOR_PATH="$runtime/apps/server/dist/resource-monitor/linux-x64/t3-resource-monitor"
9exec "$runtime/node" "$runtime/apps/server/dist/bin.mjs" "$@"