Installing MaluOS Desktop

Before you start

You need one x86-64 machine for the desk: a laptop, a workstation, or a virtual machine with a display. The desktop carries the whole server stack underneath GNOME, so it needs more than a plain desktop would.

1Download and verify the desktop ISO

The current release is 26.04.20261028. Take the desktop installer: maluos-26.04.20261028-desktop-amd64.iso (5.1 GB). A desktop qcow2 (2.0 GB) exists for a workstation VM that boots from cloud-init.

Verify it with the signed checksum file. The signing key is the MaluOS Archive Signing Key (2026), fingerprint 6387 5A4A 5397 B902 E9C5 CFF8 731A DA39 4135 B9FF:

V=26.04.20261028
curl -fsSLO https://download.maluos.com/$V/SHA256SUMS
curl -fsSLO https://download.maluos.com/$V/SHA256SUMS.gpg
curl -fsSL  https://apt.maluos.com/bootstrap/maluos-archive-keyring.gpg -o maluos-archive-keyring.gpg
gpg --no-default-keyring --keyring ./maluos-archive-keyring.gpg --verify SHA256SUMS.gpg
sha256sum -c SHA256SUMS --ignore-missing

What you should see: Good signature with the fingerprint above, and OK next to the ISO. Stop if either differs.

2Install from the ISO

1. Write the ISO to a USB stick with dd, Rufus or balenaEtcher, or attach it to the VM. Boot from it. Secure Boot can stay on.
2. Choose Install MaluOS Desktop. The installer asks for language, keyboard, network, proxy, disk layout, your user account and SSH access. The account you create here is the desk's owner: the agents you make will belong to it. The automated entry erases the first disk without asking and creates maluos/maluos with a forced password change; use it only for throw-away VMs.
3. Wait for the install and the reboot. Remove the medium if the machine boots back into the installer.

3Sign into the MaluOS session

After the reboot the login screen appears while first boot still provisions the database, vault, gateway and agent runtime in the background; that is normal and takes a couple of minutes.

1. Click your name. Before typing the password, check the session chooser (the gear at the bottom right of the login screen) says MaluOS. It is the default; pick it if something else is selected.
2. Sign in. The MaluOS wallpaper and the dock appear, and the top panel gains the MaluOS indicator.
3. Open a terminal (Ptyxis is in the dock's app grid) and check provisioning:

maluctl status

What you should see: provisioned with a time, the tenant, and the components maluos-vault and maluos-gateway saying ok. A desk does not run the MaluDB API server or the Business OS; those live on your office's server. If it says provisioned: no, wait a minute and try again, or watch journalctl -u maluos-firstboot -f.

4Meet the desk

Everything the session adds is for one purpose: agents that run on your machine with your memory and your keys, under your control.

• The indicator in the top panel shows the agents on the host and lets you start and stop them, the gateway and its backends, your model budget, your vault secrets and delegations, and the latest alerts. Changes arrive as desktop notifications; a grant request from an agent is answered from the notification itself, with a level, an expiry and a budget.
• Desk is the window behind the indicator: the host, its agents, the gateway, the vault, pending updates, the office you are enrolled with and, as a node, your estate.
• Agents is where you talk to and control agents, local and the office's, with pages for Talk, Control, Policy, Memory and Activity. Each agent is also an icon in the Agents folder of the app grid.
• Credential Manager holds your secrets, delegations and the requests agents have made.
• Tools Installer, MaluApps and Upgrade Manager are steps 5, 7 and 8.
• Power. The desk never blanks the screen or suspends on its own, so an agent working overnight is not killed by a sleeping machine. Change it in Settings → Power if you prefer.

5Install your tools

The Tools Installer in the dock installs Google Chrome, VS Code, Claude Code, Codex and Ollama in one click each, from the vendors' own packages, and shows which are already present. The same from a terminal:

maluctl tools list            # the tools and their state
maluctl tools install ID      # system-scope tools ask for your password through polkit
maluctl tools open ID

What you should see: each tool's version after maluctl tools check ID, and the tool in the app grid. Install logs are in /var/log/maluos-tools/ for system tools and ~/.local/state/maluos-tools/ for user ones.

6Add a model

The desk's gateway is running but has no model yet. Three choices, and you can combine them:

A local model on the desk

Install Ollama from the Tools Installer, or let the gateway install its pinned release, then pull a model that fits your memory and tell the gateway to use it for the fast tier:

sudo maluctl gateway ollama install
sudo maluctl gateway ollama pull llama3.2:3b
maluctl gateway chat "Say hello from my desk." --model fast

A GPU server on your network

If someone has set up a MaluOS GPU server, ask them for a key and add it as a backend. The desk's callers change nothing; the GPU host becomes one more rung of the ladder:

sudo maluctl gateway backend add gpu-1 http://gpu-1.lan:11435 --key mg_… --models qwen3:32b
sudo maluctl gateway alias set strong --tier strong --backend gpu-1 --model qwen3:32b --position 0
maluctl gateway chat "Hello from the GPU." --model strong

A cloud key of your own

Add the key in the Credential Manager, or from a terminal into your own compartment. It is yours: the gateway attaches it to your calls, and an agent can use it only after you delegate it.

maluctl secret add anthropic --provider anthropic      # prompts for the key
sudo maluctl gateway backend enable anthropic
maluctl gateway chat "Hello from the cloud." --model strong
maluctl gateway routes                                 # which rung answered, and why

7Enrol the desk with your office

If your organisation runs a MaluOS application server, your desk can join it as a desk: a location in the office's estate that belongs to you. Enrolment exchanges a one-time code for a desk token; the token lives in your vault compartment and is never written to a file.

1. Get an enrolment code from the office: your settings page there, or an operator mints one for you (Settings → Desks on the office).
2. Enrol, naming the office's app. address:

sudo maluctl office enroll https://app.example.com --code 7F3K-2Q9M --name "Ed's desk"
maluctl office status --live

What you should see: the office's name and endpoints in the status, and the desk online in the office's Settings → Desks. From now on:

• the office's model endpoint is a rung of your gateway: maluctl gateway chat "…" --model office goes through the office's ledger and budget with your desk token, and you never see a provider key;
• MaluApps in the dock lists the office's applications beside the public catalogue; maluctl office apps is the same from a terminal, and an installed web app opens in its own Firefox window;
• the Agents app shows the office's agents you may use, and the Desk's Estate page shows the office's nodes if you are a system manager there.

Leaving is sudo maluctl office leave; the token is revoked on both sides.

8Keep it updated

Security updates from Ubuntu and MaluOS updates from apt.maluos.com install themselves. The Upgrade Manager in the dock shows what is pending, installs now, switches automatic updates on or off and lists the history. From a terminal:

maluctl update status
sudo maluctl update apply -y
maluctl update history

GNOME Software still works for applications, with debs only; there is no snap store.

If something is wrong

• No MaluOS indicator after signing in. Check the session chooser said MaluOS, then the session service: systemctl --user status maluos-desktop-session.
• maluctl status says provisioned: no after ten minutes. Read journalctl -u maluos-firstboot; after fixing the cause run sudo maluctl provision --force.
• The installer crashed on the Storage screen. That was a known issue of release 26.04.20261020 with the default LVM layout, fixed since; make sure you have the current ISO.
• A black screen or a stuck boot splash on real hardware. Try the nomodeset boot option once to get in, then open an issue with the GPU model; the graphics stack has not been seen on much real hardware yet.
• Enrolment fails. The code is one-time and expires; mint a new one. The URL must be the office's app. name, reachable from the desk.
• Still stuck. Open an issue at github.com/maludb/maluos/issues.

What next

• Create your first agent. sudo maluctl agent create NAME --exec /path/to/run; it belongs to you, appears in the Agents app and in the Agents folder, and you can talk to it there.
• Share the desk's GPU with the network if it has one and sits at a desk all day: the switch is on the System Monitor's GPUs tab, or sudo maluctl gateway share on.
• Pair with a GPU server as in step 6 so the heavy models run elsewhere.