Built like an OS.
Architected for AI.
Every design decision in Genesis OS prioritises local-first operation, persistent memory, and zero-compromise privacy — from the daemon kernel to the Docker image.
Up and running
in 4 steps
Prerequisites
Install Docker Desktop (or Docker Engine + Compose). That's all. No Node.js, Python, or Ollama needed on your host.
Clone the repository
Clone from GitHub. The repository includes docker-compose.yml, all Dockerfiles, and the workspace directory.
Start the stack
Run docker compose up in the project root. Ollama automatically pulls gemma4:e4b on first boot (~9.6 GB download).
Open Genesis OS
Navigate to http://localhost:3000 in any browser. The full OS desktop opens immediately.
# 1. Clone git clone https://github.com/shaik-shahansha/genesisAIOS cd genesis-os # 2. (Optional) customize model cp .env.example .env # Edit .env: GENESIS_MODEL=gemma4:e2b for lighter CPUs # 3. Start everything docker compose up # First run downloads the model — be patient # Subsequent starts are instant # 4. Open in browser # → http://localhost:3000 # ───────────────────────────── # Optional: run in background docker compose up -d # View logs docker compose logs -f daemon
Set GENESIS_MODEL=gemma4:e2b in your .env file. Same features, 7.2 GB download, faster on CPU.
Five layers.
One coherent system.
Genesis OS is composed of five loosely-coupled layers communicating over a shared event bus and HTTP APIs. Each layer can be upgraded or replaced independently — the interfaces never change.
The nervous system
of Genesis OS
All internal communication flows through a central EventEmitter bus — never through direct function calls between packages. This loose coupling means any component can be upgraded, replaced, or extended without touching other parts of the system.
- Daemon never crashes — all errors caught, logged, recovered
- File watcher events flow through bus to memory indexer
- Tool execution emits
approval_requiredevents - Voice wakeword detection fires via bus to UI
- LLM streaming chunks pushed to connected WebSocket clients
- Proactive cron jobs emit scheduled messages through bus
// The internal event bus const { EventEmitter } = require('events'); const bus = new EventEmitter(); bus.setMaxListeners(50); module.exports = bus; // ──────────────────────────── // Emitting events bus.emit('approval_required', { tool: 'run_shell', args: { cmd: 'rm -rf /tmp/old' }, resolve, reject }); // ──────────────────────────── // Listening to events bus.on('file:changed', async ({ path }) => { await memory.index(path); }); bus.on('wakeword:detected', () => { voice.startListening(); });
Reason → Act → Observe.
Repeat.
Multi-step reasoning
The agentic loop continues calling tools until the task is complete or needs user input. "Summarise all invoices in my Documents folder" triggers file enumeration, reading, and synthesis automatically.
Approval gates
Before any tool with requiresApproval: true runs, the UI shows a confirmation card. You see exactly what command will run and can cancel or approve.
All requests have timeouts
Every Ollama call, ChromaDB query, and external fetch has an AbortSignal timeout. If any service is slow or down, Genesis degrades gracefully — it never hangs indefinitely.
Streaming to UI
LLM output streams token-by-token via Server-Sent Events. Tool execution progress streams in real-time. You never stare at a loading spinner wondering what's happening.
One file.
Complete stack.
services: ollama: image: ollama/ollama volumes: - ollama_data:/root/.ollama ports: ["11434:11434"] entrypoint: ollama-entrypoint.sh daemon: build: . # Node.js daemon ports: ["3000:3000"] environment: GENESIS_MODEL: ${GENESIS_MODEL:-gemma4:e4b} OLLAMA_BASE_URL: http://ollama:11434 depends_on: [ollama, memory] volumes: - ./docker/workspace:/workspace memory: build: Dockerfile.memory # Python sidecar ports: ["7701:7701"] volumes: - genesis_data:/data voice: build: Dockerfile.voice # Python sidecar ports: ["7702:7702"] volumes: ollama_data: genesis_data:
Five services, zero configuration
Ollama, daemon, memory, voice, and the UI all start with a single command. Service dependencies are declared in compose — everything starts in the right order automatically.
Persistent volumes
Your memories, conversation history, and model weights are stored in named Docker volumes. They survive container restarts and upgrades — data is never lost.
Works without GPU
Gemma 4's MoE architecture activates only ~4B parameters at inference. Fast enough for real conversations on a modern laptop CPU. No NVIDIA card required.