AngelOS

1. Introduction

AngelOS is a complete operating system designed for children aged 6-12. It combines a safe, enclosed environment with a modern, intuitive design that appeals to children — without compromising on privacy or security.

The design philosophy rests on three pillars:

• Protection without imprisonment — Angel explains why something isn't allowed, instead of just blocking it
• Privacy as foundation — all data stays local, no telemetry, no analytics
• Accessibility — runs on hardware costing as little as €50, no powerful computer needed

The system is built as a web application running in a kiosk browser on a stripped-down Linux system. This provides the flexibility of web technology with the control of a native OS.

2. Architecture Overview

AngelOS consists of five layers, from hardware to user interface:

The frontend (Shell) communicates with the Python backend through an abstract Bridge layer that automatically selects the appropriate transport based on the runtime environment.

3. The Shell

The shell is a complete desktop environment built with web technology. It provides a macOS-like experience with a dock, window manager, status bar and launcher.

Tech Stack

• Preact 10 — React-compatible framework, 3KB gzipped
• Vite 6 — Bundler with HMR and code splitting
• Tailwind CSS 4 — Utility-first CSS with custom design tokens
• Tiptap — Rich text editor (writing app)
• Canvas API — Drawing app and Snake game
• Web Audio API — Music player with visualizer

Window Manager

The window manager supports drag, resize, minimize, maximize and z-index stacking. Windows are animated with cubic-bezier easing for a native feel. State is managed via Preact hooks — no external state library needed.

Design System

@theme {
  --color-angel-purple: #a78bfa;
  --color-angel-pink: #f472b6;
  --color-angel-blue: #60a5fa;
  --color-angel-green: #4ade80;
  --color-angel-gold: #fbbf24;
  --color-angel-surface: rgba(255, 255, 255, 0.72);
}

4. App Ecosystem

Apps are manifest-driven and lazy-loaded. Each app defines its metadata, permissions and default window size:

{
  "id": "writing",
  "version": "1.0.0",
  "permissions": ["files:read", "files:write"],
  "category": "productivity",
  "size": { "w": 680, "h": 520 }
}

5. The Bridge

The Bridge is the communication layer between the JavaScript shell and the Python backend. It abstracts four transport modes behind a single uniform API:

bridge.chat(message)        // Angel AI chat
bridge.checkUrl(url)        // Content filtering
bridge.screenTime()         // Query screen time
bridge.fileList(category)   // List files
bridge.fileWrite(cat, name, content)
bridge.askPapa(message)     // Telegram to parent

6. Angel AI

Angel is the AI guardian of AngelOS, powered by Claude Haiku. Angel fulfills three roles:

Chat Companion

Angel answers questions in a child-friendly manner. The system prompt limits answers to 150 words and prevents sharing of personal information. Maximum 50 messages per day.

Content Filtering Pipeline

1. DNS-level blocklists (StevenBlack hosts + CleanBrowsing Family)
2. Local whitelist/blacklist check
3. AI-based content check (with 24-hour cache)
4. Result: allow, block, or ask_parent

Telegram Bridge

Angel sends real-time notifications to the parent via Telegram: blocked websites, screen time exceeded, "Ask parent" requests, and a daily report at 20:00.

7. Security Model

Sandbox Architecture

Apps run in sandboxed iframes without direct internet access. The browser app is the only app that can generate external traffic, but exclusively through the Angel content filtering pipeline.

System Lockdown

• Ctrl+Alt+Delete disabled
• Magic SysRq disabled
• USB storage blocked via modprobe blacklist
• GRUB password for recovery mode
• Chromium managed policy blocks chrome://, about:*, file://
• DevTools, downloads and extensions disabled
• F5, F11, F12, Ctrl+L, Ctrl+T, Ctrl+W blocked in shell JavaScript

8. Privacy by Design

• All data local — files, chat history, browsing history and screen time stored in local SQLite database
• No telemetry — no usage data collected or transmitted
• No analytics — no tracking pixels, no third-party cookies
• No cloud sync — data doesn't leave the device unless parent explicitly configures it
• Encrypted storage — persistence partition can be optionally encrypted
• Retention — logs automatically deleted after 90 days

The only external communication is to the Claude API (for Angel chat and content filtering) and optionally to the Telegram API (for parental notifications). Both are optional and can be disabled for fully offline use.

9. Deployment

USB Kiosk Build

USB Stick (16GB)
├── EFI Partition (200MB)     — GRUB2 bootloader
├── System Partition (3-5GB)  — squashfs root filesystem
└── Persistence (8-12GB)      — overlayfs upper layer
    ├── /home/maya/            — user files
    ├── /var/lib/angel/        — database + config
    └── /etc/NetworkManager/   — WiFi credentials

Boot Sequence (~15s USB, ~8s disk)

1. UEFI/BIOS → GRUB2 (timeout=0, quiet boot)
2. Linux kernel + initramfs (zstd compressed)
3. overlayfs mount: squashfs (read-only) + persistence (writable)
4. systemd parallel init: NetworkManager, PipeWire, angel-server
5. getty autologin → startx → Openbox + Chromium kiosk

Remote Updates

Shell updates (frequent): aiohttp server checks manifest → download → verify → apply → restart. System updates (rare): A/B partition scheme with GRUB pointer switching.

10. Performance

11. Roadmap