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
• Hyprland installed and working
• An AUR helper (yay or paru) for AUR packages the profile/layers pull in
• Internet connection for package installation

Installation Steps

Clone the Repository

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

Run the Installer

Default: zero prompts

./install.sh

Installs the daily-driver setup (full profile, no optional layers) straight through, no questions asked. Your choice is written to aphotic.toml at the repo root, the source of truth for every re-run after that.

Interactive wizard

./install.sh --opt-in

Walks you through:

1. Selecting a base profile (minimal or full)
2. Choosing optional layers (gaming, dev, ai, exploit and its sublayers)
3. Selecting a theme
4. Whether to install the optional Aphotic Assistant (NVIDIA only)

Same aphotic.toml write at the end either way.

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

Note

--dry-run is checked before anything else runs — no sudo prompt, no package installs, no filesystem writes happen ahead of it.

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 enable the BlackArch repo, which is less stable than Arch's official repos — the installer warns and asks for explicit confirmation before touching /etc/pacman.conf (interactively) or proceeds under the same disclaimer flag (scripted).

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 instead of repeating the wizard.

Updating

cd Aphotic-Hypr
git pull
./install.sh

Aphotic detects your saved aphotic.toml and re-resolves your profile/layers against any changes upstream, snapshotting your current configs first exactly as a fresh install would. The same aphotic update CLI command does the git pull + re-deploy for you from anywhere, once installed.

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 Agent Graph for details.

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.

Command-Line Flags

Flag	Effect
--opt-in	Launches the interactive layer-picker wizard (profile, layers, theme). Without this flag and without a terminal, a fresh install defaults to the daily-driver setup with zero prompts.
--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).
--no-assistant	Skips the Aphotic Assistant, doesn't ask.
--config-only	Config sync only: back up, copy Configs/ over ~/.config/, restart the shell. No package installs, no system prep, no wizard. This is the fast path after a git pull.
--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.

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 (and every aphotic update) snapshots your existing configs here before touching anything, unless --no-backup was passed.
• --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 <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.