APHOTIC

Documentation / Installation

Installation Guide

This page covers how to install and set up Aphotic on your system.

Prerequisites

[!IMPORTANT] Aphotic assumes an Arch/AUR base. Tested and supported on plain Arch and on Omarchy. EndeavourOS installed with Desktop Environment: None also works. It’s the same Arch/AUR base as a minimal install. See Compatibility for distro-specific notes.

  • Arch Linux, Omarchy, EndeavourOS (Desktop Environment: None), or a similar Arch/AUR derivative
  • sudo access and an internet connection

You don’t need Hyprland or an AUR helper beforehand. The installer installs Hyprland itself, and if neither yay nor paru is on PATH it builds yay from the AUR before installing anything that needs it.

Installation Steps

Clone the Repository

git clone https://github.com/T-Crypt/Aphotic-Hypr && cd Aphotic-Hypr
chmod +x install.sh

You don’t need to pick a branch. On the default stable channel, install.sh fetches the tags, checks out the newest release tag (vX.Y.Z) and installs that. If the checkout has local changes, it installs the current tree as it is. See Release channels.

Run the Installer

Guided setup (the default on a terminal)

./install.sh

Run with no options on a real terminal, the installer walks you through four numbered steps, then shows one summary to accept before anything on the system changes:

  1. How much software? — the minimal or full base profile
  2. Optional extra tool sets — the layers (gaming, dev, ai, exploit). Pressing Enter means none.
  3. How it looks — the theme
  4. Optional add-ons — the Aphotic Assistant (offered only when an NVIDIA GPU is detected), the starship prompt, and zsh as your login shell. Pressing Enter means none.

If Aphotic is already installed on the machine, the guided setup first offers to reuse your previous profile and layers and then asks only steps 3 and 4. The two consequential questions, replacing an existing NVIDIA driver and adding the BlackArch repo, stay as their own separate prompts. The guided setup always deploys Aphotic’s config files.

Zero prompts

With no options and no terminal (CI, or a piped install), the installer takes the daily-driver setup straight through: the full profile, no optional layers, the tokyonight theme, and Aphotic’s config files. Your choice is written to aphotic.toml at the repo root, the source of truth for every re-run after that.

Just the layer picker

./install.sh --opt-in

Skips the rest of the guided setup and asks only for the profile, the layers (as a preset menu: all of them, none, or one by one) and the theme.

Automated Installation

# Install with specific profile and layers, skipping the prompts
./install.sh --profile full --with gaming,dev

# Dry run to see the full resolved plan without installing anything
./install.sh --profile full --with gaming,dev --dry-run

# Skip the pre-install backup (not recommended)
./install.sh --profile full --with gaming,dev --no-backup

A flag-driven run on a terminal still asks whether to install Aphotic’s config files into ~/.config (default no), because without them you get Hyprland with none of Aphotic’s desktop.

[!NOTE] --dry-run prints the plan and changes nothing: no package installs, no backup, no file writes, and no switch to a release tag.

Installing an exploit layer non-interactively

Any exploit/exploit-* layer needs an authorized-use disclaimer accepted before it installs. Interactively this is a typed confirmation prompt; in a scripted/CI install (stdin isn’t a TTY) you must pass --accept-exploit-disclaimer alongside --with, or the install fails. See Security for what the disclaimer actually says and why it exists.

./install.sh --profile full --with exploit-recon,exploit-web --accept-exploit-disclaimer

Most exploit-* sublayers also need the BlackArch repo, which is less stable than Arch’s official repos. The installer prints a warning and asks before adding it (default no). Declining drops only the tools that need BlackArch; the rest of the install carries on.

The login screen

The installer makes the Aphotic greeter (greetd running a Quickshell login surface) your login screen. sddm stays installed as the way back: aphotic displaymanager switch sddm --confirm-tested. The switch is skipped, and the current login screen kept, when:

  • you pass --keep-sddm
  • the machine is Omarchy, which keeps its own login
  • you previously switched back to sddm (that choice sticks through later updates)
  • greetd, Quickshell or Hyprland’s start-hyprland (Hyprland 0.56 or newer) is missing, or the greeter files did not deploy

When a package fails

  • An optional package that fails is skipped, and the install finishes without it. The failures are listed at the end.
  • A required package that fails stops the install with a one-line explanation. If the nightly install canary has a newer known-good date, the installer offers to finish from the Arch Linux Archive snapshot of that day. AUR packages can’t come from the archive.
  • On a terminal, the installer then offers a redacted failure report to review and send as a GitHub issue. Nothing is sent unless you answer yes. Set APHOTIC_NO_REPORT=1 to skip the offer.

Configuration File

After installation, Aphotic writes aphotic.toml at the repo root — your resolved profile, layers, and theme. A re-run of install.sh detects this file and offers to reuse it. A non-interactive re-run with no --profile/--with reuses it without asking.

Updating

The most complete update is re-running the installer from the checkout:

cd Aphotic-Hypr
./install.sh                 # moves to the newest release, installs new packages, redeploys configs
./install.sh --config-only   # the same release move, configs only

On the stable channel both commands fetch the tags and check out the newest release tag before doing anything else. ./install.sh also snapshots your current configs to ~/.config-backup/ first.

There are two lighter commands:

  • aphotic update follows your saved channel: on stable it checks out the newest release tag, on edge it switches to dev and pulls. Then it runs aphotic restore --populate and aphotic reload --full. --populate only adds config files you don’t have yet and never overwrites. The Hyprland, wallust and matugen configs are symlinks into the checkout, so they follow the new version at once. The Quickshell shell config (~/.config/quickshell/aphotic) is a copy, so it stays on the old version until you run ./install.sh --config-only. --dots-only stops after the git step; --channel overrides the saved channel for one run.
  • aphotic sync (also the update button in Settings → About) runs git pull --ff-only, then ./install.sh --config-only, refreshes installed plugins, and lists any packages the new release needs that aren’t installed. The pull needs a branch checked out, so it works on edge. A stable checkout sits detached at a tag, and there the pull fails and nothing is deployed.

[!WARNING] Upgrading from 1.x to 2.0.0? Agent tracking (Claude Code, Codex, OpenCode hooks) and Agent Graph are no longer installed automatically with the ai layer — they are now separate, opt-in plugins. After updating, run:

aphotic plugin install claude-hooks     # or codex-hooks / opencode-hooks
aphotic plugin install agent-graph

Without this, the bar’s agent icon and the Agent Graph tab will be absent. See Agentic Workflows for details.

Release channels

Channel What it installs
stable (default) The newest release tag. The checkout is left detached at that tag.
edge The current checkout as it is, with no tag switch. aphotic update on edge moves the checkout to the dev branch, where work lands before a release.

Pick one with ./install.sh --channel <stable|edge>. The choice is saved to ~/.local/state/aphotic/channel.

Uninstalling

./uninstall.sh

This restores your most recent backup — no manual archaeology through your backup directory. If you also want to remove the packages your profile installed:

./uninstall.sh --purge-packages

Package removal happens behind its own separate confirmation. --aphotic-toml <path> points the uninstaller at a different aphotic.toml.

Command-Line Flags

Flag Effect
--channel <stable\|edge> stable (default) installs the newest release tag; edge installs the current checkout. See Release channels.
--opt-in Just the interactive layer picker (profile, layers, theme), without the rest of the guided setup.
--profile <minimal\|full> Selects the base package set. Skips the profile prompt.
--with <layer,layer,...> Comma-separated layers to merge in: gaming, dev, ai, exploit (a convenience bundle of exploit-recon+exploit-web+exploit-network), or any individual exploit-* sublayer (exploit-recon, exploit-web, exploit-network, exploit-passwords, exploit-wordlists, exploit-reversing, exploit-forensics, exploit-reporting). Skips the layer prompts.
--accept-exploit-disclaimer Required alongside --with in non-interactive/scripted installs when any exploit/exploit-* layer is selected.
--theme <name> Pre-selects a theme. Skips the theme prompt.
--with-assistant Installs the Aphotic Assistant (local chatbot, needs an NVIDIA GPU; implies the ai layer). Without an NVIDIA GPU it is skipped with a warning.
--no-assistant Skips the Aphotic Assistant, doesn’t ask.
--keep-sddm Keeps sddm as the login screen instead of switching to the Aphotic greeter.
--nvidia-driver <keep\|reinstall> Only matters if an NVIDIA driver is already installed. keep leaves it alone; reinstall removes it and installs nvidia-open-dkms. Interactive installs are asked; non-interactive ones default to keep.
--config-only Config sync only: back up, copy Configs/ over ~/.config/, restart the shell. No package installs, no system prep, no wizard, and aphotic.toml is left as it is. This is the fast path after a git pull.
--strip-conflicts Removes installed packages Aphotic’s shell replaces (waybar, rofi/wofi, dunst/mako/swaync and similar) without asking. Interactive installs are asked; non-interactive ones leave them installed.
--keep-conflicts Leaves those packages alone without asking, even interactively.
--dry-run Prints the full resolved install plan and exits — nothing is installed, backed up, or written.
--no-backup Skips the pre-install config snapshot. Off by default; use with intent.
--keep-backups <N> How many timestamped backups to retain before pruning. Defaults to 5.
-h, --help Full flag reference.
-v, --version Print the installed Aphotic version.

--with-greetd-preview is still accepted so older scripts don’t break, but it does nothing: the greeter now installs as the login screen by default.

Custom apps live in profiles/custom_apps.lst and are folded into the resolved package list automatically — no separate prompt needed.

Backup System

There are two separate, unrelated backup mechanisms — don’t confuse them:

Installer snapshots (~/.config-backup/) — automatic, tied to install.sh/uninstall.sh:

  • Every install.sh run snapshots your existing configs here before touching anything, unless --no-backup was passed. aphotic update does not.
  • --keep-backups <N> (default 5) prunes older snapshots automatically after each run.
  • ./uninstall.sh restores the most recent one of these automatically — no manual archaeology needed.
  • There’s no CLI for browsing these directly; they’re plain timestamped directories under ~/.config-backup/.

aphotic backup CLI (~/.local/state/aphotic/backups/) — a separate, manually-invoked snapshot/revert tool for your dotfiles, independent of installing/uninstalling:

  • aphotic backup create [--label <name>] — snapshot now
  • aphotic backup list — list your manual snapshots
  • aphotic backup revert [--yes] <id> — restore one (auto-snapshots your current state first, so a revert is itself always reversible)
  • aphotic backup clean [--keep N] — prune old ones (default keep 10)

The installer also detects and reuses your existing aphotic.toml to avoid repeating the wizard on a re-run — see Configuration File above.

Next Steps

Once installed, see Getting Started for a walkthrough of what to try first, or Keybindings for the full shortcut reference.

View public Wiki source ↗