Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


vpsAdminOS is a small OS serving as a host for unprivileged Linux system containers. It is based on not-os and NixOS. It is designed to run full distributions inside unprivileged containers which look and feel as much as a virtual machine as possible.

vpsAdminOS is developed and used in production by, a non-profit organization which provides virtual servers to its members. See vpsfree-cz-configuration for example cluster configuration.



vpsAdminOS uses:

  • LTS kernel with a mix of out-of-tree patches to improve container experience,
  • runit as an init system,
  • ZFS for storage,
  • our own tools for system container management called osctl,
  • LXC is used to run the containers,
  • AppArmor for additional security,
  • BIRD for network routing.

Building OS

Our kernel live-patch facility requires ccache to build the OS.

git clone
cd vpsadminos

vpsAdminOS is developed on top of the latest NixOS release, so make sure that the correct version of nixpkgs is in NIX_PATH, or set it as follows:

git clone --branch nixos-22.11
export NIX_PATH=`pwd`

vpsAdminOS can now be built and run:

# Build the OS

# Run under qemu
make qemu

The QEMU runner creates two disk images - sda.img and sdb.img which are added as QEMU ATA drives and can be used to create a mirrored ZFS pool that persists across reboots.


# Login via ssh or use qemu terminal with autologin
ssh -p 2222 localhost

# Configure osctld:
osctl pool install tank

# Create a container:
osctl ct new --distribution alpine myct01

# Configure container networking:
# Bridged veth
osctl ct netif new bridge --link lxcbr0 myct01 eth0

# Routed veth
osctl ct netif new routed myct01 eth1
osctl ct netif ip add myct01 eth1

# Start the container:
osctl ct start myct01

# Work with containers:
osctl ct ls
osctl ct attach myct01
osctl ct console myct01
osctl ct exec myct01 ip addr

# More information:
man osctl


Converting OpenVZ Legacy containers into vpsAdminOS

vpsAdminOS Converter can be used to convert OpenVZ Legacy containers containers into vpsAdminOS. See the documentation.

Nested containers

vpsAdminOS supports nested containers, e.g. LXC/LXD or Docker.

Nesting LXC/LXD containers can be enabled per container using:

osctl ct set nesting <id>

Docker works out-of-the-box with several known issues.