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, mode 0700).
  • /dev/sandbox/<user> is only a symlink to it. /dev is 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.conf creates /var/lib/luxos, /var/lib/luxos/sandbox (root 0755) 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:

  1. runs pacstrap -c -K with the configuration /usr/share/luxos/sandbox/lux.conf (lux.conf format, TOML, converted by lux-config into 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,
  2. 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,
  3. removes setuid/setgid bits and file capabilities, adds user sandbox (your UID) with home /home/sandbox (with Downloads and Shared), hostname sandbox,
  4. builds in a hidden .build-<user> directory, chowns to you and atomically renames it into place,
  5. 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:

  1. as the sandbox's fake root with network: pacman -Syu --needed base-devel git and the repository dependencies (--asdeps);
  2. the archive is unpacked into /home/sandbox/.cache/lux-build/<name> and makepkg -f runs as the sandbox user with network (the build script never runs on the host);
  3. pacman -U installs the built packages (without -debug packages) 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/bin of an app package gets a small wrapper script in ~/.local/share/luxos/sandbox/bin/<command> that runs luxos-sandbox run --net --launcher -- /usr/bin/<command> "$@". That folder is always the last entry of PATH (/etc/profile.d/zz-luxos-sandbox.sh at login, the LuxOS bashrc/zshrc/lsh in every new terminal – also in a session started before the update), so a system program of the same name always wins: after lux install --system pi, pi runs /usr/bin/pi. No wrapper is made for a name the system already has, nor for sudo, su, pkexec, passwd, ssh, gpg, shells, lux, luxos-* and similar.
  • Apps with a window (a .desktop file without Terminal=true/NoDisplay=true) appear in Launchpad and the menu as "<App> (Sandbox)" (~/.local/share/applications/luxos-sandbox-app-<package>--<id>.desktop), started with luxos-sandbox run --gui --net in 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 use luxos-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 after lux update. Unchanged files are not rewritten; stale wrappers/entries/icons are removed (only files carrying the luxos-sandbox launcher / X-LuxOS-Sandbox-Launcher mark – 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 just pi in 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 /mnt and /home/sandbox. Your home, /run/user, /media, /sys, host files and other users are not visible. /tmp and /run are private tmpfs.
  • Symlink attacks: the host side never opens sandbox paths by name; directories are opened component by component with O_NOFOLLOW and passed to bwrap as file descriptors (--bind-fd).
  • Processes: own PID namespace; ptrace, process_vm_readv/writev, pidfd_getfd, kcmp blocked.
  • 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 mount and the new mount API, pivot_root, chroot (except during install), setns, nested user namespaces (clone3 returns ENOSYS), 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 --net only 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 are prohibit routes. DNS goes to 169.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 /usr and /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 ~/.Xauthority and never its FamilyWild entry. When the sandbox exits, luxos-sandbox revokes it (XSecurityRevokeAuthorization; the X server disconnects anything still using it; if luxos-sandbox dies, the server revokes it when the connection closes). An untrusted client sees only BIG-REQUESTS and XC-MISC (no RECORD, XTEST, XInputExtension, MIT-SHM, XKEYBOARD), XQueryKeymap returns nothing, event selection on other windows is ignored, XGetImage of other windows and of the screen fails and XSendEvent into 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 run luxos-sandbox trusted-display COMMAND on|off (~/.config/luxos/sandbox/trusted-display; list with luxos-sandbox trusted-display). It is still a temporary authorization for that run only (level trusted), Xephyr stays confined and only shares the IPC namespace for MIT-SHM. The default is always untrusted.
  • Resources: systemd-run --user --scope with MemoryMax=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-x11 permission gets your desktop's X socket and your trusted cookie in an X11 session (Flatpak copies it from XAUTHORITY), so it can read keys, take screenshots and inject input. LuxOS does not wrap Flatpak or change its default permissions (apps start with plain flatpak run). Use the Sandbox for untrusted programs with a window.
  • Terminal: shell/run in a terminal share the terminal (for Ctrl+C/job control); TIOCSTI is blocked, but escape sequences can still reach the terminal emulator.
  • Shared folder: anything written to ~/Sandbox is 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. ~/Sandbox on the host is kept.

See also: Safe, Configuration.