Installation

Installing NikOS

One command for the common case, and three modes when you need control over which version you get.

Before you start

• Ubuntu or Xubuntu 22.04, 24.04 or 26.04 LTS. The installer refuses anything else.
• A non-root user with sudo. Running the installer as root is refused.
• ~20 GB free disk for a base install; up to 93 GB more if you later pull every optional model group.
• 4 GB RAM minimum, 8 GB recommended.
• Internet access throughout — packages, themes and models are all fetched during the run.

Quick install

curl -fsSL https://raw.githubusercontent.com/nikolareljin/nikos/main/install.sh | bash

This clones the repository to ~/.local/share/nikos, moves it to the newest release tag, offers a dialog menu for the optional bundles, then runs the playbook behind a per-role progress gauge. The TUI follows the controlling terminal rather than stdin, so the piped one-liner gets the same interface a clone-and-run install does. Add NIKOS_USE_DIALOG=0 for the plain-prompt path.

Choosing a version

With no options the installer resolves and installs the newest release tag. Pre-release tags (0.6.0-rc1) and floating tags (production) are never selected automatically.

NIKOS_REPO_REF=<ref> is equivalent to --ref. Installing a tag leaves the persistent checkout on a detached HEAD, which is expected.

Development mode

git clone --recurse-submodules https://github.com/nikolareljin/nikos
cd nikos
bash install.sh --dev

--dev runs the checkout the script lives in, exactly as it stands. Nothing is cloned, fetched, pulled or stashed, and ~/.local/share/nikos is never touched — so testing a branch cannot damage a working install. It refuses to run outside a NikOS checkout and cannot be combined with --ref.

What happens during the run

1. The installer checks the OS, your sudo access and the Ansible version, offering an upgrade from the Ansible PPA if it is too old.
2. You pick optional bundles from a menu, or skip them all. Without a controlling terminal the installer stops here rather than silently installing none of them.
3. Ansible runs 27 roles against localhost, shown as a per-role progress gauge.
4. The full log is written to ~/.config/nikos/logs/, with install-latest.log symlinked to the most recent run.

First boot

Reboot if you came from Ubuntu; log out and back in if you were already on Xubuntu. On the first terminal session a one-time Git setup wizard runs. Pick GitHub, GitLab, Bitbucket or a custom Git server and it creates an SSH key, adds it to that host, sets your git identity and optionally clones your dotfiles; or pick Skip and manage keys yourself. It writes ~/.config/nikos/github-configured and does not run again; nikos-git-setup --reset runs it again.

Day-to-day

# update to the newest release and re-run the playbook
nikos update

# update to a specific branch or tag instead
nikos update --ref 0.6.0

# add an optional bundle later
nikos add postgres
nikos add ollama-vision

# check what is installed and whether anything is broken
nikos status
nikos doctor

# this machine's class and approved model per role; offer to remove the rest
nikos models
nikos models prune

# free disk from caches nothing uses (a dry run; --apply removes, after a yes)
nikos clean
nikos clean --apply

# read the last playbook log
nikos log 100

Every role is idempotent, so re-running changes only what has drifted. nikos update reads its target from what is checked out: a release install advances to the newest release only when that release is genuinely newer, and a branch install stays on its branch. An update never downgrades. From 1.3.0 it also keeps the Ollama models on this machine's approved set: it asks, one model at a time, before removing a model not approved for this machine, then pulls what the selected modules lack (details: What's included).

nikos clean lists, with sizes, what nothing uses: Docker build cache unused for a week (every builder), untagged images, node_modules in git repositories with no commit for 30 days, nothing uncommitted and nothing running from them, the uv cache, and unused pnpm, npm and pip cache entries. It removes them only with --apply. It never removes Docker volumes, containers, virtual environments, build output or tracked files. It is in NikOS 1.2.0 and later (nikos update brings it). Details: docs/debugging.md.

Customising before you run

Create vars/local.yml to override defaults without editing tracked files:

nikos_timezone: "Europe/London"
nikos_desktop_flavor: "xubuntu-full"
nikos_remove_gnome: true
nikos_ai_model_tier: "large"  # instead of measuring the machine
nikos_tesseract_languages: [eng, srp, deu]
nikos_nvidia_drivers: false    # leave GPU drivers alone
nikos_firefox_dark: false      # leave Firefox's theme alone
nikos_chromium_dark: false     # leave Chromium / Chrome alone

The full set of variables is documented in docs/customization.md.

If something goes wrong

More in docs/debugging.md.