rakuos-ai

RakuOS-AI v2

A variant of RakuOS Linux — hybrid atomic distribution with deep AI integration via a three-layer architecture.

Three-Layer Architecture

┌─────────────────────────────────────────────────────────────┐
│                  LAYER 1: Lean bootc Image                  │
│  FROM ghcr.io/rakuos/rakuos-base:latest                      │
│  Bakes in: Podman, Distrobox, CDI tooling, rakuos-ai CLI,   │
│  Sensei container image, systemd services                    │
│  NO heavy AI packages — stays lean                           │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│          LAYER 2: RakuOS Persistent Overlay (/usr)          │
│  GPU drivers (NVIDIA CUDA / AMD ROCm) — native, via overlay  │
│  Ollama binary + native deps — via overlay                    │
│  Uses `rakuos install` (dnf5.real into overlayfs)            │
│  Persists across reboots, rebuilds on bootc upgrade           │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│        LAYER 3: "Sensei" Multi-Agent Framework               │
│  Runs in PRIVILEGED podman container:                        │
│    --privileged --pid=host --network=host                    │
│    -v /var/run/dbus (system D-Bus for systemd)               │
│    -v /var/lib/rakuos-ai:/state (overlay + model state)      │
│    GPU via CDI (--device nvidia.com/gpu=all)                 │
│    Full access to CachyOS kernel (sched_ext, BPF)            │
│  Python multi-agent orchestrator + specialized agents        │
│  API on 127.0.0.1:8777 for desktop UI                         │
└─────────────────────────────────────────────────────────────┘

Why Three Layers?

Quick Start

# 1. First-time setup — installs GPU drivers + Ollama into overlay, starts Sensei
sudo rakuos-ai setup

# 2. Check full stack status
rakuos-ai status

# 3. Interact with Sensei
rakuos-ai sensei chat "What's my GPU memory usage?"

# 4. Pull an AI model (goes into overlay storage)
rakuos-ai model pull llama3.2

Project Structure

rakuos-ai/
├── Containerfile              # Layer 1: Lean bootc image
├── sensei/
│   ├── Dockerfile             # Layer 3: Sensei privileged container
│   ├── src/
│   │   ├── main.py             # Orchestrator entry point
│   │   ├── agents/             # SystemAgent, PackageAgent, InferenceAgent, etc.
│   │   ├── tools/              # D-Bus, podman, ollama, sysctl, BPF clients
│   │   └── orchestrator/       # Agent routing and lifecycle
│   └── configs/               # Agent definitions
├── system_files/
│   ├── usr/bin/rakuos-ai      # CLI tool
│   ├── usr/libexec/rakuos-ai/ # install-ai-overlay, gpu-detect, sensei-launch
│   ├── etc/systemd/system/   # Boot-ordered services
│   └── etc/containers/        # Security policies
└── .github/workflows/         # CI/CD

License

MIT