instantOS: an Arch based system built around shell scripts

What the repository actually is

instantOS is described as an Arch based distro that works out of the box but is still aimed at power users, and the tagline in the readme is shorter: it works. Fast. Powerful.

The repository itself is not the distribution's documentation or its package tree. The readme says this repo contains utilities used all around instantOS, and points to the website for a proper readme. The repository info section narrows it further: this repository contains the instantutils sources and the live ISO build in the iso/ directory.

So the split is: a website for documentation, this repository for the code, and the ISO build for the artefact you actually install.

The top level listing shows the shape of it, and it is almost entirely shell. There is instantutils.sh, autostart.sh, monitor.sh, rootinstall.sh, userinstall.sh and repo.sh at the top level, along with directories for setup/, programs/, desktop/, config/, udev/, xorg/, manpages/, signing/, iso/, colab/. There is a Makefile, a justfile, a cliff.toml for the changelog, an offlineiso.md document, a docker-compose.yml and a docker-compose.tcg.yml, and a.devcontainer directory.

The primary language of the repository is Shell, and the licence is GPL-2.0. The last push was on 2026-10-14 and the recent releases are dated, v2026.09.29-5 and v2026.08.24-4, with an older v7-beta tag from 2023.

The release naming is worth noting, because it tells you the project treats a release as a dated snapshot rather than a semver sequence. A distribution that ships a rolling set of packages has no meaningful version bump to make, so the date plus a build counter is the only honest identifier.

There is also a Discord, a Patreon and a Buy Me a Coffee link, a Codacy badge and a maintenance badge for 2026, which together paint a picture of a small project maintained in the open with a funding mix of individual sponsorship and, given the presence of the Patron link, some recurring support.

The scripts that make up instantutils

The top level of the repository is a set of shell scripts with names that describe their role on a running system, and the names are more informative than a directory listing would be.

instantutils.sh is the main entry point and is installed as instantutils. autostart.sh becomes instantautostart, which is the script that runs when the session starts and is the thing that wires up the pieces a user expects to be there. monitor.sh becomes instantmonitor, which is the background process that watches over the running system. rootinstall.sh and userinstall.sh are the two halves of installation, and the split between them is the interesting part: one needs administrative rights and the other does not, and having them as separate scripts means a non-root installer does not need to escalate.

repo.sh is installed alongside them into share/instantutils, which suggests it is about package repositories rather than about the utilities themselves, and it sits next to the two install scripts in the share directory rather than in bin.

The programs/ directory is the other half of the design, because the Makefile installs everything in it straight into the bin directory. That means any script dropped into programs/ becomes a command available to the user, with no Makefile edit required. It is the same trick the manpages use, and together they mean the utility set can grow without touching the build file.

Then there are the directories that hold data rather than code. The desktop/ directory holds the desktop entry files that end up in share/applications, so the system applications are defined as data. The xorg/ directory holds configuration that gets installed into /etc/X11/xorg.conf.d, which is how the display server is configured. The udev/ directory holds device rules, the signing/ directory holds signing keys, and config/ is the general configuration area.

The manpages/ directory is worth a second look, because it is the only documentation in the repository. The Makefile finds files matching a regex under manpages and installs them into the man1 directory with mode 644, which means the utilities are documented in the standard way and the man pages for them work the moment the system is installed.

The justfile and how the ISO gets built

The justfile is the most interesting file in the repository, because it encodes a build system that has to work in several very different places.

The build-iso target auto-detects. It checks for /etc/arch-release or a pacman command and, if either is present, builds the ISO natively. Otherwise it checks whether Docker is installed and its daemon is running, and if so it builds inside an Arch Linux Docker container. If neither is true, it errors out with a message telling you to install or start Docker, or to run on Arch Linux, and points you at the headless QEMU route for Google Colab.

That auto-detection is the design. The same repository has to build the ISO on a developer's Arch machine, inside a container on a CI runner, and inside a virtual machine in a browser, and rather than having three separate documented procedures it has one target with three branches.

The Docker path is:

    docker run --privileged --rm \
      -v "{{ justfile_directory() }}:/workspace" \
      -w /workspace \
      -e SOURCE_DATE_EPOCH="${SOURCE_DATE_EPOCH:-$(date +%s)}" \
      archlinux:base-devel \
      bash -c "set -e; pacman -Syu --noconfirm --needed archiso git sudo curl jq; ./iso/build.sh {{ FLAGS }}"
    sudo chown -R $USER:$USER "{{ justfile_directory() }}/iso/build"

Several details in that block are doing real work. The image is archlinux:base-devel, so the build runs against the same distribution the output targets. The package install line uses pacman with --noconfirm and --needed for the tools the build needs, archiso for the ISO itself, plus git, sudo, curl and jq. The container runs privileged and with the repository bind-mounted at /workspace, and the working directory is set to /workspace so the build script path resolves.

SOURCE_DATE_EPOCH is passed through as an environment variable with a fallback to the current time. That is the standard reproducible-builds mechanism: pinning the timestamp makes the output byte-identical between builds, and the fallback means it still works when nobody sets it. Passing it into the container rather than computing it inside means the value is fixed by the caller and the container cannot quietly diverge.

The final chown fixes the ownership of the build output, because the container runs as root and the files it writes would otherwise be owned by root on the host. That is a small line that prevents a confusing set of permission errors afterwards.

The native path, by contrast, is a single line that calls the build script directly, because on an Arch host with pacman the tooling is already present. There is also a build-iso-offline target for the offline-install-capable ISO, which auto-detects in the same way.

What the Makefile installs

The Makefile is a different kind of artefact from the justfile, and it explains what instantutils actually is on a running system.

The install target splits into install_external and install_local, and the split is interesting because of the comment attached to install_external. The Makefile says this should really be handled in a better way, because the external hotkey version might be out of sync with what is installed here, and it makes things harder in Nix and with updating.

So the keybindings are fetched at install time from a URL rather than being generated from the same source as the system, and the author has flagged that as a known wart. The external fetch pulls a hotkeys markdown file from the website repository and pipes it through two sed expressions, one to indent the lines and one to strip the heading markers, producing a plain keybinds file.

install_local does the rest. It installs autostart.sh as instantautostart, monitor.sh as instantmonitor and instantutils.sh as instantutils into the bin directory. It finds the manpages matching a regex and installs them into the man directory, copies setup/ into share/instantutils, installs the desktop entry files into share/applications, and copies everything under programs/ into bin.

Two things stand out. First, the manpages are installed with find and -exec, which means a new manpage is picked up without touching the Makefile. Second, programs/ is installed wholesale into bin, so every program in that directory becomes a command on the system path. That directory is how the distribution exposes its utility scripts without each one needing an install rule.

The prefix is /usr with DESTDIR support throughout, so the whole thing is packageable. The setup directory is chmod 755 recursively, which is what makes those scripts executable once they are in place, and the desktop entries are installed with mode 644 into the applications directory where a desktop environment will pick them up.

There is also a .PHONY declaration pattern throughout, which is a sign of care. The targets are declared phony so that a file named install or clean in the working directory cannot stop make from running them.

Docker as a virtual machine harness

The docker-compose.yml in this repository is not running a service, and the name of the service gives it away: arch-installer-vm.

It uses the qemux/qemu image with the container name arch-installer-vm, and it exists to run a virtual machine that installs Arch Linux. The environment sets KVM to Y for high-performance hardware virtualization, a RAM size of 4G, four CPU cores and virtio-gpu for the display.

The devices section is the part that shows what the setup needs. /dev/kvm is passed in to enable KVM hardware acceleration, and /dev/net/tun is required for network bridging. The cap_add list grants NET_ADMIN, also for network bridging, and the ports section exposes 8006 on the host, which is the web interface of the QEMU front end.

The volumes then wire in the two things the VM needs. The built instantOS installer ISO is mapped to /boot.iso, so the VM boots the thing you just built, and a vm-data directory is mapped to /storage to give the virtual hard drive persistence between runs. The restart policy is on-failure with a two minute stop grace period.

This is a neat piece of engineering, because it lets you boot your freshly built ISO without installing anything on the host and without giving the VM the whole machine. You build the installer image, then you build a machine that boots it, and the whole loop runs on a container with two device passthroughs.

The pairing with the Colab experiment is what makes the setup make sense. The readme says you can test the live ISO inside a browser-based virtual machine using Google Colab, with the caveat that running an OS VM in Colab is highly experimental and may be slow or unstable. The colab/ directory at the top level holds the notebook, and the justfile's colab module is the headless QEMU path that the build-iso error message points you to.

So the intended workflow has three tiers. Build the ISO natively on Arch, or in Docker if you are not on Arch, or in a Colab notebook if you have neither. Then boot it in the QEMU container with hardware acceleration. The whole loop is reproducible on a laptop or on a hosted notebook.

Editorial conclusion

Adopt instantOS if you want a fast, minimal system that still arrives with a working desktop and a set of utilities rather than a bare installer, and you are comfortable with Arch. Do not adopt it if you want a conventional distribution with a conventional package workflow, because the design is deliberately built from shell scripts that install into the system directly. Before you commit, read the website documentation rather than the repository readme, because the repository only holds the utilities and the ISO build, and note that the Colab route is described as highly experimental.

Frequently asked questions

Official sources

1. instantOS/instantOS on GitHub
2. Issues
3. License: GPL-2.0
4. README
5. Releases