Installation
Verify release files, prepare x86_64 USB installation media, identify the disk, and install manually; includes ARM64 QEMU boot instructions.
On this page
Choose release files
This guide covers the OpenXTOS v1.0.2 source release (commit c24e923717670c4724cdaf24c7c105caee8dc2fb) and the downloadable v1.0.2 binary prerelease. v1.0.2 provides the x86_64 installer ISO, ARM64 QEMU bundle, per-architecture corresponding source, and SHA256SUMS.txt; the installation and QEMU steps below use these v1.0.2 binaries, with source building covered in the system documentation.
| File | Version and purpose |
|---|---|
| v1.0.2 source ZIP / tar.gz | GitHub-generated project source archives for the tag; not a substitute for the third-party corresponding-source packages required for the binaries. |
| openxtos-v1.0.2-x86_64-installer.iso | v1.0.2 x86_64 BIOS/UEFI installer ISO. |
| openxtos-v1.0.2-arm64.tar.gz | v1.0.2 ARM64 QEMU virt boot bundle; not a universal ARM board installer. |
| RISC-V64 | Source-build and QEMU verification paths exist; no image is currently published. |
Download and verify
Download the v1.0.2 ISO, matching corresponding source, and checksum list into an empty directory. Requires curl, CA certificates, and sha256sum; this does not checksum GitHub’s automatically generated project source archives.
set -eu
mkdir -p "$HOME/openxtos-v102"
cd "$HOME/openxtos-v102"
curl --fail --location --show-error -O 'https://github.com/Aitaide/OpenXTOS/releases/download/v1.0.2/openxtos-v1.0.2-x86_64-installer.iso'
curl --fail --location --show-error -O 'https://github.com/Aitaide/OpenXTOS/releases/download/v1.0.2/openxtos-v1.0.2-x86_64-corresponding-source.tar.gz'
curl --fail --location --show-error -O 'https://github.com/Aitaide/OpenXTOS/releases/download/v1.0.2/SHA256SUMS.txt'
sha256sum --check --ignore-missing SHA256SUMS.txtThe v1.0.2 ISO SHA-256 is 589bf33ed91b3db27c25f987f2b7508a5e97ad3f1fa6653938be69ef43b4a68c. Stop on a mismatch; do not flash.
Prepare USB and boot
The USB installation steps below apply to the v1.0.2 x86_64 ISO, not the v1.0.2 source archives.
- Use an expendable USB drive. Obtain Rufus, balenaEtcher, or an equivalent raw-image writer from a trusted source. Do not merely copy the ISO file into the USB filesystem.
- Select the verified ISO, then confirm the chosen USB model and capacity. Select DD mode in Rufus, or raw-image writing in another tool. Confirm again that the selected device is not the host system disk.
- Safely eject the USB. Disable Secure Boot on the target x86_64 machine, then select the USB BIOS or UEFI boot entry. Secure Boot is unsupported.
- In GRUB select OpenXTOS installer (manual installation). A local VGA console and ttyS0 at 115200 baud are available. Boot reaches a shell without automatic installation or disk writes.
The installation target is an internal disk in the target machine, not the USB just written. If boot fails, check ISO hash, raw-write mode, architecture, BIOS/UEFI selection, and Secure Boot state first. Preserve screen or serial errors rather than trying unknown disks.
Identify the target whole disk
Run these commands only in the target machine’s XTOS installer console. List all disks, then identify the target by actual model, complete serial, and exact byte capacity. Device names can change; /dev/nvme0n1 is an example, not a safe default.
lsblk -o NAME,MODEL,SERIAL,SIZE,TYPE,MOUNTPOINTS
lsblk -dn -o SERIAL /dev/nvme0n1
blockdev --getsize64 /dev/nvme0n1
cat /proc/cmdlineThe installer accepts actual /dev/nvme…n… or /dev/sd… whole-disk paths, not aliases or partitions. It requires at least 2 GiB, removable=0, a nonempty exactly matching serial, and exact byte capacity. Mounted disks or partitions, active swap, holders, and identity mismatches are refused. The boot command line must include xtos.installer=1. Identity is checked again before the first write, and payload hashes are checked.
Install manually
xtos-install /dev/nvme0n1 'EXACT-SERIAL' EXACT-BYTES ERASE-XTOSArguments are whole-disk path, serial, byte capacity, and confirmation token. The installer creates a GPT with a BIOS boot area, FAT32 EFI partition, and ext4 root, installs BIOS/UEFI GRUB, and copies the system. Wait for the standalone XTOS_INSTALL=PASS line. An interruption or error is not completion; do not immediately rerun the erase command.
sync
poweroff -fFirst boot and persistence
Remove USB and boot the installed disk. Expect XTOS baremetal system and XTOS_READY=1. The root filesystem mounts ext4 by the UUID in xtos.root and uses switch_root. Installer USB and ordinary QEMU initramfs sessions instead run in memory; their changes are not automatically saved to the installed disk or host.
uname -r
/usr/bin/xtos-rt-status
cat /proc/cmdline
cat /proc/mounts
xtos-selftestxtos-selftest must return 0 for that software check to pass; XTOS_READY=1 is only a readiness marker. To check persistence, first confirm the installed ext4 root, create your own record under /root with a new unused filename, sync and reboot, then inspect and remove it. A file in installer RAM does not prove disk persistence.
This is not an encrypted-disk, Secure Boot, production-update, or complete account-management solution. Storage, networking, IRQs, load, latency, and BCI devices require separate acceptance on target hardware.
Recovery and failures
Keep the verified USB and backups. On installation or installed-system boot failure, save errors and serial logs first; a failure is not permission to erase again. The second USB GRUB entry, OpenXTOS recovery (installation disabled), omits xtos.installer=1 and opens a recovery console where xtos-install refuses to run.
- XTOS_ROOT=FAIL can mean fallback to a RAM recovery root. Inspect /proc/cmdline, lsblk, and blkid, and compare root UUID and partitions. /root in that shell is not necessarily installed-disk data.
- Reidentify the disk before inspection and prefer read-only mounting; ext4 read-only inspection also needs consideration of noload to avoid journal replay. Copy important data first; do not repair a mounted filesystem.
- On installer refusal, inspect serial, exact bytes, whole disk versus partition, mounts, swap, and holders. Correct the actual cause without bypassing identity checks or forcing formatting.
- For SSH failure, locally check whether authorized_keys is on the installed root, the Dropbear startup condition, addresses, and DHCP. The default empty authorization file does not expose remote root access.
ARM64 QEMU boot bundle
The QEMU commands below run the v1.0.2 ARM64 bundle and validate software behavior in a virtual machine, not compatibility with physical ARM boards.
On Ubuntu 24, install qemu-system-arm and ipxe-qemu first; the latter provides efi-virtio.rom for the default virtual network card. On other distributions, confirm QEMU and the ROM are available through the package manager.
set -eu
curl --fail --location --show-error -O 'https://github.com/Aitaide/OpenXTOS/releases/download/v1.0.2/openxtos-v1.0.2-arm64.tar.gz'
curl --fail --location --show-error -O 'https://github.com/Aitaide/OpenXTOS/releases/download/v1.0.2/openxtos-v1.0.2-arm64-corresponding-source.tar.gz'
curl --fail --location --show-error -O 'https://github.com/Aitaide/OpenXTOS/releases/download/v1.0.2/SHA256SUMS.txt'
sha256sum --check --ignore-missing SHA256SUMS.txt
test ! -e arm64
tar -xzf 'openxtos-v1.0.2-arm64.tar.gz'
qemu-system-aarch64 -machine virt -cpu cortex-a57 -m 2G -smp 2 \
-kernel arm64/Image -initrd arm64/initramfs-arm64.cpio.gz \
-append 'console=ttyAMA0 panic=1' -nographicuname -m
uname -r
/usr/bin/xtos-rt-status
/bin/test_rt
/bin/test_spsc
/bin/test_signal
poweroff -fExit QEMU with Ctrl+a followed by x if needed. The bundle includes Image, initramfs, DTBs, resolved kernel.config, and notices. Its ordinary initramfs root is RAM-backed; data not saved externally is lost on shutdown. This is not a universal ARM board installer. Physical boot needs matching firmware, device tree, storage/peripheral drivers, and independent hardware validation; this QEMU command is not a board-flashing procedure.
Update and application tools
The following describes update and pkg app in the public source. The public v1.0.2 installer ISO and ARM64 QEMU bundle do not include these tools; Live builds that include them use a separate build path. Check in the target XTOS console first, not through similarly named commands on a general Linux host.
command -v update
command -v pkgCheck and download updates
Run in an XTOS environment that includes update. It needs networking, a trustworthy clock, the image-pinned /usr/share/xtos/repo-public.pem key, CA certificates, and enough space for downloads. It tries configured mirrors in order, verifies the Ed25519 signature on release-index.json, then compares the version in /etc/xtos-release.
update checkcheck returns 0 when no update is needed, 1 when an update is available, and 2 on error. The mirror-maintained index can lag behind GitHub Releases; the website release version does not establish index synchronization. Stop on mirror, signature, or index errors rather than bypassing verification.
update download --dest /xtos/downloaddownload fetches files for the current architecture, checks sizes and SHA256 hashes, and creates download-manifest.json. It does not install automatically or replace the running root filesystem. Download completion is not upgrade completion. Back up an installed system, boot verified new installation media, then follow this page’s installation procedure.
In the source, update apply --from DIR --to DEV --confirm ERASE-XTOS re-authenticates the trusted index and files, then writes the installer image to a spare whole-disk medium; it is not an in-place upgrade of the running root filesystem. update recover takes the same arguments and re-authenticates and fully rewrites a spare medium with a matching interruption journal. There is no automatic rollback guarantee. Both erase the target: back it up and confirm it is unmounted and not the running medium. These tools are absent from the current core bundles.
Install and verify applications
Use only in an environment containing XTOS pkg. Obtain a real xpkg from a trusted publisher and check its name, version, and architecture. Replace the example demo.xpkg with the actual file and demo with the application name from its manifest. Installation needs write permission on the destination, normally /opt/xtos-apps/<name>/<version>/.
pkg app install demo.xpkg
pkg app list
pkg app verify demoDefault installation checks archive paths, manifest file coverage, per-file sizes, and SHA256 hashes. It activates the application directory and updates the registry only after those checks. Applications are separate from the image-based system base. Matching hashes establish consistency with the manifest, not publisher identity.
pkg app install demo.xpkg --pubkey /path/to/vendor-public.pemOn installation or verify failure, stop using the package, retain the error, and contact its publisher. Do not remove checks to force installation. Directory separation is not a process sandbox and does not guarantee removal of data an application writes elsewhere.
Sources and trust
The release index, system-build repository, and application packages verify different objects. release-index.json and its .sig define the versions and files seen by update. The userspace repository uses manifest.json, SHA256SUMS, and their signatures for builds. xpkg uses its own manifest and an optional vendor signature. These are not interchangeable.
The source endpoints are https://packages.xtos.cn/ and https://packages.xtos.si/. Reachability, caching, and mirror selection do not replace verification with a pinned key. Check actual mirror availability and indexed versions. A published public.pem can be compared with a trusted key; fetching it from the same location as a file does not establish trust.
Reject indexes that fail signature verification and files whose SHA256 differs from a trusted manifest. For GitHub release attachments, use the SHA256SUMS.txt procedure above; checksums are not independent signature authentication.
Source and redistribution
Corresponding-source archives match the binaries by architecture and include project-tag source plus matching package source, inventories, and notices for embedded host tools or static runtimes. GitHub’s automatically generated project source archive alone does not cover every third-party binary embedded in the ISO. The x86 ISO /usr/share/doc/openxtos/ and ARM64 bundle notices/ retain project licenses, NOTICE, package inventories, and third-party notices.
Images use fixed source c24e923717670c4724cdaf24c7c105caee8dc2fb and packaging recipe 110048c955c71a0701f5eee04351ab7a4903b0f6. The x86_64 installer fixes UEFI loader generation, and the Cyton diagnostic tool adds read-length checks. Corresponding source includes this recipe and its patches. Core images and the homepage developer Live candidate are identified separately.
When redistributing, retain matching corresponding source, build/install scripts, configuration, patches, licenses, copyright, and modification notices, and meet each component’s Apache-2.0/GPL-2.0 obligations. A link or logo is not a substitute for corresponding source; changed binaries need source matching those changes.