> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryoku.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Extras

> Add real software to Ryoku's small core through Extras, curated bundles the Hub installs, removes, and reports for you.

Ryoku keeps its core deliberately small: a terminal, an editor, a browser, a
file manager, and the shell that ties them together. Everything else, a game
launcher, a streaming rig, a security lab, a full dev stack, is added on demand
through **Extras**. An Extra is a **bundle**: a curated set of software
installed together, so adding a whole workflow is one click instead of an
afternoon of hunting packages and their drivers.

Extras install *software*. For the small desktop **widgets** you place on the
wallpaper (a stock ticker, a photo frame), see [Plugins](/docs/plugins), a
separate system.

## Install a bundle

<Steps>
  <Step title="Open the Store">
    Press `Mod + ,` for Ryoku Settings and open **Store** (under **Add-ons**).
    The Store browses shell plugins and Extras bundles side by side; each bundle
    is a card with a description and its live install state.
  </Step>

  <Step title="Pick a bundle and install">
    Open a bundle to see what it contains, then **Install**. Ryoku opens a
    floating terminal so `sudo` and the AUR helper have a real TTY, and streams
    progress as each item lands.
  </Step>

  <Step title="Watch it fill in">
    Items report present or absent state live, so the card updates as the bundle
    installs. Remove the same way: open the bundle and choose **Remove**.
  </Step>
</Steps>

Under the hood the actuator is `ryoku-extras-install`, and `ryoku-hub` fetches
and caches the catalogue from the
[`ryoku-extras`](https://github.com/neur0map/ryoku-extras) repo (with an offline
fallback to the cache). The Hub is the normal way in; the
[terminal](#from-a-terminal) drives the same actuator.

## The bundles

Eleven bundles ship in the catalogue. Install as many as you like, they layer.

| Bundle            | Tagline                                 | What it adds                                                                                                |
| ----------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Gaming            | drivers · launchers · chat              | Wine and Proton compatibility stack, game launchers, performance overlays, and a Wayland-friendly Discord.  |
| Audiophile        | pipewire · tools · control              | EasyEffects, patchbays, mixers, and PipeWire inspection.                                                    |
| The Influencer    | stream · record · edit                  | OBS with Wayland capture, video and image editors, and mic cleanup.                                         |
| Office Worker     | docs · mail · meetings                  | LibreOffice and office suites, PDF read and edit, mail and calendar, and Teams.                             |
| SecPulse Basic    | starter cyber lab                       | Nmap, Gobuster, wordlists, and the HTB / TryHackMe starter kit.                                             |
| SecPulse Advanced | recon · firewall · ops                  | Nikto, Shodan, the ProjectDiscovery recon suite, masscan, and firewall helpers.                             |
| The Ricer         | customize · inspect · tweak             | Eye-candy apps, theming tools, color pickers, and visual editors.                                           |
| The Vibecoder     | agents · terminals · flow               | Claude Code, Codex, Gemini, aider, and the terminal helpers for building with AI.                           |
| The Developer     | real dev workflows                      | Zed, the Docker stack, and git and database TUIs.                                                           |
| The Hacker        | reversing · forensics                   | Ghidra, radare2, gdb, Wireshark, volatility, around 25 reversing and forensics tools.                       |
| CachyOS Kernel    | faster kernel · keeps stock as fallback | The performance-tuned CachyOS kernel; the stock kernel stays as the fallback. See [Kernels](/docs/kernels). |

<Note>
  The **CachyOS Kernel** bundle is a kernel swap, not an app set. Read
  [Kernels](/docs/kernels) for the trade-offs, the rollback path, and how it is
  wired before you install it.
</Note>

## What a bundle contains

A bundle is a list of items, each one of three kinds. You never write or see the
routing, the actuator picks the right path per item.

| Kind        | What it is                                                                                                            | How it installs                                                                                                                                                                                               |
| ----------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **package** | An Arch package name.                                                                                                 | Auto-routed at install time: if it resolves with `pacman -Si` it is an official-repo package installed via `ryoku-pkg-add`, otherwise it is built from the AUR via `ryoku-pkg-aur-add`. Packages are batched. |
| **script**  | A small installer from the catalogue's `installers/`, for tools not in pacman or the AUR (Go, pipx, vendor binaries). | Fetched with `ryoku-hub extras installer <name>` and run with `bash`, detected afterwards by a `command -v` check.                                                                                            |
| **plugin**  | A shell [plugin](/docs/plugins), a desktop widget the bundle ships.                                                   | Its source is fetched into `~/.local/share/ryoku/plugins/<id>/` (via `ryoku-hub extras plugin`). You then enable and place it from **Settings > Installed**.                                                  |

<Warning>
  **script** items are arbitrary installers, so removing a bundle does **not**
  reverse them; uninstall those tools by hand. **package** items go through
  `pacman -Rs`, which refuses to drop anything another installed package still
  needs, so removing a bundle never breaks the rest of the system. Removing a
  **plugin** item deletes its files but keeps your placement in
  `~/.config/ryoku/plugins.json`, so reinstalling drops it back where you had it.
</Warning>

## From a terminal

The Hub is the normal entry point, but `ryoku-extras-install` drives everything
from a shell. Bundle and item ids are the ones in the
[`ryoku-extras`](https://github.com/neur0map/ryoku-extras) catalogue (for
example `gaming`, `the-developer`, `cachyos-kernel`).

```bash theme={"dark"}
# See what a bundle has installed vs. what is missing (machine-readable).
ryoku-extras-install status
ryoku-extras-install status bundle gaming

# Install an entire bundle.
ryoku-extras-install install bundle gaming

# Install or remove a single item from a bundle.
ryoku-extras-install install item gaming steam
ryoku-extras-install remove item gaming steam

# Remove a bundle's package items.
ryoku-extras-install remove bundle gaming
```

Set `RYOKU_EXTRAS_DRYRUN=1` to print the plan without touching the system:

```bash theme={"dark"}
RYOKU_EXTRAS_DRYRUN=1 ryoku-extras-install install bundle gaming
```

<Tip>
  `ryoku-hub` owns the network and the cache. The `ryoku-pkg-*` and installer
  helpers only read the already-cached catalogue, they never fetch on their own,
  so a dry run and a real run see exactly the same plan.
</Tip>

## Notes

* **Multilib is handled for you.** A bundle that needs 32-bit libraries (Steam
  and the lib32 overlay in **Gaming**, for instance) declares
  `requires: ["multilib"]`, and the actuator enables the `[multilib]` pacman repo
  with `ryoku-pkg-multilib` before it routes any package. The **CachyOS Kernel**
  bundle likewise pulls in the CachyOS repo the same way.
* **Live per-item status.** The actuator publishes a JSON report per bundle under
  `$XDG_RUNTIME_DIR/ryoku-extras/<id>.json`; the Hub watches it, so the Store
  updates in place as a bundle installs or removes.

## See also

<CardGroup cols={2}>
  <Card title="Plugins" icon="puzzle-piece" href="/docs/plugins">
    Small desktop widgets and frame popouts, a different system from software bundles.
  </Card>

  <Card title="Kernels" icon="microchip" href="/docs/kernels">
    The CachyOS Kernel bundle in depth: trade-offs and rollback.
  </Card>

  <Card title="Ryoku Settings" icon="sliders" href="/docs/settings">
    The Hub's Store and every other panel, opened with `Mod + ,`.
  </Card>
</CardGroup>