Quick Start

Get started building Redox OS in minutes

Quick Start Guide

Get Redox OS up and running quickly on your system. This guide will walk you through building a Redox OS image using the recommended Podman build method.

New to Redox? This quick start focuses on getting you a working Redox image fast. For detailed installation and build options, see the Installation Guide.

What is Redox OS?

Redox is a Unix-like operating system written in Rust with a microkernel design. Key features include:

Memory Safe

Written entirely in Rust for memory safety

Microkernel

Fault isolation and improved security

POSIX Compatible

Run Linux and BSD programs

Modern Tooling

Comprehensive build system with Podman

Prerequisites

Before building Redox, ensure you have:

• Linux, macOS, or BSD system (Windows via WSL2)
• At least 8 GB RAM (16 GB recommended)
• 30-60 GB free disk space
• Reliable internet connection for downloading dependencies
• Podman or Docker (Podman recommended)

Build Methods

Redox supports two build methods:

Podman (Recommended)

Podman build uses containers for a consistent build environment:

• ✅ Isolated from host system
• ✅ Consistent dependencies
• ✅ Works on any Linux distro
• ✅ No need to install build dependencies

Best for: Most users, especially beginners

Native

Native build uses your host system directly:

• ✅ Faster builds (no container overhead)
• ✅ Direct access to build artifacts
• ✅ Better for active development
• ⚠️ Requires manual dependency installation

Best for: Advanced users, active developers

Quick Start: Podman Build

1. Install Podman

   Install Podman on your system:

   Ubuntu/Debian

   sudo apt install podman
   
2. Download and Run Bootstrap Script

   Download the Podman bootstrap script and run it:

   curl -sf https://gitlab.redox-os.org/redox-os/redox/raw/master/podman_bootstrap.sh -o podman_bootstrap.sh
   time bash -e podman_bootstrap.sh
   

   The bootstrap script will:

   • Clone the Redox repository
   • Build a Podman container with all dependencies
   • Set up the build environment

   This takes 5-15 minutes depending on your internet connection.

3. Navigate to Redox Directory

   cd redox
   
4. Build Redox

   Build a complete Redox OS image:

   make all
   

   On systems without SELinux (like Ubuntu), use:

   make all USE_SELINUX=0
   

   The build process takes 30-90 minutes depending on your hardware. It will:

   • Download and compile all packages
   • Build the kernel and userspace
   • Create a bootable disk image
5. Run Redox in QEMU

   Once the build completes, start Redox in QEMU:

   make qemu
   

   For KVM acceleration (much faster), use:

   make qemu kvm=yes
   

   You should see Redox boot and reach the Orbital desktop environment!

Build Configuration

You can customize your build with different configurations:

Desktop (Default)

Full desktop environment with COSMIC apps:

make all CONFIG_NAME=x86_64/desktop

Server

Minimal server configuration:

make all CONFIG_NAME=x86_64/server

Demo

Demo configuration with example programs:

make all CONFIG_NAME=x86_64/demo

Minimal

Absolute minimum bootable system:

make all CONFIG_NAME=x86_64/minimal

Architecture Support

Build for different CPU architectures:

x86_64 (Default)

make all ARCH=x86_64

Common Make Targets

Here are the most useful make commands:

Command	Description
make all	Build complete OS image
make live	Build live ISO image
make qemu	Run in QEMU emulator
make mount	Mount the filesystem for inspection
make clean	Clean build artifacts
make rebuild	Clean and rebuild from scratch

View all make targets

See the complete Make Commands Reference for all available targets and options.

Next Steps

Explore the Architecture

Learn about Redox’s microkernel design

Build System Details

Understand the build system in depth

Start Contributing

Join the Redox development community

Hardware Compatibility

Check if your hardware is supported

Troubleshooting

Build fails with 'Permission denied'

On non-SELinux systems, make sure to use:

make all USE_SELINUX=0

QEMU shows black screen

Try using software rendering:

make qemu vga=no

Build is very slow

• Enable KVM if on Linux: make qemu kvm=yes
• Use a native build instead of Podman for faster iteration
• Ensure you have enough RAM (16 GB recommended)

Container build fails

Clean the container and rebuild:

make container_clean
bash podman_bootstrap.sh

Getting Help

Need Help?

• Chat: Join our Matrix or Discord
• Issues: File issues on GitLab
• Documentation: See the Troubleshooting Guide
• FAQ: Check the Frequently Asked Questions