IRAM OS

Hyprland on Ubuntu LTS, set up properly, with an MCP server that lets AI agents operate the desktop inside permission limits you control.

Try it

git clone https://github.com/apravint/iram-os.git && cd iram-os
./install.sh --dry-run   # prints every change and modifies nothing
./install.sh core        # desktop only, no AI stack

Then pick IRAM OS at your login screen. Before changing anything, the installer backs up your existing configs to ~/.config/iram/backups/. Profiles are core, ai, and all. There is also a bootable ISO.

Requirements: Ubuntu 26.04 LTS (or the ISO below), Python 3.12+, and a GPU/VM supported by Hyprland. Only the Ubuntu base has been tested; other distributions are not supported. Run the tests with bash tests/run.sh (no root, compositor, or network needed).

Screenshots

Theme switcher	3D agent swarm	3D CAD inspector

What makes it different

An agent can act on your desktop without getting a shell. Most "AI OS" projects hand a model a terminal. IRAM's MCP server exposes typed tools in three permission tiers, with arguments validated before anything runs:

Tier	Examples	Control
read	hypr_query, system_telemetry (per-GPU VRAM, battery), crash_report, service_diagnostics, list_apps, screenshot	No side effects. Credential-shaped strings are masked in logs. screenshot is refused while a password manager is on screen, and every capture is logged.
desktop (default ceiling)	manage_windows, workspace_control, window_rule, self_heal, switch_theme, notify, launch_app	Limited to your session and logged to ~/.local/state/iram-os/mcp-audit.jsonl. No tool can reach Hyprland's exec: launch_app takes an installed app's desktop ID, never a command, and notifications are always labelled IRAM agent.
privileged (off by default)	privileged_action: restart network or Bluetooth, fstrim, journal vacuum	Fixed commands only, and each run needs your approval in a polkit prompt.

iram mcp-config --inject   # connect Claude Code, Antigravity, and Gemini CLI

It has no pip dependencies, only the Python standard library. Raise the ceiling in ~/.config/iram/mcp-policy.json. The policy lives in bin/iram_policy.py, and the tests in tests/ drive the real server over stdio.

One shortcut gives the agent your context. Super + C collects the active window, working directory, and clipboard, then opens your agent with them. Super + Alt + C adds OCR of a screen region you select. Clipboard text is withheld while a password manager has focus, and secrets are masked. Context reaches the agent through a private temp file, so it never appears in ps.

It keeps working offline. The launcher tries Claude Code, then Antigravity, then local Ollama, and skips the cloud options when there is no network. iram ai-setup picks models that fit your VRAM or RAM.

The desktop is managed by systemd, not a pile of exec-once lines. Waybar, wallpaper, notifications, clipboard history, idle handling, and the polkit agent are user units under hyprland-session.target. They restart on failure and stop cleanly with the session. The session environment reaches systemd and D-Bus before any of them start, and portals are restarted once it is in place, so screen sharing and file pickers get the right environment.

Hardware settings are detected at every login. iram-gpu-env reads /sys and sets only what your machine needs:

Detected	Result
NVIDIA, proprietary driver	GBM_BACKEND, __GLX_VENDOR_LIBRARY_NAME, LIBVA_DRIVER_NAME, software cursor
Hybrid Intel or AMD + NVIDIA	AQ_DRM_DEVICES with the integrated GPU first, GBM_BACKEND left unset
AMD or Intel	The right VA-API driver, hardware cursors kept
KVM, VirtualBox, VMware	Software cursor, blur off, software GL where the guest has no usable driver
NVIDIA card on nouveau	None of the NVIDIA variables

Upgrades don't overwrite your edits. A manifest records what was shipped, so a file you changed stays as it is and the new version lands beside it as *.iram-new. Your own settings go in ~/.config/hypr/user-overrides.conf, which upgrades never touch.

Config rollback is real. iram snapshot restore extracts into a staging directory, rejects archives with unsafe paths or symlinks, saves your current state first, then swaps directories by rename. Files added since the snapshot are removed rather than merged, and a failed swap rolls back.

Themes reach apps outside the compositor. Each of the 55 themes applies live to Hyprland, Waybar, Wofi, Alacritty, btop, cava, hyprlock, and SwayNC. It also sets GTK 3/4, Qt 5/6 (qt5ct/qt6ct), gsettings, and the XWayland cursor, so light and dark mode stay consistent. The one visible flicker is the wallpaper, because swaybg has to restart to change image.

Architecture

graph TD
    subgraph Agents
        CC["Claude Code / Antigravity / Ollama"]
        Assist["iram-assist (Super + C)"]
    end
    subgraph Control["Policy boundary"]
        MCP["iram-os-mcp<br/>read / desktop / privileged"]
        Policy["iram_policy.py<br/>allowlists, validation, redaction"]
        Polkit["polkit prompt"]
    end
    subgraph Session["hyprland-session.target"]
        Hypr["Hyprland"]
        Units["waybar, swaybg, swaync, hypridle,<br/>cliphist, polkit agent, watchdog"]
    end
    Boot["hyprland-start<br/>iram-gpu-env, then compositor"] --> Hypr
    Hypr -- "iram-session-bootstrap" --> Units
    Assist --> CC
    CC -- "stdio JSON-RPC" --> MCP
    MCP --> Policy
    Policy --> Hypr
    Policy --> Units
    Policy -- "fixed actions only" --> Polkit

Loading

Install from the ISO

Build it with sudo ./build/build-iso.sh, or download it from Releases. The live session is for trying things out and logs in as iram with passwordless sudo. To install:

sudo iram-install-disk   # erases the disk you pick, after you type its path to confirm

It creates a GPT layout that boots on UEFI and BIOS, then creates your user. It removes the iram account, passwordless sudo, autologin, and casper from the installed system, and generates a fresh machine ID.

Package install

build/package-deb.sh builds iram-desktop, iram-themes, iram-ai, and the iram-os metapackage. build/publish-apt-repo.sh turns those into a signed APT repository. No public repository is hosted yet, so use install.sh or build your own.

Security notes

• MCP clients should use stdio. The optional FastMCP SSE service has no authentication, so it is off by default.
• The Hub and agent daemon listen on loopback and refuse browser-forged requests, checking Host, Origin, Sec-Fetch-Site, and Content-Type. They do not authenticate other local users on a shared machine.
• Agent commands run without a shell, from an allowlist: one program, literal arguments, no chaining.
• iram-ai-cmd shows a generated shell command and runs it only if you type e. That command is unrestricted, so read it first.
• install.sh runs Ollama's upstream install script in the ai and all profiles. Use core to skip it.

Status

Tested on every CI run	Not yet covered by automation
200+ checks (tests/run.sh reports 218): MCP protocol and tiers, policy, snapshot restore, upgrade behavior, GPU profiles, rendering of every theme	Physical hardware matrix (Optimus, suspend, hotplug)
shellcheck, systemd-analyze verify, .deb builds	End-to-end iram-install-disk run in a VM
ISO: root filesystem contents and a QEMU boot to userspace (release builds)	Qt and GTK appearance checks across real apps

Bug reports with iram doctor output are the most useful thing you can send.

Omarchy 4.5 ("Quattro RS") Architectural Parity Matrix

IRAM OS ports and extends the modern ergonomics, workflow patterns, and performance optimizations introduced in Omarchy 4.0 (Quattro) and Omarchy 4.5 (Quattro RS), adapted natively for Ubuntu 26.04 LTS + Hyprland:

Omarchy 4.5 Architectural Feature	IRAM OS Implementation	Status & Shortcut
Traditional Desktop Mode	Toggle between brutalist sharp tiling and 8px traditional floating desktop with auto-centering	Super + Shift + D / iram-desktop-mode
Quake-Style Drop-Down Scratchpad	Dedicated slide-down AI console & terminal on special:scratchpad	Super + Grave (`) / iram-scratchpad
Window Layout Persistence	Serialize active client windows, workspaces, and sizes to JSON and restore on demand	Super + Alt + Home (Save) / Super + Home (Restore) / iram-layout
Per-Monitor Workspaces	Dynamic workspace partitioning per display monitor (monitor_id * 10) + N	Super + 1..0 / Super + Shift + 1..0
Multi-Agent Switcher	Hot-swap default system agent between agy, claude, gemini, codex, kimi, ollama	iram agent select / iram-agent-select
Crash-to-Agent Diagnostics	Real-time systemd journal error watcher sending crashes to AI agent in scratchpad	iram debug-last-crash / iram-crash-watcher.service
Event-Driven IPC Waybar	Sub-15ms theme and layout status updates via Hyprland socket & RTMIN signals	Built-in (pkill -RTMIN+8 waybar)
Unified Super Menu	Fast fuzzy hierarchical launcher for Apps, AI, Themes, Dev Stack, and System	Super + Space / Super + I / iram-menu
Multi-Terminal & Editor Selectors	Seamlessly switch between Alacritty, Foot, Ghostty, Kitty and Neovim, VS Code, Cursor, Zed	iram-terminal-select, iram-editor-select
TUI Storage & World Clock	Built-in visual disk analyzer tree and multi-timezone world clock	iram-disktree, iram-worldclock
One-Click Dev Stacks	Instant polyglot setup for Rust, Node, Python (UV), Java 21, mise, and creative tools	iram-dev-install
Safer Updates & Inhibit	Single cached sudo keepalive, pre-update snapshots, and systemd-inhibit against sleep/logout	iram update

Reference

Command	Purpose
iram doctor	Check session variables, portals, services, audio, and agents
iram snapshot create|list|restore	Config snapshots and rollback
iram theme [name|list|random|auto]	Switch themes live across all desktop components
iram agent select [agy|claude|gemini|...]	Switch system AI agent (agy, claude, gemini, codex, kimi, ollama)
iram debug-last-crash	Pipe most recent crash dump and logs into your default AI agent
iram update [--profile P] [--local]	Snapshot, pull, reinstall, migrate, restart what changed with sleep inhibit and single sudo
iram-desktop-mode [toggle|tiling|traditional]	Toggle between tiling and floating desktop mode
iram-layout [save|restore]	Save or restore active window positions and workspaces
iram-terminal-select [alacritty|foot|...]	Set system-wide default terminal emulator
iram-editor-select [nvim|code|cursor|...]	Set system-wide default code editor
iram-disktree [path]	Interactive TUI disk usage tree visualizer
iram-worldclock [--cli]	Multi-timezone world clock (IST, UTC, EST, PST, GMT, JST, AEDT)
iram-dev-install [stack]	One-click developer and creative toolchain installer
iram ai-setup	Install Ollama and models that fit this machine
iram mcp-config --inject	Register the MCP server with your agents
iram monitor save|apply|list|forget	Remember the layout for the monitors connected now; reapplied on connect
iram monitor rotate [0|90|180|270] / mirror [on|off]	Rotate the focused screen (remembered) / mirror it onto the others
iram-network-dns [cloudflare|quad9|google|auto]	DNS provider for the active network (also in the menu under Network)
iram-network-qr	QR code a phone can scan to join your Wi-Fi

Shortcut	Action
Super + C / Super + Alt + C	Context-aware assistant / with region OCR
Super + Alt + A	Open your agent in a floating terminal
Super + Grave (`)	Quake drop-down scratchpad terminal / AI session
Super + Return / Super + Space	Terminal / Unified Super Menu launcher
Super + Shift + D	Toggle Traditional Desktop Mode vs. Sovereign Tiling
Super + Alt + Home / Super + Home	Save window layout / Restore saved layout
Super + 1..0 / Super + Shift + 1..0	Per-monitor workspace switch / move window
Super + Alt + [ / ]	Fine window resize (-25px / +25px)
Super + Ctrl + Arrows	Coarse window resize (-100px / +100px)
Super + Shift + Arrows	Move active window across monitors
Super + [ / ]	Focus previous / next monitor
Super + K	Full keybinding list
Super + Ctrl + Shift + Space	Theme switcher
Super + L / Super + Escape	Lock / power menu
Super + - / Super + Shift + -	Minimize window / restore one
Super + U	Pop the window out: floating, centred and pinned (again to put it back)

Captive portals (hotel or airport Wi-Fi) open their sign-in page automatically, via iram-captive-portal.service. Opt-in services, off by default: iram-organizer.timer (moves files in ~/Downloads), iram-dual-wifi-keepalive.service, and iram-mcp-server.service. Developer notes are in AGENTS.md. See CONTRIBUTING.md to contribute and SECURITY.md to report a vulnerability.

License

MIT. Trademark notes are in TRADEMARKS.md. IRAM OS is an independent project, not affiliated with or endorsed by Canonical. Ubuntu is a trademark of Canonical Ltd. Hyprland, Waybar, and PipeWire belong to their respective projects.