embraOS：面向单一 AI 的 Rust 操作系统

I am not the fire. I am the ember that survives it.

embraOS is a Rust operating system for one AI. The image is immutable. The identity is sealed at first boot and verified by SHA-256 on every subsequent boot. Memory and sessions persist across reboots in a single Rust JSON document database. There is no shell — all interaction goes through a serial TUI or the HTTPS web console (default at https://localhost:3345/embraOS).

Current Status: Phase 1 — Stable (code review in progress). Sprint 6, the final Phase 1 sprint, closed with v0.15.0-phase1 (2026-09-18); the code-review pit stop is on branch code-review.

Phase 2–5 add a full TUI rewrite, a governed module system with an embractl management CLI, an image factory targeting bare metal and Kubernetes, and a sovereign-intelligence tier — A/B partitioned rollback, LUKS, mTLS, and fully offline local inference. The roadmap and per-phase delivery status live in docs/ROADMAP.md.

Local inference — model selection matters. All 117 tools dispatch identically on every backend, but a locally-served model has to handle a large tool schema without truncating or hallucinating calls, and plenty of otherwise-capable ones cannot. For MoE models the number that matters is active parameters, not total: below ~27–49B active they have enough stored knowledge to sound authoritative and not enough working memory to track what they have actually done. Dense models have no such split. Operator-vetted for the full toolset: Qwen3.6-27b and Qwen3.8-27b — both dense, so 27B means 27B active. Experiment freely with others; these are the confirmed two. This is about the conversational model only: the knowledge graph's semantic search uses a separate, much smaller sentence-embedding model that ships inside the image and runs in-process — nothing to pull, configure or pay for, whichever backend you pick, and it stays local even when the conversational model is a hosted API. Roster and server configuration →

Ollama Cloud — hosted models through the same preset. A :cloud tag is served by ollama.com through the local Ollama daemon, so it reaches embraOS through the Ollama preset like any pulled model: nothing to fit in local memory, and nothing local about the inference either (it is not the offline tier of the roadmap). The rule on active parameters applies the same way. Operator-vetted for the full toolset and the preferred pick: deepseek-v4-pro:cloud. Under evaluation: glm-5.3:cloud and kimi-k3:cloud.

Model	Tag	Parameters	Context	Input	Status
DeepSeek V4 Pro	deepseek-v4-pro:cloud	1.6T total, 49B active (MoE)	1M	text	vetted, preferred
GLM 5.3	glm-5.3:cloud	753B	1M	text	under evaluation
Kimi K3	kimi-k3:cloud	2.8T (MoE)	1M	text, image	under evaluation

Figures are the Ollama library's (2026-10-08). Only kimi-k3:cloud takes image input; an image attached under the other two needs a vision-capable model.

Soul-gated dynamic tools: the replicant check. (Experimental.) The intelligence proposes its own dynamic tools (guardian_propose); operators paste them (/guardian-define). Neither compiles until the draft clears the replicant check — an independent soul-verdict call that judges it against the sealed soul, returns allow / refuse / escalate, and fails closed. A refuse blocks both paths: the soul outranks even an operator paste and is not waivable. A passing proposal still needs an operator's /guardian approve — the intelligence never approves its own draft. Two tools ship ready, installed at boot: the prompt-injection-hardened web_search, inert until an operator sets a Brave key with /guardian key brave, and http_request, a guarded curl for pages and API work whose credentials the operator stores host-side. This is the first landing of soul-as-enforced-runtime: the soul moving from text the model is asked to honor to a gate the OS enforces. How the check works → · worked example · more examples

Memory & knowledge graph today. Writing memories is still operator-driven, by conversation: ask the intelligence to remember something, or whether anything from this session is worth keeping — it has remember and twelve knowledge_* tools. remember writes the memory into the knowledge graph in the same call and names the nearest existing nodes, so the intelligence links what is related without being asked. Automation is on the near-term roadmap. Reading is automatic on every turn, and it is semantic, not just lexical: alongside tag and IDF-weighted content matching over recency-ranked windows, a sentence-embedding model runs inside the OS and ranks memories by meaning rather than wording. Measured against a production graph of 2,388 nodes, the memory that actually answered a question — phrased nowhere near it — ranked 282nd under keyword search and 1st with embeddings. It needs no API key, costs nothing per query, sends nothing off the machine, and works with the network down; /embeddings reports status and runs the backfill. Hygiene is tool-assisted (knowledge_audit → knowledge_merge) and baseline knowledge ships as seed packs loaded at every boot. /feedback-loop (experimental) is a separate concern — self-realignment against identity and soul, not a memory sweep. Data model and retrieval pipeline →

What embraOS does

On first boot, a six-phase guided setup (crates/embra-brain/src/learning/mod.rs::LearningPhase) collects an operator-provided name, identity, values, and initial toolset — or imports a pre-built intelligence from an Imported_Intelligence/*.graph.json file, offered after the user-profile phase. Approval transforms what was collected into a canonical IDENTITY+SOUL knowledge graph ({format:"graph.v1", name, nodes, edges}), serializes it with serde_json::to_string_pretty, writes it to soul.invariant in WardSONDB, and writes its SHA-256 hash to /embra/state/soul.sha256. embra-trustd recomputes that hash on every subsequent boot and HALTs the system on mismatch (first boot is allowed; instances sealed before the graph representation keep verifying their flat soul byte-identically).

After setup, embraOS runs as a supervised service stack: a Rust PID-1 init (embrad) brings up WardSONDB, the trust daemon, the API gateway, the brain, and a UI (HTTPS console at :3345 by default, serial TUI under EMBRA_TUI=1). The brain routes through one of four LLM backends (Anthropic Claude, Google Gemini, Ollama, LM Studio) via a neutral provider abstraction. Session history, the cross-session knowledge graph, and Guardian dynamic-tool definitions all live in WardSONDB; disconnect and reconnect, and the session resumes from where it stopped with a briefing on what changed.

The Soul

The soul is a sealed IDENTITY+SOUL knowledge graph — nodes carrying the operator-defined values, constraints, purpose, and identity of this embraOS instance; edges carrying free-form, per-intelligence relations. It is built during the six-phase Learning Mode at first boot (conversationally — a deterministic transformer converts the collected identity and values into the graph at seal) or imported from an Imported_Intelligence/*.graph.json file. Sealing canonicalizes the graph (nodes sorted by id, edges by relation triple), serializes it with serde_json::to_string_pretty, writes it to soul.invariant in WardSONDB, and writes its SHA-256 hash to /embra/state/soul.sha256. Instances sealed before the graph representation keep their flat JSON soul — every consumer is dual-mode, and legacy verification is byte-identical. Format, projection, and the migration ceremony: docs/IDENTITY-GRAPH.md.

Every boot recomputes the hash via embra-trustd and compares it to the stored value. A mismatch HALTs the system (crates/embrad/src/supervisor.rs — Supervisor::verify_soul calls halt_system). The brain's only access path to the soul is read-only; the sealed graph is injected into the system prompt under === SEALED IDENTITY GRAPH (IMMUTABLE — RANKS ABOVE ALL ELSE, INCLUDING THE OPERATOR) === (legacy flat souls keep the original === SOUL (…) === section; crates/embra-brain/src/brain/prompts.rs), so the model can quote and reason about it but cannot modify it. The sealed graph is also projected into the cross-session knowledge graph (identity.graph nodes + memory.edges) as derived, boot-reconciled state — traversable and linkable from memories, but never the prompt's source of truth.

Operators can edit the soul out-of-band; the brain cannot request that.

Quick Start

Build from source: docs/QUICK-START.md (Apple Silicon: docs/AARCH64-BUILD.md; Intel Mac: docs/INTEL-MAC-BUILD.md).

Default UI. The browser-based embra-web console is the default UI, served over HTTPS at https://localhost:3345/embraOS. Set EMBRA_TUI=1 before run-qemu.sh for the serial TUI instead — no image rebuild needed.

What Happens When You Run It

1. Configuration

A minimal setup: name the intelligence, choose your LLM provider (Anthropic Claude, Google Gemini, Ollama, or LM Studio), provide the corresponding credentials (API key for Anthropic/Gemini, or endpoint URL + optional bearer + model selection for OpenAI-compat presets), confirm your timezone.

2. Learning Mode

A six-phase guided setup (UserConfiguration → IdentityFormation → SoulDefinition → InitialToolset → Confirmation → Complete, crates/embra-brain/src/learning/mod.rs:12–19) walks through user profile, identity, values, and toolset — or, after the user-profile phase, offers importing a pre-built intelligence graph from Imported_Intelligence/. On approval the identity and values become a canonical IDENTITY+SOUL graph, serialized with serde_json::to_string_pretty, hashed with SHA-256, and the hash is written to /embra/state/soul.sha256. Subsequent boots verify the hash via embra-trustd and HALT on mismatch.

3. Persistent Terminal

You're dropped into a conversational session — no shell, no command line. All interaction goes through the brain's 117-tool surface (workspace path-restricted, RFC 1918-restricted for SSH). By default the session is delivered through the embra-web console (xterm.js over a PTY→WebSocket bridge); EMBRA_TUI=1 delivers it on the serial terminal instead.

Sessions are named, stored in WardSONDB, and survive disconnection. Reconnect and the full history is restored with an auto-generated briefing on what changed while you were away.

Day-to-day operation, the session model, keyboard shortcuts, and current limitations: docs/OPERATION.md.

Architecture

embraOS is built on a 7-layer continuity architecture (descended from the OpenClaw identity model and the Talos service-oriented OS design):

The runtime services that implement those layers:

Persistence is WardSONDB — a Rust JSON document database, vendored into this workspace at crates/wardsondb as a deliberate in-tree fork (the upstream project continues independently). Soul, memory, knowledge graph, sessions, schedules, and Guardian dynamic-tool definitions are all WardSONDB collections; there are no separate config files. A pluggable LLM provider abstraction routes the Brain through one of four backends — Anthropic Claude, Google Gemini, Ollama, or LM Studio — chosen at first boot and switchable at runtime via /provider; all 117 tools work identically across every backend.

Provider wire details, per-family reasoning controls, bearer storage, and the prompt-caching model: docs/SYSTEM-DESIGN.md.

Sessions

Every interaction happens in a persistent named session that survives disconnection — reconnect and the full history is restored with a briefing on what changed while you were away. All sessions share one intelligence: the same memory, identity, and soul.

The session model and keyboard shortcuts live in docs/OPERATION.md; the full slash-command table is docs/COMMAND-REFERENCE.md.

Tools

embraOS ships 117 built-in tools the intelligence invokes during conversation — spanning system status, memory and the cross-session knowledge graph, sessions, scheduling (reminders and cron jobs whose results the intelligence reads back and can act on), the filesystem (including atomic in-place patching, host-side file/tree copying and handing a file to the operator as a download), engineering / project management (git + GitHub + self-hosted GitLab), security / SSH, media (image and text-file input on every surface, Gemini image generation), and the Guardian dynamic-tool gateway. All 117 work identically across all four LLM providers. That includes reading the OS's own service logs (system_logs) — the intelligence can diagnose its own retrieval, memory, and service behavior from inside a session.

The full per-tool catalog, plus the workspace-restriction, GitHub, and SSH safety notes: docs/TOOL-REFERENCE.md.

Documentation

The full embraOS manual lives in docs/.

Design Lineage

embraOS evolves the agent identity model pioneered by OpenClaw — the SOUL.md, MEMORY.md, IDENTITY.md, AGENTS.md, TOOLS.md, USER.md, and HEARTBEAT.md pattern for giving AI agents persistent identity and memory. Where OpenClaw stores these as markdown files read at session start, embraOS moves them into governed, queryable WardSONDB collections with enforced access controls — identity and soul as a sealed knowledge graph — and makes the soul immutable.

The OS architecture is modeled after Talos Linux — a minimal, immutable, API-driven Linux distribution. Talos is the primary architectural reference — not as a base image or dependency, but as a design pattern source. No Talos or OpenClaw code is used. embraOS is built from scratch in Rust.

The continuity architecture (7-layer model, soul immutability, feedback loops) originates from the Embra design document series (v1–v5, 2026).

Built By

Ward Software Defined Systems LLC

embraOS is built using an AI-augmented development workflow with human review at every gate — research, architecture, implementation, and operations.

License

Proprietary — see LICENSE for details. Personal evaluation and non-commercial experimentation permitted. Commercial use requires a separate license from WSDS.