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, 13 cores (26 threads) to itself, a 96 GiB memory limit, `/dev/kvm`, and Podman's NAT network.
8Knife listens on container loopback port 3773; devices reach it through the mesh
9as `snowglobe` (device `4b85ee48…`). User namespaces work inside, but Podman's
10seccomp filter blocks the `chroot` Chromium-based sandboxes need, so Chromium,
11Electron, and T3's browser run with their own sandbox off inside the container.
12[knife-linux-oom.py](knife-linux-oom.py) exempts the Knife server, Claude, and
13Codex from the OOM killer; whatever they run stays killable at score 800.
14It sets every server thread to nice -20, harnesses to 0, and their commands to
1519, including newly executed commands. All use normal CPU scheduling.
16
17Deploys never restart the container: restarting stops Knife and every running
18agent. Image and unit changes apply at the next manual
19`systemctl restart knife-linux`; packages installed live with
20`knife-linux-podman exec --user root --privileged knife-linux dnf install …`
21last only until then, so add them to the Containerfile too. Devices cannot be
22added to the running container.
23
24| Container path | Host source |
25| --- | --- |
26| `/work` | the unencrypted, uncompressed `work` SSD pool, `/srv/work` |
27| `/home/clo` | `/srv/knife-linux/home` on encrypted `work/knife-linux` |
28| `/usr/local/bin/jj` | the storage host's `jj-real`, read-only |
29
30jj per-repo configs in `~/.config/jj/repos` are copies of the Mac VM's, keyed
31by each repository's `config-id`.
32
33`work/knife-linux` must stay case-sensitive for Fedora packages and overlay
34layers. `knife-linux-podman` is the
35only entry point to that store: it pins a separate temp directory and file locks,
36because a second rootful store sharing Nomad's lock segment would free the other
37store's locks during its post-reboot refresh.
38
39```sh
40ssh root@10.0.0.1 'systemctl status knife-linux'
41ssh root@10.0.0.1 'journalctl -u knife-linux -n 80 --no-pager'
42ssh -t root@10.0.0.1 'knife-linux-podman exec -it knife-linux bash -l'
43```
44
45The mesh identity and floating profiles in `~/.knife` are the ones the retired
46`knife-linux` VM enrolled. Only the container runs that identity. Retirement
47recovery archives are kept privately on the owner's Mac at
48`~/.local/share/knife-linux-recovery/20261023` and on the external Documents drive
49at `Knife Recovery/20261023`. Each copy was restored into an isolated container
50with networking disabled, checking the application, databases, and identity keys.
51
52`~/computer.py` is a copy of [computer.py](computer.py), a standard-library client
53for scripting VMs through the Computer MCP; its connection lives in
54`~/.config/computer-mcp`. [computer-client-test.py](computer-client-test.py)
55runs it against a local dashboard with a stub host. Git pushes to Shale use a
56personal access token from Clover's Shale settings, kept by git's credential
57store in `~/.git-credentials`.
58
59## Runtime and updates
60
61The published Linux runtime lives under `~/.knife/runtime/versions`, with
62`~/.knife/runtime/current` selecting the active version and `runtime/release-feed`
63selecting the Knife release feed. [knife-server](knife-server) is installed as
64`~/.local/bin/knife`; the container's `start` command runs the foreground service
65launcher in web mode, allowing remote updates to replace the server in place.
66The previous source build remains under `~/.local/share/knife-server`.
67
68## Agent homes
69
70[agent-home.py](agent-home.py) exports global instructions and skill catalogs,
71dereferencing Mac/Nix links. Instructions live once in `~/.config/agents/AGENTS.md`;
72Claude and Codex link to it. Shared skill trees live in `~/.config/agents/skills`.
73
74Memory snapshots from the owner Mac and the Mac VM were imported separately from
75credentials and transcripts. Claude project paths under `~/.claude/projects`
76link to canonical stores in `~/.local/share/agents/imported-memories`, including
77the Mac VM's `/Volumes/Code/project` keys. Conflicting versions are preserved,
78and indexes include both versions. Original sources remain intact.
79
80Codex uses the shared Claude-memory hook at `~/.config/agents/codex-memory-hook.py`,
81configured in `~/.codex/config.toml`. Generated Codex memory artifacts also retain
82their original `~/.codex/memories*` locations. Managed agent homes use the global
83instructions, skills, project memories, and hook configuration.
84
85Knife links each Codex profile home's shared entries to `~/.codex`. If Codex
86writes a real file where Knife expects a link, that profile fails at startup with
87"already exists and is not a symlink". If the file matches the `~/.codex` copy,
88delete it; Knife recreates the link on restart.
89Initialize the global Codex home before materializing fresh floating profiles:
90independent first runs create local SQLite files that conflict with shared-home
91links. Do not copy `.knife` identities, auth vaults, or a live SQLite database
92file over an active process.