OrionOS Runtime: Technical Documentation & Discussion

by Alex Johnson 54 views

📘 CHAPTER 1 — OrionOS Runtime Overview

1.1 — Introduction to OrionOS Runtime

At its core, OrionOS Runtime is a hybrid platform meticulously crafted using Rust and TypeScript. It's engineered to function as an isolated, secure, and modular computing environment, seamlessly integrating within any host system, be it Windows, Linux, or macOS. Think of it not as a replacement for your traditional operating system, but as a mini-OS living inside your current one. It offers a suite of powerful features, including a virtual file system, an internal database, a built-in language, an isolated execution engine (sandbox), an independent internal network, a portable application format called Capsules, a multi-level security layer, and universal APIs for creating internal applications. The primary goal of OrionOS is to create a controlled ecosystem, one that empowers the execution of secure, reproducible, and independent applications. This makes it suitable for a wide array of users – from end-users and businesses to developers, sensitive applications, automations, and even academic research. Its architecture is a harmonious blend of Rust's security and performance prowess with TypeScript's productivity and flexibility, culminating in a comprehensive execution environment. This unique combination ensures that applications running within OrionOS are not only robust but also benefit from a streamlined development process. The OrionOS Runtime environment, with its secure and modular design, provides a robust platform for a variety of applications, ensuring that each application operates in a controlled and predictable manner.

1.2 — System Philosophy

The OrionOS Runtime operates on four fundamental principles. These principles guide the design and functionality of the system, ensuring it meets the needs of its diverse user base.

1. Security by Design (Secure-by-Default)

Security is not an afterthought in OrionOS; it's baked into the very foundation. Everything within the OrionOS ecosystem operates within a sandbox. This means no component has direct access to the host system without explicit permission. This approach extends to isolated memory, a virtual file system, a virtual network, declarative permissions, and integrated auditing. Each application runs in its own isolated environment, preventing unauthorized access and ensuring the integrity of the host system and other applications. The security-by-design philosophy ensures that OrionOS Runtime provides a safe and trustworthy environment for all types of applications, especially those dealing with sensitive data or critical operations.

2. Determinism and Reproducibility

One of the core tenets of OrionOS is determinism. A Capsule, the application format for OrionOS, will execute in precisely the same way, regardless of the machine it's running on. This is achieved through internal versioning, a hermetic environment, and a design that eliminates external dependencies. Developers can rely on consistent behavior, simplifying testing and deployment processes. This reproducibility is crucial for applications where consistency and predictability are paramount. The deterministic nature of OrionOS makes it an ideal platform for applications requiring precise and repeatable execution.

3. Total Portability

Applications built for OrionOS enjoy unparalleled portability. They can run seamlessly on Windows, Linux, and macOS – without requiring any modifications. This cross-platform compatibility streamlines development and deployment, allowing applications to reach a wider audience without the hassle of platform-specific adjustments. The total portability offered by OrionOS reduces development overhead and ensures that applications can be easily distributed and used across different operating systems. This feature is particularly beneficial for developers targeting multiple platforms.

4. Extreme Modularity

The OrionOS architecture is built upon extreme modularity. Every part of the system is an independent module. This includes OrionFS (the file system), OrionDB (the database), OrionLang (the language), OrionNet (the networking), OrionVM (the virtual machine), OrionCapsule (the application format), and OrionAPI (available in both Rust and TypeScript). This modularity is not just a design choice; it's a strategic advantage that allows for future expansion and customization. Each module can be updated and improved independently, without affecting the rest of the system. The modular design of OrionOS enhances its flexibility and scalability, making it adaptable to evolving requirements.

1.3 — Ecosystem Components

The OrionOS Runtime ecosystem comprises seven primary components, each playing a vital role in the overall functionality and security of the platform.

1. OrionCore (Core)

This is the heart of OrionOS, written in Rust for maximum performance and security. OrionCore manages internal processes, security protocols, memory management, permissions, application lifecycle, and auditing. It's the foundational layer that ensures the smooth and secure operation of the entire system. OrionCore's robust design is crucial for maintaining the stability and integrity of the OrionOS Runtime environment.

2. OrionFS (Virtual Filesystem)

OrionFS is a binary virtual file system, structured by blocks and internal tables. Its key properties include independence from the host's disk, support for isolation, replication capabilities, and optional encryption. This virtualized file system ensures that applications operate within a secure and controlled environment, isolated from the host system's file structure. OrionFS provides a secure and portable storage solution for applications running within OrionOS.

3. OrionDB (Internal Database)

OrionDB is a key-value database with indexes and memory pages, natively integrated into the file system. It's ultra-lightweight, portable, and supports simple transactions with guaranteed atomicity. This internal database provides a fast and efficient way for applications to store and retrieve data, without relying on external database systems. The tight integration of OrionDB with OrionFS enhances its performance and security.

4. OrionLang (Internal Language)

OrionLang is an interpreted language with a simple syntax, designed for automations, embedded scripts, operation control, and Capsule initialization. The parser and executor are written in Rust, ensuring both performance and security. This language provides a flexible and secure scripting environment for various tasks within the OrionOS ecosystem. OrionLang enables developers to create scripts and automations that interact seamlessly with the system.

5. OrionNet (Internal Network)

OrionNet is a network protocol isolated from the host system. It includes internal routing, internal peer-to-peer channels, encapsulation for external internet access, privacy layers, and a secure handshake mechanism. This isolated network ensures secure communication between applications within the OrionOS environment. OrionNet provides a secure and private networking layer for applications running within OrionOS.

6. OrionVM (Execution Engine / Sandbox)

OrionVM is the virtual machine of OrionOS. It executes Capsules, controls permissions, regulates time, CPU, and memory usage, prevents escapes from the environment, and generates execution proofs. This virtual machine provides a secure and isolated environment for running applications, ensuring that they cannot interfere with the host system or other applications. OrionVM is a critical component for maintaining the security and stability of the OrionOS Runtime environment.

7. OrionCapsule (Application Format)

An OrionCapsule is the "software unit" of OrionOS. It's a single file containing code (TS/OrionLang/Rust-WASM), data, manifests, permissions, internal dependencies, a cryptographic signature, and execution rules. Think of it as a secure, portable, and verifiable .exe file. OrionCapsules simplify application distribution and deployment, ensuring that all necessary components are packaged together in a secure and verifiable format. The OrionCapsule format enhances the security and portability of applications within the OrionOS ecosystem.

1.4 — General Architecture (High-Level View)

The OrionOS Runtime functions as a specialized executable container, operating within the host system while providing its own distinct environment. This environment includes its own subsystems, network, file system, database, and language, all isolated from the host system. The diagram below illustrates a simplified representation of the OrionOS architecture:

+-----------------------------------------------------------+
|                    Host Operating System               |
|        (Windows / Linux / macOS)                          |
+--------------------------+--------------------------------+
                           |
                           v
+-----------------------------------------------------------+
|                 OrionOS Runtime (Rust Core)               |
|-----------------------------------------------------------|
|  OrionCore   |   OrionVM   | OrionNet | OrionFS | OrionDB |
+--------------+-------------+----------+---------+---------+
|                   APIs Rust / TypeScript                 |
+-----------------------------------------------------------+
|                   OrionCapsule Applications                |
+-----------------------------------------------------------+

This architecture ensures that applications running within OrionOS operate in a controlled and predictable environment, without direct access to the host system's resources. The OrionOS Runtime thus offers a secure and portable platform for a wide range of applications.

1.5 — Typical Use Cases

OrionOS is versatile and can be used in a variety of scenarios:

For Businesses:

  • Secure data processing
  • Isolated automations
  • Execution of reliable scripts
  • Portable applications
  • Environments requiring confidentiality

For Developers:

  • Creating isolated applications
  • Testing code securely
  • Distributing portable tools
  • Generating executable pipelines

For Common Users:

  • Running portable applications
  • Sending/receiving Capsules
  • Storing private data
  • Using simple automations

1.6 — Documentation Objective

This documentation serves four simultaneous profiles:

  • ✔ Companies: Security, isolation, auditing, reliability.
  • ✔ Academia: Formal models, theoretical architecture, innovation.
  • ✔ Developers: APIs, examples, internal structure.
  • ✔ Recruiters: Demonstrated technical domain.

1.7 — Chapter 1 Conclusion

This chapter presented:

  • Overview
  • Philosophy
  • Objectives
  • High-level architecture
  • Main components
  • Strategic purpose

Now that the landscape has been established, we can delve into the technical part.

📘 Next chapter:

CHAPTER 2 — Internal Architecture of the OrionOS Runtime (with diagrams, layers, abstractions, execution flow, threading model, and Rust + TS integration)

📘 CHAPTER 2 — Internal Architecture of the OrionOS Runtime

This chapter describes the complete internal architecture of the OrionOS Runtime, covering system layers, interactions between Rust and TypeScript, execution flow, isolation mechanisms, module design, internal pipelines, concurrency model, and resource management. A comprehensive understanding of the internal architecture is crucial for developers and system administrators looking to leverage the full capabilities of OrionOS.

2.1 — Internal Architecture Overview

The OrionOS Runtime is divided into five main layers, each isolated by design. This layered architecture enhances security, maintainability, and scalability.

┌──────────────────────────────────────────────┐
│               Layer 5: Applications           │
│              (OrionCapsules / Apps)          │
├──────────────────────────────────────────────┤
│           Layer 4: APIs (TS + Rust)         │
├──────────────────────────────────────────────┤
│            Layer 3: OrionVM Sandbox         │
├──────────────────────────────────────────────┤
│  Layer 2: Native Modules (FS, DB, Net, Lang)  │
├──────────────────────────────────────────────┤
│              Layer 1: OrionCore             │
└──────────────────────────────────────────────┘

Each layer plays a specific role in the overall functionality of the system, and the interactions between layers are carefully controlled to ensure security and stability. The layered approach allows for modular development and easier debugging.

2.2 — Layer 1: OrionCore (Rust)

The OrionCore is the heart of the system. It is written 100% in Rust, ensuring high performance and security. This layer contains the internal process manager, permission system, auditing capabilities, memory and CPU control, runtime initialization, handshake with the host system, isolation between modules, Capsule validation, and global module registry. The OrionCore is responsible for the fundamental operations of the OrionOS Runtime, including security and resource management. Its robust design is critical for the overall stability and security of the system.

Internal Structure (Simplified):

OrionCore
├── process_manager.rs
├── resources.rs
├── permissions.rs
├── capsule_loader.rs
├── audit.rs
├── vm_bridge.rs
└── crypto.rs

The modular structure within OrionCore allows for focused development and easier maintenance of individual components. Each module is responsible for a specific aspect of system management, contributing to the overall efficiency and stability of OrionOS.

2.3 — Layer 2: Native Modules (Rust)

Each subsystem in OrionOS is constructed as an independent module. This includes OrionFS (virtual filesystem), OrionDB (internal database), OrionLang (parser + executor), OrionNet (virtual network), and OrionCrypto (cryptographic primitives). These modules run within OrionCore and are accessed only by the VM, ensuring they never have direct access to the host system. This isolation is a key aspect of the OrionOS security model. The independence of these modules allows for targeted updates and improvements without affecting other parts of the system.

2.4 — Layer 3: OrionVM (Decorated Sandbox)

The OrionVM is the environment where applications actually run. It interprets code, executes Capsules, manages internal threads, validates permissions, limits CPU/RAM usage, monitors internal calls, and prevents escapes to the host system. The OrionVM ensures that applications operate within a secure and controlled environment, preventing them from accessing resources or performing actions outside their designated scope. This is a critical component for maintaining the security and stability of the OrionOS Runtime.

The VM operates in 3 sublayers:

  1. Executor (Rust): Executes bytecode, controls instructions, controls permissions.
  2. Bridge (Rust ↔ JS): Translates calls to TypeScript, validates security, serializes data between languages.
  3. JS Runtime (TypeScript): Executes apps written in TS, interacts with secure APIs, generates UI, logic, etc.

The layered approach within OrionVM enhances its ability to manage and control application execution. Each sublayer is responsible for a specific aspect of the execution process, contributing to the overall security and efficiency of the virtual machine.

2.5 — Layer 4: APIs (TypeScript + Rust)

The APIs accessible to applications within the sandbox are available in both TypeScript and Rust. TypeScript APIs include fs, db, net, crypto, capsule-utils, sysinfo, and isolation. Rust APIs provide access to high-performance modules, internal VM operations, and native extensions. Communication between Rust and JS uses WASM + secure JSON. These APIs provide a secure and efficient interface for applications to interact with the OrionOS Runtime environment. The dual-language API approach allows developers to choose the best language for their specific needs.

2.6 — Layer 5: Applications (OrionCapsules)

Each Capsule contains code, data, manifests, permissions, a signature, versioning information, and audit policies. Capsules run exclusively within the OrionVM, ensuring a secure and isolated execution environment. The OrionCapsule format simplifies application deployment and management, as all necessary components are packaged together in a single file. The secure nature of OrionCapsules makes them ideal for distributing and running applications within the OrionOS ecosystem.

2.7 — Execution Model

The execution flow of a Capsule is as follows:

[ Capsule ]
     |
     v
[ OrionCore: validates signature ]
     |
     v
[ OrionVM: creates instance ]
     |
     v
[ Loads necessary modules ]
     |
     v
[ Executes code (Rust/TS/WASM) ]
     |
     v
[ Generates logs / audit data ]
     |
     v
[ Closes context and releases resources ]

This execution model ensures that every Capsule is validated and executed within a secure and controlled environment. The steps involved in the execution process are designed to minimize the risk of security breaches and ensure the integrity of the OrionOS Runtime.

2.8 — Concurrency Model

The runtime uses Rust for real parallelism (OS threads) and TypeScript for asynchronous concurrency (event loops). An internal channel is used for isolated communication between tasks. Each application runs in a "Task Capsule," which includes VM thread, JS context, permission mask, memory limit, and timeout settings. This concurrency model allows OrionOS to efficiently manage multiple tasks and applications, providing a responsive and scalable environment.

2.9 — Structural Security

The system implements isolation via Capsuled-VM, individual sandboxes, no direct access to the host system, mandatory signatures, zero unauthorized native execution, and resource control per application. These security measures are critical for maintaining the integrity and confidentiality of applications and data within the OrionOS Runtime. The structural security features of OrionOS make it a robust platform for running sensitive applications.

2.10 — Rust ⇆ TypeScript Flow

A common flow involves TS calling an API, which is then bridged to Rust, processed by a native module, and the result is returned to TS. For example, a db.get("users") call is translated to TS → (bridge) → Rust (OrionDB) → returns. This seamless integration between Rust and TypeScript allows developers to leverage the strengths of both languages within the OrionOS ecosystem. The bridge ensures secure and efficient communication between the two languages.

2.11 — Internal Module Communication

All modules communicate with each other through an isolated Registry:

ModuleRegistry
├── handle(FS)
├── handle(DB)
├── handle(Net)
├── handle(Lang)
└── handle(Crypto)

This prevents side effects between modules, enhancing the stability and predictability of the system. The isolated communication mechanism ensures that modules interact in a controlled manner, preventing interference and maintaining the integrity of the OrionOS Runtime.

2.12 — Complete Internal Architecture Diagram

┌──────────────────────────────────────────┐
│                Applications                │
│               (Capsules)                 │
└───────────▲──────────────────────────────┘
            │ APIs TS/Rust           
┌───────────┴──────────────────────────────┐
│                OrionVM                    │
│    ┌──────────────────────────────────┐   │
│    │ Executor Rust + JS Engine (TS)  │   │
│    └──────────────────────────────────┘   │
└───────────▲──────────────────────────────┘
            │
┌───────────┴──────────────────────────────┐
│       Native Modules (Rust)             │
│ FS | DB | Net | Lang | Crypto | Capsload │
└───────────▲──────────────────────────────┘
            │
┌───────────┴──────────────────────────────┐
│               OrionCore                   │
└───────────────────────────────────┘

This diagram provides a comprehensive overview of the internal architecture of the OrionOS Runtime, illustrating the relationships between the various components and layers. The layered architecture and modular design contribute to the overall security, stability, and scalability of the system.

CHAPTER 2 Completed.

📘 CHAPTER 4 — OrionFS: Structured Virtual Filesystem

The OrionFS is the internal virtual filesystem of the OrionOS Runtime. It does not directly use the host system's disk. Everything is stored in a single, isolated binary file controlled by OrionCore. This design ensures security, portability, determinism, cross-platform compatibility, and total independence from the host system. OrionFS is a critical component for maintaining the security and portability of applications and data within the OrionOS ecosystem.

4.1 — OrionFS Objectives

  1. Absolute Isolation: No application has access to the real disk.
  2. Determinism: A Capsule can be moved between machines without alteration.
  3. Low Complexity + High Efficiency: Simpler structures than EXT4/NTFS, but highly predictable.
  4. Optional Encryption: To protect sensitive data.
  5. Reproducible Snapshots: Allow auditing and replication.

4.2 — OrionFS Architecture

The filesystem is divided into 5 internal structures:

OrionFS
├── SuperBlock
├── BlockTable
├── DirectoryTable
├── DataBlocks
└── MetaIndex

  1. SuperBlock: Stores essential data such as version, size, flags, hash algorithm, and internal pointers.

    struct SuperBlock {
    magic: u32,
    version: u16,
    block_size: u32,
    total_blocks: u32,
    hash_type: u8
}

  2. BlockTable: A block allocation table, similar to FAT. Each block has properties indicating whether it's free, occupied, the start of a file, or a continuation.

  3. DirectoryTable: Represents directories and files. Each entry contains name, type (file, dir, link), size, local permissions, and a pointer to the initial block.

  4. DataBlocks: The real area for raw data, where files, internal content, database data, scripts, and internal capsules are stored.

  5. MetaIndex: Global metadata, including timestamps, attributes, history, and snapshot pointers.

4.3 — Fundamental Operations

OrionFS exposes typical operations, but all internal:

  • Create file: fs.write("/configs/user.json", data)
  • Read file: fs.read("/logs/latest.log")
  • List directories: fs.list("/capsules/")
  • Remove: fs.delete("/tmp/")
  • Snapshots: fs.snapshot("before_training")

4.4 — OrionFS Encryption

The entire FS can be unencrypted, partially encrypted, or fully encrypted. OrionCore provides AES-GCM-256 for blocks, SHA-256/SHA3 for integrity, and internal key management. This encryption capability ensures the confidentiality of data stored within OrionFS.

4.5 — Replication and Portability

You can take the orion.fs file and place it on Windows, Linux, macOS, a remote server, a USB drive, or a Docker container. It always works the same, ensuring portability and ease of replication.

4.6 — Uses Within OrionOS

OrionFS stores logs, the OrionDB database, OrionLang scripts, persistent capsules, VM metadata, temporary files, and private user data. Its versatility makes it a central component of the OrionOS Runtime.

4.7 — OrionFS Guarantees

  1. No application accesses the host disk.
  2. Integrity is always validated.
  3. Permissions per application.
  4. Total reproducibility.
  5. Compatible with any host OS.

CHAPTER 4 Completed.

📘 CHAPTER 5 — OrionDB: Structured Internal Database

OrionDB is the internal, embedded database in OrionOS, fully integrated with OrionFS. It is designed to be extremely fast, lightweight, secure, deterministic, portable, and embedded within a single file. The database plays a crucial role in managing and storing data within the OrionOS Runtime.

5.1 — OrionDB Objectives

  1. Predictable Performance: Operations in a few milliseconds.
  2. Zero External Dependencies: Does not use SQLite, Redis, Mongo, etc.
  3. Fully Packaged Within OrionFS: The DB is just an encrypted sub-block.
  4. Simple ACID Consistency: Guaranteed integrity even in case of interruption.
  5. Efficient Indices: Key-value search → 1 read.
  6. Compact Size: Lean structure, without unnecessary overhead.

5.2 — Internal Architecture

OrionDB is formed by:

OrionDB
├── Header
├── Page Table
├── Pages
│   ├── Index Pages
│   ├── Data Pages
│   └── Overflow Pages
└── Commit Log
  1. Header: Contains version, total size, initial page, integrity information, internal pointers, and transaction state.
  2. Page Table: Indicates where each page is located and its type (0 = index, 1 = data, 2 = overflow, 3 = free).
  3. Pages:
    • Index Pages: Highly compact B+ tree structures for fast searches.
    • Data Pages: Where key-value entries are stored.
    • Overflow Pages: Used when the value is larger than a page's space.
  4. Commit Log: A minimalist transactional log ensuring simple ACID (Atomicity, Consistency, Isolation, Durability) properties.

5.3 — Data Model

OrionDB is a Hierarchical Key-Value store, supporting strings, numbers, arrays, objects, and binary blobs. Keys are in path format, such as "capsule/uuid/config/theme" or "system/net/firewall/rules". The hierarchical key-value model provides a flexible and efficient way to store and retrieve data within OrionDB.

5.4 — Fundamental Operations

The operations exposed by OrionCore include put(key, value), get(key), delete(key), scan(prefix), and transaction { … }. These operations provide a comprehensive set of tools for managing data within the database.

5.5 — Indexing Strategies

OrionDB uses two levels of indexing:

  1. Fast Hash (in-memory hash table)
  2. Persistent B+ Tree

5.6 — Integration with OrionFS

OrionDB is not a separate file; it lives within OrionFS at /system/orion.db. This integration provides several advantages, including snapshots of the FS capturing the DB, transparent encryption, and only one external file to migrate. The tight integration with OrionFS enhances the performance and security of OrionDB.

5.7 — Consistency and Durability

The database is designed to be highly stable, even on weak machines. Guarantees include atomic page writes, checksum corruption detection, automatic rollback, and deterministic recovery. These features ensure the reliability and integrity of data stored within OrionDB.

5.8 — Use Cases Within OrionOS

OrionDB is used for runtime state, persistent configurations, structured logs, intelligent caching, and application data. Its versatility makes it an essential component of the OrionOS Runtime.

5.9 — Estimated Performance

Operation | Average Time
--------|----------
put() small | ~0.2–0.5 ms
get() small | ~0.1 ms
scan(prefix) | 1–5 ms
commit | 1–3 ms

This performance is faster than SQLite in most embedded scenarios due to smaller pages, no full journaling, and an optimized KV index. The high performance of OrionDB makes it suitable for a wide range of applications within the OrionOS ecosystem.

CHAPTER 5 Completed.

To delve deeper into the concepts discussed in this documentation, you might find valuable resources on trusted websites related to operating system architecture and security. For example, the LWN.net is a great resource.