Installing remux and KOReader on the reMarkable 2 (2nd Edition)

Introduction

This is a new edition of my original post for installing the above software. I first wrote it back in January, and since then the ecosystem has moved on. Whilst I didn’t intend for it to become a popular guide, it appears it has… and so here are a newer set of instructions.

Disclaimer

These instructions worked when I wrote them. There is an active community on discord who can help, if problems are encountered, but no-one makes any guarantees about this software or this guide.

Instructions

1. The most important step is to check whether the version of the software you are on is supported by the community. Each release currently necessitates new configuration being discovered and documented.
   1. Go to your Settings Page, and note the software version you are currently on. e.g. 2.11.0442
   2. Open the Toltec website and check what the warning about supported versions says. e.g.
      • Warning: Toltec does not yet support any OS build newer than OS 2.11.0.442. You will soft-brick your device if you install before support is released. See remarkable2-recovery for information on how to recover your device if you have done this.
   3. If your version is the most recent supported version, congratulations you can use Toltec with a minimum of fuss.
   4. If your version is older, you can attempt to update to the most recent supported version
      1. Press the version number shown on your settings page.
      2. Enable auto-updates, if they aren’t already.
      3. Press Check for updates and look at the version it starts to download.
      4. If it’s downloading a newer version than is supported by Toltec then immediately cancel the download by toggling auto-updates off. In this situation stick with your older software version until support is announced.
2. At this point Disable automatic updates. You will want to re-enable automatic updates only once Toltec gains support for the newer versions. Keep an eye on the toltec website, or their GitHub repository, for new support statements.
3. Obtain the ReMarkables IP Address and SSH Password
   • Menu > Settings > Help > Copyrights and Licenses > General Information > Look at the bottom
   • WRITE THE SSH PASSWORD DOWN SOMEWHERE SAFE. In case you can’t get back to this screen should something go wrong.
4. SSH in.
   • ssh root@<ip> and provide the password
5. (Optional) Setup an SSH Key to allow password-less SSH access.
   • This is useful as there have been reports of the SSH Password changing when the reMarkable software updates, but there has never been a report of the authorised SSH Keys for the root user being reset.
6. Install Toltec package repository
   • Run the two commands from the website
7. Install remux – a GUI launcher to switch between apps
   • opkg install remux
8. Enable remux
   • systemctl enable --now remux
9. Reboot the reMarkable
   • reboot
10. Test that remux is working
    • Swipe up from the bottom of the ReMarkable 2. You should see a menu appear with one entry in it.
11. Install koreader
    • opkg install koreader
12. Test that koreader is working
    1. Swipe up from the bottom of the ReMarkable 2 and select koreader from the list
    2. In the app, swipe down from the top to access the KOReader menu.
       • Note you can’t read your ReMarkable documents in KOReader as even ePubs appear to be converted in to an incompatible format (inside /home/root/.local/share/remarkable/xochitl for the curious)
13. Congratulations, you are done!

When a toltec update is available

1. SSH back in as before
2. Upgrade the packages
   • opkg update
   • opkg upgrade
3. Reboot the device

When a reMarkable update is available

1. Wait until the toltec website declares support for that version
2. Reenable updates in the reMarkable software, and upgrade
3. Restart the reMarkable
4. SSH back in as usual
5. toltecctl reenable
6. systemctl enable --now remux
7. Reboot the device

Nicer toltec package upgrades

1. You can install the nao package manager to provide a visual way of managing toltec upgrades
   • opkg install nao
2. You can now use the nao GUI to check for toltec upgrades and to install them. You should still reboot the device after upgrading. It shows up in remix just like KOReader does.

Running bleeding edge software

So you want to run reMarkable software ahead of the current version supported by Toltec? Doing so is outside the scope of this guide, but toltecctl switch-branch is a useful command for such situations. Be warned that the packages in testing may still not support newer reMarkable releases, and may have other problems.