| author | |
| committer | |
| log | 78daa503d015fc5d1b70bd8a1927000f47ceb64b |
| tree | 42a6f9a110fa397929a2955bc24f31b5d70a7c82 |
| parent | 628f936c593ab09248911fa3f03f28e819d870d4 |
| signature | Signed by SSH key SHA256:52mNGHRsVFBDED9IAX5pe+LRWUefqTbxEReunq21QvU |
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-sol7 files changed, 279 insertions(+), 1 deletions(-)
nixos/knife-linux.Containerfile created+28| ... | ... | @@ -0,0 +1,28 @@ |
| 1 | FROM registry.fedoraproject.org/fedora:44@sha256:0d2a354dfdf7ba75083fe371eb6239842fe13f38c52d339dae1ebcf13c7c4062 | |
| 2 | ||
| 3 | # Development tools, plus the libraries and fonts T3's headless Chrome needs. | |
| 4 | RUN 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 | ||
| 13 | RUN 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 | ||
| 22 | ARG UID | |
| 23 | ARG GID | |
| 24 | RUN groupadd --gid "$GID" chloe && useradd --uid "$UID" --gid "$GID" --no-create-home --home-dir /home/clo clo | |
| 25 | USER clo | |
| 26 | ENV HOME=/home/clo LANG=C.UTF-8 PATH=/home/clo/.local/bin:/usr/local/bin:/usr/bin:/bin | |
| 27 | WORKDIR /Volumes/Code/project | |
| 28 | ENTRYPOINT ["/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, ... }: | |
| 2 | let | |
| 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"; | |
| 18 | in | |
| 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 |
| 16 | 16 | }; |
| 17 | 17 | in |
| 18 | 18 | { |
| 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 ]; | |
| 20 | 20 | |
| 21 | 21 | networking.hostName = "snowglobe"; |
| 22 | 22 | 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.""" | |
| 3 | import argparse | |
| 4 | from pathlib import Path | |
| 5 | import tarfile | |
| 6 | ||
| 7 | ||
| 8 | def 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 | ||
| 46 | if __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 | |
| 4 | agents directly beside ZFS. [knife-linux.nix](../nixos/knife-linux.nix) builds it | |
| 5 | from [knife-linux.Containerfile](../nixos/knife-linux.Containerfile) on each start | |
| 6 | and runs it as the `knife-linux` system service: uid 3000 (`clo`), no | |
| 7 | capabilities, 12 CPUs, a 32 GiB memory limit, and Podman's NAT network. Knife | |
| 8 | listens on container loopback port 3773; devices reach it through the mesh as | |
| 9 | `snowglobe` (device `4b85ee48…`). User namespaces work inside, so Chrome's | |
| 10 | sandbox 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 | ||
| 18 | Projects keep the Mac VM's paths, so jj workspaces, Knife project paths, and | |
| 19 | Claude memory keys match on both. A workspace's `node_modules` serves one OS at | |
| 20 | a time; run `vp i` after moving a workspace between them. pnpm's global config | |
| 21 | uses the storage host's `/Volumes/Code/cache/pnpm12` store and `files` index | |
| 22 | format. jj per-repo configs in `~/.config/jj/repos` are copies of the Mac VM's, | |
| 23 | keyed by each repository's `config-id`. | |
| 24 | ||
| 25 | `globe/clover/knife-linux` must stay case-sensitive. Its parent is not, and | |
| 26 | Fedora packages and overlay layers fail under case folding. Podman's store lives | |
| 27 | on this dataset because the root NVMe is nearly full. `knife-linux-podman` is the | |
| 28 | only entry point to that store: it pins a separate temp directory and file locks, | |
| 29 | because a second rootful store sharing Nomad's lock segment would free the other | |
| 30 | store's locks during its post-reboot refresh. | |
| 31 | ||
| 32 | ```sh | |
| 33 | ssh root@10.0.0.1 'systemctl status knife-linux' | |
| 34 | ssh root@10.0.0.1 'journalctl -u knife-linux -n 80 --no-pager' | |
| 35 | ssh -t root@10.0.0.1 'knife-linux-podman exec -it knife-linux bash -l' | |
| 36 | ``` | |
| 37 | ||
| 38 | The mesh identity and floating profiles in `~/.knife` are the ones the retired | |
| 39 | `knife-linux` VM enrolled. Only the container runs that identity. Retirement | |
| 40 | recovery archives are kept privately on the owner's Mac at | |
| 41 | `~/.local/share/knife-linux-recovery/20261023` and on the external Documents drive | |
| 42 | at `Knife Recovery/20261023`. Each copy was restored into an isolated container | |
| 43 | with networking disabled, checking the application, databases, and identity keys. | |
| 44 | ||
| 45 | ## Runtime and updates | |
| 46 | ||
| 47 | The 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 | |
| 50 | SHA256: `372d14b9d5b41eef1e8bcc856966fbc8749dd091df1ac09682c9238770f68b39`. | |
| 51 | Private installation archives are on ZFS in `/srv/vm/.knife-linux-deploy-20261023`. | |
| 52 | Apply [knife-linux-codex.patch](knife-linux-codex.patch) before building. It keeps | |
| 53 | Codex'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 | ||
| 56 | Build inside the container from a fresh source directory, keeping the current | |
| 57 | runtime available until verification succeeds: | |
| 58 | ||
| 59 | ```sh | |
| 60 | pnpm install --frozen-lockfile | |
| 61 | vp run --filter t3 build | |
| 62 | CARGO_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 | |
| 65 | CARGO_BUILD_JOBS=4 cargo build --locked --release \ | |
| 66 | --manifest-path native/resource-monitor/Cargo.toml | |
| 67 | ``` | |
| 68 | ||
| 69 | After 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 | |
| 72 | assets 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` | |
| 74 | only 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, | |
| 79 | dereferencing Mac/Nix links. Instructions live once in `~/.config/agents/AGENTS.md`; | |
| 80 | Claude and Codex link to it. Shared skill trees live in `~/.config/agents/skills`. | |
| 81 | ||
| 82 | Memory snapshots from the owner Mac and the Mac VM were imported separately from | |
| 83 | credentials and transcripts. Claude project paths under `~/.claude/projects` | |
| 84 | link to canonical stores in `~/.local/share/agents/imported-memories`, including | |
| 85 | the Mac VM's `/Volumes/Code/project` keys. Conflicting versions are preserved, | |
| 86 | and indexes include both versions. Original sources remain intact. | |
| 87 | ||
| 88 | Codex uses the shared Claude-memory hook at `~/.config/agents/codex-memory-hook.py`, | |
| 89 | configured in `~/.codex/config.toml`. Generated Codex memory artifacts also retain | |
| 90 | their original `~/.codex/memories*` locations. Managed agent homes use the global | |
| 91 | instructions, skills, project memories, and hook configuration. | |
| 92 | ||
| 93 | Knife links each Codex profile home's shared entries to `~/.codex`. If Codex | |
| 94 | writes 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, | |
| 96 | delete it; Knife recreates the link on restart. | |
| 97 | Initialize the global Codex home before materializing fresh floating profiles: | |
| 98 | independent first runs create local SQLite files that conflict with shared-home | |
| 99 | links. Do not copy `.knife` identities, auth vaults, or a live SQLite database | |
| 100 | file over an active process. |
tools/knife-server created+9| ... | ... | @@ -0,0 +1,9 @@ |
| 1 | #!/bin/sh | |
| 2 | set -eu | |
| 3 | ||
| 4 | runtime="$HOME/.local/share/knife-server/current" | |
| 5 | export T3CODE_HOME="${T3CODE_HOME:-$HOME/.knife}" | |
| 6 | export T3CODE_CLI_PATH="$HOME/.local/bin/knife" | |
| 7 | export KNIFE_MESH_ADDON="$runtime/apps/server/dist/knife-mesh/linux-x64/knife_mesh.node" | |
| 8 | export T3CODE_RESOURCE_MONITOR_PATH="$runtime/apps/server/dist/resource-monitor/linux-x64/t3-resource-monitor" | |
| 9 | exec "$runtime/node" "$runtime/apps/server/dist/bin.mjs" "$@" |