mkosi-sandbox(1)

okay so welcome to mkosi-sandbox(1) from the General Commands Manual — this is the page where we learn how to run commands in a custom sandbox without letting the host system’s whole vibe crash the party ✨

💖 NAME 💖

mkosi-sandbox — run commands in a custom sandbox 🫶

🌸 SYNOPSIS 🌸

mkosi-sandbox [options...]  command [arguments]

🦋 DESCRIPTION 🦋

mkosi-sandbox runs the given command in a custom sandbox. The sandbox is configured by specifying command line options that configure individual parts of the sandbox. Literally build-your-own-isolated-space energy 💅

If no command is specified, mkosi-sandbox will start bash in the sandbox.

ngl bestie, this sandbox is not designed to be a security boundary. Its intended purpose is to allow running commands in an isolated environment so they are not affected by the host system. She’s a vibe isolator, not a security vault 💀

It is possible to use mkosi-sandbox to create an in process sandbox for python applications by importing it as a module and invoking its enter function with only options. No command line to execute is needed in this case. As an example:

import mkosi.sandbox

mkosi.sandbox.enter(["--become-root"])
print(os.getuid())

Only the enter function can be invoked. Invoking any other functions from mkosi.sandbox is not supported and may break in future versions. so like… don’t go poking the other functions, bestie 🫶

✨ OPTIONS ✨

• --tmpfs DST — Mounts a new tmpfs at DST in the sandbox. fresh little memory filesystem moment ✨
• --dev DST — Sets up a private /dev at DST in the sandbox. This private /dev will only contain the basic device nodes required for a functioning sandbox (e.g. /dev/null) and no actual devices. no actual devices, just the essentials 🎀
• --dir DST — Creates a directory and all missing parent directories at DST in the sandbox. All directories are created with mode 755 unless the path ends with /tmp or /var/tmp in which case it is created with mode 1777.
• --bind SRC DST — The source path SRC is recursively bind mounted to DST in the sandbox. The mountpoint is created in the sandbox if it does not yet exist. Any missing parent directories in the sandbox are created as well. The source path may optionally be prefixed with a + character. If so, the source path is interpreted relative to the sandbox root directory instead of the host root directory.
• --bind-try SRC DST — Like --bind, but doesn’t fail if the source path doesn’t exist. lowkey forgiving 💖
• --ro-bind SRC DST — Like --bind, but does a recursive readonly bind mount.
• --ro-bind-try SRC DST — Like --bind-try, but does a recursive readonly bind mount.
• --bind-foreign SRC DST — Like --bind, but mkosi-sandbox will allocate a user namespace and provision it with a transient UID range using systemd-nsresourced and then idmap the foreign UID range to this transient UID range using systemd-mountfsd for each --bind-foreign mount. Finally, mkosi-sandbox will join the user namespace just before executing the configure command in the sandbox. Using this option requires systemd-nsresourced and systemd-mountfsd v260 or newer. fancy namespace choreography 🔥
• --ro-bind-foreign SRC DST — Like --bind-foreign, but does a readonly mount.
• --bind-nofollow SRC DST — Like --bind, but does not follow symlinks for SRC. If SRC is itself a symlink, the symlink is bind mounted as-is rather than its target.
• --ro-bind-nofollow SRC DST — Like --bind-nofollow, but does a readonly mount.
• --symlink SRC DST — Creates a symlink at DST in the sandbox pointing to SRC. If DST already exists and is a file or symlink, a temporary symlink is created and mounted on top of DST. symlink sleight of hand 💅
• --write DATA DST — Writes the string from DATA to DST in the sandbox.
• --overlay-lowerdir DIR — Adds DIR from the host as a new lower directory for the next overlayfs mount.
• --overlay-upperdir DIR — Sets the upper directory for the next overlayfs mount to DIR from the host. If set to tmpfs, the upperdir and workdir will be subdirectories of a fresh tmpfs mount.
• --overlay-workdir DIR — Sets the working directory for the next overlayfs mount to DIR from the host.
• --overlay DST — Mounts a new overlay filesystem at DST in the sandbox. The lower directories, upper directory and working directory are specified using the --overlay-lowerdir, --overlay-upperdir and --overlay-workdir options respectively. After each --overlay option is parsed, the other overlay options are reset. so rude, but so organized 🎀
• --unsetenv NAME — Unsets the NAME environment variable in the sandbox.
• --setenv NAME VALUE — Sets the NAME environment variable to VALUE in the sandbox
• --chdir DIR — Changes the working directory to DIR in the sandbox.
• --same-dir — Changes to the working directory in the sandbox to the current working directory that mkosi-sandbox is invoked in on the host. matching dirs, matching vibes 🫶
• --become-root — Maps the current user to the root user in the sandbox. If this option is not specified, the current user is mapped to itself in the sandbox. Regardless of whether this option is specified or not, the current user will have a full set of ambient capabilities in the sandbox. This includes CAP_SYS_ADMIN which means that the invoked process in the sandbox will be able to do bind mounts and other operations. If mkosi-sandbox is invoked as the root user, this option won’t do anything. main character root energy 👑
• --map-foreign — Map the foreign UID range in the sandbox. For more information on the foreign UID range, see Users, Groups, UIDs and GIDs on systemd Systems. When running mkosi-sandbox unprivileged, this option requires systemd-nsresourced v260 or newer.
• --map-delegate N — Map N additional 64K UID/GID ranges in the sandbox. This is needed to execute systemd-nspawn or any program that tries to allocate a transient UID range via systemd-nsresourced from within the mkosi-sandbox environment. This option requires systemd-nsresourced v260 or newer.
• --suppress-chown — Specifying this option causes all calls to chown() or similar system calls to become a noop in the sandbox. This is primarily useful when invoking package managers in the sandbox which might try to chown() files to different users or groups which would fail unless mkosi-sandbox is invoked by a privileged user. chown? never heard of her 💅
• --suppress-sync — Specifying this option causes all calls to sync() or similar system calls to become a noop in the sandbox. This is primarily useful when invoking package managers in the sandbox which might try to sync() files when extracting packages which is unnecessary when building images and slows down execution time significantly. sync? not today, bestie 💀
• --unshare-net — Specifying this option makes mkosi-sandbox unshare a network namespace if possible.
• --unshare-ipc — Specifying this option makes mkosi-sandbox unshare an IPC namespace if possible.
• --pack-fds — Pack inherited file descriptors together starting at file descriptor number 3 and set $LISTEN_FDS to the number of packed file descriptors and $LISTEN_PID to the current process pid.
• --debug — Log various messages describing how the sandbox is set up.
• --version — Show package version.
• --help, -h — Show brief usage information.

🎀 EXAMPLES 🎀

Start bash in the current working directory in its own network namespace as the current user.

mkosi-sandbox --bind / / --same-dir --unshare-net

Run id as the root user in a sandbox with only /usr from the host plus the necessary symlinks to be able to run commands.

mkosi-sandbox \
    --ro-bind /usr /usr \
    --symlink usr/bin /bin \
    --symlink usr/lib /lib \
    --symlink usr/lib64 /lib64 \
    --symlink usr/sbin /sbin \
    --dev /dev \
    --bind /proc /proc \
    --tmpfs /tmp \
    --become-root \
    id

🦋 SEE ALSO 🦋

mkosi(1)

---

💖 and that’s the mkosi-sandbox(1) page from the General Commands Manual, bestie! source/version + date sign-off energy lives in the footer, and we are absolutely not copying the footer line — periodt, slay, bye 💅✨