What is IC-OS?
IC-OS is an umbrella term for all the operating systems within the Internet Computer, including SetupOS, HostOS, and GuestOS. These three specialized operating systems work together to provide a secure, isolated, and upgradeable environment for running IC replica nodes. Each operating system serves a distinct purpose in the node lifecycle:SetupOS
Boots new replica nodes and installs HostOS and GuestOS
HostOS
Runs on the host machine and launches GuestOS in a virtual machine
GuestOS
Runs inside a VM and executes the core IC protocol
The Three Operating Systems
SetupOS
SetupOS is responsible for the initial node deployment process. When a Node Provider receives new hardware, they:- Download the SetupOS image onto a bootable USB drive
- Add necessary configuration to the image
- Boot the node from the USB drive
HostOS
HostOS is the operating system running directly on the host machine hardware. Its primary responsibility is to launch and manage the GuestOS virtual machine using QEMU/libvirt. Key characteristics:- Intentionally limited in capabilities by design
- Does not perform any trusted IC protocol operations
- Provides secure isolation for the GuestOS
- Manages virtual machine lifecycle
GuestOS
GuestOS runs inside a QEMU virtual machine on top of HostOS. This is where the actual Internet Computer protocol execution occurs. Key characteristics:- Contains the replica and orchestrator binaries
- Executes all IC protocol operations
- Runs in a virtualized, isolated environment
- Ensures consistent runtime across different hardware platforms
How They Work Together
The three operating systems form a secure, layered architecture:Deployment Flow
- Initial Setup: SetupOS boots from USB and validates hardware
- Installation: SetupOS installs both HostOS and GuestOS to disk
- First Boot: Machine reboots into HostOS
- VM Launch: HostOS starts the GuestOS virtual machine
- Protocol Execution: GuestOS runs the IC replica and joins the network
Security Through Isolation
The virtualization layer provides several security benefits:- Isolation: GuestOS runs in a VM, isolated from the host hardware
- Limited Attack Surface: HostOS has minimal capabilities and services
- Secure Communication: VM sockets (VSOCK) provide controlled communication between GuestOS and HostOS
- Hardware Independence: Virtual machine ensures consistent execution environment
Upgrade Architecture
Both HostOS and GuestOS use an A/B partition scheme that enables upgrades without downtime:The A/B partition layout allows one partition set to run the system while the other is upgraded, then the system switches to the newly upgraded partition on the next boot.
Partition Structure
Each OS maintains:- Boot A/B: Separate boot partitions for each system version
- Root A/B: Separate root filesystems for each system version
- Var A/B: Separate mutable data partitions for each system version
- Config: Shared configuration partition preserved across upgrades
Ubuntu Foundation
All three IC-OS variants are based on Ubuntu:- Built from minimal Ubuntu Docker images
- Only required packages and services included
- Reproducible build process using Bazel
- Weekly base image updates for security patches
The minimal, controlled approach to system assembly is key for maintaining a secure platform. Rather than using full upstream ISO images, the system is assembled from well-understood components.
Build System
IC-OS images are built using a sophisticated process:- Docker Build: System assembled as Docker image first
- Image Transformation: Docker image converted to bootable disk images
- Binary Injection: IC services and binaries added late in the build
- Bazel Orchestration: All builds managed through Bazel
Next Steps
Build IC-OS Images
Learn how to build IC-OS images locally using Bazel
GuestOS Details
Deep dive into the GuestOS architecture and components
HostOS Details
Understand HostOS responsibilities and limitations
SetupOS Details
Learn about the node setup and installation process