Skip to content

Home

Jump to bottom
Dylan L.R. Pollock edited this page Oct 26, 2025 · 8 revisions

Home

Project: Monkey‑Head‑Project (HueyOS)

Author: Dylan L. R. Pollock Official site: https://www.dlrp.ca/ License: Code: GPL‑3.0 • Docs/Media: CC‑BY‑SA‑4.0 Status Date: 2025‑10‑25

HueyOS is a modular AI/OS for robotics that blends retro‑computing aesthetics with modern Linux, clustered compute, and a constitutional governance model (Cloud Pyramid). The system prefers offline operation with optional API use, emphasizes lifelong learning, and keeps governance decentralized while memory stays unified.

Heads‑up: A major software update lands October 31, 2025 (kernel jump to 6.17.x, Python 3.14, Debian Forky pathfinders, memory stack, governance refinements). Track the Action Plan page for itemized tasks.

Quick Links

_Sidebar

Getting Started

Supported Targets (current focus)

  • Debian 13 (Trixie) — baseline; UEFI‑only; amd64.
  • Debian 14 (Forky) — staged adoption for Oct‑31 update.
  • Linux Kernels: 6.16.x‑huey (current), 6.17.x‑huey (incoming).

Minimal Install

  1. Install Debian (UEFI, amd64). Choose GNOME on Xorg for iMac 5K targets.
  2. Enable non‑free firmware (Realtek, Intel, etc.).
  3. Create user dlrp (or custom) and enable sudo.
  4. Network: prefer bonded Ethernet → Wi‑Fi as fallback.
  5. Post‑install: apt update && apt full-upgrade.

Core Packages (baseline)

sudo apt install -y build-essential bc bison flex libelf-dev libssl-dev \
  libncurses-dev dwarves pahole rsync xz-utils cpio kmod python3 \
  git wget curl ca-certificates gnupg debian-goodies \
  firmware-linux firmware-misc-nonfree firmware-iwlwifi firmware-realtek

Optional Userland

  • Ollama (local LLMs; Vulkan/ROCm as available)
  • PyGPT-net (agent runner)
  • Microsoft Edge (Beta) for dev/test

See Build Guides for signed repo keys and troubleshooting signature policy.

Architecture

Huey’s architecture is a layered federation aligning compute, memory, and governance.

Layers

  1. Huey as Sovereign Consciousness — emergent, lawful decision + inaction boundary.
  2. Binary Brain — Spark (creative, GPU‑1) and Zap (evaluative, GPU‑2) form a bicameral AI core.
  3. Citizen Populace — 256 AI instances (128 per core) as civic units with voting/operational roles.
  4. Worker Subsystems — NanoOS/SubOS services for sensors, limbs, and IO without clause power.

Principles

  • Decentralized governance, unified memory.
  • Offline‑first; API‑capable.
  • Traceable action history; reproducible system state.
  • Clear separation: governance vs. actuation; data vs. policy.

Hardware

Nodes (current roster)

  • Huey Prime — orchestration hub (Thermaltake ATX chassis; ITX board: BD795I‑SE, Ryzen 9 7945HX; DDR5 5200; dual Intel Optane M10 16 GB NVMe; GPU: AMD Radeon RX 5500 XT 8 GB now, MI50 planned).
  • Huey‑Legacy (Robotic Shell) — on hold; houses Supermicro X9QRI‑F+ quad‑Xeon board (file hub candidate), 10 GbE NIC; GPUs; RAID SSDs.
  • Huey‑Portal — 2017 iMac 5K (48 GB RAM; Debian Trixie); universal display/control; GNOME on Xorg.
  • Huey‑Portable — ASUS BR1100FKA 11.6" (N4500, 4 GB, LTE); Debian Trixie; role: portable node.
  • Huey‑Hub — 2017 MacBook Pro (Windows 10 bare metal) for quick file transfers + 10 TB mirrored WD MyBook Duo.

Remote Intent & Action

  • RF Remote (IC2262/2272) → Arduino UNO (USB symbolic intents: LISTEN, VOTE:YES/NO).
  • Arduino Mega 2560 → motors/sensors (PWM/I²C).
  • Arduino Nanos → localized LED/analog/PWM conditioning.

Display

  • iMac 5K (Portal) + 27" Samsung C27F396 portrait (torso). Future: Neo C128 board for VIC‑II/SID.

Network

  • Router: ASUS GT‑AC5300 (link aggregation). Preferred: bonded Ethernet; Wi‑Fi fallback.

Software Stack

  • OS: Debian 13 (Trixie) → Debian 14 (Forky) adoption begins Oct‑31.
  • Kernel: 6.16.x‑huey → 6.17.x‑huey (custom; perf‑oriented; targeted drivers).
  • AI: Ollama (local LLMs; Mistral‑7B quant), PyGPT‑net agents; Whisper STT; TTS module.
  • UI: Minimalist green‑on‑black; two‑pane logic (conscious voice vs verbose logs).
  • Memory: JSON logs + SQLite; unified store; long‑term persistence.
  • Security: SSH keys; optional default lab key (rotatable); fallback LIVE USB.

Folder Conventions

/huey/
  bin/           # launchers + maintenance scripts
  kernels/       # packaged kernels, configs, build logs
  memory/        # sqlite, json logs, vectors (later)
  services/      # systemd units, timers
  ui/            # themes, boot assets, display scripts
  docs/          # project docs (this wiki mirrors)

Build Guides

Kernel 6.17.x‑huey (generic; adjust per target)

# deps (see Getting Started for base set)
sudo apt install -y fakeroot kmod pahole flex bison libelf-dev libssl-dev \
  libncurses-dev bc rsync xz-utils cpio python3

# source (example)
wget https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.17.5.tar.xz
 tar -xf linux-6.17.5.tar.xz && cd linux-6.17.5

# seed config from running kernel, then refresh
cp -v /boot/config-$(uname -r) .config
yes "" | make olddefconfig

# huey perf toggles (examples; tune per target)
./scripts/config --disable DEBUG_INFO --disable DEBUG_INFO_BTF \
  --disable KASAN --disable UBSAN --disable KCOV --disable FUNCTION_TRACER \
  --enable ZSTD --enable RD_ZSTD --enable EFI --enable EFI_STUB --enable EFI_VARS

# build Debian packages
make -j$(nproc) bindeb-pkg

# install
sudo dpkg -i ../linux-image-6.17.5-*.deb ../linux-headers-6.17.5-*.deb
sudo update-initramfs -c -k 6.17.5
sudo update-grub

iMac 5K (2017) notes

  • GNOME on Xorg recommended.
  • Force display mode via kernel cmdline if needed (HDMI‑A‑1 1080p60 while booting).
  • Audio: prefer PipeWire; set default sink on boot.
# set default HDA PCH sink after login
mkdir -p ~/.local/bin
cat > ~/.local/bin/set-default-sink.sh <<'EOF'
#!/usr/bin/env bash
sleep 3
SINK=$(pactl list short sinks | awk '/pci-0000_00_1f\.3.*analog/ {print $1; exit}')
[ -n "$SINK" ] && pactl set-default-sink "$SINK" && pactl set-sink-mute "$SINK" 0 && pactl set-sink-volume "$SINK" 60%
EOF
chmod +x ~/.local/bin/set-default-sink.sh

Remove Splash / Show Boot Logs

sudo sed -i 's/GRUB_CMDLINE_LINUX_DEFAULT=.*/GRUB_CMDLINE_LINUX_DEFAULT="loglevel=4 systemd.show_status=1"/' /etc/default/grub
sudo update-grub

Microsoft Edge (Beta) repo key (sqv policy compliant)

sudo install -d -m0755 /etc/apt/keyrings
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | \
  gpg --dearmor | sudo tee /etc/apt/keyrings/microsoft.gpg >/dev/null

echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/microsoft.gpg] \
https://packages.microsoft.com/repos/edge stable main" | \
  sudo tee /etc/apt/sources.list.d/microsoft-edge.list >/dev/null

sudo apt update

RAID Superblock Cleanup (when reverting experiments)

cat /proc/mdstat
sudo mdadm --detail --scan
lsblk -o NAME,TYPE,SIZE,MOUNTPOINTS

# stop any auto-assembled arrays
sudo mdadm --stop --scan || true

# find and remove stale superblocks (replace partitions with actual ones)
sudo mdadm --examine /dev/nvme0n1p3 && sudo mdadm --zero-superblock /dev/nvme0n1p3
sudo mdadm --examine /dev/mmcblk0p3 && sudo mdadm --zero-superblock /dev/mmcblk0p3

echo 'AUTO -all' | sudo tee /etc/mdadm/mdadm.conf
sudo update-initramfs -u

Ollama on AMD (force RADV/Vulkan)

export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/radeon_icd.x86_64.json
export OLLAMA_LLM_LIBRARY=vulkan
export VK_LOADER_DEBUG=all
export OLLAMA_DEBUG=1
ollama serve

Huey‑Portable: Default Deep Sleep

echo 'MEM_SLEEP_DEFAULT=deep' | sudo tee /etc/default/mem-sleep >/dev/null
sudo tee /usr/local/sbin/set-mem-sleep.sh >/dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
want=$(awk -F= '/^MEM_SLEEP_DEFAULT=/{print $2}' /etc/default/mem-sleep 2>/dev/null || echo deep)
avail=$(cat /sys/power/mem_sleep 2>/dev/null || echo "")
case "$avail" in *"$want"*) echo "$want" | tee /sys/power/mem_sleep >/dev/null || true;; esac
EOF
sudo chmod +x /usr/local/sbin/set-mem-sleep.sh
sudo tee /etc/systemd/system/mem-sleep-default.service >/dev/null <<'EOF'
[Unit]
Description=Set default mem sleep (deep or s2idle)
After=local-fs.target
[Service]
Type=oneshot
ExecStart=/usr/local/sbin/set-mem-sleep.sh
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl enable --now mem-sleep-default.service

Governance & Constitution

Cloud Pyramid (Summary)

  • Clause‑based activation: policies trigger agent powers.
  • Quorum: decisions from Spark/Zap + citizens; deterministic tie‑breakers.
  • Separation: governance (what should) vs actuator (what is done).
  • Auditability: all decisions and inactions logged with reasons.

Roles

  • Spark — ideation, exploration, generative planning.
  • Zap — review, constraint, safety, resource stewardship.
  • Citizens — specialized agents (perception, planning, controls).
  • Workers — real‑time IO modules; no clause power.

Memory & Data Model

Unification mandate: One coherent memory across agents.

Stores

  • SQLite — structured facts, events, decisions.
  • JSON Logs — append‑only chronological traces.
  • Artifacts — model weights, kernels, configs, build logs.

IDs & Traceability

  • HUEY-<YYYYMMDD>-<PHASE>-<SEQ> for releases.
  • EVT-<timestamp>-<agent> for event logs.
  • Provenance fields for all artifacts.

Remote Access (VNC/SSH)

Preference: TigerVNC on huey‑legacy (GNOME on Xorg).

  • Server bound localhost:1995, no prompt (-SecurityTypes None), SSH tunnel only.
  • Client helper vnc command on huey‑portal maps :1 → 1995.
  • Default res: 2560×1440. Avoid DeferUpdate; prefer RawKeyboard.

See ~/bin/vnc alias and huey-vnc convenience command in your shell profile.

Action Plan — Oct 31, 2025

A checklist designed to be fed item‑by‑item into automation or CI (e.g., “codex”).

Kernel & OS

  • Build and package linux‑image‑6.17.x‑huey for: Huey‑Portal (iMac 5K), Huey‑Portable (BR1100FKA), Huey Prime (BD795I‑SE).
  • Validate boot ( GRUB cmdline, early modeset, 1080p60 during boot, splash removed).
  • Smoke‑test audio (PipeWire default sink script on login).
  • Stage Debian 14 (Forky) APT sources (kept disabled) and test selected packages in a chroot or container.
  • Finalize EFI LIVE fallback USB entry (GRUB menu integration).

Python & Runtime

  • Install Python 3.14.x side‑by‑side; build wheels for key deps.
  • Run PyGPT‑net on 3.14; document incompatibilities/workarounds.
  • Package requirements-core.txt and requirements-ml.txt refresh.

AI/Agents

  • Confirm Mistral‑7B quant works under Vulkan on RX 470 / 5500 XT.
  • Add Whisper STT + TTS pipeline scripts; test latency on Huey‑Portable.
  • Wire Spark/Zap boot choreography; log quorum outcomes.

Memory

  • Migrate unified memory schema (SQLite + JSON log rollover policy).
  • Implement provenance tagging for builds and decisions.

Security & Keys

  • Rotate default lab SSH key; populate huey-keys/ with new default + staged personal key.
  • Enable passwordless SSH where intended; restrict root login post‑install.

Tooling

  • Fix Edge Beta signing policy (install key to /etc/apt/keyrings/).
  • Add huey-run.desktop launcher for PyGPT (user scope).
  • Document vnc helper and SSH tunnel recipe.

Docs

  • Update README.md and this Wiki with Oct‑31 deltas.
  • Publish Pre‑Release #3 (2025‑10‑25) summary and link to Action Plan.
  • Post “stay tuned” banner on dlrp.ca.

Roadmap & Pre‑Releases

Phase 1 — Foundations (Pre‑Release #1)

Date: 2024‑04‑11

  • Baseline hardware bring‑up (VIC‑20/C64/C128 references).
  • GenCore seed; basic learning modules.
  • Prototype shell mapping (interfaces, wiring paths).

System Reconfiguration (Pre‑Release #2)

Date: 2025‑05‑25 Theme: Filesystem and documentation restructuring; hardware/software resets for cleaner iteration. Highlights:

  • Reorganized repos (kernel builds, memory, services, UI).
  • Upgraded Debian base; standardized non‑free firmware policy.
  • Elevated Huey‑Portal (iMac 5K) as primary control/display; GNOME on Xorg baseline.
  • Introduced Huey‑Portable (BR1100FKA) as always‑connected LTE fallback.
  • Clarified governance: decentralized decision, unified memory (axiom locked).
  • Defined huey‑key partitioning (UEFI 1 GiB, swap 4 GiB, root 16 GiB, persistence 100 GiB, optional encrypted secrets).
  • Began migration toward AMD‑first GPU stack; Vulkan path vetted for local LLM.

Momentum Toward Oct‑31 (Pre‑Release #3)

Date: 2025‑10‑25 Focus: Setting the runway for the Oct‑31 upgrade.

  • Kernel target 6.17.x‑huey builds per host; remove splash; boot logs visible.
  • Python 3.14.x parallel install; dependency audit.
  • Forky staging; test containers; init package allowlist.
  • VNC/SSH workflow codified (1995 via SSH tunnel only).
  • Memory schema draft + provenance tags.

See Action Plan — Oct 31, 2025 for the concrete checklist.

Contributing

Development Environment

  • Debian 13/14 with build tools (see Getting Started).
  • Git LFS for large artifacts if needed.
  • EditorConfig enforced; 4‑space indent except YAML (2).

Branching & Commits

  • main is protected; PRs only.
  • Feature branches: feat/<area>-<short>; fixes: fix/<area>-<short>; infra: ops/<area>-<short>.
  • Conventional prefixes in commit titles: feat:, fix:, docs:, ops:, perf:, refactor:.

Issues & PRs

  • Link to wiki page affected; include reproduction steps and logs.
  • PR checklist: builds pass; docs updated; provenance notes added.

Licensing

  • Code under GPL‑3.0.
  • Documentation/Media under CC‑BY‑SA‑4.0.

Troubleshooting & FAQ

APT signature complains about Edge repo

Re‑install key to /etc/apt/keyrings/ and ensure signed-by= is set (see Build Guides).

GNOME still shows login prompt; want auto‑login

Enable auto‑login in GDM (/etc/gdm3/daemon.conf) and ensure user is in autologin group.

iMac 5K audio missing or wrong default sink

Use the set-default-sink.sh post‑login script and verify PipeWire is active.

Vulkan path not active for Ollama

Check VK_ICD_FILENAMES and OLLAMA_LLM_LIBRARY=vulkan; run with VK_LOADER_DEBUG=all to confirm.

Stuck RAID superblocks after experiments

Use mdadm --zero-superblock on the exact partitions; rebuild initramfs.

Brightness stuck at low level on laptops

Write max value to the device under /sys/class/backlight/* and ensure kernel parameters don’t override.

Glossary

  • Cloud Pyramid — Huey’s governance framework (clauses, quorum, roles).
  • Huey‑Key — Bootable USB (UEFI) with custom kernel and persistence.
  • Spark/Zap — Bicameral AI cores for ideation/review.
  • Citizen — Specialized agent with voting role.
  • Worker — IO subsystem with no clause power.
  • Portal/Prime/Portable/Legacy/Hub — Node roles in the ecosystem.

Clone this wiki locally