decky-nexus

Nexus Mods: Decky Loader Plugin (Unofficial)

Browse, download, install, and enable/disable Nexus Mods content for the currently selected game, entirely from Gaming Mode with a controller, on SteamOS and Bazzite. No Desktop Mode required.

Built with AI, tested by hand. Nearly all of this plugin’s code was written by Claude, Anthropic’s AI. What makes it trustworthy is not the author but the process around it: hundreds of hours of human direction, hands-on testing, and every supported game installed, modded and played on real hardware before it shipped. We state this plainly because you deserve to know how the thing you are installing was made.

Unofficial, and in beta. This is a community-built plugin. It is not an official Nexus Mods product, is not supported by Nexus Mods, and nothing here is endorsed by them. It uses their public API like any other third-party client. Bugs are ours, so please report them here rather than to Nexus Mods support.

Supported games

Twenty-five games. Every one unmarked below was installed, modded and played on real hardware before it shipped. That is what supported means here: not that the code has a config entry for it, but that someone finished a session with mods running.

  1. Baldur’s Gate 3
  2. Cyberpunk 2077
  3. Elden Ring
  4. Fallout 4
  5. Fallout: New Vegas
  6. Helldivers 2
  7. Kingdom Come: Deliverance
  8. Kingdom Come: Deliverance II
  9. Mass Effect Legendary Edition
  10. Middle-earth: Shadow of Mordor *
  11. Mount & Blade II: Bannerlord
  12. NieR:Automata
  13. Palworld
  14. Red Dead Redemption 2
  15. Resident Evil 4
  16. Skyrim Special Edition
  17. Slay the Spire 2
  18. STAR WARS Battlefront II (2017)
  19. Stardew Valley
  20. Starfield *
  21. Subnautica
  22. Subnautica 2
  23. Subnautica: Below Zero
  24. The Witcher 3
  25. Valheim

* Community added game. Not tested by author.

On the roadmap

Groundwork exists for these and they are NOT ready. They may appear in the plugin; treat anything you do with them as untested.

Requested, not started

Asked for and on the list. No code exists for these yet, so they will not appear in the plugin until they do.

Want one moved up, or a new one added? Open a game request and say which. Adding a game means installing it, modding it and playing it on hardware, so the list grows slowly and on purpose.

What it does

Not supported yet: Vortex profile import, and mods that need a Windows tool to install.

How to use it

The plugin shows mods for the game you are currently looking at, so it needs to know which game you mean. There are two ways to tell it, and both are things you were probably doing anyway:

If you open the plugin from the Steam home screen or a menu, it has no game to work with and will say so rather than guess.

From there:

Mods apply the next time the game starts. Nothing is written into the game until you install something, and every supported game can be put back to vanilla from the plugin.

What you need

Crediting mod authors

Mods exist because people give their work away, and a plugin that makes them invisible is a plugin that quietly costs them. So:

If something you install turns out to be good, endorse it. It costs nothing and it is the whole economy these mods run on.

Installing

You need Decky Loader first: this is a Decky plugin, not a standalone app.

Installing is done from Desktop Mode and takes about two minutes.

If you have never set a password on your Deck, do that first, because Decky needs it and so does this. In Desktop Mode open Konsole and run passwd. It asks for a new password twice and nothing appears as you type, which is normal. Then install Decky, then come back here.

  1. Switch to Desktop Mode.

    Steam button -> Power -> Switch to Desktop. The Deck reboots into a desktop.

  2. Open this page on the Deck, in the browser there, and open Konsole as well.

    Konsole is in the bottom-left menu (the launcher icon): type konsole and open it. Leave both open, you will switch between them.

  3. Copy this line, paste it into Konsole, and press Enter.

    curl -L https://raw.githubusercontent.com/RedRanger14/decky-nexus/main/install.sh | sh
    

    To paste, right-click in Konsole -> Paste. The easiest way to right-click on a Deck is the left trigger (L2). Ctrl+Shift+V does not work from the on-screen keyboard.

    Do not put sudo in front of it. The script asks for your password itself, at the one step that needs it. Running the whole thing as root looks in the wrong home folder and fails.

  4. Type your password when it asks.

    Nothing appears on screen as you type, which is normal. It is the same password you set when you installed Decky, because Decky owns its plugin folder as root and installing into it needs permission.

  5. It installs, then asks for your Nexus Mods API key.

    Leave it sitting at that prompt and go and fetch the key.

    In the browser: log in to Nexus Mods -> your profile picture, top right -> Site preferences -> API Keys in the left-hand menu -> scroll to the very bottom -> copy the Personal API Key.

  6. Back in Konsole, paste the key at the prompt and press Enter.

    Left trigger (L2) to right-click -> Paste, then Enter. It saves the key, so you never type it on a controller.

    Rather not paste your key into a terminal? Press Enter on its own to skip. You can add it on the plugin’s Settings page instead.

    Steam’s interface will flicker during the install, and Decky may show a toast saying something failed. Ignore it. Restarting Decky restarts part of Steam’s UI with it, and Decky reports losing its own connection as a failure. The terminal is the one telling the truth.

  7. Return to Gaming Mode.

    The Return to Gaming Mode icon is on the desktop.

  8. Open the plugin.

    Quick Access Menu (the … button) -> the plug icon -> Nexus Mods.

    The panel footer shows the version and the words unofficial beta. If your game is supported and installed, it will already have found it, and your key is already in place.

That is Desktop Mode done with for using the plugin. Browsing, installing mods, collections and health checks all happen from the Quick Access Menu on the controller.

Updating is the one exception, and it is the same two minutes: see below.

Updating

Repeat the install: Desktop Mode, Konsole, same line. It fetches the newest release, checks it is complete before removing the old version, and restarts Decky. Your installed mods, API key and settings live outside the plugin folder and are not touched.

From v1.11.3 the plugin updates itself from Gaming Mode: open the Quick Access Menu, press Updates, and a plugin update appears above your mod updates. Decky asks you to confirm, then downloads it, checks it against the published SHA-256 and installs it. No Desktop Mode, no terminal, no password.

The older paragraph here said this was impossible because Decky’s plugin folder is owned by root. The folder is, but Decky Loader owns it and runs as root, so the plugin does not write it: it asks Decky to, through the same mechanism Decky’s own store uses.

The Konsole line above still works and is the way to install in the first place, or to recover if an update ever goes wrong. Nothing breaks by staying on an older version.

If you would rather not run a script

Download the latest Nexus-Mods-<version>.zip from Releases, put it in your Downloads folder, then in Gaming Mode: Quick Access Menu -> plug icon -> gear -> General -> turn on Developer mode at the bottom, then the Developer tab -> Install from zip -> Home -> Downloads -> pick the zip.

A note on “Install from URL”

That same Developer tab offers Install from URL, and it does not work with this plugin. Decky takes the plugin’s name from the URL rather than from the zip, then stops during install with nothing written to its log, so the screen sits on “PARSING ZIP FILE” forever. The identical zip installs correctly through Install from zip, and the download and archive were both verified byte for byte on the device, so it is neither.

Do not use it, and do not wait for it. If it starts working, this section will say so.

Beta

This is a beta. It changes game files, and while every game it supports can be returned to vanilla from inside the plugin, back up saves you care about first. Report anything wrong on GitHub Issues, the plugin can package the details for you from the Health page.

Architecture

Standard Decky plugin layout (from the official template):

Frontend ↔ backend communication: callable() for request/response, decky.emit() + addEventListener for backend-initiated events (e.g. download progress).

Development

Prerequisites: Node.js ≥ 18, pnpm, Python 3.

pnpm i
pnpm run build   # bundles src/ into dist/index.js via rollup

Deploying to hardware

From Windows (this project’s dev machine): pnpm run deploy: runs deploy.ps1, which builds the frontend, packs the runtime files, ships them over SSH to ~/homebrew/plugins/Nexus-Mods/ on the device, and restarts plugin_loader. Uses Windows’ built-in OpenSSH and tar; no Docker or decky CLI needed.

One-time device setup (Steam Deck, in Desktop Mode → Konsole):

  1. passwd: set a password for the deck user if you never have.
  2. sudo systemctl enable --now sshd: turn on SSH permanently.
  3. Note the device’s address: steamdeck.local usually resolves from Windows; otherwise get the IP from Settings → Internet.

One-time laptop setup:

  1. Run pnpm run deploy once: it creates .vscode/settings.json (gitignored) from the defaults and exits.
  2. Edit .vscode/settings.json: set deckip (hostname or IP) and deckpass (the password from step 1 above; used for sudo on the device). Leave deckpass as-is to be prompted each deploy instead of storing it.
  3. Optional, to skip SSH password prompts: ssh-keygen -t ed25519 then type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh deck@steamdeck.local "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

Flags: -SkipBuild deploys the current dist/ as-is; -PackOnly builds the tarball without touching the device.

The same script deploys to the Bazzite box, point deckip/deckuser/deckdir at it in settings.json. Both targets run Decky; Bazzite treats it as first-class, but expect occasional breakage after SteamOS updates.

Current test device: a Lenovo Legion Go 2 running SteamOS (hostname steamdeck.local, user deck, behaves identically to a Steam Deck for all plugin purposes). It suspends aggressively; the deploy script probes and retries, but wake the device before deploying. The device password must be printable ASCII (the deploy pipe scrubs non-printable bytes around it).

The template’s .vscode/ bash tasks and the decky CLI zip pipeline remain the store-submission path later.

Debugging on-device

Dev-loop smoke test

The current hello-world panel has a Ping backend button that round-trips a callable, displays backend environment info (user, home path, versions), and fires a backend-emitted event that surfaces as a toast, verifying all three communication channels work on real hardware.

Build Order

  1. ✅ Hello-world plugin from the template; confirm dev loop on real hardware (Deck + Bazzite box).
  2. Read selected game’s app ID; hardcode StS2 → Nexus game domain mapping.
  3. Nexus API auth (API key via settings page) + read-only browse UI.
  4. Download + extract to mods/ (Premium flow first).
  5. Enable/disable via folder moves + state tracking.
  6. Modded-save warning, polish, controller UX pass.
  7. Dogfood with StS2 domain expert; QA/test plan.
  8. Decide free-user nxm:// story and second game candidate.

License

BSD-3-Clause (inherited from the Decky plugin template, see LICENSE).