---
name: maluos-desktop
description: Install MaluOS Desktop (GNOME 50 with the agent-aware MaluOS session), sign into the MaluOS session, verify background provisioning, install tools (Chrome, VS Code, Claude Code, Codex, Ollama) with the Tools Installer, add a local, GPU-server or cloud model to the desk's gateway, and enrol the desk with a Business OS office. Use when the user is setting up a MaluOS desktop, laptop or workstation, or asks about the Desk, Agents, Credential Manager, MaluApps or Upgrade Manager windows, or about office enrolment from a desk.
---

# Installing MaluOS Desktop

Human guide: https://maluos.com/howto/desktop/ . Same procedure, written for an assistant that
acts on the desk with its owner.

## Where you are running

- **On the desk** (a terminal in the MaluOS session, or SSH): `test -e /etc/maluos-release` and
  `grep -q 'VARIANT="Desktop"' /usr/lib/os-release`. Everything below runs here. Commands marked
  *as the owner* must run as the person's login, not root: the vault, the office enrolment and
  the tools in user scope are tied to that account.
- **Elsewhere**: you can download, verify and guide; nothing else until the desk is up.

## Preconditions

- x86-64, at least 4 GB memory and 40 GB disk (8 GB and 60 GB recommended, plus memory for a
  local model). Secure Boot may stay on.
- The desktop carries the whole server stack (MaluDB, vault, gateway, agent runtime) and
  provisions it on first boot; it does not run the MaluDB API server or the Business OS. Those
  live on the office's server.
- Real-hardware caveat: tested in VMs (BIOS, UEFI), a laptop and Proxmox; graphics and boot
  splash not yet seen widely. Report black screens with the GPU model.

## Procedure

### 1. Download and verify

```sh
V=$(curl -fsSL https://download.maluos.com/LATEST)
curl -fsSLO https://download.maluos.com/$V/maluos-$V-desktop-amd64.iso
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
```

Expected `Good signature` with fingerprint `6387 5A4A 5397 B902 E9C5 CFF8 731A DA39 4135 B9FF`
and `OK`. Stop otherwise.

### 2. Install (the person, at the console)

Boot the medium; choose **Install MaluOS Desktop**. The account created in the installer is the
desk's owner; agents made later belong to it. The automated entry erases the first disk and
creates `maluos`/`maluos` with a forced password change: throw-away VMs only. The install
screens show Ubuntu naming and are text-mode; the installed system is MaluOS Desktop.

### 3. Sign in and confirm provisioning

The login screen appears while provisioning runs in the background. The session chooser (gear
at bottom right of the login screen) must say **MaluOS**; it is the default.

```sh
maluctl status                      # provisioned; components maluos-vault and maluos-gateway ok
journalctl -u maluos-firstboot -f   # if it still says provisioned: no
systemctl --user status maluos-desktop-session   # the session service behind the indicator
```

### 4. What the session gives (so you can point the person to it)

Indicator in the top panel: agents (start/stop), gateway and backends, budget, secrets and
delegations, alerts; grant requests answered from the notification with level, expiry and
budget. Dock windows: **Desk**, **Agents** (Talk, Control, Policy, Memory, Activity; each agent
also an icon in the Agents folder), **Credential Manager**, **Tools Installer**, **MaluApps**,
**Upgrade Manager**. Power defaults: no screen blank, no automatic suspend, so agents survive
the night; Settings → Power changes it.

### 5. Tools *(as the owner)*

```sh
maluctl tools list             # ids and state; Chrome, VS Code, Claude Code, Codex, Ollama
maluctl tools install ID       # system-scope tools authenticate through polkit
maluctl tools check ID         # prints the version; exit 1 when absent
maluctl tools log ID
```

### 6. A model for the desk (pick any; operator commands need sudo)

Local:

```sh
sudo maluctl gateway ollama install
sudo maluctl gateway ollama pull llama3.2:3b
maluctl gateway chat "hello" --model fast
```

A MaluOS GPU server on the LAN (the person gets a key from its operator; see the
`maluos-gpu-server` skill):

```sh
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
```

The person's own cloud key, into their own compartment *(as the owner; the key is typed at the
prompt, never in chat)*:

```sh
maluctl secret add anthropic --provider anthropic
sudo maluctl gateway backend enable anthropic
```

Verify with `maluctl gateway chat "hello" --model strong` and `maluctl gateway routes`.

### 7. Enrol with the office *(the person obtains the code; enrolment is root)*

The office is a MaluOS application server (`maluos-app-server` skill). A one-time enrolment
code comes from the office's Settings → Desks, minted for this person.

```sh
sudo maluctl office enroll https://app.example.com --code 7F3K-2Q9M --name "Ed's desk"
maluctl office status --live
maluctl office apps            # the office's catalogue over the public signed one
maluctl office agents
```

After enrolment: `--model office` is a gateway rung using the desk token (the person never
sees a provider key); MaluApps shows the office's apps; Agents shows the office's agents.
Agents on the desk reach the office's models only after
`maluctl secret delegate --to agent:NAME --secret office-desk-token` and an egress policy of
at least `internal`. Leaving: `sudo maluctl office leave`.

### 8. Updates

`maluctl update status`, `sudo maluctl update apply -y`, the Upgrade Manager for the switches.

Run `scripts/verify.sh` from this skill on the desk to check the result.

## Stop and ask before

- erasing a disk; rebooting while the person has work open;
- enrolling with an office (it registers the machine with the organisation under the person's
  name) or leaving one (the token is revoked, office apps disappear);
- adding a cloud key (they type it) or delegating a key to an agent;
- turning GPU sharing on (`maluctl gateway share on`): other machines can then use this desk.

## Never

- run owner-scoped commands (`maluctl secret …`, `maluctl office apps/agents`, user-scope tools)
  as root; they would act for the wrong principal;
- paste a token, code, password or key into the transcript; enrolment codes are one-time;
- change the session chooser to a non-MaluOS session to "fix" a missing indicator; diagnose the
  session service instead.

## Troubleshooting map

| Symptom | Look at | Fix |
|---|---|---|
| no indicator after sign-in | session chooser; `systemctl --user status maluos-desktop-session` | pick MaluOS; restart the user unit |
| `provisioned: no` after 10 min | `journalctl -u maluos-firstboot` | fix cause; `sudo maluctl provision --force` |
| installer crash on Storage with LVM | an old ISO (26.04.20261020) | use the current release |
| black screen on real hardware | GPU model | boot once with `nomodeset`; open an issue |
| enrolment 4xx | code expired/used; wrong URL (must be the `app.` name) | mint a new code |