User guide

A practical guide to trying, installing and using the Debian 13 Openbox setup. ErdOS 1 Alpha 1 is an experimental amd64 release; start in a VM and keep backups before installing on real disks.

Try the live desktop

  1. Download the ISO and checksum from GitHub Releases and verify the download.
  2. Attach the ISO to a VM, or use an image writer to write it to a USB device. Writing an image erases that USB device; copying the ISO file onto a formatted drive is not the same operation. Debian documents USB installation media.
  3. Use a 64-bit Intel/AMD system and disable Secure Boot. Choose Try ErdOS in the boot menu.
  4. At the console, log in as user with password live. Openbox starts automatically on tty1.

The public live account has sudo access. There is no SSH server, graphical login manager or configured persistence. Live-session changes disappear on reboot. Other virtual consoles stay in text mode.

Choose Logout in the right-click menu to end the graphical session and return to a fresh login prompt. Log in again to start Openbox.

Verify a download

Put the ISO and erdos-amd64.iso.sha256 from the same release in one directory, then run:

sha256sum -c erdos-amd64.iso.sha256

The result should say erdos-amd64.iso: OK. If it fails, do not boot that copy; check that the files came from the same release and download again. SHA256SUMS verifies all uploaded release assets when they are present together.

A checksum detects changed bytes. An unsigned checksum does not prove a publisher’s identity.

Install to disk

Installation starts from Install ErdOS (offline) in the ISO’s boot menu. Reboot out of the live desktop to select it. The official Debian text installer copies the configured desktop and sets up accounts and GRUB.

Choose language, keyboard, timezone, account details and partitioning. Installation runs entirely from the USB without Ethernet-driver, Wi-Fi, DHCP, NTP or mirror-download questions. Available firmware is retained for the installed desktop. Internet access is not needed to install; connect after the first boot. Specialized hardware may still need additional drivers.

Your first installed account gets sudo access using its own password. There is no separate root-password question, package-selection screen or mirror-country/server/proxy selection. BIOS bootloader destination selection remains manual.

Replace the entire disk

  1. Back up anything you need from the destination disk.
  2. Choose Guided — use entire disk.
  3. Select the intended disk by its model and capacity. Check carefully when several disks or USB devices are connected.
  4. Choose a partition layout and review the resulting plan.
  5. Approve the final Write the changes to disks? prompt only when the listed disk and partitions are correct.

Whole-disk installation erases the selected disk when you confirm. ErdOS does not preselect a destination disk or preapprove erase/write questions.

Installer asking which of two virtual disks to partition
The manual disk picker in a two-disk VM test. Your device names and capacities will differ.

Install alongside another OS

  1. Back up the existing system. In that OS’s disk-management tools, shrink its partition and leave at least 20 GB of unallocated space. Free space inside its filesystem is not enough.
  2. Boot the ErdOS USB in the same BIOS/UEFI mode as the existing OS.
  3. Choose Guided — use the largest continuous free space. If unavailable, stop and prepare sufficient unallocated space first.
  4. Check that only new Linux partitions will be formatted. Preserve the existing OS partitions and, on UEFI systems, its EFI System Partition.
  5. Review the plan and the final write confirmation before approving.

Do not choose whole-disk partitioning for an alongside installation. GRUB can detect another OS, but encrypted systems, Windows/macOS and unusual firmware may require additional boot configuration; those setups have not been tested by this project.

Final confirmation listing the partitions to format, with No selected
The final write prompt defaults to No and lists exactly what will be changed.

First boot

Remove the ISO/USB when installation finishes, boot the installed system and log in with the account you created. Openbox starts on tty1. Connect to Wi-Fi using Settings → Network. Test administrative access with sudo -v, entering your normal account password, then run sudo apt update.

APT is already configured for Debian Trixie, updates, security and non-free firmware. No manual mirror setup or source-file editing is needed. Live and installed sessions share signed HTTPS repositories. Automatic clock synchronization starts when a time server is reachable. The installer writes repository settings locally; the first apt update downloads their indexes after you connect.

Desktop and applications

Right-click the desktop for Sakura, Chromium, PCManFM and Twig. The Applications submenu reads installed desktop entries when opened, so added or removed graphical applications appear without a polling daemon or APT hook. Command-line tools need a desktop entry to show there.

The desktop has no panel or tray. Use Super+Space or the Menu key for the Openbox menu, Super alone or Super+O for windows, and Super+Shift+O for workspaces. Settings provides sound, network, battery and time controls. Openbox briefly shows its own popup when switching workspaces.

  • Audio: open Settings → Sound to choose output/input devices, adjust volume or mute. Supported volume and mute keys also work.
  • Networking: open Settings → Network to enable Wi-Fi, refresh networks, connect or manage saved connections. Advanced profiles are available through Network Connections in Applications.
  • Bluetooth: open Settings → Bluetooth to scan, pair and connect devices.
  • Battery: open Settings → Power for charge, charging status and hardware-reported health.
  • Clock: open Settings → Date & Time for the current time, time zone and automatic synchronization status.
  • Files: PCManFM handles USB mounting and network shares. Open smb://server/share for SMB; automatic Windows WS-Discovery browsing is not guaranteed. SFTP uses the SSH client.
  • Text: Twig opens plain text and common source files by default. Mounted shares are exposed through GVfs FUSE for editor access.
  • Touchpad: natural scrolling, two-finger scrolling and two-finger right-click are enabled on supported devices.

Network passwords are requested when needed; there is no bundled desktop keyring. Most manuals, package documentation and non-English translations are trimmed. Package copyright notices remain.

The bottom of the right-click menu contains Logout, Reboot and Power off. Logout ends both X and the tty1 login session.

Disk and memory usage

The November 16, 2026 image used approximately 1.86 GiB installed and 379.8 MiB of RAM at idle in this VM measurement. These are observed usage figures, not minimum hardware requirements.

A fresh UEFI installation on a 24 GiB virtual disk, with two virtual CPUs, 2 GiB of RAM, and a 1280 × 800 display. The ISO was removed before booting the installed system. No packages were added, removed or upgraded, and no APT indexes were downloaded.

Disk usage counts used filesystem blocks on the ext4 root and FAT EFI filesystems, including their metadata. It excludes unused space and the separate 1.25 GiB swap partition created by guided partitioning. 1,994,240,000 bytes were used on root and 311,296 bytes on EFI: 1,994,551,296 bytes total.

RAM is MemTotal − MemAvailable from /proc/meminfo, which accounts for reclaimable memory. The figure is the median of five samples taken ten seconds apart after letting the normal desktop settle for two minutes. The panel-free desktop, file-manager daemon, gesture/workspace listener, audio, NetworkManager and time-sync service ran normally; no application windows were open. The serial console shell and Python sampler are included in the RAM measurement. Swap use was 0 bytes. The VM had no network or Bluetooth adapter; Bluetooth is enabled by default but its service stays inactive without hardware.

Hardware, drivers, updates and opened applications change these numbers. GiB and MiB use powers of 1024. Allow additional space for packages and your files; the installation guide recommends leaving at least 20 GB available.

November 16 build: raw measurements and tested ISO checksum

Settings

Press Super + I or choose Settings in the desktop right-click menu. Appearance, Touchpad, Keyboard, Menu, Gestures, Displays, Sound, Network, Bluetooth, Power and Date & Time share one window. Use the Apply button for the setting you change; connection and pairing actions use their own buttons. Power is an information page.

Change themes, fonts, desktop color; edit shortcuts, add custom application commands and change swipe actions; adjust touchpad behavior, automatic monitor extension, brightness, audio and Wi-Fi. The app reuses Python and GTK already in ErdOS and closes completely when you close its window.

Displays lists advertised resolutions with a 15-second Keep/Revert confirmation. Confirmed modes are restored at login for the same outputs. Power shows battery information; Date & Time lets you view the clock, change the system time zone and check automatic time synchronization. Bluetooth supports scanning, pairing, connection and trusted devices. Advanced network profiles use the existing Network Connections app. Controls, persistence and limitations. View the November 16 Settings screenshot (before the Menu tab and custom shortcuts were added).

Settings sectionControls
AppearanceGTK theme, font, dark preference and desktop color
TouchpadScrolling direction, tap to click, two-finger right-click and pointer speed
KeyboardWorkspaces, Super-only overview, existing shortcuts and custom commands
MenuAdd, edit, delete and reorder right-click menu entries
GesturesSwipe distance and actions
DisplaysResolution, automatic monitor extension and laptop brightness
SoundOutput/input devices, volume and mute
NetworkWi-Fi and saved connections
BluetoothAdapter power, scan, pair, connect, trust and forget
PowerBattery and external-power information; no sleep-policy controls
Date & TimeCurrent time, time zone and automatic synchronization

Keyboard shortcuts

Super is usually the Windows key. The number-row workspace bindings use physical X11 keycodes. Keypad tiling supports either NumLock state.

ShortcutAction
Super + Enter / Ctrl + Alt + TOpen Sakura
Super + BOpen Chromium
Super + EOpen PCManFM
Super + IOpen ErdOS Settings
Super + TOpen Twig
Super + Q / Alt + F4Close focused window
Super + HMinimize
Super alone / Super + O / EscapeOpen / dismiss the window overview
Super + Shift + OWorkspace overview
Super + Space / MenuOpenbox menu
Ctrl + Super + Left / RightCycle windows directly (gesture fallback)
Super + Tab / Shift + Super + TabCycle windows forward / backward
Shift + Super + top-row 1–9Switch an existing workspace
Super + F1–F9Alternative workspace switching
Ctrl + Shift + Super + top-row 1–9Move a window to that workspace without following
Super + Left / RightTile left / right half
Super + Up / Super + MMaximize
Super + DownRestore original size and position after tiling/maximizing
Super + numpad 4 / 6 / 8 / 2Tile left / right / top / bottom half
Super + numpad 7 / 9 / 1 / 3Tile top-left / top-right / bottom-left / bottom-right quarter
Super + numpad 5Maximize
Alt + left-drag / right-dragMove / resize a window
Print ScreenSave full desktop screenshot
Alt + Print ScreenSave active-window screenshot
Shift + Print ScreenSelect an area for a screenshot

Screenshots save silently to ~/Pictures/Screenshots. Repeated tiling and maximization retain a window’s original geometry until restored; restore also keeps the window visible if its former monitor has been unplugged.

Hardware keys

Standard volume, speaker mute and microphone mute keys are bound through PipeWire’s wpctl. Volume steps are 5%, capped at 100%. Screen brightness uses 5% steps and keyboard backlights use 10% steps through brightnessctl, when the hardware provides suitable controls. External-monitor DDC brightness is not included.

Fn/media-key mode is usually controlled by keyboard firmware. In a VM, the host or viewer can intercept keys before ErdOS receives them. Test the viewer’s send-key or keyboard-grab options before changing guest bindings.

Touchpad gestures

On a compatible touchpad, ErdOS uses this swipe layout. A clear swipe triggers once after crossing a deliberate movement threshold, before you lift your fingers. Small movements and ambiguous diagonal swipes are ignored. Windows do not follow your fingers through an animation.

SwipeAction
3 fingers upShow the open-window overview
3 fingers downClose the overview
3 fingers left / rightPrevious / next window on the current workspace
4 fingers left / rightNext / previous workspace, wrapping at the ends

Dynamic workspaces keep one empty workspace after the last occupied or current one. Switching to that spare creates another. Empty gaps retain their numbers; unused trailing workspaces are removed. The overview includes windows from all workspaces. Select a window with the pointer or arrow keys and Enter; Escape or three fingers down dismisses it. Repeating swipe-up leaves an already open overview visible. Swipe-down does nothing to an ordinary application when the overview is closed.

Skippy-XD starts only when needed, with physics and animations disabled. Unmapped or minimized windows may use an icon/title placeholder rather than a live thumbnail. Super+O opens the overview without a touchpad; Ctrl+Super+Left/Right provides the same direct window cycle used by swipes.

Only touchpad input nodes get active-user access. Keyboard device-node access and input-group membership are not added. The Super-only shortcut observes X11 key events and does not log typed text. The reader pauses for inactive/locked login sessions and exits with X. VMs often expose only a mouse; physical three/four-finger detection depends on the touchpad and how the VM passes it through.

Customize bindings and sensitivity in ~/.config/erdos/gestures.conf, using /etc/erdos/gestures.conf as a starting point. Set an action to none to disable a binding. The old libinput-gestures configuration is no longer used. An action already triggered cannot be undone by changing direction or cancelling the swipe; lift your fingers before the next swipe. Restart with erdos-gesture stop then erdos-gesture session. Diagnostics are in ~/.local/state/erdos/gestures.log and overview.log.

Multiple monitors

At login or a connection change, ErdOS extends external displays to the right and keeps the laptop screen primary. Each output uses a suitable advertised mode. With no internal panel, the helper keeps a connected primary or chooses the first connected screen.

Drag windows across displays; tiling follows the monitor containing the window. Workspaces span all screens, so switching workspaces switches them together.

Automatic layout listens to RandR events, rather than polling. It leaves manual changes alone until the next connection change or login. Settings → Displays lets you select advertised resolutions, with automatic rollback unless confirmed within 15 seconds. Confirmed modes return at login for the same output set; reconnecting a monitor resets the automatic layout to preferred modes. Advanced users can stop the helper with erdos-displays --stop or reapply defaults with erdos-displays --apply.

Physical docks, multi-GPU and mixed-DPI setups still need hardware testing.

Troubleshooting

Print Screen does nothing

First check ~/Pictures/Screenshots: saving is silent. Run command -v scrot and erdos-screenshot in Sakura. An older ISO removed scrot during installation; repair it with sudo apt update followed by sudo apt install scrot. The current image retains it. If the command works but the key does not, check the host/VM key handling.

Sudo says my account is not in the sudoers file

Current installations grant the first account sudo. On an older installation where a separate root password was set, note your login name using whoami, run su -, and enter that root password. As root, run apt-get install sudo and adduser YOUR_LOGIN_NAME sudo. Replace the placeholder with your actual login name. Log out completely and back in before testing sudo -v.

Wi-Fi or another device is missing

ErdOS includes firmware for common hardware, not every device. Identify the hardware and use Debian packages for additional firmware or drivers. An Ethernet connection or supported USB network adapter may help get online. Firmware absent from the ISO cannot be made available merely by hiding installer questions.

Settings shows no battery

The Power tab reports no battery when the kernel exposes none, including most VMs and desktop computers. Physical battery and backlight support depends on the kernel and device firmware.

I need more package documentation or translations

Remove /etc/dpkg/dpkg.cfg.d/01-minimal-docs with sudo, then reinstall the affected packages. Copyright notices are retained even in the minimal image.

For a reproducible bug, include the ISO checksum, boot mode, live/installed status, hardware or VM model and steps in a GitHub issue. Redact private information. Validation and known limitations describe the test coverage.

← Back to ErdOS