🐧 a micro (µ)Linux Cloud Native OS designed for high performance, minimal overhead and a small footprint.

View on GitHub



Build Packages Review

uLinux (µLinux) is a micro (µ)Linux Cloud Native OS designed for high performance, minimal overhead and a small footprint.

uLinux is container-ready and small enough that it could be used as a sort of “UniKernel” for your applications.

If you care about performance, footprint, security and minimalism like I do you’ll want to use µLinux for your workloads.

NOTE:: µLinux is NOT a full blown Desktop OS nor will it ever likely be. It is also not ever likely to build your favorite GCC/GLIBC/Clang software as it only ships with a very small C compiler (tcc) and libc (musl). Consider using Alpine for a more feature rich system or any other “heavier” / “full featured” distro.

Supported Platforms


Fast Boot

uLinux is designed for high performance and small footprint. uLinux is expected to boot within ~1s on a modern system. See Screenshots.

Very Lightweight!

uLinux will boot on as little as 64MB of RAM! Yes that’s right!

Other notable attributes:

The goal is to stick to these attributes as far as we can! The only way to grow your uLinux system once installed is through ports and packages.

Full Container Support

uLinux supports full containerization and comes shipped with a very small lightweight container / sandbox tool called box. See box.

Currently supported Container Engines:


uLinux currently supports building C and Assembly and ships with the following compilers and tools:

There is no support for GCC/GLIBC.


To use docker you must first install it using ports.

ports -u
cd /usr/ports/cgroups-mount
pkg build
pkg add
cd /usr/ports/docker
pkg build
pkg add
svc -r dockerd
docker ps

CloudInit / CloudConfig

uLinux fully supports configuration via CloudInit/CloudConfig. See CloudInit.


screenshot-1 screenshot-2 screenshot-3

Getting Started

Prebuilt Images

This repo contains prebuilt images to get you started quickly without having to build anything yourself.

Please see the Release for the latest published versions of:



Once booted with either the Hybrid Live ISO or Kernel + RootFS you can install uLinux to disk by typing in a shell:

# setup /dev/sda

Assuming /dev/sda is the device path to the disk you want to install to.

WARNING: This will automatically partition, format and install uLinux with no questions asked without hesitation. Please be sure you understand what you are doing.


First make sure you have Docker installed on your system as the build uses this extensively to build the OS reliably across all platforms consistently.

NOTE: Docker is not strictly required in order to build uLinux. You may also just run the ./main.sh build script yourself as long as you have installed all required build dependencies. See the Dockerfile.builder for details on what dependencies need to be available for a successful build.

Also make sure you have QEMU installed as this is used for testing and booting the OS into a Guest VM.

Then just run:

$ make


You can customize the build by overriding the customize_kernel() and customize_rootfs() functions in customize.sh:

if any of the customize_* functions fail the build will fail.


uLinux is fully cloud-init capable and supports the following cloud-init platforms:

uLinux’s cloud-init fully supports a subset of the cloud-config YAML spec including:

In addition there is also full support for running an arbitrary shell script as the `user-data.

There is a sample CloudDrive config in clouddrive as the top-level of the repo which can be customized by editing the user-data script and running make clouddrive.


uLinux comes with its own unique set of service management tools called svc and service (which is just a wrapper for svc). Services are stored in a directory at /bin/svc.d which has the following structure:

# cd /bin/svc.d
# find .

Each file listed in /bin/svc.d/avail can either be:

Configuration for services is expected to be stored in /etc/default/<service> which contains files that are sourced and in shell format. The bare.sh wrapper looks here by default for configuration for “bare” services. Other services may also store and look for their configuration here but this is not mandatory.


This is the primary tool for managing services:


This is simply a wrapper for svc and supports the following three commands:

Packaging and Ports

If you are at all familiar with CRUX or ArchLinux then the packages and ports and tools provided by uLinux will be somewhat familiar to you.

Packages in uLinux are basic Tarball(s) of a prebuilt piece of software with one minor notable exception. It also includes state of the package database which is used to update the uLinux package database on your system (each package stores its installed state in separate directories in /var/db/pkg).

Ports in uLinux are very similar to that of the Pkgfile format of CRUX with only one notable exception. They only support POSIX Shell as that is the only type of shell that ships with uLinux. Therefore you cannot use an array for source= it must be a space or newline delimited string.

Configuration of pkg and ports are stored in /etc/pkg.conf and here you can customize the behavior of the packaging and ports tools. The most notable configuration options currently are:

NOTE: Currently ports does not support multiple collections_)

What following is a brief description of the tools available and their usage.


This is the primary tool for managing packages installed on a uLinux system.

See the help for details on usage:

# pkg
=> pkg [a]dd pkg.tar.gz
=> pkg [b]uild
=> pkg [c]hecksum
=> pkg [d]el pkg
=> pkg [l]ist [pkg]


This tool updates and synchronizes the ports collection on disk depending on the configuration of PKG_PORTSDIR with a remote collection specified by URL. The remote collection must contain a collection of ports as well as the index file generated by repogen and each file must be retrievable with by wget.

Other Utilities

There are a number of other utilities that live outside (currently) of pkg and port, these are:



uLinux comes shipped with a simple Container / Sandbox tool called `box. It has a familiar user experience if you are used to Docker (but nowhere near as feature rich of course!).

Simply run box to get a shell in an isolated environment that is fully isolated from your system’s mounts, namespace, pid, devices, etc. The only part that is shared from the host is the host’s networking.

# box
KhJpKC / # ps aux
    1 root      0:00 /bin/sh
    6 root      0:00 ps aux

Or run box <command> like so:

# box echo 'I am pid $$'
I am pid 1


Mostly useful as a way to debug and enter the environment of an installed system where uLinux is used as a “rescue” system.

$ enter-chroot /path/to/rootfs

NOTE: You must have already mounted the root file system at the desired path before running enter-chroot /path/to/rootfs.


Just run:

$ make test

This uses QEMU and on macOS X we use the nanos Homrebrew formulae of QEMU that supports hardware accelaration:

brew tap nanovms/homebrew-qemu
brew install nanovms/homebrew-qemu/qemu

The OS comes pre-shipped with Dropbear (SSH Daemon) as well as a Busybox Userland. The test script (test.sh) also uses QEMU and sets up a User mode network which forwards port 2222 to the guest VM for SSH access.

You can access the guest with:

$ ssh -p 2222 [email protected]


uLinux is licensed under the terms of the MIT License.