ALOS

ALOS

Advanced Local Operating System

Fully offline. Zero cloud. Zero API key. Zero subscription.

A production-quality personal AI assistant that runs 100% on your own machine — with a professional desktop GUI, local LLM inference, voice I/O, hardware control, and an extensible Skills ecosystem.

---

[](LICENSE) [](https://python.org) [](https://riverbankcomputing.com/software/pyqt/) [](https://ollama.ai) [](tests/) [](https://github.com/sandy001-kki/ALOS) [](https://github.com/sandy001-kki/ALOS)

---

[Quick Start](#quick-start) · [Features](#features) · [GUI](#gui-overview) · [Skills](#skills-system) · [MCP](#mcp-servers) · [ESP32](#esp32-hardware-integration) · [Roadmap](FUTURE_PLAN.md)

---

What is ALOS?

ALOS is an open-source personal AI platform that gives you the power of a large language model — with memory, tools, voice, and hardware control — without sending a single byte to the cloud.

You talk to ALOS in plain language. It understands your intent, routes to the right handler, calls tools or skills if needed, and responds. All computation runs on your own hardware, with SQLite persistence for every conversation, task, event, and health log you create.

Think of it as Claude Code + Claude Desktop — but fully local, fully open, and fully yours.

---

Why ALOS?

| Problem with existing AI assistants | How ALOS solves it | | --- | --- | | Data sent to cloud servers | 100% local inference — nothing leaves your PC | | Requires monthly API subscription | Runs on free, open-weight Ollama models | | Generic responses, no personal memory | SQLite memory: conversations, tasks, events, health logs | | No hardware integration | ESP32 bridge: control relays, TFT display, touch UI | | Closed extension ecosystem | Open Skills system — write a tool in one Python file | | No voice I/O | faster-whisper STT + Windows SAPI / pyttsx3 TTS |

---

Quick Start

Prerequisites

| Requirement | Version | Install | | --- | --- | --- | | Python | 3.10+ | python.org | | Ollama | latest | ollama.ai | | Git | any | git-scm.com |

1 — Clone

git clone https://github.com/sandy001-kki/ALOS.git
cd ALOS

2 — Install dependencies

Windows:

setup.bat

Linux / macOS:

bash setup.sh

Or manually:

pip install -r requirements.txt

3 — Pull a model

# Start the Ollama server
ollama serve

# In another terminal, pull the default model
ollama pull llama3.2:1b

4 — Launch

# Full GUI — recommended
python gui_app.py

# Text-only terminal
python cli.py

# Voice — microphone + speaker
python voice_cli.py

---

Start here

| If you are... | Read this first | Then do this | | --- | --- | --- | | New to ALOS | [What is ALOS?](#what-is-alos) | [Quick Start](#quick-start) | | A developer adding a skill | [Skills system](#skills-system) | [Write your own skill](#write-your-own-skill) | | Connecting MCP servers | [MCP servers](#mcp-servers) | [Add via config.json](#add-via-configjson) | | Integrating ESP32 hardware | [ESP32 integration](#esp32-hardware-integration) | [Hardware setup](#hardware-setup) | | A contributor | [Contributing](#contributing) | [Good first issues](#good-first-issues) | | Interested in ALOS-LM custom model | [FUTUREPLAN.md](FUTUREPLAN.md) | [Phase 3](FUTURE_PLAN.md#phase-3--alos-custom-language-model) |

---

Features

Core AI

• Local LLM inference via Ollama — runs llama3.2, mistral, codellama, gemma, phi, and any compatible model
• 8 specialized intent handlers — Chat, Schedule, Reminders, Health, Code, Smart Home, Day Planner, System
• Conversation history with configurable depth (max_history in config)
• Streaming response rendering in the GUI

Desktop GUI

• Three-panel layout: navigation sidebar + chat panel + context panel
• Dark professional theme — Claude Code-style design system
• Intent badges on each message — shows which handler processed the request
• Toolbar with model selector, screen monitor, hardware bridge, command palette
• System tray icon — minimize to tray, morning briefing shortcut

Voice I/O

• Speech-to-text using faster-whisper (runs locally, no API)
• Text-to-speech using Windows SAPI (Windows) or pyttsx3 (Linux/macOS)
• Voice tab in the input bar — push to talk

Memory and persistence

• SQLite database with WAL mode — fast, reliable, crash-safe
• 7 tables: sessions, conversations, tasks, schedule, health_log, memory, preferences
• MemoryManager API — read/write from any handler or skill

Skills system

• Modular Python plugins with a @tool decorator
• SkillRegistry manages loading, enabling, and disabling at runtime
• Built-in skills: Filesystem, PC Control, Web Search
• Write a new skill in one file with no framework knowledge needed

MCP servers

• Connects to any Model Context Protocol server
• Supports both stdio (subprocess) and HTTP transports
• GUI panel to add, connect, and disconnect servers at runtime
• Tool results injected back into the LLM conversation automatically

Smart Home / ESP32

• WebSocket server on port 8765 — ESP32 connects automatically
• Control 4 relay channels from voice commands or the GUI
• ILI9341 TFT display (320×240) running a 5-screen LVGL GUI
• XPT2046 touchscreen for on-device navigation
• Animated eyes — visual feedback when ALOS is listening or responding

Day Planner

• Daily task management with priority levels
• Morning briefing — summary of tasks, events, and health data
• Proactive health check-ins — ALOS reminds you to drink water, take breaks

---

GUI overview

┌─────────────────────────────────────────────────────────────────┐
│  [Model: llama3.2:1b ▼] [◫ Screen] [⬡ Bridge] [⌘ Palette] [◀] │
├──────────┬──────────────────────────────────────┬───────────────┤
│ Sidebar  │           Chat Panel                 │ Context Panel │
│          │                                      │               │
│ ◈ Chat   │  ALOS  [schedule]  10:32            │  TASKS        │
│ ☑ Planner│  ┌──────────────────────────────┐   │  ⚑ Fix bug   │
│ ♥ Health │  │ Good morning Sandy! Today     │   │  · Review PR │
│ ⌂ Smart  │  │ you have 3 tasks and 1 event. │   │               │
│   Home   │  └──────────────────────────────┘   │  TODAY'S EVENTS│
│ ⚙ Skills │                                      │  10:00 Standup│
│ ⬡ MCP    │  You  ──────────────────────  09:01 │               │
│ ⊛ Settings│  ┌──────────────────────────────┐  │  HARDWARE     │
│          │  │ What should I focus on today? │  │  ● connected  │
│          │  └──────────────────────────────┘  │  Relay 1: ON  │
│  ● Ollama│                                      │  Relay 2: OFF │
│  online  ├──────────────────────────────────────┤               │
│          │ [Chat] [Voice] [Code]  Tools: Skills ▸│               │
│          │ Ask ALOS anything…     (Enter to send)│               │
└──────────┴──────────────────────────────────────┴───────────────┘

Keyboard shortcuts

| Shortcut | Action | | --- | --- | | Ctrl+P | Open Command Palette | | Ctrl+L | Clear chat | | Ctrl+, | Open Settings | | Enter | Send message | | Shift+Enter | New line in input |

---

Architecture overview

flowchart TD
    A["User Input\n(text / voice)"] --> B["IntentDetector\n8-class classifier"]
    B --> C["Router"]

    C --> D1["ChatHandler"]
    C --> D2["ScheduleHandler"]
    C --> D3["HealthHandler"]
    C --> D4["CodeHandler"]
    C --> D5["SmartHomeHandler"]
    C --> D6["PlannerHandler"]
    C --> D7["ReminderHandler"]
    C --> D8["SystemHandler"]

    D1 & D2 & D3 & D4 & D6 & D7 --> E["ALOSEngine\nOllama LLM"]

    E --> F["SkillRegistry\nFilesystem · PCControl · WebSearch"]
    E --> G["MCPRegistry\nstdio · HTTP servers"]

    F & G --> E

    D5 --> H["HardwareBridge\nWebSocket :8765"]
    H --> I["ESP32\nRelays · TFT · Touch"]

    E --> J["MemoryManager\nSQLite WAL"]
    E --> K["ChatPanel\nResponse rendering"]

---

Configuration

Edit config.json to change model, voice, skills, hardware, and MCP settings:

{
  "ai": {
    "model": "llama3.2:1b",
    "ollama_host": "http://localhost:11434",
    "max_history": 20
  },
  "voice": {
    "whisper_model": "base",
    "tts_rate": 175
  },
  "hardware": {
    "enabled": false,
    "websocket_port": 8765,
    "esp32_ip": "192.168.1.100"
  },
  "skills": {
    "filesystem": false,
    "pc_control": false,
    "web_search": false
  },
  "mcp_servers": [
    {
      "name": "filesystem",
      "type": "stdio",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "D:\\"]
    }
  ]
}

Available Ollama models

ollama pull llama3.2:1b      # fast, 1B — default
ollama pull llama3.2:3b      # better quality
ollama pull mistral           # great for code
ollama pull codellama         # specialized for code
ollama pull phi3              # Microsoft, very fast
ollama pull gemma2:2b         # Google, efficient

---

What ALOS understands

ALOS classifies every message into one of 8 intents automatically. No special syntax needed.

| Intent | Example phrases | | --- | --- | | chat | "Hello", "What's machine learning?", "Tell me a joke" | | schedule | "Schedule dentist on Friday at 3pm", "What do I have today?" | | reminder | "Remind me to call mom at 5pm", "Set a reminder in 30 minutes" | | health | "I drank 2 glasses of water", "I feel tired", "Log my mood as 7" | | planner | "Add task: finish report", "Show my tasks", "Morning briefing" | | code | "Write a Python function to sort a list", "Debug this error" | | smarthome | "Turn on the lights", "Turn off the fan", "Switch on AC" | | systemcommand | "/status", "/clear", "Switch model to mistral", "Clear history" |

---

Skills system

The Skills system allows ALOS to call Python tool functions at runtime. Each skill is an independent Python module — no framework boilerplate required.

Built-in skills

| Skill | Tools available | Default | | --- | --- | --- | | Filesystem | readfile, listdirectory, findfiles, writefile | Off | | PC Control | setvolume, openapp, lockscreen, mediaplay, mediapause | Off | | Web Search | searchweb, openurl, getpage_content | Off |

Enable via GUI

1. Click ⚙ Skills in the sidebar
2. Toggle a skill ON or OFF
3. Tools from that skill become available to the LLM immediately — no restart needed

Write your own skill

Create a single file in core/skills/:

# core/skills/weather_skill.py
from core.skills.base_skill import BaseSkill, tool

class WeatherSkill(BaseSkill):
    name        = "weather"
    description = "Get current weather and forecasts"
    version     = "1.0.0"

    @tool("Get current weather for a city")
    def get_weather(self, city: str) -> str:
        # Your implementation here
        return f"Fetching weather for {city}..."

    @tool("Get 7-day forecast for a city")
    def get_forecast(self, city: str, days: int = 7) -> str:
        return f"Fetching {days}-day forecast for {city}..."

Then register it:

# core/skills/builtin.py → register_all()
from core.skills.weather_skill import WeatherSkill
registry.register(WeatherSkill())

---

MCP servers

ALOS supports Model Context Protocol — the open standard from Anthropic for connecting AI models to external tools and data sources.

Any MCP-compatible server can be wired into ALOS, and its tools are exposed to the LLM alongside built-in Skills.

Add via GUI

1. Click ⬡ MCP Servers in the sidebar
2. Click + Add Server
3. Enter server name, transport type (stdio or http), and command or URL
4. Click Connect

Add via config.json

"mcp_servers": [
  {
    "name": "filesystem",
    "type": "stdio",
    "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home"]
  },
  {
    "name": "github",
    "type": "stdio",
    "command": ["npx", "-y", "@modelcontextprotocol/server-github"]
  },
  {
    "name": "remote-tools",
    "type": "http",
    "url": "http://localhost:3001"
  }
]

Popular MCP servers

# Filesystem access
npx -y @modelcontextprotocol/server-filesystem /your/path

# Git operations
uvx mcp-server-git

# GitHub integration
npx -y @modelcontextprotocol/server-github

# Web browser automation
npx -y @modelcontextprotocol/server-puppeteer

---

ESP32 hardware integration

ALOS controls physical hardware via an ESP32 microcontroller over a WebSocket connection. The firmware runs a fully interactive 5-screen LVGL GUI on a TFT touchscreen display.

Hardware components

| Component | Specification | | --- | --- | | Microcontroller | ESP32 (any variant) | | Display | ILI9341 TFT — 320×240 pixels | | Touch | XPT2046 resistive touchscreen | | Relay outputs | 4 channels — lights, fan, AC, heater | | Communication | WebSocket over WiFi | | Firmware framework | Arduino + LVGL |

LVGL display screens

1. Home — relay status overview
2. Controls — tap to toggle relays
3. Status — ALOS connection status and IP
4. Eyes — animated ALOS face (listening indicator)
5. Sensors — temperature and humidity (with DHT22)

Hardware setup

1. Open esp32/alos_firmware/config.h and set your WiFi credentials
2. Flash esp32/alos_firmware/alos_firmware.ino via Arduino IDE
3. In ALOS GUI, click ⬡ Bridge in the toolbar to start the WebSocket server
4. ESP32 connects to ws://:8765 automatically on boot

Voice commands for hardware control

"Turn on the lights"      → Relay 1 ON
"Turn off the lights"     → Relay 1 OFF
"Turn on the fan"         → Relay 2 ON
"Switch on AC"            → Relay 3 ON
"Turn off the heater"     → Relay 4 OFF
"What is the temperature" → Reads DHT22 sensor value

---

Project structure

ALOS/
├── gui_app.py                  # GUI entry point
├── cli.py                      # CLI entry point
├── voice_cli.py                # Voice CLI entry point
├── config.json                 # All user configuration
├── requirements.txt            # Python dependencies
│
├── core/
│   ├── engine.py               # ALOSEngine — Ollama LLM wrapper
│   ├── intent_detector.py      # 8-category intent classifier
│   ├── router.py               # Message routing to handlers
│   ├── planner.py              # Day planner + health check-ins
│   ├── handlers/
│   │   ├── chat_handler.py
│   │   ├── schedule_handler.py
│   │   ├── reminder_handler.py
│   │   ├── health_handler.py
│   │   ├── code_handler.py
│   │   ├── planner_handler.py
│   │   ├── smart_home_handler.py
│   │   └── system_handler.py
│   ├── skills/
│   │   ├── base_skill.py       # BaseSkill + @tool decorator
│   │   ├── skill_registry.py   # SkillRegistry
│   │   ├── builtin.py          # Built-in skill registration
│   │   ├── filesystem_skill.py
│   │   ├── pc_control_skill.py
│   │   └── web_search_skill.py
│   └── mcp/
│       ├── client.py           # MCP client (stdio + HTTP)
│       └── registry.py         # MCPRegistry
│
├── gui/
│   ├── main_window.py          # 3-panel main window
│   ├── sidebar.py              # Navigation sidebar
│   ├── chat_panel.py           # Message bubbles + intent badges
│   ├── input_bar.py            # Chat/Voice/Code tabs + skill chips
│   ├── context_panel.py        # Tasks, events, hardware status
│   ├── command_palette.py      # Ctrl+P command overlay
│   ├── skills_panel.py         # Skills browser dialog
│   ├── mcp_panel.py            # MCP servers manager dialog
│   ├── toast_manager.py        # Floating notification toasts
│   ├── settings_dialog.py      # Settings dialog
│   ├── tray_icon.py            # System tray icon
│   └── styles.py               # Design system — colors, QSS stylesheet
│
├── database/
│   ├── schema.py

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sandeepbollavaram](https://github.com/sandeepbollavaram)
- **Source:** [sandeepbollavaram/ALOS](https://github.com/sandeepbollavaram/ALOS)
- **License:** MIT
- **Homepage:** https://sandeepkumarbollavaram.in

Install and usage instructions live in the source repository linked above.