reMarkable Paper Pro toolkit — inkshell + SuperDvorak remapper

Tools that make the reMarkable Paper Pro (with the Type Folio keyboard) far more useful than a notebook:

inkshell — a real SSH terminal, a web browser, and a comic / manga reader, all running inside the tablet's own interface. Open a tile, type on the Type Folio, and you're in a shell on any machine you can SSH to — or browsing the web, or reading a CBZ. Tuned for e-ink: fast "A2" refresh, a bold terminal font, sessions that survive sleep/Wi-Fi drops, full Unicode, no on-screen keyboard.
remapper — turns the Type Folio into a SuperDvorak layout with modifier-key layers, by intercepting the keyboard at the input level. Comes with a visual editor you run from your Mac.

You install everything from your Mac with one command:

brew install smith-chris/inkshell/inkshell
inkshell setup

Once set up, bare inkshell starts a shareable terminal session — your reMarkable can join the very session you're working in on the Mac (and vice versa). See Shared sessions.

🧪 Alpha software

This is an early, experimental, alpha-stage project under active development. Expect rough edges, bugs, and changes without notice. Because it runs inside the tablet's own system app, a bad build — or the optional boot-time autostart — can in the worst case leave the device needing a factory recovery. Only use it if you're comfortable with that. The full risk warning and recovery steps are in Safety / risk below.

New to this? The sections "What it's good at, and the trade-offs" and Safety / risk are worth reading before you start.

⚠️ Read this first — no warranty, use at your own risk

This software is provided "AS IS", without warranty of any kind. The authors take no responsibility for any damage of any kind — including a bricked, unbootable, or data-wiped device — that may result from using it. You assume all risk.

What that means concretely:

To install this you must put the tablet into Developer Mode, which erases the tablet's data the first time you enable it. Back up anything you care about first (the reMarkable desktop/mobile apps sync your notebooks).
This is an unofficial project. It is not made by, endorsed by, or supported by reMarkable. Using it is not covered by your warranty and may void it.
The default install only writes to a temporary area that is cleared on reboot, so it is relatively low-risk and easy to undo. The optional "load on every boot" step writes to the system partition and carries more risk — see Safety / risk before using it.

If you are not comfortable with that, stop here.

What you need

The tablet:

A reMarkable Paper Pro in Developer Mode.
A Type Folio keyboard (required for the remapper; recommended for the terminal).
The USB-C cable.

Your Mac:

Homebrew and Node 22+ (brew install node).
sshpass for the one-time Developer-Mode password step: brew install hudochenkov/sshpass/sshpass. Everything after that is SSH-key auth.

That's all for a prebuilt install. A few modules pull in extra tools, installed on demand and only if you choose them:

If you choose…	You'll also want	Why
Any Mac module (remote shell / structured browser)	`brew install go`	builds the tablet's networking helpers (`macpick` + `tssock`) — needed for Wi-Fi or Tailscale, since the tier-picker `macpick` is used on every network
Structured browser	(automatic)	the CLI runs `npm install` + fetches Chrome for Testing on your Mac
`--from-source`	Docker + `zig`	build `inkshell.so` (reMarkable SDK) + the remapper locally instead of fetching prebuilt

Install — step by step

1. Enable Developer Mode on the tablet

On the tablet: Settings → General → Software (on some versions it's under Help / About) → enable Developer Mode.

This wipes the tablet the first time. Sync/back up your notebooks first.
When it's done, the tablet shows a screen with a root SSH password. Keep it handy — inkshell setup asks for it once. (The password changes every time you toggle Developer Mode.)

2. Connect the USB cable

Plug the tablet into your Mac. It appears as a small USB network device at 10.11.99.1 — the same on every reMarkable.

3. Install and run

brew install smith-chris/inkshell/inkshell
inkshell setup

inkshell setup runs the guided setup wizard:

Connect — pick USB (or Wi-Fi), enter the Developer-Mode password once. The CLI installs an SSH key so every later step is passwordless, and saves the device under ~/.config/inkshell.
Health check (ink-doctor) — verifies the tablet is reachable and in Developer Mode, checks free space and OS version, and checks the extension framework (xovi + the OS-specific qmldiff "hashtab"). Anything fixable gets a one-tap fix.
Modules — pick what to install (see the table below).
Install — bootstraps xovi if needed, deploys inkshell.so (atomically, so it can't corrupt a running tile), adds the Chromium engine if you chose that module, and re-injects so the tile appears.
Mac companion + Networking — only if you picked a Mac-dependent module (remote shell / structured browser). Sets up your Mac and chooses how the tablet reaches it (LAN vs Tailscale). See Mac companion.
Activation — how inkshell comes back after a reboot. The safe default is xovi-tripletap. See After a reboot.

The first prebuilt install just downloads small artifacts; --from-source builds them and can take a few minutes the first time.

4. Open inkshell

On the tablet, find the inkshell tile in the sidebar and open it. Use the tabs to switch between the terminal, the browser, and the comic reader (whichever modules you installed).

Modules

Pick any subset in the wizard (or re-pick later with inkshell modules).

Module	What it does	Needs a Mac?	Notes
Local shell	A shell tab into the tablet itself	–	on by default
Comic reader	CBZ / PDF / manga reader tab	–	on by default
Remote shell	SSH into your Mac, in a tmux session that survives sleep/Wi-Fi	✅	persistent scrollback
Structured browser	An OBML/Opera-Mini-style scene+diff browser painted natively — reflowable text, local typing echo, low bandwidth	✅	needs a small daemon on your Mac
Chromium browser	A full Chromium engine running on the tablet	–	large (~hundreds of MB on-device); opt-in

The two on-by-default modules need no Mac and no network. The remote shell and structured browser are the reason to set up the Mac companion.

After a reboot

xovi's injection lives in temporary storage that is wiped on every reboot, so after a reboot the inkshell tile is gone until xovi is re-injected. There are three ways to bring it back, safest first:

xovi-tripletap (the safe default). The wizard offers to install xovi-tripletap: after a reboot, triple-press the power button and xovi re-injects. No system-partition writes, no boot-loop risk — the tablet always boots stock and you opt in by pressing a button.
On demand from your Mac:
```
inkshell start
```
Load on every boot automatically (risky, opt-in). See Safety / risk, then re-run the wizard with the long flag:
```
inkshell --dangerously-allow-setting-up-xovi-and-inkshell-autostart
```
This writes the read-only system partition so xovi loads at boot. A broken boot-time build can boot-loop the interface (recoverable — see Safety). Only enable it once you've confirmed a build is stable across several reboots.

Mac companion (remote shell / structured browser)

If you chose a Mac-dependent module, the wizard sets up your Mac:

macOS Remote Login must be on (System Settings → General → Sharing → Remote Login). The wizard checks and guides you.
It authorizes the tablet's own SSH key on your Mac, scoped to the minimum each module needs:
- Remote shell → restrict,pty (a shell with a pty; SSH port/agent/X11 forwarding disabled for that key).
- Structured browser → restrict,port-forwarding,permitopen="127.0.0.1:8888" (only a tunnel to the local browser daemon — no shell).
For the remote shell it installs a small ~/bin/inkshell-shell wrapper that keeps your session in a tmux server (so it survives the tablet sleeping or dropping Wi-Fi) and ensures tmux is installed.
For the structured browser it installs a local browser daemon that binds 127.0.0.1:8888 only (never the network), runs npm install + fetches Chrome for Testing, and loads it as a LaunchAgent. The tablet reaches it over an SSH tunnel.

Security notes — your Mac's exposure.

The tablet's private key lives on the tablet, readable only by root. Anyone who obtains it could use it within the scope above — keep the tablet secure. Revoke access any time by deleting the # inkshell:<device> line from ~/.ssh/authorized_keys.

Keep Remote Login key-only (disable password login in Remote Login → Options, or PasswordAuthentication no).

First contact pins your Mac's host key on the tablet (trust-on-first-use); do it over USB or on a network you trust.

Your terminal scrollback lives in a tmux server on your Mac and survives disconnects. Clear it any time: tmux -L inkshell kill-server.

Reaching your Mac from anywhere

The wizard's Networking step asks how the tablet should reach your Mac:

Local Wi-Fi only — simplest. The CLI writes the Mac address routed toward the tablet. If DHCP later changes it, the tablet scans only its current local /24, proves the correct host with the scoped inkshell key, and repairs the saved address automatically.
Tailscale (any network) — put both on a private Tailscale mesh VPN (free for personal use) and the tablet reaches your Mac from any network, including cellular, with nothing exposed to the public internet. The reMarkable has no kernel TUN device, so the wizard installs a pinned Tailscale build in userspace mode, supervised by systemd, and walks you through tailscale up once. The generated route prefers Tailscale IPv6 to avoid collisions with managed VPNs that claim the shared Tailscale IPv4 range, while retaining IPv4 fallback. Prefer this over forwarding SSH ports on your router — port-forwarding puts your Mac's SSH in front of the whole internet.

The tablet picks the fastest working path per connect (USB ▸ LAN ▸ public endpoint ▸ Tailscale). If a managed VPN filters the USB IPv4 path, the Mac CLI discovers the cable's scoped IPv6 SSH peer automatically. A managed VPN on the Mac can overlap another VPN's IPv4 range. inkshell doctor reports the known WARP/Tailscale overlap, prefers Tailscale IPv6, and does not alter corporate policy. If you already operate an approved key-only SSH endpoint at home, configure it entirely through the CLI:

inkshell networking --networking tailscale \
  --public-host your-ddns.example --public-port 22022

The endpoint is written only to your local CLI/device config; it is never built into inkshell. The CLI pins the Mac's current SSH host key on the tablet before the public tier can be used. Keep your Mac awake while you rely on it.

The SuperDvorak remapper

inkshell remapper install      # deploy the remapper as a boot service
inkshell remapper configure    # open the visual key editor (web UI)

The remapper is a small keyboard-input filter. It cannot crash the tablet's interface — if it ever fails you simply get the stock keyboard back — so it's safe to install as a boot service.

inkshell remapper configure opens a VIA-style visual editor in your browser: click a key on the Type-Folio layout to reassign it (or type a keycode directly), switch between modifier layers, and Save — the change is pushed to the tablet and hot-reloaded instantly, no restart. The keymap is plain JSON.

The editor includes read-only SuperDvorak and SuperQwerty layouts (plus a stock reset baseline). Duplicate either layout to make a custom editable profile; the originals stay pristine and are always available from the profile picker.

⚠️ Match the editor's PC / Mac toggle to your Type Folio. On the tablet, Settings → Keyboard lets you pick a Windows or Mac layout, which swaps Ctrl and ⌘ (Meta) at the keymap level. The editor has a matching PC / Mac toggle (the band under the header); set it to whatever your folio is on. In Mac mode the remapper swaps Ctrl↔⌘ on output, so a keymap written in normal PC terms still produces the right modifiers. If chords come out as ⌘ where you meant Ctrl (or vice-versa), the toggle and the folio disagree.

Shared sessions

Bare inkshell turns the current terminal window — macOS Terminal, Ghostty, iTerm, the VS Code terminal, anything — into a shareable inkshell session. It's a tmux session on a private -L inkshell socket, so it survives the tablet sleeping or losing Wi-Fi, and the same session can be attached from your Mac and mirrored live on the reMarkable at the same time. Start a build on the Mac, pick it up on the tablet from the couch, hand it back — same shell, same scrollback.

inkshell                 # start/attach a session for the current folder
inkshell <label>         # a session named <label> (exact name → join it)
inkshell --new [label]   # always start a fresh session
inkshell ls              # list every session on the socket
inkshell pick            # interactive picker → choose a session → attach
inkshell attach <name>   # attach a specific session by name

The picker is the Mac equivalent of the reMarkable's session list — it shows the same sessions, including ones started on the tablet, so you can pick one up on either side. (Put exec inkshell --new in your terminal's startup command to make every new window/tab its own shareable session.)

Requires tmux on the Mac (brew install tmux; inkshell setup installs it for you). To mirror from the reMarkable, pick the Remote shell module during setup.

Drive an agent from your phone

A shared session can run a coding agent instead of a plain shell:

inkshell --agent claude [label]   # run Claude Code in the session, tagged @agent
inkshell --agent codex  [label]   # …or Codex

Because it's the same -L inkshell tmux session, that agent is already driven from both the Mac and the reMarkable at once. inkshell-agentd adds an optional third surface — a reflowable web UI you open on your phone:

node inkshell-xovi/scripts/inkshell-agentd.mjs      # → http://localhost:8889

It joins at the agent layer: it reads the pane with tmux capture-pane and types with tmux send-keys, and never attaches as a sized tmux client — so the reMarkable stays the size authority and the phone adds zero terminal-size pressure. Only @agent sessions are exposed; plain shells stay terminals-only.

The daemon binds 127.0.0.1 by default — never 0.0.0.0, never a port-forward. To reach it from your phone off your home network, put the Mac on Tailscale and either point HOST at the Mac's tailnet IP or front it with tailscale serve; add a shared token for defense in depth:

INKSHELL_AGENTD_TOKEN=secret HOST=100.x.y.z node inkshell-xovi/scripts/inkshell-agentd.mjs

Experimental. The phone bridge passes its local tests but isn't yet wired into the guided inkshell setup — run it by hand from a repo checkout as above.

Other commands

inkshell setup                # (re-)run the guided install wizard
inkshell doctor               # diagnose the tablet + Mac, with one-tap fixes
inkshell modules              # re-pick which modules are installed
inkshell remapper configure   # open the visual key-remap editor (web UI)
inkshell start                # re-inject xovi after a reboot (safe, non-persistent)
inkshell uninstall            # remove inkshell from the tablet (keeps your comic library)
inkshell --help               # full command + flag reference

Build from source

Prebuilt artifacts are the default. To build inkshell.so (reMarkable's Docker SDK) and the remapper (zig) locally instead, add --from-source:

inkshell setup --from-source

Updating

brew upgrade smith-chris/inkshell/inkshell   # update the CLI
inkshell setup                               # redeploy the new build to the tablet

Getting help

Found a bug, or something not working? Open an issue at https://github.com/smith-chris/inkshell/issues. It helps to include your tablet's OS version (inkshell doctor prints it), inkshell version, and whether you installed the prebuilt artifacts or --from-source.

Version / about

The canonical version is the Mac CLI:

inkshell version

inkshell doctor also prints the connected tablet's OS version and the installed module state. There is not yet a separate on-device About panel.

How it works (short version)

inkshell runs as an extension under xovi, an injection framework for the tablet's xochitl app, so it lives inside the normal interface instead of replacing it. The terminal engine is a fork of rm-literm (GPL-2.0), heavily reworked for the Paper Pro's colour e-ink panel. Prebuilt artifacts are cross-compiled to the tablet's ARM64 architecture (with --from-source, inside a Docker image using reMarkable's public SDK) and verified against a checksum manifest before deploy.

More detail for contributors: docs/ARCHITECTURE.md, and a full first-install walkthrough in docs/GETTING-STARTED.md.

Glossary

xochitl — the stock reMarkable UI process.
xovi — the extension framework that injects inkshell into xochitl.
qmldiff — xovi's patch format for adding QML UI to the stock app.
hashtab — the OS-version-specific lookup table qmldiff needs before it can patch xochitl safely.
A2 / GC16 — e-ink refresh modes: A2 is fast black/white for interaction; GC16 is slower, cleaner 16-level grayscale.
OBML-style — an Opera Mini-like browser model where a Mac daemon sends a compact page scene to the tablet instead of a full live browser.

What it's good at, and the trade-offs

Good for: a real, persistent SSH terminal you carry on the tablet — checking on a server, kicking off a build, editing over vim/tmux, tailing logs — plus distraction-light web reading and a comic/manga reader, on a glare-free screen that lasts days on a charge. Sessions survive sleep, Wi-Fi drops, and reconnects.

Trade-offs to understand before you install:

The remote shell is SSH, not a local computer. inkshell is the front-end; the work runs on a Mac/server you SSH into, which must be awake and reachable. The local-shell tab is a shell on the tablet itself (limited, but real).
E-ink, not an LCD. Typing uses a fast "A2" refresh that trades shades of grey for speed, so expect some ghosting until the next full repaint. It's tuned to feel responsive, but it will never be an LCD terminal.
A Type Folio is assumed. The terminal is usable without one but designed around a physical keyboard; the remapper requires it.
Unofficial and invasive. It injects into the stock app via xovi. It can't touch your notebooks, but it does run inside xochitl — see Safety / risk.
Tied to your OS version. A reMarkable software update can require re-running inkshell doctor (which rebuilds the OS-version-specific qmldiff "hashtab") before the tile works again.
The structured browser is Mac-assisted and alpha. It needs the companion daemon on your Mac; it's off by default. The Chromium browser runs fully on-device but is large. See docs/STRUCTURED-BROWSER.md and docs/CHROMIUM-BROWSER.md.

Safety / risk

The default install writes only under /home/root/xovi/ on the tablet. That area is temporary storage, cleared on every reboot, so a bad install can't persist — worst case you reboot and you're back to stock, or you run inkshell modules to change what's installed.

The optional autostart (inkshell --dangerously-allow-setting-up-xovi-and-inkshell-autostart) is different: it writes one small file to the tablet's read-only system partition so the framework loads on every boot. This is the one genuinely risky step. If the extension that loads at boot is broken, xochitl (the entire interface) can crash on start and keep crashing — a boot loop in which the inkshell tile and the UI never come up.

Understood risks:

Boot loop. A bad autostarted build can leave the interface stuck restarting.
A reMarkable software update may overwrite the file (harmless — autostart just stops working) or refuse to apply.
A backup .so left in extensions.d/ causes a fatal "processed more than once" crash-loop — keep backups outside that directory.

If you hit a boot loop — how to recover

First, undo it over USB — this usually works and loses no data. A crashing app does not take down the base system: the tablet's SSH over the USB cable (root@10.11.99.1) is normally still reachable even while the UI loops. From your Mac, remount the system partition writable, delete the boot file, and reboot:
```
ssh root@10.11.99.1 "mount -o remount,rw / && rm -f /lib/systemd/system/xochitl.service.d/99-xovi.conf && systemctl daemon-reload && reboot"
```
(/lib/systemd/system lives on the read-only rootfs, so the mount -o remount,rw / is required — without it the rm fails and the chain stops before reboot.) The tablet comes back to stock, notebooks untouched.
If even USB SSH is unreachable — use reMarkable's official recovery. If the device is wedged so badly that SSH never comes up, the only fix is reMarkable's own recovery tool, rm_recover, run over the device's USB recovery mode (the i.MX serial-download mode). It reflashes the OS and wipes the device — a factory reset. Follow reMarkable's official recovery instructions for the exact steps — do not improvise: https://support.remarkable.com (search "recovery"). Afterwards you re-enable Developer Mode and reinstall from scratch (inkshell doctor rebuilds the hashtab).

Recommendation: leave autostart off until you've run inkshell via inkshell start (or triple-press) across several reboots and confirmed it's stable on your device and OS version. The default install (no autostart) cannot boot-loop you — a reboot always returns you to stock.

Credits & licenses

inkshell is GPL-2.0, forked from rburchell/literm via asivery/rm-literm.
xovi and the xovi extension ecosystem — by asivery. Installed from the public rm-xovi-extensions releases.
xovi-tripletap — the safe triple-press activation, by rmitchellscott.
The visual remapper editor is inspired by VIA.
Type Folio photos used by the visual remapper are maintainer-owned photos taken for this project.
The e-ink rendering approach was informed by Err0r-v2/Scanly.
Cookie-consent auto-handling vendors DuckDuckGo's autoconsent (MPL-2.0) — inkshell-xovi/scripts/browserd/vendor/autoconsent/LICENSE.
CBZ / zip handling uses miniz (MIT) — inkshell-xovi/third_party/miniz/LICENSE.
The terminal escape-sequence parser (inkshell-xovi/src/parser.cpp / parser.h) is © 2020 Crimson AS under the MIT license — inherited from the literm fork, and the only MIT-licensed C++ in a tree that is otherwise GPL-2.0.
Ad / tracker blocking uses a public, EasyList / EasyPrivacy-derived set of hostnames + element-hiding selectors — inkshell-xovi/data/adblock.json.
Bundled fonts: FiraCode (SIL OFL 1.1 — see inkshell-xovi/data/firacode.LICENSE), Hack (MIT, with Bitstream Vera portions under the Bitstream Vera License — see inkshell-xovi/data/hack.LICENSE), Iosevka (SIL OFL 1.1 — see inkshell-xovi/data/iosevka.LICENSE), Noto Emoji (see inkshell-xovi/data/noto-emoji.LICENSE), and GNU Unifont (see inkshell-xovi/data/unifont.LICENSE).

This repository is released under the GNU General Public License v2.0 — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.githooks		.githooks
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
cli		cli
docker		docker
docs		docs
inkshell-xovi		inkshell-xovi
remapper		remapper
scripts		scripts
vendor		vendor
.clang-format		.clang-format
.clang-tidy		.clang-tidy
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LADDER.md		LADDER.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Repository files navigation

reMarkable Paper Pro toolkit — inkshell + SuperDvorak remapper

🧪 Alpha software

⚠️ Read this first — no warranty, use at your own risk

What you need

Install — step by step

1. Enable Developer Mode on the tablet

2. Connect the USB cable

3. Install and run

4. Open inkshell

Modules

After a reboot

Mac companion (remote shell / structured browser)

Reaching your Mac from anywhere

The SuperDvorak remapper

Shared sessions

Drive an agent from your phone

Other commands

Build from source

Updating

Getting help

Version / about

How it works (short version)

Glossary

What it's good at, and the trade-offs

Safety / risk

If you hit a boot loop — how to recover

Credits & licenses

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

reMarkable Paper Pro toolkit — inkshell + SuperDvorak remapper

🧪 Alpha software

⚠️ Read this first — no warranty, use at your own risk

What you need

Install — step by step

1. Enable Developer Mode on the tablet

2. Connect the USB cable

3. Install and run

4. Open inkshell

Modules

After a reboot

Mac companion (remote shell / structured browser)

Reaching your Mac from anywhere

The SuperDvorak remapper

Shared sessions

Drive an agent from your phone

Other commands

Build from source

Updating

Getting help

Version / about

How it works (short version)

Glossary

What it's good at, and the trade-offs

Safety / risk

If you hit a boot loop — how to recover

Credits & licenses

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages