Quickstart Guide

Get Portix OS up and running on your system in just a few minutes. This guide walks you through installing prerequisites, building the kernel, and running it in QEMU.

Prerequisites

Before building Portix, ensure you have the following tools installed on your system:

Required Tools

Install Rust Nightly

Portix uses unstable Rust features that require the nightly toolchain.

# Install Rust if you haven't already
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install nightly toolchain
rustup toolchain install nightly

# Add rust-src component for core library
rustup component add rust-src --toolchain nightly

The rust-src component is required because Portix compiles its own core and alloc libraries for the bare-metal target.

Install NASM

NASM is required to assemble the bootloader and interrupt service routines.

sudo apt-get update
sudo apt-get install nasm

Install Python 3

Python 3 is used by the build scripts.

sudo apt-get install python3

Install QEMU

QEMU is used to test and run the operating system in a virtual environment.

sudo apt-get install qemu-system-x86

Install LLVM Binutils (objcopy)

Required for binary manipulation during the build process.

sudo apt-get install llvm binutils
# Or for cross-compilation:
sudo apt-get install mingw-w64

Optional Tools

These tools are optional but provide additional functionality:

xorriso or genisoimage: For creating proper ISO9660 CD-ROM images with El Torito boot
qemu-img: For generating VDI and VMDK disk formats
pycdlib: Python library for ISO generation (pip install pycdlib)

Without xorriso, genisoimage, or pycdlib, the build script will create a raw disk copy as the ISO file, which won’t work as a CD-ROM in some virtualization software.

Building Portix OS

Clone the Repository

git clone https://github.com/yourusername/portix-os.git
cd portix-os

Run the Build Script

The build script handles everything: assembling the bootloader, compiling the kernel, and creating disk images.

python scripts/build.py

This command will:

Verify all required tools are installed
Assemble boot.asm (Stage 1 bootloader)
Compile the Rust kernel with custom target
Assemble stage2.asm (Stage 2 loader)
Create a raw disk image (portix.img)
Generate ISO, VDI, and VMDK formats
Automatically launch QEMU

The build process uses Rust’s -Z build-std flag to compile core and alloc from source for the bare-metal target.

Build Output

After a successful build, you’ll see output similar to:

╔══════════════════════════════════════════════════╗
║         PORTIX BUILD SYSTEM  v4.4                ║
║  Genera: IMG · ISO · VDI · VMDK · SIM            ║
╚══════════════════════════════════════════════════╝

[OK]    boot.bin — 512 bytes
[OK]    isr.o — 2048 bytes
[OK]    kernel.bin — 245760 bytes → 481 sectores
[OK]    stage2.bin — 32768 bytes (64 sectores)
[OK]    portix.img — 8.0 MB
[OK]    dist/portix.iso — 8.5 MB
[OK]    dist/portix.vdi — 8.2 MB
[OK]    dist/portix.vmdk — 8.1 MB

All generated files are located in:

build/ - Intermediate build artifacts
build/dist/ - Final distribution images

Running Portix OS

Quick Start with QEMU

If you ran python scripts/build.py without the --no-run flag, QEMU will launch automatically after building. Otherwise, you can run Portix manually:

Raw Disk Mode
ISO CD-ROM Mode
VMDK Mode
Ventoy Simulation Mode

Boot from the raw disk image (default mode):

python scripts/build.py --mode=raw

This boots Portix as an IDE hard disk in QEMU.

Boot from the ISO image:

python scripts/build.py --mode=iso

If you have xorriso, genisoimage, or pycdlib installed, the ISO will be a proper CD-ROM image with El Torito booting. Otherwise, it will boot as a raw disk.

Generate and boot from VMDK format:

python scripts/build.py --mode=vmdk

Test Portix in a Ventoy-like environment with offset boot:

python scripts/build.py --mode=ventoy-sim

Build Script Options

The build.py script supports several command-line options:

Option	Description
`--mode=<mode>`	Specify boot mode: `raw`, `iso`, `vmdk`, `vmi`, `ventoy-sim`
`--no-run`	Build without launching QEMU
`--no-iso`	Skip ISO generation
`--no-vm`	Skip VDI/VMDK generation
`--clean`	Clean all build artifacts

python scripts/build.py --no-run

What to Expect When It Boots

When Portix successfully boots, you’ll see:

Boot Sequence

The boot process transitions through:

Stage 1 loads Stage 2 from disk
Stage 2 sets up Long Mode and loads the kernel
Kernel initializes hardware and enters the main loop

System Tab (F1)

The default view shows:

CPU information (brand, cores, features)
Memory information

Boot status with green checkmarks:

✓  OK   Modo largo (64-bit) activo
✓  OK   GDT + TSS cargados
✓  OK   IDT configurada (0-19 + IRQ)
✓  OK   PIC remapeado, IRQ0 habilitado
✓  OK   PIT @ 100 Hz
✓  OK   Teclado PS/2 inicializado
✓  OK   Ratón PS/2 inicializado
✓  OK   Escaneo de discos ATA completo
✓  OK   Framebuffer VESA activo

Terminal Tab (F2)

An interactive terminal with commands:

ayuda - Show available commands
system - Display system information
cpu - Show CPU details
disk - List disk partitions
pci - Show PCI devices
clear - Clear terminal
edit <filename> - Open text editor

PORTIX v0.7.4  Kernel Bare-Metal
Escribe 'ayuda' para comandos.

>

Interactive UI

Portix includes:

Mouse support: PS/2 mouse with cursor rendering
Keyboard input: Full keyboard support with modifiers
Tab navigation: F1-F5 or click tabs to switch views
File Explorer (F5): Browse FAT32 file system
IDE (F4): Built-in code editor with syntax highlighting

Keyboard Shortcuts

Key	Action
F1	System information
F2	Terminal
F3	Devices (PCI, ACPI)
F4	IDE (code editor)
F5	File Explorer
Tab	Cycle through tabs
Esc	Close menus / Clear terminal
PgUp/PgDn	Scroll terminal history
Home/End	Jump to top/bottom of terminal

Mouse Controls

Left Click: Select, interact with UI elements
Right Click: Context menus (in Explorer)
Scroll Wheel: Scroll terminal history
Drag: Move scrollbars

Running in VirtualBox

To run Portix in VirtualBox:

Create a New VM

Open VirtualBox
Click “New” to create a virtual machine
Name: “Portix OS”
Type: Other
Version: Other/Unknown (64-bit)

Configure VM Settings

Memory: At least 256 MB
Hard disk: Use existing - select build/dist/portix.vdi
System → Motherboard → Enable “IO APIC”
System → Processor → 1 CPU (more if available)
Display → Video Memory → 16 MB minimum

Boot the VM

Start the VM. It should boot directly into Portix OS.

If using the ISO file with xorriso/pycdlib, add it as a CD-ROM drive in Storage settings.

Running on Real Hardware

Running Portix on real hardware is experimental and may not work on all systems. Always test in a VM first.

To run Portix on real hardware:

Prepare USB Drive

Write the raw image to a USB drive:

sudo dd if=build/dist/portix.img of=/dev/sdX bs=4M status=progress
sudo sync

Replace /dev/sdX or /dev/diskX with your actual USB device. This will erase all data on the drive!

Configure BIOS

Boot into your system’s BIOS/UEFI settings (usually F2, Del, or F12)
Disable Secure Boot (Portix uses BIOS Legacy mode)
Set boot order to boot from USB first
Save and exit

Boot from USB

Insert the USB drive and restart your computer. If configured correctly, Portix should boot.

Troubleshooting

Build Errors

Error: nasm not found

Install NASM using your package manager (see Prerequisites section).

Error: objcopy not found

Install binutils or mingw-w64 packages:

# Ubuntu/Debian
sudo apt-get install mingw-w64-x86-64-binutils

# Arch Linux
sudo pacman -S binutils

Error: rust-src component missing

rustup component add rust-src --toolchain nightly

Kernel panic or boot failure

Check the serial log for detailed error messages:

cat build/logs/serial.log

Debug logs are also available:

cat build/logs/debug.log

Runtime Issues

Black screen in QEMU

This may indicate a boot failure. Check:

QEMU is using the correct boot mode
The disk image was built successfully
Review build/logs/serial.log for errors

Keyboard not responding

PS/2 keyboard initialization may have failed. This is common in some VM configurations. Try:

Restarting the VM
Checking QEMU version (older versions may have PS/2 issues)

No graphics / VGA text mode

Portix requires VESA framebuffer support. Ensure:

QEMU is using -vga std (default in build script)
VirtualBox has sufficient video memory allocated

Next Steps

Now that you have Portix running:

Explore the Terminal

Try commands like system, cpu, disk, and pci to explore your system

Write Some Code

Press F4 to open the IDE and create text files

Browse Files

Press F5 to explore the FAT32 file system

Contribute

Learn how to contribute to Portix OS development

Additional Resources

Build Logs: Check build/logs/build.log for detailed build information
Serial Output: Debug kernel messages in build/logs/serial.log
QEMU Debug: Hardware-level debug info in build/logs/debug.log

Having issues? Check the serial log first - it contains detailed kernel-level debug output that can help diagnose problems.

Congratulations! You’ve successfully built and run Portix OS. Explore the system, try different commands, and see what this bare-metal kernel can do.

Get Started

Architecture

Core Components

Development

Quickstart

Quickstart Guide

Prerequisites

Required Tools

Optional Tools

Building Portix OS

Running Portix OS

Quick Start with QEMU

Build Script Options

What to Expect When It Boots

Navigation

Keyboard Shortcuts

Mouse Controls

Running in VirtualBox

Running on Real Hardware

Troubleshooting

Build Errors

Runtime Issues

Next Steps

Explore the Terminal

Write Some Code

Browse Files

Contribute

Additional Resources

Build docs developers (and LLMs) love

Get Started

Architecture

Core Components

Development

​Quickstart Guide

​Prerequisites

​Required Tools

​Optional Tools

​Building Portix OS

​Running Portix OS

​Quick Start with QEMU

​Build Script Options

​What to Expect When It Boots

​Navigation

​Keyboard Shortcuts

​Mouse Controls

​Running in VirtualBox

​Running on Real Hardware

​Troubleshooting

​Build Errors

​Runtime Issues

​Next Steps

Explore the Terminal

Write Some Code

Browse Files

Contribute

​Additional Resources

Build docs developers (and LLMs) love

Quickstart Guide

Prerequisites

Required Tools

Optional Tools

Building Portix OS

Running Portix OS

Quick Start with QEMU

Build Script Options

What to Expect When It Boots

Navigation

Keyboard Shortcuts

Mouse Controls

Running in VirtualBox

Running on Real Hardware

Troubleshooting

Build Errors

Runtime Issues

Next Steps

Additional Resources