Guide for AI assistants on LuxOS
How an AI assistant (LuxAI, Lux Code or any other agent) should perform common tasks safely on a LuxOS computer. LuxOS is Arch-based, but several Arch habits are wrong here.
Golden rules
- Use
lux, neverpacman. There is nopacmancommand and no/etc/pacman.confor/etc/pacman.d— never suggest them,yay,paruorpacman-contribtools. Installlux install NAME, removelux remove NAME, updatelux update, searchlux search TERM, infolux info NAME, owner of a filelux owns PATH. Repositories, held packages and mirrors are in/etc/lux/lux.conf(LuxOS format, not pacman INI) and/etc/lux/mirrorlist; see package management. The engine tools in/usr/lib/lux/alpm/bin(lux-engine,lux-engine-key,lux-engine-conf) are only for advanced cases (read-onlylux-engine -Q…, importing a repository key); never change packages with them. - Never guess, ask for, store or pipe passwords. Do not run
echo PASSWORD | sudo -S, do not ask the user to type a password into the chat. LuxOS tools request administrator rights themselves:luxusessudoin a terminal and a polkit dialog (pkexec) when it has no terminal but a graphical session; the user types the password in that dialog. - Confirm before changing the system.
luxalways asks[Y/n]; pass-yonly after the user agreed in the conversation (e.g.lux -y install gimp). Without a terminal, run it with stdin not attached to a TTY so the graphical polkit prompt is used. - Prefer the LuxOS app or command made for the task (table below) over editing config files.
LuxOS defaults live in
/etc/xdg/luxos; user changes go to~/.config. Never edit files under/usr– they are replaced by updates. - Do not touch secrets. Never print
luxos-account tokenor~/.config/luxai/account.json; useluxos-account status. Never ask for or handle the Safe password. - No partial updates. Do not refresh databases without upgrading;
lux updatedoes the full, correct sequence (keys first, then everything). - Community (AUR) packages: never install them yourself.
lux installtries the repositories, LuxOS apps and Flathub first; a package that exists only in the community source (AUR) is built by the user in a terminal (lux install NAME, no sudo) and goes into their sandbox by default –--systemonly on the user's explicit request. LuxAI's agent is refused by lux. Tell the user that community packages are not checked by LuxOS. - Printer or scanner driver missing? Prefer the verified package from
[luxos-drivers](lux-engine -Ss NAME, thenlux install NAME) over building the same driver from the AUR; the printing helper installs it by itself when the printer is connected (pkexec /usr/lib/luxos/printing/luxos-printing-helper sync). - Root shells are rarely needed. Use
pkexecfor a single command that really needs root (wheel users may also usesudoin a terminal); don't start interactive root shells.
Which tool for which task
| Task | Use | Notes |
|---|---|---|
| Install / remove / update software | lux install, lux remove, lux update; GUI: LuxOS Store (luxos-store [search]) |
Store shows repo desktop apps, [luxos-apps], .lux apps and Flathub search results (no AUR) |
| Automatic updates, update status | Software Update (luxos-update), luxos-care status |
mode: luxos-care mode carefree\|classic (root) |
| CPU scheduler (scx_lavd / kernel) | luxos-care scheduler; sudo luxos-care scheduler lavd\|default |
/etc/luxos/scheduler.conf, luxos-scheduler.service; system.lsl kernel.scheduler |
| Fix a locked package database / keys | lux fix |
never delete /var/lib/lux/db.lck during an update |
| Add a repository, hold a package, mirrors | /etc/lux/conf.d/NAME.conf with [repo.NAME] + server = "URL"; hold = ["PKG"] in [packages] of /etc/lux/lux.conf (TOML); lux mirrors |
check with lux config check; multilib: sudo /usr/lib/lux/lux-config enable-repo multilib |
| System health | lux doctor |
|
| Drivers | Drivers (luxos-drivers), lux drivers, luxos-hwdetect --report |
restart after installing |
| Wallpaper, light/dark/auto, Dock, top bar, boot splash | Desktop & Dock (luxos-settings); luxos-appearance light\|dark\|auto\|toggle\|wallpaper FILE\|bar-opacity N\|dock-opacity N |
|
| Monitors, arrangement, main display, resolution, rotation, text size | Displays (luxos-display-settings); Screens in Control Center, luxos-displays menu (Super+P) |
changes revert after 15 s unless kept |
| Router admin page, network details, devices on the LAN, ping/DNS test | Router app (luxos-router), see network-admin.md |
router page opens only LAN addresses; never store router passwords |
| Keyboard layouts | Keyboard Layouts (luxos-keyboard) |
system-wide via localectl, needs polkit |
| Keyboard shortcuts | Keyboard Shortcuts (luxos-shortcuts) |
xfconf channel xfce4-keyboard-shortcuts |
| Battery, power mode, sleep, lid | Battery & Power (luxos-power) |
|
| Battery Saver / Data Saver | luxos-powersaver on\|off\|toggle\|status, luxos-datasaver on\|off\|toggle\|status |
also Control Center tiles |
| Bluetooth | Bluetooth (luxos-bluetooth) |
|
| Fingerprint login | Fingerprint (luxos-fingerprint) |
password always works too |
| Screen saver, lock delay | Screen Saver & Lock (luxos-lock-settings); lock now: xflock4 |
|
| Quick toggles (Wi-Fi, DND, dark mode, savers, brightness, volume) | Control Center (luxos-control-center) |
|
| Printers, scanners | Printers & Scanners (luxos-printers, --add), Scanner (luxos-scan) |
|
| Screenshots, screen recording | luxos-screenshot (--screen, --portion, --window, --record-screen, --stop) |
never capture the screen without the user asking |
| Send files to phones / other PCs | LuxDrop (luxdrop) |
LocalSend compatible |
| Find a place or address, plan a route (car/bike/walk/public transport), departures from a stop, places nearby, "where am I", show something on a map | luxos-maps --json search\|reverse\|route\|transit-route\|timetable\|nearby\|where-am-i\|open … |
JSON on stdout; see Maps and places |
| Encrypted folder | Safe (luxos-safe; luxos-safe status, luxos-safe lock) |
user unlocks in the dialog |
| Run untrusted software | Sandbox (luxos-sandbox) |
see below |
| Why a downloaded program does not start, restore deleted files | Lux Guard (luxos-guard scan FILE, luxos-guard list, luxos-guard restore PATH) |
see below |
| Back up to an external/network disk, restore an older version, restore everything on a new install | Backups (luxos-backup status, luxos-backup list, luxos-backup restore [--from TIME] PATH, luxos-backup restore --all --source DISK) |
backups.md |
| LuxAI account | LuxAI Account (luxos-account), luxos-account login\|status\|logout |
|
| System info | About This Computer (luxos-about), about os, fastfetch, cat /etc/os-release |
|
| Processes, force quit | System Monitor (luxos-monitor, Super+Alt+Esc) |
|
| Feedback / bug report | luxos-feedback |
|
| Other Xfce settings | xfce4-settings-manager (Super+,), xfce4-power-manager-settings, /usr/bin/xfce4-keyboard-settings (key repeat) |
some Xfce dialogs are redirected to LuxOS apps |
Common admin tasks
Install an app
lux search inkscape # find the exact name
lux info inkscape # check what it is
lux install inkscape # asks [Y/n], then for the admin password
Flatpak (if installed): lux install org.gimp.GIMP. A local file: lux install ./app.lux or
lux install ./pkg.pkg.tar.zst. LuxOS apps: lux install lsl, lux install lux-code,
lux install lsl-ide.
Update the system
Run lux update (or press Update Now in Software Update). Afterwards: if lux says the kernel
was updated, suggest a restart; unmerged config file: lux config-diff <file>.
Services
Standard systemd: systemctl status NAME, pkexec systemctl restart NAME. Do not disable LuxOS
units (luxos-care-*, luxos-safe-guard, luxos-guard, earlyoom) unless the user explicitly asks.
Users, hostname, time zone
Standard Arch tools work (hostnamectl, timedatectl, useradd -s /usr/bin/lsh); new users get
the lsh shell, and members of wheel may use sudo. Keyboard layouts must go through Keyboard
Layouts (it also sets the login screen).
Change a desktop setting from a script
Only inside the user's own graphical session: xfconf-query -c CHANNEL -p PROPERTY -s VALUE, or
the luxos-appearance / luxos-displays commands. Never run GUI tools, xrandr or xfconf changes
against a display that is not the user's active session. Reset with xfconf-query … -r.
Maps and places
For places, addresses, distances, travel times, directions, public transport and nearby places use
the Maps command-line interface instead of scraping map or timetable websites. It prints one JSON
object, never opens a window (except open) and shares the app's caches and rate limits
(OpenStreetMap, Transitous and Overpass: at most 1 request per second for the whole computer – do
not loop over many places, never bulk-geocode, scan areas or poll departures).
luxos-maps --json search "Karlovo náměstí, Praha" # results[]: name, address, lat, lon, geo_uri, osm_url
luxos-maps --json search "pharmacy" --near 50.08,14.42 # prefer results near a point
luxos-maps --json reverse 50.0757,14.4199 # place: address of a point
luxos-maps --json route "Praha hlavní nádraží" "Pražský hrad" --mode walk # car|bike|walk|transit
luxos-maps --json route here "Brno" --mode car # "here" = the user's location (needs permission)
luxos-maps --json transit-route "Karlovo náměstí, Praha" "Pražský hrad" # public transport, now
luxos-maps --json transit-route here "Brno hlavní nádraží" --time 2026-08-24T10:00:00+02:00 --arrive
luxos-maps --json timetable "Karlovo náměstí, Praha" # next departures at stops within 500 m
luxos-maps --json timetable --stop-id cz-PID_U237Z3P --type arrivals # one stop (stop_id from transit-route)
luxos-maps --json nearby here --category pharmacies # nearest first; --radius M, --limit N
luxos-maps --json nearby 50.0757,14.4199 --name "Lidl" # by name
luxos-maps --json where-am-i # lat, lon, accuracy_m, source (geoclue|ip)
luxos-maps --json open "Pražský hrad" # show a place in the Maps window
luxos-maps --json open --route here "Pražský hrad" --mode transit # show a route in the Maps window
luxos-maps --render-preview route.json --size 480x270 --out /tmp/route.png # route picture (PNG)
routereturnsdistance_m,duration_s, readabledistance/durationandsteps[](instruction,street,distance_m,lat,lon). Instructions are in English; translate them for the user.{"ok": false, "error": "NoRoute"}means there is no route.transit-routereturnsitineraries[](default 3):departure_time/arrival_time(HH:MM, in the local time zone of the stops –timezone), ISOdeparture/arrival,duration,transfers,realtime,cancelled, a ready Englishsummaryandlegs[](mode_name,line,headsign,operator,from/towithname,platform,stop_id, times,delay_min,realtime,cancelled). Mention delays (delay_min> 0), platform changes (platform_changed) and cancellations.NoRoute= no connection at that time; the coverage depends on open timetable data (some regions have none).timetablereturnsconnections[](time,scheduled_time,delay_min,line,headsign,stop,platform,realtime,cancelled,operator,summary). Times are live whenrealtimeis true, otherwise planned.nearbycategories:restaurants,cafes,groceries,fuel,charging,parking,pharmacies,hospitals,hotels,attractions,public_transport,toilets,playgrounds. Results:name,distance,address,opening_hours,phone,website,osm_url,geo_uri.- Times for
--time: ISO 8601 with a time zone (2026-08-24T10:00:00+02:00) orHH:MM(today, local time); omit for now.--arrivemakes it the latest arrival. {"ok": false, "error": "busy"}: Transitous or the public Overpass server is overloaded (Maps then waits 30 s). Tell the user and try once later – do not retry in a loop.- Location is private.
where-am-iandherework only after the user allowed My Location in the Maps app; otherwise the answer is{"ok": false, "error": "consent"}– tell the user to open Maps and click the location button once. Never try other ways to find the user's location. - Always mention the
attributionfield when you present the data: "© OpenStreetMap contributors" for map data, and for public transport "Transitous and its open-data providers" (https://transitous.org/sources/). - A
geo:link (geo_uri) opens in Maps for the user;osm_urlopens openstreetmap.org in the browser. - Route card picture:
routeandtransit-routeincludepreview(start, end,bboxsouth/west/north/east,legs[]withcolorand Google-encodedpolyline+precision). Do not passpreviewto the language model (it is only coordinates); save the JSON to a file and runluxos-maps --render-preview FILE --size 480x270 --out FILE.pngto get the card image (uses the Maps tile cache, downloads only that picture's few tiles).--itinerary Ndraws another connection (needstransit-route --geometry). - Details: maps.md.
Map tools for LuxAI (same as LuxAI on the phone)
The tool definitions of the LuxAI phone app map 1:1 to these commands, so a built-in desktop tool is
a thin wrapper (coordinates as LAT,LON):
| Tool | Command |
|---|---|
map_geocode(query, country_codes?, language?, limit 1-10 = 5) |
search QUERY --limit N |
map_reverse(latitude, longitude, zoom 3-18?, language?) |
reverse LAT,LON |
map_nearby(latitude, longitude, category?, query?, radius_meters 50-10000 = 1500, limit 1-50 = 20) |
nearby LAT,LON --category C --name QUERY --radius R --limit N |
map_route(start_latitude, start_longitude, end_latitude, end_longitude, travel_mode driving\|walking\|cycling = driving) |
route A B --mode car\|walk\|bike |
map_transit_route(start_*, end_*, time?, arrive_by = false, max_transfers 0-8 = 3, limit 1-5 = 3) |
transit-route A B --time T [--arrive] --max-transfers N --limit N |
transit_timetable(latitude, longitude, time?, type departures\|arrivals, radius_meters 25-2000 = 500, limit 1-12 = 8, language?) |
timetable LAT,LON --type TYPE --time T --radius R --limit N |
current_location() |
where-am-i (only with the user's permission in Maps) |
Rules from the phone tool descriptions: resolve names to coordinates first (map_geocode) and
never guess coordinates; inspect alternatives for ambiguous places; route durations are estimates
without live traffic; transit times are time-dependent (omit time for now, otherwise ISO 8601
with offset); current_location only when the user explicitly asks for something near them or
from where they are – never proactively, repeatedly or in the background.
country_codes and language of map_geocode/map_reverse are not needed on LuxOS (Maps uses
the system language and prefers places near the map/the --near point).
LuxAI (native, from 1.0) has built-in tools map_geocode, map_reverse, map_nearby, map_route,
map_transit_route, transit_timetable, current_location (Chat and Agent, read-only) and map_open
(Agent, open apps permission); they call these commands and show a route card with a preview. Other
assistants run the commands directly (read-only, except open and --render-preview).
Sandbox for untrusted programs
luxos-sandbox gives each user an isolated minimal Arch system at /dev/sandbox/<user> (a link
to /var/lib/luxos/sandbox/<user>), started with bubblewrap, seccomp and no access to the user's
files, D-Bus, sound or the local network.
luxos-sandbox create # once, asks for the admin password
luxos-sandbox install firefox # Arch [core]/[extra] packages, inside the sandbox
luxos-sandbox run --gui --net firefox # own Xephyr window, internet only
luxos-sandbox run ./downloaded-file # the file is copied in, never mounted
luxos-sandbox reset --yes # wipe and recreate
Use luxos-sandbox install, not lux, for sandbox apps. It is not a VM – kernel exploits can
escape; for clearly malicious software recommend a virtual machine. Details: sandbox.md.
Lux Guard
Lux Guard checks programs and scripts from downloads, attachments and USB drives when they start.
"Permission denied" for such a file usually means Lux Guard refused it: run luxos-guard scan FILE
(reasons, origin) and journalctl -t luxos-guard -n 20, then explain the reason. Critical files
(wiping the disk or home, ransomware, hidden code) run only in the Sandbox – recommend Run in
Sandbox or deleting the file; never stop the service, never use luxos-guard allow --force and
never copy or rewrite the file to get around the check. Deleted or encrypted files can be restored
from hourly snapshots: luxos-guard snapshots, luxos-guard restore [--from TIME] [--overwrite] PATH
(as the user). Details: guard.md.
Safe (encrypted folder)
/safe/<user> is unlocked only by the user in the Safe dialog (luxos-safe unlock --open). While
unlocked, every process of the same user can read it, so do not read Safe files unless the user asks.
It always locks on sleep and logout. Never chattr, chmod or force-unmount anything under /safe.
Details: safe.md.
LSL on LuxOS
LSL (Lux Simple Lang) is installed with lux install lsl (/usr/bin/lsl). Run lsl file.lsl,
compile lsl compile file.lsl out, help lsl help, offline manual lsl man. In the lsh shell
LSL lines can be typed directly (print 6 * 7). The language reference is in the LSL collection,
starting at LSL overview.
Things that are different from Arch Linux
- No
pacman, noyay/paruneeded –luxcovers repositories, Flathub, community/AUR (sandbox) and.lux. - No
/etc/pacman.conf: configuration is/etc/lux/lux.conf(TOML tables,hold = [...]instead ofIgnorePkg; the old 0.9 format is still read, seelux.md), database/var/lib/lux, cache/var/cache/lux/pkg, log/var/log/lux.log, keyring/etc/lux/keyring. The engine is based on Arch's libalpm (pacman code). - Default shell is
lsh(bash-compatible).~/.lshrcinstead of~/.bashrc. - Kernel is
linux-luxos(own LuxOS kernel; older installs switch fromlinux-zenautomatically); initramfs built withmkinitcpio; Btrfs subvolumes@,@home,@log,@cache,@tmp. - Desktop defaults are in
/etc/xdg/luxos, LuxOS state files in~/.config/luxos(configuration.md). - earlyoom, not systemd-oomd, handles low memory; zram is the swap.
- Updates may run automatically in the background (LuxOS Care); if the package database is locked, wait instead of forcing.
/usris usually read-only (system protection): never copy files into it, install withlux; own programs go to/usr/localor~/.local. "Read-only file system" in/usris expected (system-protection.md).
Manual pages
The same documentation is installed as manual pages (generated from these files, so they never
differ): man luxos (overview: what is where), man lux and man lux.conf (packages and
/etc/lux/lux.conf), man luxos-care, man luxos-sandbox, man luxos-safe, man luxos-guard, man luxos-backup,
man luxdrop, and for LSL man lsl (command line), man 7 lsl (language and standard library)
and man lslc. Suggest them to users who prefer the terminal; man -k luxos lists them.
When something fails, follow troubleshooting.md and report the exact error message to the user instead of guessing.