# NoSignal OS

A single-script builder that turns a stock Arch Linux ISO into a **fully
offline installer** for a ready-to-use **Hyprland desktop**: Arch +
[Hyprland](https://hyprland.org) + the
[caelestia](https://github.com/caelestia-dots/caelestia) dotfiles/shell, with
a themed [SDDM](https://github.com/sddm/sddm) login screen that matches the
desktop.

Everything needed for the install is bundled **on the ISO** — a complete
pacman repo (every package incl. all GPU driver variants, with the caelestia
stack pre-built from the AUR at ISO-build time), the pinned dotfiles, the
theme. **No internet is needed to install or on first boot**: the machine
boots straight into the themed login screen and a fully configured desktop.

> NoSignal is the *ISO builder*. It bundles and installs the upstream caelestia
> dotfiles; it is not affiliated with that project.

> ⚠️ **Experimental — and built to be modified.** NoSignal OS is young and
> opinionated; expect rough edges. It is designed to be reshaped by *you*: every
> NoSignal tweak sits in a config-override layer on top of stock caelestia
> (delete a file to revert one), and the installed system ships an **on-box AI
> guide** so you can customise and fix it with
> [Claude Code](https://claude.com/claude-code) — see
> **[Customising the desktop](#customising-the-desktop-on-box-ai-guide)** below.

## What you get on the installed system

- **Hyprland + caelestia shell** (Quickshell), restyled with a restrained
  flat look (no blur/glassmorphism) and the OS's own Moebius-style wallpaper
  set (dynamic Material palette generated from the wallpaper).
- **Themed SDDM login** that mirrors the desktop palette/wallpaper/font
  (`sudo sddm-theme-sync` re-syncs it after you change wallpaper).
- **Omarchy-style keybindings** — `Super+K` opens a searchable cheatsheet of
  every bind. Universal `Super+C`/`Super+V` copy/paste, `Print` = region
  screenshot, `Super+Space` launcher, `Super+D` dashboard/calendar,
  `Super+Grave` workspace overview.
- **Software story**: `yay` (AUR), the **Shelly** GUI store on `Super+I`
  (repos + AUR + Flathub), flatpak preconfigured.
- **Btrfs + bootable snapshots**: every package transaction snapshots
  (snapper + snap-pac), and each snapshot appears as a bootable entry in the
  **Limine** menu (10-second timeout) — roll back a bad update from the boot
  screen.
- **`nosignal-update`**: one command for snapshot → package upgrade → layer
  migrations; a Settings → Updates page shows pending counts.
- **Gaming (opt-in)**: the `[multilib]` repo is enabled and Omarchy-installer
  shims are included, so
  [DeckShift](https://github.com/28allday/DeckShift)-style Steam gaming
  sessions can be added post-install — including a login fix that keeps a
  password on cold boots. Not active unless you set it up.
- Bluetooth, printing (CUPS + network discovery), power-profiles, zram swap,
  ufw on, locale/timezone/keymap of your choice.

## Customising the desktop (on-box AI guide)

NoSignal OS is meant to be tinkered with, so nothing is locked down. Every
NoSignal change lives in a **config-override layer** at `~/.config/caelestia/`
on top of stock caelestia — edit a file to change behaviour, delete it to fall
back to the default. Updates and rollbacks are safe: `nosignal-update` snapshots
before every upgrade, and each snapshot is a bootable entry in the Limine menu.

To make changes easy — even if you don't know the internals — the installed
system ships an **on-box AI skill for [Claude Code](https://claude.com/claude-code)**.
It explains exactly what's safe to edit, how to change keybinds / monitors /
wallpaper / theme, how updates and snapshots work, how to install software, and
how to recover the desktop if the shell ever fails to start.

- **Just ask.** Run `claude` on a NoSignal machine and it **auto-discovers** the
  `nosignal` skill — say *"customise my NoSignal desktop"* or *"the bar didn't
  load, fix it"* and it reads the guide before touching anything.
- **Point an assistant at the files directly** if you prefer:
  - `~/.claude/skills/nosignal/SKILL.md` — the Claude skill (guardrails + tasks)
  - `~/.local/share/nosignal/ONBOX-AI-NOTES.md` — the full system briefing
  - `~/.local/share/nosignal/NoSignal-keybindings.md` — the keybinding reference

The skill is strictly for managing **your installed system** — it carries no
build/release tooling, and it always reads the guardrails before editing config.

## Build the ISO

The builder runs on an **Arch Linux** (or Arch-based) host with an internet
connection — it uses `pacman`, `makepkg`, and `devtools` to assemble the offline
package set, so it can't run on a non-Arch distro.

**1. Install the build dependencies:**

```bash
sudo pacman -S --needed git libisoburn squashfs-tools coreutils devtools pacman-contrib
```

**2. Clone this repository and enter it:**

```bash
git clone https://github.com/28allday/NoSignal-OS.git
cd NoSignal-OS
```

**3. Download a stock Arch Linux ISO into this folder.** The filename must start
with `archlinux-`. Grab the latest from any mirror, e.g.:

```bash
curl -LO https://geo.mirror.pkgbuild.com/iso/latest/archlinux-x86_64.iso
```

(or pick a mirror from <https://archlinux.org/download/>.)

**4. Run the builder:**

```bash
./nosignal.sh
```

It downloads the full package closure and builds the AUR pieces in a clean
chroot — allow roughly **15–40 minutes** on the first run (you'll be asked for
`sudo`). Everything is cached in `./offline/`, so later rebuilds take a couple of
minutes.

**5. Done.** `nosignal-arch-YYYYMMDD.iso` (~4 GB) appears in the folder —
Ventoy-compatible and `dd`-bootable. Write it to a USB stick and install (see
**Install** below).

## Install

**1. Write the ISO to a USB stick.** Replace `/dev/sdX` with your USB device
(check it with `lsblk` first — this erases the whole stick):

```bash
sudo dd if=nosignal-arch-YYYYMMDD.iso of=/dev/sdX bs=4M status=progress conv=fsync
```

(or just drop the `.iso` onto a [Ventoy](https://www.ventoy.net) USB.)

**2. Boot the USB** on the target machine — **UEFI only** (no BIOS/MBR).

**3. Follow the installer.** It is **fully offline** (no network questions) and
asks for: hostname, user, password, your region (timezone / locale / keyboard),
and the target disk. It then **wipes that disk** — 1G EFI + btrfs with
`@`/`@home`/`@snapshots`/`@log` subvolumes and the Limine bootloader — and runs
a clean, centred progress screen. **It erases the chosen disk — back up first.**

**4. Reboot** into the themed SDDM login and your desktop. Connect Wi-Fi from the
desktop's network panel; once you're online, run `sudo pacman -Syu` one time to
sync the package databases.

## GPU detection

The installer auto-detects the GPU(s) and installs the right drivers,
borrowing CachyOS [`chwd`](https://github.com/CachyOS/chwd)'s **method** (PCI
display-class scan → vendor-id → driver set) but implemented natively, so the
ISO stays vanilla Arch (no CachyOS repos / lib32 / cachyos-kernel deps).
Multiple GPUs union their package sets (e.g. an Intel/AMD iGPU + an NVIDIA
dGPU). All variants are bundled in the offline repo; only the matching subset
is installed.

| Detected | Packages |
|----------|----------|
| NVIDIA (`10de`) | `nvidia-open-dkms nvidia-utils egl-wayland libva-nvidia-driver nvidia-settings linux-headers` + DRM/KMS setup |
| AMD (`1002`) | `mesa vulkan-radeon` |
| Intel (`8086`) | `mesa vulkan-intel intel-media-driver` |
| VM guest (`1af4`/`1b36`/`1234`/`15ad`/`80ee`) | `qemu-guest-agent spice-vdagent` |
| Unknown | `vulkan-swrast` (software fallback) |

For NVIDIA it also does the Wayland-critical bits (the same ones chwd does):
early-loads `nvidia nvidia_modeset nvidia_uvm nvidia_drm` in the initramfs,
drops the `kms` hook so nouveau doesn't grab the card, sets
`nvidia_drm.modeset=1`, and writes the EGL/VA env to `/etc/environment`.

## Notes / current limitations

- **UEFI only.** No BIOS/MBR boot.
- **No disk encryption** yet.
- **NVIDIA uses the open kernel module** (`nvidia-open-dkms`), which is for
  Turing and newer (RTX 20-series+). Older Maxwell/Pascal cards would need
  the proprietary/legacy branch — not yet selected by generation.
- The bundled packages are a snapshot from build day — run `sudo pacman -Syu`
  once online.

## Credits

NoSignal OS is a thin builder around excellent upstream work — it bundles,
themes, and installs these projects rather than replacing them. Please support
the originals. Each remains under its own licence.

- **[Arch Linux](https://archlinux.org)** — the base system and live ISO.
- **[Hyprland](https://hyprland.org)** — the Wayland compositor.
- **[caelestia](https://github.com/caelestia-dots/caelestia)** — the desktop
  dotfiles and shell that define the look and most of the UX. The installed
  shell is a light soft-fork; the CLI / theming engine is upstream, unchanged.
- **[Quickshell](https://quickshell.outfoxxed.me)** — the runtime the shell runs on.
- **[SDDM](https://github.com/sddm/sddm)** — the login manager (themed to match).
- **[Limine](https://github.com/limine-bootloader/limine)**, with **snapper** and
  **snap-pac** — bootloader and Btrfs snapshot tooling (bootable snapshots).
- **[Omarchy](https://omarchy.org)** — keybinding layout and UX inspiration, and
  its prebuilt `[omarchy]` package repo for the Limine snapshot tools.
- **[CachyOS `chwd`](https://github.com/CachyOS/chwd)** — the GPU-detection
  *method* (PCI scan → vendor-id → driver set), reimplemented natively here.
- Fonts: **JetBrains Mono Nerd Font** and **Material Symbols**.

## License

MIT — see [LICENSE](LICENSE). The wallpaper art set is the project author's
own original work and ships with the ISO under the same licence.