mos_runtimes

What this is

A shell-based build tool that creates versioned flists for post-boot MyceliumOS runtime components. It generates environment-specific my_init service definitions, provisions user accounts and SSH keys, and manages access controls per deployment environment.

By moving non-boot-critical components out of the initramfs and fetching them post-boot as flists, mos_runtimes enables smaller initramfs images, independent component versioning, and explicit environment parity control across dev, testing, canary, and production deployments.

What this repository contains

mos_runtimes/
├── build.sh                    # Main build entry point
├── Dockerfile                  # Container image for builder environment
├── config/
│   └── myfs.conf.example       # Example myfs configuration
├── docs/
│   └── PRD.md                  # Product Requirements Document
└── scripts/
    ├── dev-container.sh        # Development container helper
    └── lib/
        ├── common.sh           # Shared utilities and logging
        ├── cargo.sh            # Rust/Cargo build helpers
        ├── config.sh           # Config repo parsing
        ├── container.sh        # Container runtime helpers
        ├── flist.sh            # Flist packing utilities
        ├── provision.sh        # User and SSH key provisioning
        ├── service.sh          # my_init service definition generation
        ├── source.sh           # Git clone and artifact fetching
        ├── stage.sh            # Filesystem staging for flists
        └── upload.sh           # S3 upload helpers

Build pipeline

For each enabled component in an environment:

1. Read config — load environment config and component config from mos_config
2. Fetch source — git clone/checkout or download release binary
3. Build binary — cargo build --release (for git sources)
4. Stage filesystem — flat staging directory with binary, service definition, and config files
5. Pack flist — myfs pack to produce .fl manifest
6. Patch manifest — swap write credentials for read-only route URL
7. Upload — upload .fl manifest to S3 (optional)

Supported environments

Environment	Component versions	Access
dev	Latest branches	Full SSH (GitHub keys), passwordless sudo
testing	Release candidates	Test team SSH, passwordless sudo
canary	Same as production	Restricted SSH, scoped sudo
production	Pinned stable tags	No dev SSH keys, no passwordless sudo

CLI usage

# Build flists for an environment
./build.sh --env dev [--component mycelium] [--pack-mode combined] [--dry-run] [--no-upload]

# List enabled components and versions for an environment
./build.sh --list --env dev

# Validate config repo structure
./build.sh --validate [--env dev]

Build options:

• --env <ENV> — target environment (required for build/list)
• --component <NAME> — build only specific component(s) (repeatable)
• --pack-mode <MODE> — individual (default) or combined
• --config-repo <PATH> — path to mos_config checkout
• --output-dir <PATH> — output directory for .fl files (default: ./dist/flists)
• --dry-run — show what would be built without executing
• --no-upload — skip uploading flists to S3
• --strip / --no-strip — strip debug symbols (default: on)
• --upx — UPX compress binaries after stripping

Role in the stack

mos_runtimes is the runtime composition layer for MyceliumOS. It works with mos_config (environment configs) and myfs (flist packing/unpacking) to deliver runtime components to nodes after boot. The consumer side (mos-runtime-fetch.sh in the initramfs) downloads and unpacks the produced flists, routing files to their destination paths based on filename suffixes.

This decouples runtime components (mycelium, youki, my_hypervisor, hero_compute, hero_proc) from the boot image, allowing independent versioning and per-environment customization.

Relation to ThreeFold

This technology is used within the ThreeFold ecosystem and was first deployed on the ThreeFold Grid. The component itself is designed as reusable infrastructure technology and should be understood by its technical function first, independent of any specific deployment.

Ownership

This repository is owned and maintained by TF-Tech NV, a Belgian company responsible for the development and maintenance of this technology.

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.