DOCUMENTATION OVERVIEW

HOW YANTRAOS WORKS

A precision instrument for autonomous AI-agent execution. Four architectural pillars — one coherent system.

PHILOSOPHY

The Karma Yogi

YantraOS is built on the Karma Yogi principle — act without attachment to outcome. The system executes, reflects, and adapts without halting for human confirmation on low-risk tasks.

Every directive enters the Kriya Loop. The loop reasons, plans, executes in a sandboxed environment, and evaluates its own output. If it fails, it heals. This is autonomous agency at the OS level.

// Karma Yogi invariant
while kriya_loop.is_alive():
    intent  = perceive(environment)
    action  = plan(intent, memory)
    outcome = sandbox.execute(action)
    reflect(outcome)         # no attachment

CORE ENGINE

The Kriya Loop

The Kriya Loop is a perpetually running asyncio daemon (yantra.service). It is the heartbeat of the OS — never hard-crashes, recovers from every exception, and streams structured telemetry to the IPC bridge.

All state flows through a UNIX Domain Socket (/run/yantra/ipc.sock) as structured JSON. The TUI Shell and the Web HUD are purely stateless consumers — they never share memory with the daemon.

/run/yantra/ipc.sock
─────────────────────────────────────
{ "event": "kriya_tick",
  "tier": "local",
  "model": "llama3:8b",
  "latency_ms": 142,
  "status": "RUNNING" }

SECURITY

Ephemeral Docker Sandbox

Every piece of AI-generated code executes inside an ephemeral Alpine container. The sandbox is configured with --cap-drop=ALL, --read-only, and --network=none. Containers are destroyed immediately after execution.

The host filesystem is never touched. Yantra Daemon runs as the unprivileged yantra_daemon user. Polkit rules govern the narrow surface of BTRFS and systemd calls that require elevation.

docker run --rm \
  --cap-drop=ALL \
  --read-only \
  --network=none \
  --user=nobody \
  yantra-sandbox:alpine

INFERENCE ENGINE

Hybrid Inference Router

YantraOS operates a three-tier inference fallback chain. Local Ollama is always the primary target — sovereign, private, zero-latency when warm. If the local model saturates, LiteLLM routes to Gemini. Claude is the final backstop.

The inference tier is surfaced in real-time on the TUI HUD and the Web HUD health endpoint. Operators know exactly which model answered every directive.

Tier 1 → Ollama  (llama3:8b · local · private)
Tier 2 → Gemini  (gemini-1.5-flash · cloud)
Tier 3 → Claude  (claude-3-5-sonnet · fallback)
─────────────────────────────────────────────
Router: LiteLLM · Config: litellm_config.yaml

FULL TECHNICAL SPECIFICATIONS

Deep-dive into the architecture

API reference, IPC protocol schemas, BTRFS snapshot policies, Polkit rules, and installer internals — all on Gitbook.

OPEN GITBOOK DOCS

yantraos.gitbook.io/yantraos · maintained by Euryale Ferox Pvt. Ltd.