Axon OS is a local-first, AI-native Linux distribution built on Ubuntu 26.04 LTS (24.04 installs can upgrade: docs/ubuntu-26.04.md). Every AI capability runs entirely on-device through Ollama by default — no cloud accounts, no API keys, no data leaving your machine. If you want, you can also pick any cloud or company model (OpenAI, Anthropic, Gemini, OpenRouter, any OpenAI-compatible endpoint) with an API key or sign-in; see docs/ai-providers.md.
The operating system is built around two centralized D-Bus services — Axon Brain (AI inference, model management, conversation history) and Axon Context (ambient desktop awareness) — that power a purpose-built GNOME Shell environment with named workspaces, an intent-driven command bar, a persistent AI side panel, and AI-native applications.
- Axon Brain (
org.axonos.Brain) — A centralized D-Bus AI gateway that handles Ollama and optional cloud-provider communication, model lifecycle, task-to-model routing (Speed / General / Deep tiers), conversation persistence in SQLite, and streaming token generation — accessible to every app on the system. - Axon Context (
org.axonos.Context) — An ambient context engine that tracks the active window, workspace, clipboard, open files, and terminal history, then feeds this context into AI queries for situationally-aware responses. - Hardware Profiler — Automatically scans your system RAM, GPU vendor (NVIDIA / AMD / Intel), and VRAM to recommend three local models: a Speed tier for instant responses, a General tier for daily use, and a Deep tier for complex reasoning and coding.
- Spaces (Super+1-9) — Named workspaces with AI-powered window auto-routing. Open a terminal and it routes to the "Terminal" space; open VS Code and it goes to "Code". Each space carries its own context.
- Intent Bar (Super+Space) — A floating command bar that accepts natural-language input and maps it to system actions, app launches, and shell commands through the Brain service.
- AI Panel (Super+A) — A slide-in side panel with persistent, context-aware AI conversations. The panel automatically includes your desktop context (active window, open files, recent commands) in every query.
- Axon Terminal — An AI-powered terminal with automatic error diagnosis, natural-language-to-command conversion, and smart suggestions when commands fail.
- GTK4 + libadwaita theming — Native GNOME components with a custom Axon dark theme built on libadwaita for crisp HiDPI rendering.
- Axon Voice (
org.axonos.Voice, Super+V) — Push-to-talk speech-to-intent: audio is transcribed locally with faster-whisper (model cached in~/.axon/models/whisper/), routed throughBrain.ClassifyIntent, and executed — with a glowing wave overlay during capture and spoken answers via speech-dispatcher. - Semantic Search (
org.axonos.Search) — An ambient indexer that chunks and embeds your documents/code into asqlite-vecvector store (~/.axon/semantic-index.db) using localnomic-embed-textembeddings. Typefind the script with the snapshot logicin the Intent Bar and get meaning-based matches; falls back to FTS5 keyword search offline. - Rogue Software Shield (
axon-shield) — Run untrusted scripts through a static + AI audit (SSH-key theft,curl | sh, reverse shells, persistence hooks...) and execute them inside a bubblewrap sandbox with a read-only home, masked secrets, and optional network blackout. - Windows programs (APEX-WIN) — Double-click any
.exeor.msi, or run./program.exein a terminal (the kernel'sbinfmt_mischands it over), and it runs with Wine through the vendored APEX-WIN runner, with no sandbox and as your user. See docs/windows-apps.md. - GUI Agent (
org.axonos.GuiAgent) — Tell the OS to change its own settings: natural-language requests are compiled by the Brain into an allowlisted plan ofgsettingsoperations ("enable night light and make text bigger") and applied in milliseconds — no synthetic clicking. - Self-Healing Boot Watchdog — Installs root on BTRFS
@/@homesubvolumes, snapshots a factory@axon-fallbackafter install, and counts boot attempts in a GRUB env file on the ESP. Two consecutive failed boots and GRUB automatically boots the rollback snapshot. - Axon Updater (
axon-update) — A graphical + headless updater that updates APT and Flatpak packages, including theaxon-ospackage from the Axon apt repo, so each release reaches installed systems without a new ISO. It runs on a daily timer. See docs/updates.md. - Zero cloud dependency — No telemetry, no mandatory accounts, no remote inference endpoints. All data stays on your machine in
~/.axon/.
- Plugin System — Write new D-Bus services with a TOML manifest.
ServiceBasebase class handles all boilerplate. Install withpython3 services/plugin_deploy.py --install <dir>. - AI Model Marketplace — Browse, download, and manage local AI models. 10-model curated catalog with disk usage monitoring and smart recommendations.
- Context-Aware AI Routing — Automatically selects the optimal model (Speed/General/Deep) based on task classification. Code tasks go to Deep, quick answers to Speed.
- Advanced Voice Pipeline — Multi-engine STT (whisper, vosk), wake word detection ("Hey Axon"), streaming partial transcripts, language selection, TTS.
- System-Wide AI Search — Unified search across files, desktop apps, and GNOME settings with AI-powered answers.
- Containerized Deployment — Run all services in Docker with
docker compose up -d. - Telemetry & Crash Reporting — Opt-in, local-only event tracking and crash dumps. No data leaves your machine.
- QA Pipeline —
scripts/qa.shruns all checks locally. CI enforces 40% coverage threshold.
Axon OS comes in two editions. Pick by graphics card:
| Edition | For | File |
|---|---|---|
| Standard | AMD, Intel and older NVIDIA cards (GTX 10-series and earlier) | axon-os-<version>-standard-amd64.iso |
| NVIDIA | GTX 16-series, RTX and newer. Includes the NVIDIA driver, signed so it works with Secure Boot on | axon-os-<version>-nvidia-amd64.iso |
- Download an
.isofrom the Releases page (a version release, ornightlyfor the newest build ofmain), or a fresh build from the latest Build ISO workflow run (Artifacts →axon-os-iso-standardoraxon-os-iso-nvidia). GitHub limits release files to 2 GB, so a release ISO is split into.part00,.part01, ... files. Put all the parts and the.sha256file in one folder, then join and check them:cat axon-os-<version>-standard-amd64.iso.part* > axon-os-<version>-standard-amd64.iso sha256sum -c axon-os-<version>-standard-amd64.iso.sha256
- Flash to a USB drive (replace
/dev/sdXwith your device):sudo dd if=axon-os-<version>-standard-amd64.iso of=/dev/sdX bs=4M status=progress oflag=sync
- Boot from the USB and follow the guided installer.
Games, launchers, emulators, AI models and GPU acceleration for local AI are not on the ISO: the welcome app and Game Center install what you pick after setup. See docs/gaming.md.
# Clone the repository
git clone https://github.com/ProjectDEV-git/Axon-OS.git
cd Axon-OS
# Install system dependencies
sudo apt-get install -y python3-gi python3-gi-cairo gir1.2-gtk-4.0 \
gir1.2-adw-1 python3-dbus gir1.2-vte-3.91
# Install Ollama (if not already installed): a pinned release, checked against its SHA-256
sudo bash build/config/install-ollama.sh
# Run the full installer (sets up D-Bus services, shell extension, apps)
./install.shNote: Running from source requires an existing Ubuntu 24.04 GNOME session.
To undo it:
./uninstall.sh --dry-runshows what would be removed,./uninstall.shremoves it (your files, Ollama and its models are kept unless you ask).
# Full build (requires sudo)
sudo bash build/build.sh
# The NVIDIA edition (the default is --edition standard)
sudo bash build/build.sh --edition nvidia
# Quick rebuild — reuse existing chroot, skip debootstrap
sudo bash build/build.sh --quick
# Ultra-fast rebuild — quick + gzip compression (3-5x faster; local testing only, not release quality)
sudo bash build/build.sh --fast
# Force full clean rebuild from scratch
sudo bash build/build.sh --fresh
# Keep chroot after build for debugging
sudo bash build/build.sh --keep-chroot
# Combine flags
sudo bash build/build.sh --quick --keep-chrootThe ISO is written to dist/axon-os-<version>-<edition>-amd64.iso. The build fails if it is over its size limit (build/size-budget.conf).
Full build documentation — including custom installer, Plymouth splash, and CI details — is in docs/building.md.
Axon OS uses a layered D-Bus architecture where all AI capabilities flow through two centralized services:
┌─────────────────────────────────────────────────────────┐
│ User │
└─────────────────────────┬───────────────────────────────┘
│
┌─────────────▼──────────────┐
│ GNOME Shell │
│ ┌──────────┐ ┌────────┐ │
│ │Intent Bar│ │AI Panel│ │
│ └────┬─────┘ └───┬────┘ │
│ │ Spaces │ │
│ ┌────▼────────────▼────┐ │
│ │ Space Manager │ │
│ └──────────┬──────────┘ │
└─────────────┼─────────────┘
│ D-Bus (session bus)
┌────────────────┼────────────────┐
│ │ │
┌────────▼─────────┐ ┌───▼─────────┐ ┌────▼──────────┐
│ org.axonos.Brain │ │org.axonos. │ │ Axon Terminal │
│ ├─ Model Routing│ │ Context │ │ Axon Files │
│ ├─ Conversations│ │ ├─ Window │ │ Axon Settings │
│ ├─ HW Profiling │ │ ├─ Clipboard│ └───────────────┘
│ └─ Streaming │ │ └─ Files │
└────────┬─────────┘ └─────────────┘
│ HTTP (localhost)
┌────────▼─────────┐
│ Ollama Daemon │
│ (localhost:11434)│
└────────┬─────────┘
│ llama.cpp / CUDA / ROCm
┌────────▼─────────┐
│ GPU │
└──────────────────┘
For the full architecture document, see docs/architecture.md.
| Component | Version / Detail |
|---|---|
| Base OS | Ubuntu 26.04 LTS (24.04 still builds) |
| Desktop | GNOME Shell 45+ |
| UI Toolkit | GTK4 + libadwaita |
| IPC Layer | D-Bus (session bus) |
| AI Services | org.axonos.Brain, org.axonos.Context |
| AI Runtime | Ollama (localhost) |
| Model Strategy | 3-tier: Speed / General / Deep (auto-profiled) |
| Conversation DB | SQLite (~/.axon/conversations.db) |
| Shell Extension | GJS (GNOME JavaScript) |
| Apps | Python 3.11+ with GTK4 |
Axon-OS/
├── apps/
│ ├── axon-ai-panel/ # AI conversation side panel
│ ├── axon-files/ # AI-powered file manager with semantic search
│ ├── axon-installer/ # Live-session welcome & install wizard (with AI setup)
│ ├── axon-settings/ # NL system settings assistant
│ ├── axon-shortcuts/ # Keyboard shortcut overlay (Super+/)
│ ├── axon-terminal/ # AI-powered terminal
│ ├── axon-voice-overlay/ # Voice input wave animation
│ ├── axon-welcome/ # First-boot welcome & model setup wizard
│ └── intent-bar/ # Natural language command palette
├── services/
│ ├── axon-brain/ # Central AI D-Bus service
│ ├── axon-context/ # Ambient desktop context engine (clipboard, shell history)
│ ├── axon-gui-agent/ # NL desktop automation agent
│ ├── axon-sandbox/ # Rogue Software Shield (bubblewrap sandbox)
│ ├── axon-search/ # Semantic file search with sqlite-vec
│ └── axon-voice/ # Voice-to-intent daemon (faster-whisper)
├── shell/
│ └── axon-shell/ # GNOME Shell extension (dock, spaces, intent bar)
├── system/ # System updater & boot watchdog
├── theme/ # GTK4 dark theme & GRUB theme
├── installer/ # Legacy Calamares branding assets (superseded by apps/axon-installer)
├── plymouth/ # Boot splash
├── build/ # ISO build scripts
├── tests/ # Integration and unit tests
└── docs/ # Architecture and build documentation
Contributions are welcome. Please open an issue first to discuss significant changes. For smaller fixes, a pull request with a clear description is sufficient. All Python code must pass ruff check and all shell scripts must pass shellcheck before merging (enforced by CI).
- Fork the repository and create a feature branch.
- Make your changes, ensuring CI passes locally where possible.
- Open a pull request against
main.
Axon OS is released under the MIT License.
Copyright (c) 2024 Axon OS Contributors.
