Skip to main content
Version: v0.4

How to Install huronOS


huronOS is still in a Work in Progress state, and many of the features that are usually expected from the installer of a distribution are not currently available.

Currently, the huronOS installer only works on GNU / Linux distributions. It has not been tested on other Unix-Like operating systems like macOS, BSD nor utilities like WSL.

Currently, it is not possible to burn the ISO image directly into the USB and have a working instance of huronOS due to unique features of the system that require a special installation method.

Currently, huronOS is not capable of working without a directives file. This file needs to live in the network and be accessible using the http or https URL schemes.


  • A working GNU / Linux distro to install the system from.
  • A USB device to install the system on (You will lose all your data so back it up).
  • Installed dependencies (see dependencies for your distribution).
  • A directives file accessible from the network that will be using huronOS. Please check the introduction to directives doc for guidance on setting up this file.


  • On Debian:
    apt install squashfs-tools parted psmisc e2fsprogs dosfstools perl-base
  • On Ubuntu:
    apt install squashfs-tools parted psmisc e2fsprogs dosfstools perl-base
  • On Fedora:
    dnf install squashfs-tools parted psmisc e2fsprogs dosfstools perl-base
  • On Arch Linux:
    pacman -S install squashfs-tools parted psmisc e2fsprogs dosfstools perl


  1. Get huronOS' ISO.
    You can either build the ISO by yourself or download it from the huronOS mirrors.
    In this case, we will suppose that we've already downloaded the ISO file huronOS-b2023.b0023-amd64.iso

  2. Mount the ISO.
    Create a directory where you will access the contents of the ISO, for example /media/iso.
    Mount the ISO on this directory:

    mount ./huronOS-b2023.b0023-amd64.iso /media/iso
  3. Prepare your system for the installation.
    Go to your ISO mounted directory, and you will find a directory structure like this:

    ├── boot
    ├── checksums
    ├── EFI
    ├── huronOS
    └── utils

    Mask your current automount tool. The installer will partition your USB, so automounter utilities can interfere with the installer. Please mask your automounter tool while using the installer. Eg. systemctl mask udisks2

  4. Upload your directives file
    huronOS requires a directives file to sync with, so upload your file to a server that makes it accessible to huronOS. This can be on the internet, on your intranet, on your local area network, on your own hosting server or even on github (by accessing raw contents).

    Note: This URL will need the creation of an exception on huronOS' firewall to the IP address of the server which is hosting this file. Not doing so would result in a soft-lock of the system, thus not being able to sync anymore.

    Please, test the access to this file from the network in which you will be using huronOS. Some WANs might have an external firewall blocking the access to your file, resulting in huronOS not being able to keep synchronizing.

  5. Install huronOS.

    1. You'll need a 16GiB+ USB drive, at least, for better performance. Please connect this USB drive; and be aware: you will lose all data on it, for the installation.

    2. Execute the installer, chose one of this options:

      • Passing all the configurations in one go

        ./ --directives-url --directives-server-ip --root-password toor --instance-ip-address --instance-ip-mask 24 --instance-ip-gateway
      • Fill the prompts:

        1. Write the directives url to sync with, please paste the URL you previously set up. If you don't have one, just leave it blank (be aware that sync won't work), this can be changed after the installation in the (HURONOS/data/configs/sync-server.conf file of the huronOS usb).
        2. Write the directives server IP to force the firewall exception to this specific server. You can leave it blank if you want to fallback to DNS resolution.
        3. Write the root password to set a root password (if left blank toor would be the default password)3. Write the ip configuration containing
        4. Write the ip configuration containing
          • Instance IP address: The ip of that particular huronOS instance
          • Instance IP mask: The mask of the instance ip address as a number, ex: 8, 16, 24
          • Instance IP gateway: The gateway of the network
    3. The installer will prompt you to select a disk to target the installation. Please do this carefully as the selected disk will be completely erased.

    4. Wait for the installer to finish and disconnect the USB drive. If something fails during the installation process, please retry.

  6. Boot from huronOS.
    Connect your USB drive and boot from it. You will be auto-logged on the contestant user. To access the root user, please check the documentation.

    Note: Booting will require enabling boot from USB devices. On UEFI boot, Secure Boot needs to be disabled.

    Note: If the computer has Windows installed, make sure to fully shutdown the computer as the Windows Fast Startup can prevent the computer from booting on other disks.

  7. Select the boot option.
    By default, huronOS will boot automatically on the Start contest system option after 7 seconds. Most of the times, this is what you want to use. Please refer to the boot options documentation for guidance on all the boot options.

Wohoo!, You have now installed huronOS!
We know, there's a lot of stuff to be improved, but you can help improving this project by contributing! Try the system, use it on your own community, organize your own contests. You will find out how much time huronOS can save you to setup competitive programming competitions. Then, if you find this distro to help your community, contribute to it!, It's best for all to focus our efforts in one big definitive solution for the environment of our contests rather than creating lot of small solutions!

Thank you :)