> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/redox-os/redox/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  **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](/installation).
</Info>

## What is Redox OS?

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

<CardGroup cols={2}>
  <Card title="Memory Safe" icon="shield">
    Written entirely in Rust for memory safety
  </Card>

  <Card title="Microkernel" icon="cube">
    Fault isolation and improved security
  </Card>

  <Card title="POSIX Compatible" icon="terminal">
    Run Linux and BSD programs
  </Card>

  <Card title="Modern Tooling" icon="hammer">
    Comprehensive build system with Podman
  </Card>
</CardGroup>

## 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:

<Tabs>
  <Tab title="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
  </Tab>

  <Tab title="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
  </Tab>
</Tabs>

## Quick Start: Podman Build

<Steps>
  <Step title="Install Podman">
    Install Podman on your system:

    <CodeGroup>
      ```bash Ubuntu/Debian theme={null}
      sudo apt install podman
      ```

      ```bash Fedora theme={null}
      sudo dnf install podman
      ```

      ```bash Arch theme={null}
      sudo pacman -S podman
      ```

      ```bash macOS theme={null}
      brew install podman
      podman machine init
      podman machine start
      ```
    </CodeGroup>
  </Step>

  <Step title="Download and Run Bootstrap Script">
    Download the Podman bootstrap script and run it:

    ```bash theme={null}
    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
    ```

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Navigate to Redox Directory">
    ```bash theme={null}
    cd redox
    ```
  </Step>

  <Step title="Build Redox">
    Build a complete Redox OS image:

    ```bash theme={null}
    make all
    ```

    <Warning>
      On systems without SELinux (like Ubuntu), use:

      ```bash theme={null}
      make all USE_SELINUX=0
      ```
    </Warning>

    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
  </Step>

  <Step title="Run Redox in QEMU">
    Once the build completes, start Redox in QEMU:

    ```bash theme={null}
    make qemu
    ```

    <Tip>
      For KVM acceleration (much faster), use:

      ```bash theme={null}
      make qemu kvm=yes
      ```
    </Tip>

    You should see Redox boot and reach the Orbital desktop environment!
  </Step>
</Steps>

## Build Configuration

You can customize your build with different configurations:

<Tabs>
  <Tab title="Desktop (Default)">
    Full desktop environment with COSMIC apps:

    ```bash theme={null}
    make all CONFIG_NAME=x86_64/desktop
    ```
  </Tab>

  <Tab title="Server">
    Minimal server configuration:

    ```bash theme={null}
    make all CONFIG_NAME=x86_64/server
    ```
  </Tab>

  <Tab title="Demo">
    Demo configuration with example programs:

    ```bash theme={null}
    make all CONFIG_NAME=x86_64/demo
    ```
  </Tab>

  <Tab title="Minimal">
    Absolute minimum bootable system:

    ```bash theme={null}
    make all CONFIG_NAME=x86_64/minimal
    ```
  </Tab>
</Tabs>

## Architecture Support

Build for different CPU architectures:

<CodeGroup>
  ```bash x86_64 (Default) theme={null}
  make all ARCH=x86_64
  ```

  ```bash ARM64 (Raspberry Pi) theme={null}
  make all ARCH=aarch64 CONFIG_NAME=aarch64/raspi3bp/minimal
  ```

  ```bash i586 (32-bit x86) theme={null}
  make all ARCH=i586
  ```

  ```bash RISC-V theme={null}
  make all ARCH=riscv64gc
  ```
</CodeGroup>

## 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      |

<Accordion title="View all make targets">
  See the complete [Make Commands Reference](/reference/make-commands) for all available targets and options.
</Accordion>

## Next Steps

<CardGroup cols={2}>
  <Card title="Explore the Architecture" icon="diagram-project" href="/architecture/overview">
    Learn about Redox's microkernel design
  </Card>

  <Card title="Build System Details" icon="hammer" href="/build-system/overview">
    Understand the build system in depth
  </Card>

  <Card title="Start Contributing" icon="code-pull-request" href="/development/contributing">
    Join the Redox development community
  </Card>

  <Card title="Hardware Compatibility" icon="microchip" href="/hardware/compatibility">
    Check if your hardware is supported
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Build fails with 'Permission denied'">
    On non-SELinux systems, make sure to use:

    ```bash theme={null}
    make all USE_SELINUX=0
    ```
  </Accordion>

  <Accordion title="QEMU shows black screen">
    Try using software rendering:

    ```bash theme={null}
    make qemu vga=no
    ```
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="Container build fails">
    Clean the container and rebuild:

    ```bash theme={null}
    make container_clean
    bash podman_bootstrap.sh
    ```
  </Accordion>
</AccordionGroup>

## Getting Help

<Card title="Need Help?" icon="life-ring">
  * **Chat**: Join our [Matrix](https://matrix.to/#/#redox-join:matrix.org) or [Discord](https://discord.gg/JfggvrHGDY)
  * **Issues**: File issues on [GitLab](https://gitlab.redox-os.org/redox-os/redox)
  * **Documentation**: See the [Troubleshooting Guide](/reference/troubleshooting)
  * **FAQ**: Check the [Frequently Asked Questions](/reference/faq)
</Card>