Manual

The Alpymist manual

How to install Alpymist, find your way around it, and change everything that can be changed. Start at the top if the desktop is new to you, or go straight to the chapter you need.

Start here

• Welcome to Alpymist Alpymist is a desktop on top of Alpine Linux: Hyprland, a tiling window manager on Wayland, with a bar, a menu, a Settings app and a set of tools chosen to work together. It is one desktop, configured once, and it arrives as signed packages rather than as a script that changes your system.
• Getting started There are two ways onto an Alpymist system: start a computer from the installer image, or add Alpymist's package repository to an Alpine Linux system you already have. Neither is a script piped into a shell.
• Finding your way around Alpymist is a tiling desktop. Windows are not dragged about and stacked; each new one takes a share of the screen beside the others, and you move between them and between workspaces with the keyboard. It takes a day to get used to, and after that a stack of overlapping windows feels like a mess.
• Hotkeys Every key Alpymist binds, in one place. They are ordinary lines in ~/.config/hypr/hyprland.conf, which is yours to change: Setup › Config › Hyprland in the menu opens it. Learn › Keybindings in the menu lists the ones your own file has, apart from the lid, the power and sleep keys and Ctrl+Alt+Delete. The keyboard's control keys come from the package and are not in your file.

The desktop

• The menu The menu is where everything is. Super+Space opens it, as does a click on the mark at the left end of the bar. Typing searches every entry of every submenu, every installed application and every setting.
• The top bar The bar runs along the top of every screen. Most of what is on it opens something when clicked.
• Settings Everything that can be set in Alpymist is one setting in one list, and there are three ways to reach it. They all change the same thing.
• Appearance Settings › Appearance has four things: the style, the accent colour, the text size and the wallpaper.
• Screens Plug in a screen and it is used: placed to the right of what is there, at its own best resolution. Arrange it once, and Alpymist remembers that arrangement for that set of screens. The desk's dock, the meeting room's projector and the laptop alone each come back as you left them.
• Keyboard, mouse and touchpad All of these apply at once.
• Sound and Bluetooth Sound is PipeWire. It needs no setting up: plug in headphones and they are used.
• Networking Click the Wi-Fi icon on the bar, or open Setup › Wi-Fi in the menu. The popup lists the networks in range. Choose one, type its password, and it is remembered and joined again whenever it is in range.
• Power Click the battery on the bar, or open Setup › Power in the menu, for the power popup: the charge, the power mode, and what the lid and the power button do. Settings › Power has the same and a little more.
• Screensaver, idle and lock Three separate things happen when a computer is left alone, each with its own timing: a screensaver appears, the screen turns off, and, if you want it, the screen locks.
• Clipboard and screenshots Terminals and other programs disagree about which keys copy and paste. Alpymist gives you one set that works in every window:
• Notifications Notifications appear in a corner of the screen and go away by themselves.

Software

• Installing software Software comes from two places, and the Store shows both in one window:
• Default applications and startup Settings › Default applications says which program opens each kind of thing. Each list offers the installed applications that can open that kind.
• Terminal and shell Its font and behaviour are in ~/.config/foot/foot.ini (Setup › Config › Terminal); its colours follow Settings › Appearance. Another terminal installed from the Store can be made the default in Settings › Default applications.
• AI Alpymist does two things for people who work with AI models: it puts the vendors' command-line tools in the menu, and it shows in the bar how much of your limits you have used. Nothing is installed and nothing is asked of any vendor until you turn it on.

System

• Updates and channels An installed system is updated in place. There is never a reason to install again from a new image.
• Security Alpymist's rule is that what it installs is safe with nobody touching it, and that anything which weakens that is a switch you turn on yourself, which says what it gives up and turns off again. This chapter is what that means in practice.
• Accounts, language and time Settings › System has what belongs to the computer and to your account on it.
• Configuration files Settings covers what most people change. Beyond it, the desktop is made of ordinary programs with ordinary configuration files, and those files are yours. This chapter is the map.

Reference

• The command line Everything the desktop does has a command behind it, and each command says what it takes with --help.
• Every setting Every setting Alpymist has, by area. Each can be changed in the Settings app, found by its title in the menu's search, or read and changed from a terminal:
• Troubleshooting Things that go wrong, and what to do about each. If yours is not here, the issue tracker is the place, with the output of alpymist-about --print and alpymist probe.

The manual says how. Why each part is the way it is, is in the decision records.