🧠 Anion

A local AI operating layer for the Linux desktop.

Linux-native · Local-first · ARIA-powered · Terminal-aware · Privacy-conscious

Architecture · Features · ARIA · Testing · Roadmap · Beta Access

Public documentation repository This repository documents Anion’s architecture, product design, features, screenshots, diagrams, release notes, and beta access. The production source code is private during beta and security hardening.

🎯 Recruiter Snapshot

⚡ Overview

Anion is a privacy-first AI assistant layer built for the Linux desktop.

It connects local model inference, terminal intelligence, desktop context, workspace awareness, memory, and a real-time desktop shell into one local-first AI system.

Most AI assistants live in a browser tab. Anion is designed to live beside the operating system.

It can understand the current desktop workflow, reason over local context, assist through ARIA, and surface useful automation while keeping sensitive actions bounded by guardrails and approval flows.

🖼️ Product Preview

Anion control plane showing local AI state, system context, and runtime status.

🧩 What I Built

🏗️ Architecture Overview

flowchart TD
    A[Linux Desktop] --> B[systemd User Services]
    B --> C[Anion Python Backend]

    C --> D[Context Engine]
    C --> E[Memory Layer<br/>SQLite / WAL]
    C --> F[ARIA Agent<br/>Bounded ReAct Loop]
    C --> G[Terminal Intelligence]
    C --> K[Ollama<br/>Local LLM Runtime]

    F --> H[Tool Allowlist<br/>Guardrails<br/>Risk Tiers]

    C --> I[Local HTTP / SSE Bridge<br/>127.0.0.1:9120]
    I --> J[Electron / React Shell]

    C --> L[Cross-Device Sync]
    L --> M[Pairing + Encrypted Channel]

    style A fill:#020617,stroke:#00D1FF,color:#fff
    style C fill:#111827,stroke:#8B5CF6,color:#fff
    style F fill:#111827,stroke:#F59E0B,color:#fff
    style I fill:#111827,stroke:#06B6D4,color:#fff
    style J fill:#111827,stroke:#10B981,color:#fff
    style K fill:#111827,stroke:#EC4899,color:#fff

Design principle

The backend is active. The frontend is a live renderer.

The Electron shell does not own the core intelligence. It reflects backend state streamed through the local HTTP/SSE bridge. This keeps orchestration, memory, tool execution, and guardrails in the Python backend instead of scattering logic across the UI.

🗺️ Architecture Map

This repository includes standalone Mermaid diagrams for recruiter-friendly technical review.

See assets/diagrams/README.md for rendering notes.

🤖 ARIA Agent Flow

ARIA is Anion’s bounded agentic assistant. It can reason through tasks and use approved tools, but it does not get unrestricted shell access.

sequenceDiagram
    participant U as User
    participant UI as Anion Shell
    participant A as ARIA Agent
    participant P as Privacy Redactor
    participant G as Guardrails
    participant O as Ollama
    participant T as Approved Tool

    U->>UI: Ask request
    UI->>A: Prompt + context
    A->>P: Check sensitive content
    P-->>A: Safe / redacted / local-only
    A->>O: Reason over task
    O-->>A: Plan or tool proposal
    A->>G: Validate tool + risk tier
    alt Safe tool
        G-->>A: Allowed
        A->>T: Execute approved tool
        T-->>A: Tool result
        A-->>UI: Final response
    else Sensitive action
        G-->>A: Approval required
        A-->>UI: Ask user for approval
    end

Read more: docs/ARIA_AGENT.md

🧠 Context + Memory Flow

Anion is context-aware because it listens to real Linux workflow signals.

flowchart TD
    A[Active Window / Workspace] --> D[Context Engine]
    B[Terminal Activity] --> D
    C[File Events / Pinned Files] --> D
    D --> E[Local Memory Store]
    E --> F[Semantic Context Retrieval]
    F --> G[ARIA Assistant]
    D --> H[Anion Shell]
    E --> H

    style D fill:#111827,stroke:#06B6D4,color:#fff
    style E fill:#111827,stroke:#8B5CF6,color:#fff
    style G fill:#111827,stroke:#F59E0B,color:#fff

Read more: docs/CONTEXT_AND_MEMORY.md

🖥️ Terminal Intelligence Flow

Anion’s terminal layer is designed for developer workflows: history, recovery, and risk previews.

flowchart TD
    A[User enters command] --> B[Terminal Wrapper]
    B --> C{Risk preview}
    C -->|Safe| D[Execute command]
    C -->|Risky| E[Require confirmation]
    E -->|Approved| D
    E -->|Rejected| F[Cancel execution]
    D --> G{Command failed?}
    G -->|No| H[Store history]
    G -->|Yes| I[Recovery Engine]
    I --> J[Rule-based fix or LLM suggestion]
    J --> H

    style C fill:#111827,stroke:#F59E0B,color:#fff
    style E fill:#111827,stroke:#EF4444,color:#fff
    style I fill:#111827,stroke:#06B6D4,color:#fff

Read more: docs/TERMINAL_INTELLIGENCE.md

🔄 Cross-Device Sync Flow

Anion supports local-network context handoff between Linux machines.

flowchart LR
    A[Linux Device A] --> B[LAN Discovery]
    C[Linux Device B] --> B
    B --> D[Pairing Flow]
    D --> E[PIN Verification]
    E --> F[Encrypted Channel]
    F --> G[Context Sync]
    G --> H[Resume Work]

    style B fill:#111827,stroke:#06B6D4,color:#fff
    style E fill:#111827,stroke:#F59E0B,color:#fff
    style F fill:#111827,stroke:#10B981,color:#fff

Read more: docs/CROSS_DEVICE_SYNC.md

✨ Key Features

🖥️ Interface Gallery

ARIA Assistant Bounded agentic assistant for local Linux workflows.	Live System Brain Visual runtime layer for context, memory, and local AI state.
Model Hub Local model management and Ollama-ready workflows.	Smart Hub Workflow intelligence, suggestions, and system-level assistance.
Control View System controls, diagnostics, and runtime visibility.	Explore Context exploration across workspace, memory, and local activity.

🧑‍💻 Terminal Screenshots

Terminal Screenshot 1	Terminal Screenshot 2
Terminal Screenshot 3	Terminal Screenshot 4
Terminal Screenshot 5	Terminal Screenshot 6

🛠️ Tech Stack

🧪 Testing Pipeline

flowchart TD
    A[Code / Release Candidate] --> B[quick]
    B --> C[full]
    C --> D[e2e]
    D --> E[chaos]
    E --> F[soak]
    F --> G[security scans]
    G --> H[gate]
    H --> I{Release status}
    I -->|Pass| J[Beta candidate]
    I -->|Fail| K[Blocked / Fix required]

    style H fill:#111827,stroke:#06B6D4,color:#fff
    style J fill:#052e16,stroke:#22C55E,color:#fff
    style K fill:#450a0a,stroke:#EF4444,color:#fff

Test scopes

Security review snapshot

Read more: docs/TESTING_AND_QA.md

🔐 Privacy Boundary

flowchart TD
    A[User Desktop] --> B[Local Anion Services]
    B --> C[Local Memory]
    B --> D[Ollama Local Models]
    B --> E[ARIA Tool Guardrails]
    E --> F{Sensitive action?}
    F -->|No| G[Approved local action]
    F -->|Yes| H[User approval required]

    B -. optional if configured .-> I[External Services]

    style A fill:#020617,stroke:#06B6D4,color:#fff
    style B fill:#111827,stroke:#8B5CF6,color:#fff
    style C fill:#111827,stroke:#10B981,color:#fff
    style H fill:#111827,stroke:#F59E0B,color:#fff
    style I fill:#111827,stroke:#EF4444,color:#fff

Anion is designed to keep workflows local by default. External services, if supported in a beta build, should be explicitly configured and documented.

Read more: PRIVACY.md

🧩 Why This Was Technically Interesting

📋 Product Status

┌─────────────────────────────────────────────────────────────┐
│          Anion v0.1.0 — Release Candidate / Beta             │
├─────────────────────────────────────────────────────────────┤
│  ✅ Feature-complete for current Linux-only scope             │
│  🔄 Dependency CVE remediation                               │
│  🔄 Subprocess security audit                                │
│  🔄 Packaging validation                                     │
│  🔄 Public documentation cleanup                             │
│                                                             │
│  ⚠️  Beta software — intended for Linux power users           │
└─────────────────────────────────────────────────────────────┘

🔒 Why the Source Is Private

The Anion source code is private during beta because the project includes security-sensitive local automation logic, Linux desktop integration code, packaging scripts, and hardening work that should be resolved before broader exposure.

Source availability will be revisited after security cleanup, packaging validation, and licensing decisions are complete.

📚 Documentation

🚀 Early Beta

👤 My Role

I designed and built Anion end-to-end.

🧭 Repository Purpose

This repo is for:

• public architecture documentation,
• product and feature explanation,
• recruiter/reviewer visibility,
• beta access information,
• diagrams and release notes,
• public issue/feedback collection.

This repo is not:

• the production source repository,
• an open-source codebase,
• a package registry,
• a public installer mirror.