Pi-native AI companion OS on NixOS
Very opinionated NixOS build personally for me and my workflows and how I imagine a PC will be in the future. My goal is to leverage the current AI Agents Technology to build an AI Firsts OS designed specifically for one end user to act like a personal life assistant and knowledge management system.
It is very experimental and I am still currently developing it based on my needs and my own code engineering preferences.
I plan to keep this project as minimal as possible so the end user can evolve the OS through Pi without carrying a large default runtime surface.
NixPI packages Pi, host integration, memory, and a small set of built-in user services into one self-hosted system.
NixPI exists to give Pi:
- a durable home directory under
~/nixpi/ - first-class host tools for NixOS workflows
- a local repo proposal workflow for human-reviewed system changes
- a private Matrix-based messaging surface
- a minimal but inspectable operating model based on files, NixOS, and systemd
Current platform capabilities:
- NixPI directory management and blueprint seeding for
~/nixpi/ - persona injection, shell guardrails, durable-memory digest injection, and compaction context persistence
- local-only Nix proposal support for checking the seeded repo clone, refreshing
flake.lock, and validating config before review - host OS management tools for NixOS updates, local/remote switch, systemd, health, and reboot scheduling
- built-in user services for Home and Element Web
- markdown-native durable memory in
~/nixpi/Objects/ - append-only episodic memory in
~/nixpi/Episodes/ - a unified Matrix room daemon with synthesized host-agent fallback and optional multi-agent overlays
- proactive daemon jobs for heartbeat and simple cron-style scheduled turns
- a first-boot flow split between a bash wizard and a Pi-guided persona step
Install NixPI from the standard minimal NixPI installer image:
# 1. Build the installer ISO
nix build .#installerIso
# 2. Write ./result/iso/*.iso to a USB stick and boot it
# 3. In the live environment:
# sudo -i
# nixpi-installer
# choose the target disk and layout in the terminal wizard
# 4. Reboot into NixPI, then finish first boot
setup-wizard.shAfter install, NixPI is operated from the local ~/nixpi git checkout:
cd ~/nixpi
sudo nixos-rebuild switch --flake .To sync with upstream later:
cd ~/nixpi
git fetch upstream
git rebase upstream/main
sudo nixos-rebuild switch --flake .See the documentation site for detailed instructions.
Full documentation is available at alexradunet.github.io/NixPI
Or browse by topic:
| Your Goal | Start Here |
|---|---|
| Installing NixPI | Quick Deploy |
| First-time setup | First Boot Setup |
| Understanding the system | Architecture Overview |
| Reading the code | Codebase Guide |
| Operating a running system | Operations |
| Deep technical reference | Reference |
To run the docs locally:
npm run docs:devInstalled by default:
sshd.servicenetbird.servicematrix-synapse.servicenixpi-daemon.serviceafter setup once AI auth and defaults are readynixpi-home.servicenixpi-element-web.service
| Path | Purpose |
|---|---|
core/ |
NixPI core: NixOS modules, daemon, persona, skills, built-in extensions, and shared runtime code |
core/os/ |
NixOS modules and host configurations |
core/daemon/ |
Matrix room daemon and multi-agent runtime |
core/pi/extensions/ |
Pi-facing NixPI extensions shipped in the default runtime |
tests/ |
unit, integration, daemon, and extension tests |
docs/ |
live project documentation (VitePress site) |
NixPI extends Pi through two active runtime layers:
| Layer | What it is | Typical use |
|---|---|---|
| 📜 Skill | markdown instructions in SKILL.md |
procedures, guidance, checklists |
| 🧩 Extension | in-process TypeScript | Pi-facing tools, hooks, commands |
Built-in service surface is part of the base NixOS system:
Homeon:8080Element Webon:8081Matrixon:6167
| Section | Contains |
|---|---|
| Overview | Project summary and entry points |
| Getting Started | New maintainer orientation |
| Architecture | Subsystem boundaries and runtime flows |
| Codebase | File-by-file responsibility guide |
| Operations | Deploy, setup, and run procedures |
| Reference | Deep technical documentation |
| Contributing | Maintainer guidelines |