Architecture

Core Thesis¶

An operating system is just a human doing things. Reading files, writing notes, thinking about problems, searching for information. These are human capabilities first. Tools are optional accelerators.

EmptyOS works at every level:

Three Layers¶

┌─────────────────────────────────────────────┐
│  Apps (62, all first-class)                  │
│  capture  search  journal  expense  task     │
│  assistant  music-studio  jobs  finance ...  │
├─────────────────────────────────────────────┤
│  Platform Runtime                            │
│  Services: vault watcher, scheduler,         │
│            real-time WebSocket, workers       │
│  Libraries: frontend (theme + components)    │
│  Connectors: ollama, comfyui, voice-api      │
├─────────────────────────────────────────────┤
│  Kernel                                      │
│  Config, 7 Capabilities, EventBus,           │
│  ServiceRegistry, AppLoader, PluginLoader    │
└─────────────────────────────────────────────┘

Kernel — config, capabilities with provider chains, event bus, service registry, loaders. Human is always the final fallback.

Platform Runtime — shared infrastructure: services (always-running), libraries (imported), connectors (external adapters).

Apps — everything user-facing. All apps share the same manifest format and lifecycle. A capture app and a music studio are both apps — the difference is what they declare in their manifest.

7 Capabilities¶

Every app accesses the world through capabilities, never direct tools:

Provider chains try each provider in order. If Ollama is down, fall back to OpenAI. If that fails, ask the human. Apps never know which provider answered — they just call self.think().

The App Model¶

An app = manifest (TOML) + backend (Python) + UI (HTML). Every app declares what it needs:

[app]
id = "myapp"
name = "My App"

[requires]
capabilities = ["read", "write", "think"]
apps = ["task", "journal"]

[provides.web]
prefix = "/myapp"

[provides.events]
emits = ["myapp:done"]

class MyApp(BaseApp):
    data = await self.read("file.md")
    result = await self.think("Analyze this", domain="code")
    tasks = await self.call_app("task", "list_tasks")
    await self.emit("myapp:done", {"key": "value"})

Event Bus¶

Apps communicate through events, not imports. When you capture a note tagged #dev, the capture app emits capture:saved. The projects app listens, routes it to the right project. The reactor app chains events into journal entries.

One action ripples to all related vault files. The system knows what happened — it writes it down.

Vault as Hard Drive¶

The vault is an external markdown folder mounted via config. Two storage domains:

If a human wrote it or needs it after reset → vault. If the system generates it at high frequency → data/.

Every vault note has three data layers:

1. Frontmatter — structured, indexed, queryable (tags, status, company)
2. Sections — semi-structured (## Timeline, ## Tasks)
3. Prose — unstructured, human-written, LLM-summarizable

Apps query by tag via vault_query(), read sections on demand, and pass prose to LLM when understanding is needed.

Self-Awareness¶

EmptyOS has a built-in integrity audit that scores 13 dimensions: 9 design principles, the Six Verbs metabolic cycle, plus security, privacy, and scale. A growth agent runs daily, a root agent reviews weekly. The topology graph at /topology visualizes all 62 apps and their connections in real time.