Merged
Conversation
- Added a read-only 'virtio-blk' implementation for presenting OCI rootfs as a block device ('/dev/vda') on Linux/KVM.
- Refined 9pfs 'Twalk' syscall behavior to handle symlink resolution securely and enforce container-root semantics for paths.
- Implemented 'Tstatfs' syscall for 9pfs to provide filesystem statistics.
- Updated documentation to reflect 'virtio-blk' architecture changes and fallback behaviors.
- Expanded kernel module support in guest-specific scripts, including virtio-blk and additional 9p modules.
dpsoft
changed the title
- Removed component-overview.excalidraw from the documentation. This diagram is no longer relevant or required.
There was a problem hiding this comment.
Pull request overview
This pull request introduces significant improvements to OCI rootfs handling in VoidBox, particularly for Linux/KVM platforms. The key change is adding support for using cached ext4 disk artifacts (attached as virtio-blk devices) for OCI base rootfs on Linux/KVM, while preserving the existing 9p/virtiofs mechanisms for skills and host mounts on both platforms.
Changes:
- Adds virtio-blk device implementation for OCI rootfs on Linux/KVM (
/dev/vdain guest) - Refactors OCI unpack to handle xattrs, special filesystem nodes, and hardlink fallbacks
- Implements disk caching and build infrastructure for ext4 artifacts
- Updates guest-agent to support block device mounting and improved pivot_root flow
- Adds comprehensive error context throughout OCI operations
- Updates documentation and test workflows for the new architecture
Reviewed changes
Copilot reviewed 31 out of 33 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| voidbox-oci/src/unpack.rs | Hardens OCI extraction with xattr/special-node handling, hardlink fallback, improved error messages |
| voidbox-oci/src/lib.rs | Adds error context wrapping for pull/unpack/mark operations |
| src/devices/virtio_blk.rs | New read-only virtio-blk MMIO device for OCI rootfs disk artifacts (400 lines) |
| src/devices/virtio_9p.rs | Adds symlink resolution, xattrwalk, statfs, and readlink support |
| src/devices/virtio_vsock*.rs | Implements timeout_secs=0 for service mode (no timeout) |
| src/vmm/mod.rs | Integrates virtio-blk device creation and MMIO registration |
| src/vmm/cpu.rs | Refactors IRQ injection, restricts device polling to vCPU0, adds edge-triggered tracking |
| src/vmm/config.rs | Adds oci_rootfs_dev and oci_rootfs_disk config fields with kernel cmdline generation |
| src/vmm/boot.rs | Improves initramfs placement with initrd_addr_max and early identity map constraints |
| src/runtime.rs | Implements OCI disk building/caching, platform-specific rootfs plan logic |
| guest-agent/src/main.rs | Major refactor: deferred OCI setup, block device mounting, improved pivot_root with switch-root fallback, enhanced error diagnostics |
| tests/oci_integration.rs | Adds block device tests, implements test disk building helper, updates paths for post-pivot execution |
| docs/*.md | Updates architecture documentation for platform-specific OCI transport |
| examples/openclaw/*.yaml | New OpenClaw smoke test and Telegram gateway workflows |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…alidation pipeline - Removed `examples/openclaw/openclaw_install_smoke.yaml`, as OpenClaw validation has been migrated to a new workflow. - Updated KVM tests to use shared `vm_preflight` module for better modularity and gate checks. - Simplified artifact validation logic in tests to defer to `vm_preflight`. - Refined error handling in various modules to improve clarity during validation skips/errors.
…peration - Replaced `Mutex<&str>` OCI setup status tracking with `AtomicU8` for improved concurrency and panic safety. - Introduced descriptive status codes and an `oci_status_str` function for converting codes to human-readable states. - Updated codebase to use atomic operations for setting and querying OCI setup state across threads. - Enhanced status-handling logic in runtime methods and error reporting paths. - Added documentation for debugging EPERM issues during OCI layer unpack in `AGENT.md`. - Expanded `stable_cache_key` function to use SHA256 for OCI disk cache keys and reduced minimum disk size in `build_oci_rootfs_disk`. - Increased symlink follow limit in 9pfs Twalk resolution to 20 for better compatibility with container filesystems.
… strategy in AGENT.md
…mentation - Introduced `openclaw_telegram_ollama.yaml` for running OpenClaw as a Telegram gateway with Ollama as the model backend. - Updated `AGENT.md` and `README.md` to provide instructions and environment prerequisites for the Ollama workflow. - Added production and validation scripts for the new gateway configuration. - Enhanced troubleshooting and monitoring sections to include Ollama-specific steps. - Expanded example workflows in `examples/README.md` to include the new Ollama integration.
- Added platform-specific details for OCI rootfs delivery, including macOS's virtiofs and Linux's virtio-blk approaches, in `AGENT.md`. - Updated defense-in-depth section to cover platform-specific read-only mechanisms for OCI rootfs. - Refined VZ backend comments to reflect virtiofs strategy for macOS. - Minor code cleanup with `#[allow(dead_code]` annotations in non-Linux test helpers.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces significant improvements to the documentation and build/test workflow for VoidBox, especially around guest image creation, OCI rootfs handling, and conformance validation. The changes clarify platform-specific requirements, document the differences between guest image scripts, and add a comprehensive operations guide for running and validating VM/OCI/OpenClaw workflows. Additionally, the README and CONTRIBUTING guides are updated for better clarity and coverage, and a new dependency is added for OCI disk cache key hashing.
Documentation and Operations Guide Enhancements:
docs/AGENT.mdfile providing an in-depth operational reference for running VoidBox with OCI images, including detailed explanations of the OCI root switch process, platform-specific behaviors (Linux/KVM vs. macOS/VZ), security strategies, test matrix, validation contract, and proper usage of guest image build scripts.CONTRIBUTING.mdwith platform-specific prerequisites, detailed instructions for building different guest images (build_guest_image.sh,build_claude_rootfs.sh,build_test_image.sh), and a matrix of when to use each. Also, the test section now covers both Linux and macOS flows, and clarifies the requirements for running VM/OCI/conformance suites. [1] [2] [3]README.mdto clarify the differences between guest image scripts, explain platform-specific OCI rootfs mounting (virtio-blk vs. virtiofs), and provide explicit instructions for production vs. test image usage—especially for OpenClaw gateway validation. Added references to new documentation and OpenClaw examples. [1] [2] [3] [4] [5]Build and CI Workflow Improvements:
.github/workflows/guest-image.ymlto usebuild_claude_rootfs.shwith theCLAUDE_CODE_VERSIONvariable, ensuring the correct native binary is included for production images.Dependency Updates:
sha2crate toCargo.tomlfor stable hashing of OCI disk cache keys, supporting robust caching of extracted OCI rootfs artifacts.General Maintenance:
CONTRIBUTING.mdroadmap, such as aarch64 and Windows/macOS support checkboxes, to reflect the current project focus.