Documentation / FAQ

Frequently Asked Questions

Quick answers to the questions that actually come up. For deep dives, follow the links instead of expecting the answer here.

Aphotic was previously known as Noctis-Hypr.

General

What is Aphotic-Hypr?

A Hyprland desktop built for four identities at once — developer environment, gaming rig, AI-assisted workflow, and security research box — on top of a minimalist tiling foundation. See Supported Features for everything that ships, or Profiles & Layers for how you pick which identities you actually want.

Why use Aphotic instead of another rice?

Most rices are a snapshot you copy over your own config and hope for the best. Aphotic is built to keep moving: package sets are declarative TOML (not bash arrays buried in a script), profiles and layers compose instead of forcing one fixed setup, every install snapshots your configs first, --dry-run shows the entire plan before anything touches your system, and ./uninstall.sh reverses it. See Design Principles for the full reasoning.

Is Aphotic-Hypr only for Arch Linux?

It assumes an Arch/AUR base throughout the installer, but that covers more than plain Arch. Omarchy and EndeavourOS (installed with Desktop Environment: None) are both tested and supported directly. See Compatibility for exactly what’s supported and what each distro needs, if anything.

Installation

Can I run this on top of an existing Hyprland setup?

Yes. The installer snapshots your existing configs before touching anything (unless you pass --no-backup), and ./uninstall.sh restores that snapshot if you want to back out. The guided setup (./install.sh with no options, on a terminal) always deploys Aphotic’s configs. A flag-driven run on a terminal asks at the “Deploying configs” step whether to copy Configs/ over ~/.config/ — answer yes, or packages install but your Hyprland config stays untouched. A run with no terminal deploys them without asking. See Installation.

What if I only want a subset of what `full` installs?

Start from minimal and add only the layers you want, or edit profiles/custom_apps.lst before installing. Profiles and layers are just TOML — nothing stops you from forking one to fit exactly what you need. See Profiles & Layers.

How do I update?

cd Aphotic-Hypr
./install.sh

On the default stable channel this moves the checkout to the newest release tag, re-resolves your saved profile/layers, installs anything new and snapshots your configs first, same as a fresh install. ./install.sh --config-only does the same release move for configs only. aphotic update is lighter and leaves the shell’s QML on the old version; see Installation for what each command covers.

How do I uninstall?

./uninstall.sh

This restores your most recent backup. Add --purge-packages if you also want it to remove everything your profile installed (behind its own separate confirmation).

Configuration

How does the profile/layer system work?

A profile (minimal or full) is the base package set; a layer (gaming, dev, ai, exploit and its sublayers) is an optional add-on merged on top. See Profiles & Layers for the full breakdown.

What are custom apps?

Anything listed in profiles/custom_apps.lst is folded into the resolved package list automatically at install time — no separate prompt needed.

How do I customize keybindings?

Add your own bindings to ~/.config/hypr/custom.lua. The installer never overwrites this file once it exists, so your customizations survive updates and re-runs. See Keybindings for the full default reference.

What if my shell isn’t started?

Press SUPER+SHIFT+B. It is a Hyprland bind, so it works with the shell down, and it opens Aphotic’s recovery surface (or a terminal menu): what failed, how often, the suspected cause, and options to disable a suspect plugin, start in safe mode, restore the last good state, or carry on.

SUPER+T also opens a terminal with the shell down. From there:

aphotic reload   # restarts the Quickshell daemon

If that doesn’t bring it back, run aphotic doctor — it checks whether aphotic-shell.service is actually deployed and enabled, along with the rest of your dependency/config state, and tells you what’s missing. See Troubleshooting for what to do with what it reports.

Theming

Why isn’t Firefox picking up my theme?

Firefox theming depends on the Pywalfox extension — install it and reload Firefox.

How do I switch themes?

aphotic theme list          # list available themes
aphotic theme set <name>    # apply a specific theme
aphotic theme next / prev   # cycle themes, or Super+./,

See Theming for how the palette is actually generated from your wallpaper and applied across the stack.

Features

What are the terminal games?

aphotic play hangman
aphotic play snake
aphotic play guess

Three small games built into the aphotic CLI, each tracking its own stats in ~/.local/state/aphotic/game-scores.json. See CLI Reference for every other command.

Development

How can I contribute?

The project is hosted at T-Crypt/Aphotic-Hypr — issues, pull requests, and feature suggestions are all welcome there. See Contributing.

Are there any planned features?

See Project Status for shipped-vs-open at a glance, or GitHub Issues for the current backlog.