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