Sandbox – isolated system for untrusted apps (/dev/sandbox/<user>)
LuxOS Sandbox (package luxos-sandbox, command luxos-sandbox, window Sandbox =
luxos-sandbox-gui) runs and installs applications you do not trust, separated from your files,
your desktop session, other users and the local network.
What /dev/sandbox/<user> is
Each user has one sandbox: a minimal Arch Linux root file system.
- The data lives permanently in
/var/lib/luxos/sandbox/<user>(owned by the user, mode0700). /dev/sandbox/<user>is only a symlink to it./devis a devtmpfs (empty after every boot), so the link is recreated at boot by systemd-tmpfiles from/etc/tmpfiles.d/luxos-sandbox-<user>.conf(written by the helper):L+ /dev/sandbox/<user> - - - - /var/lib/luxos/sandbox/<user>.- The base package
/usr/lib/tmpfiles.d/luxos-sandbox.confcreates/var/lib/luxos,/var/lib/luxos/sandbox(root0755) and/dev/sandbox.
It is not a VM and not a chroot you enter as root: programs are started inside it with
bubblewrap (bwrap, no setuid) as your normal user.
How it is built
luxos-sandbox create calls pkexec /usr/lib/luxos/sandbox/luxos-sandbox-helper create
(polkit action org.luxos.sandbox.create, auth_admin_keep – asks for the administrator password).
The helper:
- runs
pacstrap -c -Kwith the configuration/usr/share/luxos/sandbox/lux.conf(lux.conf format, TOML, converted bylux-configinto the sandbox's own/etc/pacman.conf; mirrors from/etc/lux/mirrorlist) – only official Arch Linux repositories[core]and[extra], no LuxOS repos, no AUR; man pages/docs/most locales are not extracted, - installs a small base:
filesystem bash coreutils pacman archlinux-keyring ca-certificates sed grep gawk findutils tar gzip xz zstd less nano which procps-ng curl file diffutils glibc, - removes setuid/setgid bits and file capabilities, adds user
sandbox(your UID) with home/home/sandbox(withDownloadsandShared), hostnamesandbox, - builds in a hidden
.build-<user>directory,chowns to you and atomically renames it into place, - writes the tmpfiles entry for the
/dev/sandbox/<user>link.
The helper accepts only create|reset|destroy for the calling user (PKEXEC_UID, UID ≥ UID_MIN,
< 60000). Everything else runs without root.
Command line
luxos-sandbox create # create your sandbox (admin password once, takes minutes)
luxos-sandbox status [--json] # path, link, size, installed apps
luxos-sandbox install firefox # install apps from Arch repos into the sandbox
luxos-sandbox remove-app firefox # remove apps from the sandbox
luxos-sandbox run --gui --net firefox # run a GUI app with internet
luxos-sandbox run ./downloaded-program # a host file is COPIED in first, then run
luxos-sandbox shell [--net] [--shared] # interactive bash inside ([sandbox] prompt)
luxos-sandbox reset [--yes] # wipe everything inside and create it again
luxos-sandbox destroy [--yes] # delete the sandbox (~/Sandbox stays)
luxos-sandbox sync-launchers [--json] # update commands/Launchpad entries of sandbox apps
luxos-sandbox trusted-display [CMD on|off] # per-app trusted display (default: untrusted, see below)
Options for run (before the command): --net, --gui, --shared (and --launcher, used by the
generated launchers: a one-line notice in the terminal, cleanup when the sandbox is gone).
| Option | Effect |
|---|---|
| (none) | no network (own loopback only), no window, no shared folder |
--net |
internet only: NAT through pasta; local network and this computer are blocked |
--gui |
the app gets its own nested X server (Xephyr) window "Sandbox - <app>", 1280×800, resizable – never your desktop |
--shared |
~/Sandbox on the host appears as /home/sandbox/Shared |
luxos-sandbox refuses to run as root ("Run luxos-sandbox as a normal user, not root").
Installing apps
The sandbox is a minimal plain Arch Linux, separate from LuxOS: inside it, Arch's own package
manager (the pacman package, with its /etc/pacman.conf generated from the sandbox lux.conf) is
used – this is the only place with a pacman command. install runs pacman -Syu --needed --noconfirm inside the sandbox as a fake root (network is
enabled only for this step) and deletes downloaded packages afterwards. Package names must match
^[a-z0-9@_+][a-z0-9@._+-]*$. Only Arch [core]/[extra] packages are available. Use
luxos-sandbox, not lux, for sandbox apps – lux manages the host system.
Community (AUR) packages
lux install <name> installs packages that exist only in the community source (AUR) into the
sandbox by default (see package-management.md). It uses
luxos-sandbox build-install [--asdeps] [--deps "a b"] <name> with the checked build directory as a
tar archive on standard input:
- as the sandbox's fake root with network:
pacman -Syu --needed base-devel gitand the repository dependencies (--asdeps); - the archive is unpacked into
/home/sandbox/.cache/lux-build/<name>andmakepkg -fruns as the sandbox user with network (the build script never runs on the host); pacman -Uinstalls the built packages (without-debugpackages) and the build directory is deleted.
Errors: "Building %s in the sandbox failed." (the build script failed – see the output above it),
"Installing the build tools into the sandbox failed." (no network or a broken sandbox:
luxos-sandbox reset).
Starting sandbox apps: commands and Launchpad
Apps you install into the sandbox (lux install <AUR name>, luxos-sandbox install, the Sandbox
window) are started like normal apps – nothing to set up:
- Commands: every program in
/usr/binof an app package gets a small wrapper script in~/.local/share/luxos/sandbox/bin/<command>that runsluxos-sandbox run --net --launcher -- /usr/bin/<command> "$@". That folder is always the last entry ofPATH(/etc/profile.d/zz-luxos-sandbox.shat login, the LuxOSbashrc/zshrc/lsh in every new terminal – also in a session started before the update), so a system program of the same name always wins: afterlux install --system pi,piruns/usr/bin/pi. No wrapper is made for a name the system already has, nor forsudo,su,pkexec,passwd,ssh,gpg, shells,lux,luxos-*and similar. - Apps with a window (a
.desktopfile withoutTerminal=true/NoDisplay=true) appear in Launchpad and the menu as "<App> (Sandbox)" (~/.local/share/applications/luxos-sandbox-app-<package>--<id>.desktop), started withluxos-sandbox run --gui --netin its own Xephyr window; the icon is copied from the sandbox (fallback: the Sandbox icon). Their command wrapper also uses--gui. - In a terminal the first start per login prints one dim line: "pi runs in the sandbox: internet only,
no access to your files." – the app sees only
/home/sandbox, not your home. To use a developer or CLI tool with your files, install it into the system:lux install --system <name>. - Network: launchers use
--net(internet only – LAN and this computer stay blocked, see below): most apps installed this way need the internet (AI agents, browsers, chat). For a run without network useluxos-sandbox run -- <command>. - Kept in sync automatically: after
install,build-install,remove-app,reset,destroy, at every login (/etc/xdg/autostart/luxos-sandbox-launchers.desktop) and afterlux update. Unchanged files are not rewritten; stale wrappers/entries/icons are removed (only files carrying theluxos-sandbox launcher/X-LuxOS-Sandbox-Launchermark – your own files are never touched). - Typed a command that is only in the sandbox and the wrapper is missing (e.g. a terminal from
before the update)? The shell's "command not found" handler runs
luxos-sandbox __command-hint, which recreates the wrappers and prints how to start it (luxos-sandbox run --net -- pi, or justpiin a new terminal). Dependencies and base-system commands get no hint. lux remove <name>removes a package that is only in the sandbox from the sandbox (asks first).
Security of the launchers. Everything read from the sandbox is untrusted. sync-launchers reads
the sandbox's package database (/var/lib/pacman/local), .desktop files and icons on the host
without starting the sandbox, but only through directory file descriptors with O_NOFOLLOW
(symlinks pointing anywhere, including inside, are not followed; FIFOs and devices are skipped) and with
size limits. Only explicitly installed packages count (not dependencies, the base system or the build
tools base-devel/git). Command names must match ^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$. No Exec
line or other key is ever copied from a sandbox .desktop file: the program is chosen from the
package's own /usr/bin list, the generated .desktop/wrapper always runs luxos-sandbox run. Only
Name/Comment (control, invisible and bidi characters removed, shortened) and the main freedesktop
Categories are taken. Icons: regular PNG (≤ 1 MiB, ≤ 1024×1024) or SVG (≤ 256 KiB, without
DOCTYPE/entities, scripts, event handlers, foreignObject and external references) from the standard
icon folders, otherwise the Sandbox icon.
Running a downloaded file
If the first argument is a host file (relative path with /, ~/…, or a path under your home, /tmp,
/media, /run/media, /mnt), it is copied into /home/sandbox/Downloads/<name> via stdin by a
process inside the sandbox and made executable; the original location is never mounted.
The Sandbox window
The GUI shows status (Ready / Not created), Create Sandbox, Installed apps (Run / Remove),
Install app (package name), Run app (command or Choose File…), switches Network
(default off), Window (default on = --gui), Shared folder (default off), Open Terminal
(opens luxos-terminal), Open shared folder, Reset…, and a Details log. Each installed app
with a command has a Trusted display check box (default off, asks with a warning before turning on).
What is isolated
- Files:
/inside is a fresh read-only tmpfs; persistent are only the sandbox's own/usr /etc /var /opt /srv /root /mntand/home/sandbox. Your home,/run/user,/media,/sys, host files and other users are not visible./tmpand/runare private tmpfs. - Symlink attacks: the host side never opens sandbox paths by name; directories are opened
component by component with
O_NOFOLLOWand passed to bwrap as file descriptors (--bind-fd). - Processes: own PID namespace;
ptrace,process_vm_readv/writev,pidfd_getfd,kcmpblocked. - Privileges:
--cap-drop ALL,no_new_privs, setuid does not work, single UID. - Namespaces: user/pid/ipc/uts/cgroup/net/mount (
bwrap --unshare-all),--die-with-parent,--clearenv. - Seccomp (x86_64 only, i386/x32 rejected): blocks
mountand the new mount API,pivot_root,chroot(except during install),setns, nested user namespaces (clone3returnsENOSYS), key management,bpf,perf_event_open,userfaultfd,io_uring_*,kexec_*, kernel modules,open_by_handle_at,fanotify_init,syslog, clock changes,swapon,reboot,iopl/ioperm/modify_ldt,ioctl(TIOCSTI/TIOCLINUX), unusual socket families (AF_PACKET,AF_VSOCK, Bluetooth…). - Network: without
--netonly loopback (no host abstract sockets such as the X11 socket). With--net:pasta --no-map-gw -t none -u none -T none -U none; inside, all private ranges (RFC 1918, CGNAT 100.64/10, link-local, ULA, multicast) and all host addresses areprohibitroutes. DNS goes to169.254.1.53, forwarded to the host resolver. - Session: no D-Bus (session or system), no sound (PulseAudio/PipeWire), no Wayland, no host X11, no SSH agent, no keyring.
- Clipboard: not shared (Xephyr has its own).
- Xephyr's link to your desktop (X11 SECURITY extension): on X11 any trusted client can read the
keys typed into other windows, take screenshots and inject input. Xephyr parses X protocol from the
untrusted app, so it runs in its own bwrap (read-only
/usrand/etc/X11, no home, no network, no D-Bus,--cap-drop ALL, the app's seccomp filter,--clearenv) and connects to your desktop with an untrusted authorization from the X server's SECURITY extension, new for every run (XSecurityGenerateAuthorization,untrusted,timeout 0), passed in memory (memfd) – never~/.Xauthorityand never its FamilyWild entry. When the sandbox exits,luxos-sandboxrevokes it (XSecurityRevokeAuthorization; the X server disconnects anything still using it; ifluxos-sandboxdies, the server revokes it when the connection closes). An untrusted client sees onlyBIG-REQUESTSandXC-MISC(noRECORD,XTEST,XInputExtension,MIT-SHM,XKEYBOARD),XQueryKeymapreturns nothing, event selection on other windows is ignored,XGetImageof other windows and of the screen fails andXSendEventinto other windows is refused. Without the SECURITY extension on your display the sandbox window does not start (fail closed); LuxOS's Xorg has it on. GLX inside Xephyr is software rendering (Mesa). - Trusted display (per-app opt-in): the untrusted Xephyr draws without
MIT-SHM, which is slower for video and games. For one command you can turn on Trusted display next to the app in the Sandbox window (with a warning) or runluxos-sandbox trusted-display COMMAND on|off(~/.config/luxos/sandbox/trusted-display; list withluxos-sandbox trusted-display). It is still a temporary authorization for that run only (leveltrusted), Xephyr stays confined and only shares the IPC namespace forMIT-SHM. The default is always untrusted. - Resources:
systemd-run --user --scopewithMemoryMax=50%,MemorySwapMax=1G,TasksMax=512,CPUQuota= 75 % of all cores (without a user systemd only a warning).
Environment inside: HOME=/home/sandbox, USER=sandbox, LUXOS_SANDBOX=1, LANG=C.UTF-8.
What is NOT isolated (threat model)
- Kernel bugs: the sandbox shares the kernel; a kernel exploit can escape. For really dangerous software use a virtual machine.
- Unprivileged user namespaces must be enabled in the kernel (bwrap without setuid).
- Xephyr: a Xephyr bug could give code execution outside the app's sandbox – but only inside Xephyr's
own confinement (no home, network or session) and with an untrusted link to your desktop. The SECURITY
extension does not stop
XGrabKeyboard: a hijacked Xephyr could actively take over the keyboard (what you type then goes to it). This is visible – the window you type into stops receiving text and loses focus; passive keylogging of other windows is not possible. With Trusted display a hijacked Xephyr could watch, capture and control your desktop. Apps in the same Xephyr window can see each other (keylogging between them is possible). No window manager inside, so windows have no decorations. - Flatpak apps (Flathub) are not the Sandbox: a Flatpak app with the
x11/fallback-x11permission gets your desktop's X socket and your trusted cookie in an X11 session (Flatpak copies it fromXAUTHORITY), so it can read keys, take screenshots and inject input. LuxOS does not wrap Flatpak or change its default permissions (apps start with plainflatpak run). Use the Sandbox for untrusted programs with a window. - Terminal:
shell/runin a terminal share the terminal (for Ctrl+C/job control);TIOCSTIis blocked, but escape sequences can still reach the terminal emulator. - Shared folder: anything written to
~/Sandboxis untrusted (malicious documents, symlinks). - With
--net: the app can do anything on the internet from your IP address. Networks that appear on the host after start are not blocked by host-address rules (private ranges always are). - Installs: the sandbox's package manager runs as a fake root with one UID;
chown*()pretends to succeed, so system services needing separate system users or setuid will not work; some hooks print errors. Signature checks use the sandbox's own keyring, which the sandbox itself can change. - Disk: no quota – the sandbox can fill
/var. - Timing/side channels (Spectre etc.) are not addressed.
The full threat model is installed as /usr/share/doc/luxos-sandbox/SECURITY.md. The repository has an
automated isolation test (packages/luxos-sandbox/tests/isolation-test.sh).
Reset and removal
luxos-sandbox reset --yes(or Reset… in the window) – deletes everything inside and runs pacstrap again. Use it when the sandbox is damaged (e.g. error "The sandbox is damaged … Run: luxos-sandbox reset").luxos-sandbox destroy --yes– deletes/var/lib/luxos/sandbox/<user>, the tmpfiles entry and the/dev/sandbox/<user>link.~/Sandboxon the host is kept.
See also: Safe, Configuration.