「 须臾水面明月出，沧江万顷琉璃寒 」
Warning
Most of the code is generated by human, maybe even neko.
If you found any issues, rewrite it with Claude.
* Your warranty is void.
* I am not responsible for anything that may happen to your device by using this program.
* You do it at your own risk and take the responsibility upon yourself.
* This project is open source, you can make your own fork/rewrite but not to blame the author.
* This program has no Super Cow Powers.
Not "Why not docker", but "When cannot docker".
ruri is pronounced as lyoli, or you can call it [瑠璃/琉璃] (るり) in Chinese or Japanese as well.
ruri is acronym to Lightweight, User-friendly Linux-container Implementation, as better chroot.
ruri is a powerful container implementation that runs on almost any Linux device, even with incomplete kernel configurations or minimal storage space.
- Aimed to be the most compatible
better chroot. - Default configuration works on every device with chroot support.
- Simple usage, just
ruri /path/to/rootfs [command...]to run a container. - Shell script friendly, all operations can be done with simple command line options.
- Supports chroot, unshare with pivot_root, environment/user/workdir setup, and more....
- Umount & kill containers easily and safely.
- Built-in binfmt_misc & QEMU for easy multi-arch containers.
- Rootless containers, capability control, cgroups, seccomp profile, no new privileges, and more security features.
- Flexible mount options: mount images/partitions, customizable mount flags, TMPFS and OVERLAY support.
- Customizable extra device nodes and extra masked paths.
- Experimental systemd init support.
- Config file support.
- Statically linked binaries for many architectures.
- Very small binary size (even <200k with upx), yet over 40 options.
See USAGE to explore all features of ruri.
See Enhance Container Security.
After DirtyFrag and CopyFail, seccomp is more and more important for container security.
Our default seccomp profile is now ready, and will keep tracking the latest vulnerabilities.
You can enable it by using --enable-seccomp option. And if you have any suggestions/issues for the seccomp profile, please report.
NOTE: default seccomp profile blocks personality() syscall. And it will break debian reprotest, box86/wine and some other software. You can comment out this syscall in seccomp profile to make them work.
Considering the security issues of chroot, ruri will drop CAP_SYS_CHROOT by default now
If you got any issues with this, please report.
In newest code, ruri will also do setgroups() for root user in container to avoid permission issues on some devices, If you'd like to disable it, please use --no-setgroups option.
See SECURITY.md.
rurima was planned to be the ruri manager, but since it now has a full integration of ruri, you can use it as an enhanced version of ruri.
See TERMS_OF_USE.md
You need to root your phone first, ruri supports to run with root on Android devices.
We promise that ruri has backward compatibility of cli usage and config file since v3.9.0, you can keep updated to the newest version. Any breaking changes will not be introduced to v3.9.x
If you think something does not work as expected, please open a new isssue
See Asking LLM for how to ask LLM about ruri.
You can get ruri binary (statically linked) for arm64, armv7, armhf, riscv64, i386, loong64, s390x, ppc64le and x86_64 devices in Release. Or you can run the following command to download ruri automatically
. <(curl -sL https://get.ruri.zip/ruri)This will automatically download ruri binary to ./ruri.
. <(curl -sL https://get.ruri.zip/rurima)
./rurima lxc pull -o alpine -v edge -s /tmp/alpine
sudo ruri /tmp/alpine
In container:
rm test/etc/resolv.conf
echo nameserver 1.1.1.1|tee test/etc/resolv.confsudo ruri -u /tmp/alpine
Very simple as you can see.
For command line examples, please see ruri -H.
# Run chroot container
sudo ruri /tmp/alpine
# Very simple as you can see.
# About the capabilities
# Run privileged chroot container
sudo ruri -p /tmp/alpine
# If you want to run privileged chroot container,
# but you don't want to give the container cap_sys_chroot privileges
sudo ruri -p -d cap_sys_chroot /tmp/alpine
# If you want to run chroot container with common privileges,
# but you want cap_sys_admin to be kept
sudo ruri -k cap_sys_admin /tmp/alpine
# About unshare
# Unshare container's capability options are same with chroot.
# Run unshare container
sudo ruri -u /tmp/alpine
# Finally, umount the container
sudo ruri -U /tmp/alpine
After initing the container, ruri will create a file /.rurienv by default, this config can unify container config, but it will also cover some of the command-line args, you can use --no-rurienv to disable it, or see rurienv.md to see its behavior.
You might cannot remove this file unless you run chattr -i .rurienv, but don't worry, after umounting conainer by ruri -U, this config file will be removed automatically.
If you want to change the container config, just use -U to umount it and re-run the container.
Ruri provides statically linked binary, but if you want to build it yourself, see Build.
ruri is ready to integrate into other projects, with the MIT License, it is compatiblte to be redistribute with almost all license, or commercial/closed source. An example is ruri's own build action , it runs containers for 9 different architectures to build itself, that shows its broad application prospects. Another example is rurima, I made ruri built-in for it, so it can be run as a subcommand. See Integration for a guide to integrate ruri into your projects.
On Macbook Air M4, orbstack, ubuntu 25.04:
moehacker@studio:~/ruri$ sudo /usr/bin/time -f "Time: %E\nMax memory: %M KB" ./ruri -u ../ubuntu /bin/true
In ruri() at /home/moehacker/ruri/src/ruri.c line 1419:
ruri() to run_container(): 250460ns
In ruri_run_chroot_container() at /home/moehacker/ruri/src/chroot.c line 1041:
run_container() to exec(): 7798583ns
Time: 0:00.01
Max memory: 1944 KB
| ruri | crun | % | |
|---|---|---|---|
| (noupx) | 454K | 3.0M | -84.9% |
| (withupx) | 147K | 1.3M | -88.7% |
| Alphabet | ruri used | % |
|---|---|---|
| 52 | 47 | 90% |
License of code
- Licensed under the MIT License
- Copyright (c) 2022-2025 Moe-hacker
License of clang-format config file
- GPL-2.0
- moby, especially moby/profiles for the seccomp profile.
- docker, for default container configuration and many other inspirations.
「 咲誇る花 美しく、
散り行く運命 知りながら、
僅かな時の彩を 」
(>_×)