SYS-01 // CORE_ARCHITECTURE

The System Architecture

Two processes. One socket. One mind. A mathematically decoupled architecture where the daemon and the UI share only a structured JSON stream.

2 PROCESSES1 IPC SOCKET5-PHASE LOOP3 INFERENCE MODES

ARCHITECTURE DIAGRAM // TWO-PROCESS MODEL

yantra.arch — bare-metal layout

┌──────────────────────────────────────────────────────────────┐

│ BARE-METAL ARCH LINUX │

│ (Boots to raw TTY1 — no display manager) │

├──────────────────────────────────────────────────────────────┤

│ PROCESS A: yantra.service (systemd daemon) │

│ ┌────────────────────────────────────────────────────────┐ │

│ │ SENSE → REMEMBER → REASON → ACT → LEARN │ │

│ │ telemetry ChromaDB LiteLLM Docker ChromaDB │ │

│ │ THE KRIYA LOOP │ │

│ └─────────────────────────┬──────────────────────────────┘ │

│ │ │

│ /run/yantra/ipc.sock │

│ (UNIX Domain Socket — IPC Bridge) │

│ │ │

│ PROCESS B: tui_shell.py (Textual UI, yantra_user) │

│ ┌────────────────────────────────────────────────────────┐ │

│ ║ TELEMETRY ║ THOUGHTSTREAM ║ COMMAND ║ │

│ ║ CPU: 12% ║ [SENSE] reading... ║ ║ │

│ ║ RAM: 4.1GB ║ [REASON] analyzing... ║ > _ ║ │

│ └────────────────────────────────────────────────────────┘ │

└──────────────────────────────────────────────────────────────┘

“The daemon cannot crash the UI. The UI cannot deadlock the engine.”

CORE SUBSYSTEMS // THREE PILLARS

Built to last. Built to fail safely.

[ SYS-A // HYBRID_INFERENCE ]

Hybrid Inference Engine

Hardware should not be a barrier to intelligence. YantraOS routes every inference request to the optimal backend based on what hardware is actually present. The router is LiteLLM — one API call, any model, any backend.

ALPHA MODENVIDIA/AMD · VRAM ≥ 8GB · Ollama local · Llama-3 70B · 100% offline

EDGE MODEIntegrated GPU · CPU Only · Gemini 2.0 / Claude / GPT-4o via LiteLLM

DARK MODENet Offline · Phi-3, Gemma-2B · Graceful degrade · Offline ops only

RouterLiteLLM (model-agnostic)

LocalOllama + Llama-3 70B

CloudGemini 2.0 Flash / GPT-4o

FallbackPhi-3 · Gemma-2B

PrivacyCloud is the exception

LIVE SYSTEM STATUS

DAEMON STATUSLOADING

PINECONELOADING

INFERENCELOADING

KRIYA PHASELOADING

REFRESH: 10s INTERVAL

SECURITY MODEL // THREAT ANALYSIS

Five threats. Five mitigations.

[X]LLM hallucination → rm -rf /

[✓]LLM output is NEVER executed on the host directly

[X]Daemon privilege escalation

[✓]Daemon runs as yantra_daemon (UID 999)

[X]Container escape to host filesystem

[✓]Docker has NO network OR host mount

[X]Unrestricted SSH command execution

[✓]SSH key allows ONLY whitelisted commands

[X]Secrets exfiltration via prompt inject

[✓]Secrets in /etc/yantra/secrets.env (0400) — never in model context

TECH STACK // FULL LAYER MATRIX

Every layer. Every decision.

LAYERTECHNOLOGYPURPOSE

BootArch Linux (linux-lts)Stable, minimal kernel

InitsystemdDaemon lifecycle + IPC

OS InterfacePython 3.12 / asyncioDaemon orchestration

InferenceLiteLLMModel abstraction layer

Local LLMsOllamaPrivate on-device inference

Vector MemoryChromaDBEmbedded skill/context storage

Skill StorePinecone (1536-dim)Semantic skill retrieval

ExecutionDocker + AlpineSafe command sandbox

Host GatewayOpenSSH (allowlist)Whitelisted host control

TUITextual + RichTerminal HUD renderer

IPC TransportUNIX Domain SocketDaemon ↔ UI bridge

Fleet CloudNext.js + SupabaseFleet monitoring + HUD

FilesystemBtrfs (+ Snapper)Atomic snapshots

OTA Managersystemd + pacman hookAutonomous self-update

ADRS // ARCHITECTURAL DECISIONS

Eight decisions. All intentional.

ADRDECISIONRATIONALE

ADR-001Python over Rust/GoLiteLLM, ChromaDB, PyTorch in weeks. Rust rewrites earmarked for v2.

ADR-002Docker Sandbox for executionLLM hallucinations are real. No command ever touches the host directly.

ADR-003Arch Linux foundationRolling release, bleeding-edge kernel, minimal bloat. Build exactly what's needed.

ADR-004Pure TUI, no display managerEliminates Wayland/X11 complexity. Reduces attack surface.

ADR-005UNIX socket IPCZero-latency, zero-network-overhead. No HTTP overhead. No port exposure.

ADR-006LiteLLM as routerOne API call, any model. Switching models requires zero code changes.

ADR-007Pinecone for Skill Store1536-dim cosine index for semantic retrieval of shareable behaviors.

ADR-008OTA via systemd + pacmanAtomic, pre-snapshotted self-update. Rollback guarantees without operator.

Ready to boot?

Full install guide and API reference in the docs.

Read the docs →GitHub ↗