Skip to content

VHSgunzo/runimage

Repository files navigation

RunImage

Portable single-file unprivileged Linux container in user namespaces.

image

RunImage is designed to be completely static and portable to run on almost any Linux. It is based on a specially configured Arch Linux rootfs. The technology of single-file containerization is based on a modified static AppImage runtime, squashfs image with lz4 compression method for better work speed, statically compiled binaries for the operation of the container Run.sh script, and containerization itself is carried out by statically compiled Bubblewrap.

In addition, RunImage has the ability to isolate itself from the main system, use separate portable home directories and configuration files for each executable file being run, and run separate X11 servers, including running multiple Xorg servers on TTY. XFCE is used as DE

You can use it to develop and run any applications and games, including applications and games for Windows, launch games from retro platforms using popular emulators, work with the office, with remote desktops, multimedia, browsers, messengers, and even run virtual machines with QEMU/KVM and Virt-Manager, USB and block device forwarding in VM also works

Also inside the container, you can use various means of proxification, such as proxychains, tor and others and run VNC and SSH servers. In network sandbox mode (see SANDBOX_NET*) you can use VPN (tested openvpn, wireguard, sshuttle, tun2proxy) and other network tools without root rights.

The full list of installed packages can be found in the releases file pkg_list{-release-type}.txt

Features:

  • A portable single executable file with an idea - downloaded and launched. Nothing needs to be installed in the system.
  • Works on most Linux distributions, including even very old ones or without glibc or systemd and in live boot mode.
  • OverlayFS mode (It looks like the usual means of containerization like docker) (See Usage)
  • Read-Write mount in OverlayFS mode.
  • Running and working without root rights, including package management.
  • The ability to work in a packed and unpacked form.
  • The ability to run both 32-bit and 64-bit executable files.
  • Based on Arch Linux, contains the latest software and AUR support.
  • Access to BlackArch repo.
  • Own Pacman repository with mirror.
  • Updating without extraction runimage and automatic rebuild if the update was successful.
  • The ability to launching AppImage applications with FUSE mount (not needed to extract).
  • The ability to exec commands at the host level (see ENABLE_HOSTEXEC and hostexec)
  • The ability to use both separate home directories for each executable file, and completely seamless use of the system home directory.
  • The ability to use separate configuration files for each launched executable file (see config)
  • There is no performance drawdown. All applications and executable files run at the same speed as in the system
  • The ability to Filesystem, X11, DBUS, UDEV, Network, SystemD, USERs and PIDs sandboxing.
  • Temporary home directory in RAM (can be used as a real private mode for browsers and applications)
  • Sandbox and portable home directory.
  • The ability to launching a full DE in windowed/full screen mode and on TTY
  • Works with any versions of nvidia proprietary drivers
  • Works in Wayland session.
  • Monitoring of running processes
  • Background processes control
  • Attaching to a running containers
  • The ability to start and control SystemD services with fake-systemd package.
  • Usability and comprehensibility.

Requirements:

  • Supported architectures (should work on any Linux kernel architecture. However, it is currently only built for x86_64)
  • Minimum recommended Linux kernel version 4.18+ (tested on Centos 7 with 3.10 and on Ubuntu 12.04 with 3.11 using SUID Bubblewrap and it's works, but 5.0+ with user namespaces support is recommended)
  • FUSE (but not necessarily, because it is possible to work in unpacked form without FUSE mounting). Also you can create /dev/fuse manually (as root) if the kernel module exists (see this code):
mknod /dev/fuse -m 0666 c 10 229

To get started:

  1. Download latest release from the releases page. (HF mirror)
  2. Make it executable before run.
chmod +x runimage

Usage (from RunImage help):

┌──[user@host]─[~]
└──╼ $ runimage {bubblewrap args} {executable} {executable args}

    --run-help   |--rH                    Show this usage info
    --run-bwhelp |--rBwh                  Show Bubblewrap usage info
    --run-version|--rV                    Show runimage, rootfs, static, runtime version
    --run-pkglist|--rP                    Show packages installed in runimage
    --run-binlist|--rBin                  Show /usr/bin in runimage
    --run-shell  |--rS  {args}            Run runimage shell or execute a command in runimage shell
    --run-desktop|--rD                    Launch runimage desktop
    --overfs-list|--oL                    Show the list of runimage OverlayFS
    --overfs-rm  |--oR  {id id ...|all}   Remove OverlayFS
    --run-build  |--rB  {build args}      Build new runimage container
    --run-update |--rU  {build args}      Update packages and rebuild runimage
    --run-kill   |--rK                    Kill all running runimage containers
    --run-procmon|--rPm {RUNPIDs}         Monitoring of processes running in runimage containers
    --run-attach |--rA  {RUNPID} {args}   Attach to a running runimage container or exec command

Only for not extracted (RunImage runtime options):
    --runtime-extract {pattern}          Extract content from embedded filesystem image
    --runtime-extract-and-run {args}     Run runimage afer extraction without using FUSE
    --runtime-help                       Show runimage runtime help (Shown in this help)
    --runtime-mount                      Mount embedded filesystem image and print
    --runtime-offset                     Print byte offset to start of embedded
    --runtime-portable-home              Create a portable home folder to use as $HOME
    --runtime-portable-config            Create a portable config folder to use as $XDG_CONFIG_HOME
    --runtime-version                    Print version of runimage runtime

Environment variables to configure:
    NO_NET=1                             Disables network access
    TMP_HOME=1                           Creates tmpfs /home/$USER and /root in RAM and uses it as $HOME
    TMP_HOME_DL=1                        As above, but with binding $HOME/Downloads directory
    SANDBOX_HOME=1                       Creates sandbox home directory and bind it to /home/$USER or to /root
    SANDBOX_HOME_DL=1                    As above, but with binding $HOME/Downloads directory
    SANDBOX_HOME_DIR="/path/dir"         Specifies sandbox home directory and bind it to /home/$USER or to /root
    PORTABLE_HOME=1                      Creates a portable home directory and uses it as $HOME
    PORTABLE_HOME_DIR="/path/dir"        Specifies a portable home directory and uses it as $HOME
    PORTABLE_CONFIG=1                    Creates a portable config directory and uses it as $XDG_CONFIG_HOME
    NO_CLEANUP=1                         Disables unmounting and cleanup mountpoints
    ALLOW_BG=1                           Allows you to run processes in the background
    UNSHARE_PIDS=1                       Unshares all host processes
    UNSHARE_USERS=1                      Don't bind-mount /etc/{passwd,group}
    SHARE_SYSTEMD=1                      Shares SystemD from the host
    UNSHARE_DBUS=1                       Unshares DBUS from the host
    UNSHARE_UDEV=1                       Unshares UDEV from the host (/run/udev)
    UNSHARE_MODULES=1                    Unshares kernel modules from the host (/usr/lib/modules)
    UNSHARE_LOCALTIME=1                  Unshares localtime from the host (/etc/localtime)
    UNSHARE_NSS=1                        Unshares NSS from the host (/etc/nsswitch.conf)
    UNSHARE_DEF_MOUNTS=1                 Unshares default mount points (/mnt /media /run/media)
    NO_NVIDIA_CHECK=1                    Disables checking the nvidia driver version
    NVIDIA_DRIVERS_DIR="/path/dir"       Specifies custom Nvidia driver images directory
    RUNCACHEDIR="/path/dir"              Specifies custom runimage cache directory
    SQFUSE_REMOUNT=1                     Remounts the container using squashfuse (fix MangoHud and VkBasalt bug)
    OVERFS_MODE=1                        Enables OverlayFS mode
    KEEP_OVERFS=1                        Enables OverlayFS mode with saving after closing runimage
    OVERFS_ID=ID                         Specifies the OverlayFS ID
    KEEP_OLD_BUILD=1                     Creates a backup of the old RunImage when building a new one
    BUILD_WITH_EXTENSION=1               Adds an extension when building (compression method and rootfs type)
    CMPRS_ALGO={zstd|xz|lz4}             Specifies the compression algo for runimage build
    ZSDT_CMPRS_LVL={1-22}                Specifies the compression ratio of the zstd algo for runimage build
    NO_RUNDIR_BIND=1                     Disables binding RunDir to /var/RunDir
    RUN_SHELL="shell"                    Selects $SHELL in runimage
    NO_CAP=1                             Disables Bubblewrap capabilities (Default: ALL, drop CAP_SYS_NICE)
                                            you can also use /usr/bin/nocap in runimage
    AUTORUN="{executable} {args}"        Run runimage with autorun options for /usr/bin executables
    ALLOW_ROOT=1                         Allows to run runimage under root user
    QUIET_MODE=1                         Disables all non-error runimage messages
    NO_WARN=1                            Disables all warning runimage messages
    DONT_NOTIFY=1                        Disables all non-error runimage notification
    RUNTIME_EXTRACT_AND_RUN=1            Run runimage afer extraction without using FUSE
    TMPDIR="/path/{TMPDIR}"              Used for extract and run options
    RUNIMAGE_CONFIG="/path/{config}"     runimage сonfiguration file (0 to disable)
    ENABLE_HOSTEXEC=1                    Enables the ability to execute commands at the host level
    NO_RPIDSMON=1                        Disables the monitoring thread of running processes
    SANDBOX_NET=1                        Creates a network sandbox
    SANDBOX_NET_SHARE_HOST=1             Creates a network sandbox with access to host loopback
    SANDBOX_NET_CIDR=11.22.33.0/24       Specifies tap interface subnet in network sandbox (Def: 10.0.2.0/24)
    SANDBOX_NET_TAPNAME=tap0             Specifies tap interface name in network sandbox (Def: eth0)
    SANDBOX_NET_MAC=B6:40:E0:8B:A6:D7    Specifies tap interface MAC in network sandbox (Def: random)
    SANDBOX_NET_MTU=65520                Specifies tap interface MTU in network sandbox (Def: 1500)
    SANDBOX_NET_HOSTS="file"             Binds specified file to /etc/hosts in network sandbox
    SANDBOX_NET_RESOLVCONF="file"        Binds specified file to /etc/resolv.conf in network sandbox
    BUWRAP_ARGS+=()                       Array with Bubblewrap arguments (for config file)
    EXEC_ARGS+=()                        Array with Bubblewrap exec arguments (for config file)
    XORG_CONF="/path/xorg.conf"          Binds xorg.conf to /etc/X11/xorg.conf in runimage (0 to disable)
                                            (Default: /etc/X11/xorg.conf bind from the system)
    XEPHYR_SIZE="HEIGHTxWIDTH"           Sets runimage desktop resolution (Default: 1600x900)
    XEPHYR_DISPLAY=":9999"               Sets runimage desktop $DISPLAY (Default: :1337)
    XEPHYR_FULLSCREEN=1                  Starts runimage desktop in full screen mode
    UNSHARE_CLIPBOARD=1                  Disables clipboard synchronization for runimage desktop

    SYS_BUWRAP=1                          Using system bwrap
    SYS_SQFUSE=1                         Using system squashfuse
    SYS_UNSQFS=1                         Using system unsquashfs
    SYS_MKSQFS=1                         Using system mksquashfs
    SYS_UNIONFS=1                        Using system unionfs
    SYS_SLIRP=1                          Using system slirp4netns
    SYS_TOOLS=1                          Using all binaries from the system
                                         If they are not found in the system - auto return to the built-in

Other environment variables:
    If inside RunImage:
        INSIDE_RUNIMAGE=1
    RunImage path (for packed):
        RUNIMAGE=""
    Squashfs offset (for packed):
        RUNOFFSET=""
    Null argument:
        ARGV0=""
    PID of Run.sh script:
        RUNPID=""
    Parent PID of Run.sh script:
        RUNPPID=""
    Run binary directory:
        RUNDIR=""
    RootFS directory:
        RUNROOTFS=""
    Static binaries directory:
        RUNSTATIC=""
    RunImage or RunDir directory:
        RUNIMAGEDIR=""
    RunImage external configs directory:
        RUNCONFIGDIR=""
    Sandbox homes directory:
        SANDBOXHOMEDIR=""
    Portable homes directory:
        PORTABLEHOMEDIR=""
    Cache directory:
        RUNCACHEDIR=""
    Nvidia driver images directory:
        NVIDIA_DRIVERS_DIR=""
    RunImage name or link name or executable name:
        RUNSRCNAME=""
    RunImage version:
        RUNIMAGE_VERSION=""
    RootFS version:
        RUNROOTFS_VERSION=""
    Static version:
        RUNSTATIC_VERSION=""
    RunImage runtime version:
        RUNRUNTIME_VERSION=""
    Directory for all OverlayFS:
        RUNOVERFSDIR=""
    OverlayFS ID directory:
        OVERFS_DIR=""
    OverlayFS ID mount directory:
        OVERFS_MNT=""
    RunImage runtime:
        RUNRUNTIME=""
    Rootfs type:
        RUNROOTFSTYPE=""
    squashfuse and unionfs PIDs:
        FUSE_PIDS=""
    The name of the user who runs runimage:
        RUNUSER=""
    mksquashfs:
        MKSQFS=""
    unsquashfs:
        UNSQFS=""
    unionfs:
        UNIONFS=""
    squashfuse:
        SQFUSE=""
    bwrap:
        BUWRAP=""
    slirp4netns:
        SLIRP=""

Custom scripts and aliases:
    /bin/cip                          Сheck public ip
    /bin/dbus-flmgr                   Launch the system file manager via dbus
    /bin/nocap                        Disables container capabilities
    /bin/pac                          sudo pacman (fake sudo)
    /bin/packey                       sudo pacman-key (fake sudo)
    /bin/panelipmon                   Shows information about an active network connection
    /bin/runbuild                     Starts the runimage build
    /bin/rundesktop                   Starts the desktop mode
    /bin/{xclipsync,xclipfrom}        For clipboard synchronization in desktop mode
    /bin/webm2gif                     Convert webm to gif
    /bin/transfer                     Upload file to https://transfer.sh
    /bin/rpidsmon                     For monitoring of processes running in runimage containers
    /bin/hostexec                     For execute commands at the host level (see ENABLE_HOSTEXEC)
    /usr/bin/runupdate                For runimage update

    ls='ls --color=auto'
    dir='dir --color=auto'
    grep='grep --color=auto'
    vdir='vdir --color=auto'
    fgrep='fgrep --color=auto'
    egrep='egrep --color=auto'
    rm='rm -i'
    cp='cp -i'
    mv='mv -i'
    ll='ls -lh'
    la='ls -lha'
    l='ls -CF'
    em='emacs -nw'
    _='sudo'
    _i='sudo -i'
    please='sudo'
    fucking='sudo'
    cip='curl -s ifconfig.io 2>/dev/null'
    dd='dd status=progress'
    pac='sudo pacman'
    pacman='sudo pacman'
    pacman-key='sudo pacman-key'
    packey='sudo pacman-key'

Additional information:
    You can create a symlink/hardlink to runimage or rename runimage and give it the name
        of some executable file from /usr/bin in runimage, this will allow you to run
        runimage in autorun mode for this executable file.
    The same principle applies to the AUTORUN variable:
        ┌─[user@host]─[~]
        └──╼ $ AUTORUN="ls -la" runimage {autorun executable args}
    Here runimage will become something like an alias for 'ls' in runimage
        with the '-la' argument. You can also use AUTORUN as an array for complex commands in the config.
        AUTORUN=("ls" "-la" "/path/to something")
    This will also work in extracted form for the Run binary.

    When using the PORTABLE_HOME and PORTABLE_CONFIG variables, runimage will create or
        search for these directories next to itself. The same behavior will occur when
        adding a runimage or Run binary or renamed or symlink/hardlink to them in the PATH
        it can be used both extracted and compressed and for all executable files being run:
            '$PORTABLEHOMEDIR/Run'
            '$RUNIMAGEDIR/Run.config'
        if a symlink/hardlink to runimage is used:
            '$PORTABLEHOMEDIR/{symlink/hardlink_name}'
            '$RUNIMAGEDIR/{symlink/hardlink_name}.config'
        or with runimage/Run name:
            '$PORTABLEHOMEDIR/{runimage/Run_name}'
            '$RUNIMAGEDIR/{runimage/Run_name}.config'
        It can also be with the name of the executable file from AUTORUN environment variables,
            or with the same name as the executable being run.
    SANDBOX_HOME* similar to PORTABLE_HOME, but the system HOME becomes isolated.
    SANDBOX_HOME_DIR and PORTABLE_HOME_DIR point to a specific directory or create it in the absence of.

    RunImage uses fakechroot and fakeroot, which allows you to use root commands, including in
        unpacked form, to update the rootfs or install/remove packages.
        sudo and pkexec have also been replaced with fake ones. (see /usr/bin/sudo /usr/bin/pkexec)

    RunImage configuration file:
        Special BASH-syntax file with the .rcfg extension, which describes additional
            instructions and environment variables for running runimage.
        Configuration file can be located next to runimage:
            '$RUNIMAGEDIR/{runimage/Run_name}.rcfg'
        it can be used both extracted and compressed and for all executable files being run:
            '$RUNIMAGEDIR/Run.rcfg'
        if a symlink/hardlink to runimage is used:
            '$RUNIMAGEDIR/{symlink/hardlink_name}.rcfg'
        or in $RUNCONFIGDIR directory:
            '$RUNCONFIGDIR/Run.rcfg'
            '$RUNCONFIGDIR/{runimage/Run_name}.rcfg'
            '$RUNCONFIGDIR/{symlink/hardlink_name}.rcfg'
        It can also be with the name of the executable file from AUTORUN environment variables,
            or with the same name as the executable being run.
        In $RUNDIR/config there are default configs in RunImage, they are run in priority,
            then external configs are run if they are found.

    RunImage desktop:
        Ability to run RunImage in desktop mode. Default DE: XFCE (see /usr/bin/rundesktop)
        If the launch is carried out from an already running desktop, then Xephyr will start
            in windowed/full screen mode (see XEPHYR_* environment variables)
            Use CTRL+SHIFT to grab the keyboard and mouse.
        It is also possible to run on TTY with Xorg (see XORG_CONF environment variables)
            To do this, just log in to TTY and run RunImage desktop.
        Important! The launch on the TTY should be carried out only under the user under whom the
            login to the TTY was carried out.

    RunImage OverlayFS:
        Allows you to create additional separate layers to modify the container file system without
            changing the original container file system. Works packed and unpacked. Also, in packed form,
            it allows you to mount the container in RW mode.
        It also allows you to attach to the same OverlayFS when you specify its ID:
        ┌─[user@host]─[~]
        └──╼ $ OVERFS_ID=1337 runimage {args}
            If OverlayFS with such ID does not exist, it will be created.
        To save OverlayFS after closing the container, use KEEP_OVERFS:
        ┌─[user@host]─[~]
        └──╼ $ KEEP_OVERFS=1 runimage {args}
        To run a one-time OverlayFS, use OVERFS_MODE:
        ┌─[user@host]─[~]
        └──╼ $ OVERFS_MODE=1 runimage {args}

    RunImage build:
        Allows you to create your own runimage containers.
        This works both externally by passing build args:
        ┌─[user@host]─[~]
        └──╼ $ runimage --run-build {build args}
        And it also works inside the running instance (see /bin/runbuild):
        ┌─[user@host]─[~] - in runimage
        └──╼ $ runbuild {build args}
        Optionally, you can specify the following build arguments:
            {/path/new_runimage_name} {-zstd|-xz|-lz4} {zstd compression level 1-19}
        By default, runimage is created in the current directory with a standard name and
            with lz4 compression. If a new RunImage is successfully build, the old one is deleted.
            (see KEEP_OLD_BUILD BUILD_WITH_EXTENSION CMPRS_ALGO ZSDT_CMPRS_LVL)

    RunImage update:
        Allows you to update packages and rebuild RunImage. In unpacked form, automatic build will
            not be performed. When running an update, you can also pass arguments for a new build.
            (see RunImage build) (also see /usr/bin/runupdate)
        ┌─[user@host]─[~]
        └──╼ $ runimage --run-update {build args}
        By default, update and rebuild is performed in $RUNIMAGEDIR

    RunImage network sandbox:
        Allows you to create a private network namespace with slirp4netns and inside the container
            manage routing, create/delete network interfaces, connect to a vpn (checked openvpn
            and wireguard), configure your resolv.conf and hosts, etc. (see SANDBOX_NET*)
        By default, network sandbox created in 10.0.2.0/24 subnet, with eth0 tap name, 10.0.2.100 tap ip,
            1500 tap MTU, and random MAC.

    RunImage hostexec:
        Allows you to run commands at the host level (see ENABLE_HOSTEXEC and /usr/bin/hostexec)
        ┌─[user@host]─[~]
        └──╼ $ ENABLE_HOSTEXEC=1 runimage --run-shell
        ┌─[user@host]─[~] - pass command as args
        └──╼ $ hostexec {hostexec args} {executable} {executable args}
        ┌─[user@host]─[~] - pass command to stdin
        └──╼ $ echo "{executable} {executable args}"|hostexec {hostexec args}
            --help      |-h             Show this usage info
            --shell     |-s  {args}     Launch host shell (socat)
            --superuser |-su {args}     Execute command as superuser
            --terminal  |-t  {args}     Execute command in host terminal

    For Nvidia users with a proprietary driver:
        If the nvidia driver version does not match in runimage and in the host, runimage
            will make an image with the nvidia driver of the required version (requires internet)
            or will download a ready-made image from the github repository and further used as
            an additional module to runimage.
        You can download a ready-made driver image from the releases or build driver image manually:
            https://github.com/VHSgunzo/runimage-nvidia-drivers
        In runimage, a fake version of the nvidia driver is installed by default to reduce the size:
            https://github.com/VHSgunzo/runimage-fake-nvidia-driver
        But you can also install the usual nvidia driver of your version in runimage.
        Checking the nvidia driver version can be disabled using NO_NVIDIA_CHECK variable.
        The nvidia driver image can be located next to runimage:
                '$RUNIMAGEDIR/{nvidia_version}.nv.drv'
            or in $RUNIMAGEDIR/nvidia-drivers (Default):
                '$RUNIMAGEDIR/nvidia-drivers/{nvidia_version}.nv.drv'
            or the driver can be extracted as the directory
                '$RUNIMAGEDIR/nvidia-drivers/{nvidia_version}'
            also, the driver can be in RunImage in a packed or unpacked form:
                '$RUNDIR/nvidia-drivers/{nvidia_version}.nv.drv'   -  image
                '$RUNDIR/nvidia-drivers/{nvidia_version}'          -  directory

Recommendations:
    If the kernel does not support user namespaces, you need to install
        SUID Bubblewrap into the system, or install a kernel with user namespaces support.
        If SUID Bubblewrap is found in the system, it will be used automatically.
    If you use SUID Bubblewrap, then you will encounter some limitations, such as the inability to use
        FUSE in RunImage, without running it under the root user, because the capabilities are
        disabled, and so on. So it would be better for you to install kernel with
        user namespaces support.
    I recommend installing the XanMod kernel (https://xanmod.org), because I noticed that the speed
        of runimage in compressed form on this kernel is much higher due to more correct caching settings
        and special patches.

Build/Rebuild your own runimage in manual mode:

  • Download base version of the runimage (it's called runimage)
  • Make it executable:
chmod +x runimage
  • Run it in OverlayFS mode (If you are using a proprietary nvidia driver, then I recommend disabling the driver check function by NO_NVIDIA_CHECK=1 for proper build/rebuild in manual mode. You do not need to do this in automatic mode):
OVERFS_MODE=1 ./runimage --run-shell
echo $OVERFS_MNT
echo $OVERFS_ID
  • Install or remove the necessary packages, change $OVERFS_MNT/rootfs, etc. You can change $OVERFS_MNT/rootfs in the standard ways for you. But do not close the container until the moment of build.
  • You can also specify your own type of rootfs in $OVERFS_MNT/rootfs/.type file, but it's not necessary.
  • After all the manipulations with rootfs, create a new runimage using this command in the container (See Usage):
runbuild
  • Or from another terminal tab (See Usage):
OVERFS_ID=$OVERFS_ID ./runimage --run-build
  • After the build is completed, you can close the container:
exit
# or CTRL-D

Troubleshooting and problem solving:

  • To start SystemD services with systemctl in RunImage SystemD replaced with fake-systemd package based on docker-systemctl-replacement with some modification. It's depend on python3
  • By default, all container processes running in the background will be killed after the container is closed, to allow background processes, use the environment variable ALLOW_BG=1
  • To start the SSH server you need to install patched runimage-openssh package from runimage pacman repo
pac -Sy runimage-openssh
ssh-keygen -A
# Don't forget to add your ssh keys for authorization to /etc/ssh/authorized_keys in the container
#   or to $HOME/.ssh/authorized_keys
#   password authorization disabled and don't work
systemctl start sshd    # systemctl depend on python3
# OR
/usr/bin/sshd -D &
  • When unpacked, use the Run-wrapper binary file to properly launch the container.
  • If SELinux is enabled in the system, then there may be problems with the launch and operation of Wine (solution)
  • To start nested bubblewrap containerization, you need to disable capabilities (see NO_CAP env var or use nocap)
    NO_CAP=1 runimage {args}
    # or nocap in runimage
    nocap bwrap {args}
    nocap steam {args}
    ...
  • When using TMP_HOME* you may run out of RAM, be careful with this.
  • It is also advisable to use TMPDIR when using --runtime-extract-and-run or RUNTIME_EXTRACT_AND_RUN, because by default, unpacking before starting will be carried out in /tmp, which may also lead to the end of RAM
  • With UNSHARE_PIDS, RunImage desktop does not start on TTY.
  • Xephyr does not support GL acceleration and Vulkan has performance issues (But this is not related to RunImage)
  • If you have problems with sound when running RunImage desktop on TTY, just restart pulseaudio.
  • Possible tearing on nvidia in RunImage desktop mode (solution)
    killall pulseaudio ; pulseaudio -D
  • If you disable bubblewrap capabilities using NO_CAP, you will not be able to use FUSE inside the container.
  • In packed form for fix bug with MangoHud and vkBasalt in DXVK mode need remount container with squashfuse (see SQFUSE_REMOUNT=1). In lwrun it's enabled by default.
  • If PID_MAX is less then 4194304, recommended to increase PID_MAX to 4194304 for better stability:
sudo sh -c 'echo kernel.pid_max=4194304 >> /etc/sysctl.d/98-pid_max.conf'
sudo sh -c 'echo 4194304 > /proc/sys/kernel/pid_max'

Main used projects:

Projects based on RunImage:

Similar projects:

RunImage tested and works on: