From 699aac32ea4f5ad84a4e291697e4d308dbaf5512 Mon Sep 17 00:00:00 2001 From: n4mlz Date: Fri, 27 Feb 2026 12:12:51 +0900 Subject: [PATCH 1/2] docs: update README.md --- README.md | 90 ++++++++++++++++++++++++++----------------------------- 1 file changed, 43 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 6af9cdd..9291da5 100644 --- a/README.md +++ b/README.md @@ -19,54 +19,14 @@ Cyrius is a container-focused operating system that runs OCI containers natively For implementation-oriented documentation and code-level explanations, see DeepWiki: https://deepwiki.com/n4mlz/Cyrius -## 🧭 Overview +## ✅ Overview -Linux containers are effective, but the kernel does not treat “container” as a native concept. In many systems, container lifecycle and state are maintained indirectly via user-space bookkeeping. +Cyrius is a Type-1 container runtime OS: a container runtime integrated into the kernel and running directly on bare metal. By “Type-1,” we mean the runtime lives in kernel mode as part of the OS itself (analogous to a Type-1 hypervisor), not as a user-space process on top of another OS. It is OCI-compatible, does not depend on Linux kernel code, and treats the container environment as a first-class OS object with OS-owned lifecycle and state. Processes run inside explicit environments rather than inheriting isolation as process-attached attributes. -Cyrius explores an alternative model: containers are explicit OS-managed objects, and container operations are expressed as container operations. - -## ❓ Why Cyrius - -Cyrius is motivated by practical friction points that appear when containers are represented as “processes with attributes”: - -- Isolation and visibility can rely on cross-subsystem interfaces with subtle dependencies. -- The security model can become difficult to reason about when built from many separate features. -- Container state can become coupled to user-space runtimes keeping critical handles alive. - -Cyrius aims to make the container environment a durable, OS-managed entity rather than an emergent property of a running process. - -## 🧩 Design principles - -1. Containers are first-class OS objects - A container is an explicit entity representing an execution environment. The OS tracks its lifecycle and state. - -2. Environment-first model - Creating an environment and starting a process within it are separate steps (“create then start”). - -3. Minimal host interface, container-native operations - The host-side interface focuses on container management (create/start/stop), avoiding long chains of low-level setup steps. - -4. Compatibility where it matters - Cyrius targets Linux syscall compatibility sufficient for typical container workloads, but does not aim for full Linux feature parity. - -5. Deliberate scope constraints - Cyrius assumes a two-world model (host world and container world) and does not treat nested containers as a primary goal. - -## 🧪 Status and scope - -Cyrius is experimental and under active development. Interfaces and behavior may change. - -Targets: - -- Native execution of OCI bundles (runtime config + root filesystem) -- OS-managed container lifecycle -- A pragmatic subset of Linux syscall compatibility for container workloads - -Non-targets (for now): - -- General-purpose desktop/server usage -- Full parity with all Linux system calls and Linux container-specific features -- Nested containers as a primary design goal +| | Hypervisor | Container Runtime | +| --------------------- | ------------------------------------ | ------------------------------------------------------------------------ | +| Type-1 (kernel space) | Type-1 Hypervisor (VMware ESXi) | Type-1 Container Runtime ([**Cyrius**](https://github.com/n4mlz/Cyrius)) | +| Type-2 (user land) | Type-2 Hypervisor (QEMU, VirtualBox) | Type-2 Container Runtime (runc, youki) | ## 🚀 Quick start @@ -184,10 +144,46 @@ If you are new to this codebase, start with: - the top-level build/run workflow (`cargo xtask run`) - the DeepWiki pages for boot flow, syscall handling, and container lifecycle design +## 🎯 Motivation + +Cyrius is motivated by practical friction points that appear when containers are represented as “processes with attributes”: + +- Isolation and visibility can rely on cross-subsystem interfaces with subtle dependencies. +- The security model can become difficult to reason about when built from many separate features. +- Container state can become coupled to user-space runtimes keeping critical handles alive. + +Cyrius aims to make the container environment a durable, OS-managed entity rather than an emergent property of a running process. + +## 🧠 Design principles + +1. Containers are first-class OS objects + A container is an explicit entity representing an execution environment. The OS tracks its lifecycle and state. + +2. Environment-first model + Creating an environment and starting a process within it are separate steps (“create then start”). + +3. Minimal host interface, container-native operations + The host-side interface focuses on container management (create/start/stop), avoiding long chains of low-level setup steps. + +4. Compatibility where it matters + Cyrius targets Linux syscall compatibility sufficient for typical container workloads, but does not aim for full Linux feature parity. + +5. Deliberate scope constraints + Cyrius assumes a two-world model (host world and container world) and does not treat nested containers as a primary goal. + +## 🌐 Philosophy and concepts + +Cyrius proposes a container OS model where the container runtime is integrated into the kernel and isolation is enforced by OS-native mechanisms rather than layered user-space conventions. The model assumes containers do not nest and divides the system into two worlds: the host world and the container world. Namespaces are not hierarchical. + +All processes are classified as host processes or container processes. Cyrius keeps two syscall tables: one for host control and one for Linux-compatible container execution. The kernel selects the table by inspecting the `abi` field of the `Process` structure. Host syscalls are intentionally narrow and focus on OCI-native operations such as `create`, `start`, and `stop`, reducing round-trips between kernel and user space during container setup. + +Containers are kernel objects whose state and lifecycle are owned by the OS. A `Container` defines the execution environment and does not necessarily require any running process. The `Container` structure holds environment descriptors such as `rootfs`, capabilities, resource limits, and mount/handle references for inter-process and root filesystem access. + +VFS instances for containers are fully separated from the host filesystem. Processes can access VFS only through their associated `Container`, preventing chroot-style escape patterns by construction and avoiding complex operations like `pivot_root` to swap filesystem roots. + ## 📚 Documentation - DeepWiki (implementation-focused): [https://deepwiki.com/n4mlz/Cyrius](https://deepwiki.com/n4mlz/Cyrius) -- Repository Wiki (design notes, higher-level documentation): (add link once published) ## 📄 License From 1f73560e7cd60a418a488279845795fe91cc47db Mon Sep 17 00:00:00 2001 From: n4mlz Date: Fri, 27 Feb 2026 12:13:49 +0900 Subject: [PATCH 2/2] docs: update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9291da5..c8125b1 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@

-cyrius +cyrius