Iliada

Docs

How Iliada works

Everything about Iliada in one place: why it exists, how it is built, what it keeps private, and how you can help. No jargon where plain words will do.

The idea

You want a computer that is fast, easy, safe and reliable, and that stays that way.

  • Windows runs on almost any PC, but it fills up with ads, updates that interrupt you, and programs that install pieces of themselves everywhere.
  • A Mac gets most of this right: apps are single .app files you drag in and out, each app asks before it sees your camera or your files, and settings follow you. But it only runs on Apple's hardware, and you can't see or change how it works.
  • Linux is free, open and runs on the PC you already have, but it usually expects you to use a terminal, choose between package formats and fix things yourself.

Iliada is the Mac's way of doing things, on your own PC, built entirely from free and open software. You set it up once; after that, it looks after itself.

How Iliada works

Iliada is a stack of layers, each with one job. From what you see down to the base:

  1. Your apps. Each one is a .app in Applications, running in its own sealed sandbox. They come from the Store, or you drag them in.
  2. Iliada's own apps. The Store, Settings, the Setup Assistant and Homer. All written in Rust.
  3. The desktop: COSMIC, made by System76 and written in Rust: the windows, the panel at the top, the dock at the bottom. Iliada sets its defaults (the dock, the Iliad look) and adds the permission windows that no app can cover or imitate.
  4. Iliada's services. Small programs, in Rust, that run in the background. iliada-systemd makes every system change (software, services, updates, backups) on behalf of Settings, the Store and Homer, so you never need an administrator password or a terminal. iliada-appd keeps track of your apps. The Package Translator turns Linux software into .apps.
  5. The base: NixOS. The Linux kernel, drivers and the thousands of pieces underneath, built and updated as one whole (see the next section).

Your system's whole setup lives in one folder, /etc/iliada: which software is installed, which services are on, which apps you have. Every change is recorded there, which is what makes backups and "undo" possible.

Where Nix fits

Nix is the tool that builds Iliada; NixOS is the Linux system made with it. Instead of installing and updating thousands of separate pieces one by one (which is how a system slowly breaks), Nix builds the whole system from one written description, the same way every time.

  • Updates can't half-finish. An update builds a complete new version of the system next to the running one, then switches to it. If the power goes out halfway, you still have the old one.
  • Every update can be undone. The previous versions stay in the start-up menu. Pick one and your computer is exactly as it was.
  • Your computer can be rebuilt from its description. That is how a backup brings a new PC to the same state in minutes.

You never deal with Nix yourself: Settings, the Store and Homer write the description for you. Developers can read and change it in /etc/iliada if they want to.

What it takes from other systems

Iliada copies the best idea from each system that got something right.

FromWhat Iliada takes
macOS.app bundles in Applications, drag to install and to the Trash to remove; a Store; one Settings app; the dock; apps that ask before seeing your camera, microphone or folders.
iPhone and AndroidEvery app in its own sandbox, with permissions you can change at any time in Settings → Privacy.
ChromeOSUpdates that happen in the background and can't break the computer; sign in and your settings come back.
WindowsIt runs on the PCs people already own: Intel and AMD, laptops and desktops.
Linux and NixOSFree and open source, private by design, no account required, and a base that can be rebuilt and rolled back.
DebianIts huge collection of tested software, which the Package Translator turns into .apps.

Apps, sandboxes, permissions

An app is one .app folder with everything it needs inside. Installing is copying it into Applications (the Store does this for you); removing is dragging it to the Trash. Nothing is left behind.

Where apps come from. The Store's catalog is signed by Iliada, so your computer can check every app came from there. Most apps are made from Debian's packages by the Package Translator: it unpacks them safely (their install scripts never run), works out what they need, and wraps them as an .app. Apps whose makers don't allow sharing them, like Google Chrome, are made on your own computer from the maker's download. In the future, an AI will keep watch over new Debian and Ubuntu software, add it to the Store and keep it up to date.

Each app runs sealed off. An app sees its own files and a private folder, nothing else: not your documents, not other apps, not the system. The first time it wants your Pictures folder, the camera or the microphone, Iliada asks you in a window the app can't draw or click. Your answers are in Settings → Privacy, where you can change them. Whether an app may use the internet is decided when it is added, not asked every time.

Extra isolation. For apps you trust less, Settings → Privacy can run them in their own tiny virtual machine, with their own kernel. Slower, but a broken or hostile app stays inside it.

Homer, the assistant

Press Alt + Space anywhere and say what you want: "install LibreOffice and turn on dark mode", "why won't my printer print?". Homer does it, using the same tools as Settings and the Store. He's named after the poet of the Iliad, and yes, he knows it by heart.

  • Off until you turn it on, in Settings → Homer. You choose the AI (Claude, or a model through OpenRouter) and use your own key, so you pay the AI company directly and can see what it costs.
  • He asks before he acts. In Ask mode (the default) Homer shows every change and waits for your yes. In Auto mode he gets on with everyday things himself, but still asks before anything important done in your name, like sending a message, posting or deleting, unless you tell him he may do that on his own too.
  • Homer can't do more than you can. His changes go through the same system service, with your rights. He can't run commands unless you turn on Full access.
  • Everything Homer changed is listed in his app, under Activity, and the latest change can be undone from there.

Your Iliada account

An Iliada account is optional. It keeps your desktop settings, your Privacy answers and your conversations with Homer backed up, so a new or reinstalled computer is yours again after you sign in. It is to Iliada what an Apple Account is to a Mac.

  • No password. You sign in at account.iliada-os.com with a code sent to your email, then add a passkey so your phone or computer can sign you in with a fingerprint, face or PIN.
  • A computer signs in with a code. Settings → Account shows a short code; you approve it on the account page. You can remove a computer there at any time.
  • The server can't read your data. Everything is encrypted on your computer with a key that never leaves it, before it is sent. The server only stores your email address and data it can't open.
  • Keep your recovery key. It is shown once, when you first sign in, and it is how a new computer gets your key. If you lose every computer and the recovery key, your backed-up settings can't be recovered by anyone, including us. That is the price of nobody else being able to read them.
  • You can run your own. The account server is open source (iliada-os/cloud), and a computer can use any server.

Coming later: signing in with Google or Apple, approving a new computer from one already signed in (instead of the recovery key), and a built-in password manager that works with Bitwarden.

Backing up to GitHub

Separately from the account, Iliada can back up your whole system setup (the apps you have, the software and services you turned on) to a private repository on your own GitHub account, named iliada_<your computer's name>.

  • Turn it on in the Setup Assistant or Settings → Backup: you approve a code on github.com, and Iliada creates the private repository.
  • It saves after every change, and every hour.
  • On a new computer, choose Restore from a backup in the Setup Assistant: your apps install themselves and your settings come back.
  • It holds Iliada's configuration only: no documents, photos, passwords or keys.

The difference: the Iliada account backs up your personal settings, encrypted. GitHub backup keeps your system's setup, in a private repository you can read yourself. You can use either, both, or neither.

Updates

  • Iliada looks for an update 2 minutes after your computer starts and then every 6 hours. When there is one, a notice says so; one click installs it while you keep working. Restart when it suits you.
  • Updates come ready-made from Iliada's signed download cache, so they take minutes, even on computers with little memory.
  • If an update ever misbehaves, choose the previous version in the start-up menu.
  • Apps from the Store update themselves every few hours.
  • Want new things first? Settings → Updates → Test updates gets Iliada's newest work before it is released. Fixes arrive sooner, and so do new problems.

Installing

  1. Check your PC. An Intel or AMD processor (most PCs since 2012), 4 GB of memory or more, and at least 25 GB of free disk space.
  2. Download the Iliada image (3.8 GB) from the home page and write it to a USB stick of 8 GB or more with balenaEtcher or Fedora Media Writer.
  3. Turn off Secure Boot in your PC's setup screen (usually F2, F10, F12 or Del at power-on). Iliada doesn't carry the signature Secure Boot expects yet.
  4. Start from the stick (often F9, F12 or Esc at power-on). Iliada runs from the stick, so you can try it without changing anything.
  5. Install. Choose Next to what's already on the computer (Windows, ChromeOS Flex, another Linux: it stays, and you pick at start-up), or Erase it and use the whole disk. Pick your name and password, and you're done in well under an hour.

Most hardware works. Not yet included: NVIDIA's own graphics driver (the open one is used) and some Broadcom Wi-Fi cards. If something doesn't work, Settings → About → Save report writes a plain text file describing your hardware; send it to us.

Questions

Is Iliada Linux?
Yes, underneath. You just never have to know it.
Will my Windows programs run?
No. Use the Store's apps (LibreOffice instead of Office, for example), or the web versions of the programs you use.
Does it cost anything?
No. Iliada is free and open source (MIT or Apache 2.0). Homer uses an AI service you choose and pay for yourself, and only if you turn him on.
Does Iliada send my data anywhere?
No tracking and no ads. Iliada contacts its own servers only for updates and the Store, and the account server only if you sign in, with your data encrypted first.
Can I go back to my old system?
If you installed next to it, it's still there: pick it in the start-up menu.

Contribute

Iliada is built in the open, and help of every kind is welcome: trying it on your PC and reporting what breaks, ideas, apps for the Store, translations, design and code.

RepositoryWhat's in it
iliada-os/iliadaThe system: services, the Store, Settings, Homer, the installer, and the Nix description of it all. Rust and Nix.
iliada-os/appsThe Store's catalog: a short recipe per app, and the signed list of apps.
iliada-os/cloudThe Iliada account server and its website.
  • Report a problem or suggest something: open an issue on GitHub. Attach the report from Settings → About → Save report if it's about your hardware.
  • Build it yourself: clone iliada-os/iliada, run nix develop for the tools, then cargo test. A test computer to try changes in: nix build .#nixosConfigurations.dev-vm-x86_64.config.system.build.vm. docs/architecture.md in the repository explains the design in depth.
  • Add an app: a recipe is a few lines naming the Debian package and what the app may use; see the recipes folder in iliada-os/apps.

Iliada stands on the work of the NixOS, COSMIC (System76), Debian and Rust communities.

Contact

Questions, ideas, press, or something that should work and doesn't: write to [email protected].