Skip to content
ProjectDEV-gitPublic

About

A local-AI-native Linux distro built on Ubuntu. Spaces-based desktop, Intent Bar, and always-on Ollama — no cloud, no tracking, just your machine thinking with you. Resources

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

324 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Axon OS

License: MIT Build & Lint

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.

Screenshots

Axon OS desktop preview

Features

  • 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 through Brain.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 a sqlite-vec vector store (~/.axon/semantic-index.db) using local nomic-embed-text embeddings. Type find the script with the snapshot logic in 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 .exe or .msi, or run ./program.exe in a terminal (the kernel's binfmt_misc hands 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 of gsettings operations ("enable night light and make text bigger") and applied in milliseconds — no synthetic clicking.
  • Self-Healing Boot Watchdog — Installs root on BTRFS @/@home subvolumes, snapshots a factory @axon-fallback after 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 the axon-os package 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/.

v1.0.0 — New Features

  • Plugin System — Write new D-Bus services with a TOML manifest. ServiceBase base class handles all boilerplate. Install with python3 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.sh runs all checks locally. CI enforces 40% coverage threshold.

Installation

From ISO (recommended)

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
  1. Download an .iso from the Releases page (a version release, or nightly for the newest build of main), or a fresh build from the latest Build ISO workflow run (Artifacts → axon-os-iso-standard or axon-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 .sha256 file 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
  2. Flash to a USB drive (replace /dev/sdX with your device):
    sudo dd if=axon-os-<version>-standard-amd64.iso of=/dev/sdX bs=4M status=progress oflag=sync
  3. 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.

From Source (development / testing)

# 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.sh

Note: Running from source requires an existing Ubuntu 24.04 GNOME session.

To undo it: ./uninstall.sh --dry-run shows what would be removed, ./uninstall.sh removes it (your files, Ollama and its models are kept unless you ask).

Building the ISO

# 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-chroot

The 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.

Architecture

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.

Tech Stack

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

Project Structure

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

Contributing

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).

  1. Fork the repository and create a feature branch.
  2. Make your changes, ensuring CI passes locally where possible.
  3. Open a pull request against main.

License

Axon OS is released under the MIT License.
Copyright (c) 2024 Axon OS Contributors.

About

A local-AI-native Linux distro built on Ubuntu. Spaces-based desktop, Intent Bar, and always-on Ollama — no cloud, no tracking, just your machine thinking with you. Resources

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages