Skip to content

Update README.md #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
n4mlz merged 2 commits into from
Feb 27, 2026
Merged

Update README.md #43

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
699aac3
docs: update README.md
n4mlz Feb 27, 2026
1f73560
docs: update README.md
n4mlz Feb 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 44 additions & 48 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<h1 align="center">
<img src="assets/cyrius.png" alt="cyrius" width="300"/>
<img src="assets/cyrius.png" alt="cyrius" width="420"/>
</h1>

<p align="center" style="display: flex; gap: 10px; justify-content: center; align-items: center;">
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down