# ALOS

> Fully offline personal AI assistant — local LLM, voice I/O, PyQt6 GUI, ESP32 hardware, Skills system, MCP servers. No API key. No cloud.

- **Type:** MCP server
- **Install:** `agentstack add mcp-sandeepbollavaram-alos`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sandeepbollavaram](https://agentstack.voostack.com/s/sandeepbollavaram)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sandeepbollavaram](https://github.com/sandeepbollavaram)
- **Source:** https://github.com/sandeepbollavaram/ALOS
- **Website:** https://sandeepkumarbollavaram.in

## Install

```sh
agentstack add mcp-sandeepbollavaram-alos
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://python.org) |
| Ollama | latest | [ollama.ai](https://ollama.ai) |
| Git | any | [git-scm.com](https://git-scm.com) |

### 1 — Clone

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

### 2 — Install dependencies

**Windows:**
```bash
setup.bat
```

**Linux / macOS:**
```bash
bash setup.sh
```

Or manually:
```bash
pip install -r requirements.txt
```

### 3 — Pull a model

```bash
# Start the Ollama server
ollama serve

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

### 4 — Launch

```bash
# 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 | [FUTURE_PLAN.md](FUTURE_PLAN.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](https://github.com/guillaumeklebs/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](https://modelcontextprotocol.io) 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

```mermaid
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:

```json
{
  "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

```bash
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" |
| **smart_home** | "Turn on the lights", "Turn off the fan", "Switch on AC" |
| **system_command** | "/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** | read_file, list_directory, find_files, write_file | Off |
| **PC Control** | set_volume, open_app, lock_screen, media_play, media_pause | Off |
| **Web Search** | search_web, open_url, get_page_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/`:

```python
# 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:

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

---

## MCP servers

ALOS supports [Model Context Protocol](https://modelcontextprotocol.io) — 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

```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

```bash
# 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sandeepbollavaram-alos
- Seller: https://agentstack.voostack.com/s/sandeepbollavaram
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.